Magnetic Field Models

The routines in this module can be used to calculate Tsyganenko magnetic field models using Sheng Tian’s implementation of the geopack library (https://github.com/tsssss/geopack).

Tsyganenko 89 (T89)

pyspedas.geopack.tt89(pos_var_gsm, iopt=3, suffix='', igrf_only=False)

tplot wrapper for the functional interface to Sheng Tian’s implementation of the Tsyganenko 96 and IGRF model:

https://github.com/tsssss/geopack

pos_gsm_tvar: str

tplot variable containing the position data (km) in GSM coordinates

Parameters

  • iopt (int) –

    Specifies the ground disturbance level:
    iopt= 1 2 3 4 5 6 7

    correspond to:

    kp= 0,0+ 1-,1,1+ 2-,2,2+ 3-,3,3+ 4-,4,4+ 5-,5,5+ &gt =6-

  • suffix (str) – Suffix to append to the tplot output variable

Return type

Name of the tplot variable containing the model data

T89 Example

# load some spacecraft position data
import pyspedas
pyspedas.mms.mec(trange=['2015-10-16', '2015-10-17'])

# calculate the field using the T89 model
from pyspedas.geopack import tt89
tt89('mms1_mec_r_gsm')

from pytplot import tplot
tplot('mms1_mec_r_gsm_bt89')
_images/tt89.png

Tsyganenko 96 (T96)

pyspedas.geopack.tt96(pos_var_gsm, parmod=None, suffix='')

tplot wrapper for the functional interface to Sheng Tian’s implementation of the Tsyganenko 96 and IGRF model:

https://github.com/tsssss/geopack

pos_gsm_tvar: str

tplot variable containing the position data (km) in GSM coordinates

Parameters

  • parmod (ndarray) –

    10-element array (vs. time), but only the first 4 elements are used

    1. solar wind pressure pdyn (nanopascals)

    2. dst (nanotesla)

    3. byimf (nanotesla)

    4. bzimf (nanotesla)

  • suffix (str) – Suffix to append to the tplot output variable

Return type

Name of the tplot variable containing the model data

T96 Example

# load some spacecraft position data
import pyspedas
pyspedas.mms.mec(trange=['2015-10-16', '2015-10-17'])

# calculate the params using the solar wind data; see the "Solar Wind Parameters" section below for an example

# interpolate the MEC timestamps to the solar wind timestamps
from pyspedas import tinterpol
tinterpol('mms1_mec_r_gsm', 'proton_density')

# calculate the field using the T96 model
from pyspedas.geopack import tt96
tt96('mms1_mec_r_gsm-itrp', parmod=params)

from pytplot import tplot
tplot('mms1_mec_r_gsm-itrp_bt96')
_images/tt96.png

Tsyganenko 2001 (T01)

pyspedas.geopack.tt01(pos_var_gsm, parmod=None, suffix='')

tplot wrapper for the functional interface to Sheng Tian’s implementation of the Tsyganenko 2001 and IGRF model:

https://github.com/tsssss/geopack

pos_gsm_tvar: str

tplot variable containing the position data (km) in GSM coordinates

Parameters

  • parmod (ndarray) –

    10-element array (vs. time), but only the first 6 elements are used

    1. solar wind pressure pdyn (nanopascals),

    2. dst (nanotesla)

    3. byimf (nanotesla)

    4. bzimf (nanotesla)

    5. g1-index

    6. g2-index (see Tsyganenko [2001] for an exact definition of these two indices)

  • suffix (str) – Suffix to append to the tplot output variable

Return type

Name of the tplot variable containing the model data

T01 Example

# load some spacecraft position data
import pyspedas
pyspedas.mms.mec(trange=['2015-10-16', '2015-10-17'])

# calculate the params using the solar wind data; see the "Solar Wind Parameters" section below for an example

# interpolate the MEC timestamps to the solar wind timestamps
from pyspedas import tinterpol
tinterpol('mms1_mec_r_gsm', 'proton_density')

# calculate the field using the T01 model
from pyspedas.geopack import tt01
tt01('mms1_mec_r_gsm-itrp', parmod=params)

from pytplot import tplot
tplot('mms1_mec_r_gsm-itrp_bt01')
_images/tt01.png

Tsyganenko-Sitnov 2004 (TS04)

pyspedas.geopack.tts04(pos_var_gsm, parmod=None, suffix='')

tplot wrapper for the functional interface to Sheng Tian’s implementation of the Tsyganenko-Sitnov (2004) storm-time geomagnetic field model

https://github.com/tsssss/geopack

pos_gsm_tvar: str

tplot variable containing the position data (km) in GSM coordinates

Parameters

  • parmod (ndarray) –

    10-element array (vs. time):

    1. solar wind pressure pdyn (nanopascals),

    2. dst (nanotesla),

    3. byimf,

    (4) bzimf (nanotesla) (5-10) indices w1 - w6, calculated as time integrals from the beginning of a storm

    see the reference (3) below, for a detailed definition of those variables

  • suffix (str) – Suffix to append to the tplot output variable

Return type

Name of the tplot variable containing the model data

TS04 Example

# load some spacecraft position data
import pyspedas
pyspedas.mms.mec(trange=['2015-10-16', '2015-10-17'])

# calculate the params using the solar wind data; see the "Solar Wind Parameters" section below for an example

# interpolate the MEC timestamps to the solar wind timestamps
from pyspedas import tinterpol
tinterpol('mms1_mec_r_gsm', 'proton_density')

# calculate the field using the TS04 model
from pyspedas.geopack import tts04
tts04('mms1_mec_r_gsm-itrp', parmod=params)

from pytplot import tplot
tplot('mms1_mec_r_gsm-itrp_bts04')
_images/tts04.png

Solar Wind Parameters

To generate the “parmod” variable using Dst and solar wind data, use the get_tsy_params routine.

pyspedas.geopack.get_tsy_params.get_tsy_params(dst_tvar, imf_tvar, Np_tvar, Vp_tvar, model, pressure_tvar=None, newname=None, speed=False, g_variables=None)

This procedure will interpolate inputs, generate Tsyganenko model parameters and store them in a tplot variable that can be passed directly to the model procedure.

dst_tvar: str

tplot variable containing the Dst index

imf_tvar: str

tplot variable containing the interplanetary magnetic field vector in GSM coordinates

Np_tvar: str

tplot variable containing the solar wind ion density (cm**-3)

Vp_tvar: str

tplot variable containing the proton velocity

model: str

Tsyganenko model; should be: ‘T89’, T96’, ‘T01’,’TS04’

Parameters

  • newname (str) – name of the output variable; default: t96_par, ‘t01_par’ or ‘ts04_par’, depending on the model

  • speed (bool) – Flag to indicate Vp_tvar is speed, and not velocity (defaults to False)

  • pressure_tvar (str) – Set this to specify a tplot variable containing solar wind dynamic pressure data. If not supplied, it will be calculated internally from proton density and proton speed.

Returns

  • Name of the tplot variable containing the parameters.

  • The parameters are –

    1. solar wind pressure pdyn (nanopascals),

    2. dst (nanotesla),

    3. byimf,

    (4) bzimf (nanotesla) (5-10) indices w1 - w6, calculated as time integrals from the beginning of a storm

    see the reference (3) below, for a detailed definition of those variables

get_tsy_params Example

# load Dst and solar wind data
import pyspedas
pyspedas.kyoto.dst(trange=['2015-10-16', '2015-10-17'])
pyspedas.omni.data(trange=['2015-10-16', '2015-10-17'])

# join the components of B into a single variable
# BX isn't used
from pytplot import join_vec
join_vec(['BX_GSE', 'BY_GSM', 'BZ_GSM'])

from pyspedas.geopack.get_tsy_params import get_tsy_params
params = get_tsy_params('kyoto_dst',
                     'BX_GSE-BY_GSM-BZ_GSM_joined',
                     'proton_density',
                     'flow_speed',
                     't96', # or 't01', 'ts04'
                     pressure_tvar='Pressure',
                     speed=True)