European Space Agency

Royal Belgian Institute for Aeronomy

um520 - select an external magnetic field model

subroutine  um520(kext, amjd, param, lbext, kunit, ifail)

Parameters:

• kext [integer4,in] :: index of the external magnetic field mode [0..6]

• amjd [real8,in] :: Modified Julian Day

• param (N_EXT_PARAMS) [real8,in] :: set of parameters for the external magnetic field models.

• lbext [character32,out] :: label of the external field model

• kunit [integer4,in] :: file unit for the summary table (see note of ut990())

• ifail [integer4,out] :: error flag (see Diagnostics)

Description

The subroutine um520() may be used to initialize the external magnetic field description inside the common block uc140. The kext argument allows to choose between different models as listed in the first table below. The subroutine um520() initializes the selected field model as well as the position of the Sun and the GSM or SM coordinate transformation. The position of the Sun and the transformation are deduced from the geomagnetic field model (selected by subroutine um510()) and from the modified Julian Day specified by the argument amjd.

The Mead & Fairfield model (kext = 1) and most of Tsyganenko models (kext= 2, 3 and 4) depend on the planetary magnetic activity index \(K_p\). The dynamic Olson & Pfitzer model (kext= 6) depends on the disturbance storm-time index \(D_{st}\), the density of solar wind and the velocity of solar wind. The Tsyganenko 1996 model (kext= 7) depends on the solar wind pressure and the components y and z of the interplanetary magnetic field. The Ostapenko & Maltsev model (kext= 8) depends on the planetary magnetic activity index \(K_p\), the disturbance storm-time index \(D_{st}\), the dynamic pressure of the solar wind and the z component of the interplanetary magnetic field. These different parameters are specified to the subroutine um520() by the way of the argument param. The correspondance between the different parameters and the indices of the argument param are given in the second table below. The last column of the table is used to indicated correspondances with old arguments of the subroutine (see history).

kext	External magnetic field model
0	None
1	Mead & Fairfield (1975) [1]
2 *	Tsyganenko short (1987) [6]
3 *	Tsyganenko long (1987) [6]
4 *	Tsyganenko (1989) [6]
5	Olson & Pfitzer quiet (1977) [2]
6	Olson & Pfitzer dynamic (1988) [5]
7 *	Tsyganenko (1996) [8]
8	Ostapenko & Maltsev (1997) [4]
9 *	Tsyganenko (2002) [9], [10]
10*	Tsyganenko (2004) [12]
11	Paraboloid model, Alexeev [2000] [13]

* The Tsyganenko external models are not distributed with UNILIB. Please see G.10 - Are the Tsyganenko Models included?

Note

Dr. Tsyganenko recommends not using the obsolete 1987 versions

External Field Models

param	Description	Range	Default	Used by (kext)	Old argument
1	Planetary magnetic activity index \(K_p\) (see Note)	0 to 9	0	1, 2, 3, 4, 8	fkp
2	Disturbance storm-time index \(D_{st}\) (nT)	-600 to 50	-30	6, 7, 8	dst
3	Solar wind pressure (nPa)	0.5 to 10	3	7, 8
4	Solar wind density (cm-3)	1 to 100	25	6	swd
5	Solar wind velocity (km/s)	100 to 1200	300	6	swv
6	Interplanetary magnetic field X component (nT)	-50 to 50	6
7	Interplanetary magnetic field Y component (nT)	-50 to 50	0	7
8	Interplanetary magnetic field Z component (nT)	-50 to 50	0	7, 8
9	Standoff distance to the subsolar point (Re)	4 to 14	10
10	AL: Auroral Electrojet index	-3000 to 100	-100	11
11	G1: IMF related indices	0 to 10	6	9
12	G2: IMF related indices	0 to 10	10	9
13	W1: see [12]	0 to 20	4	10
14	W2: see [12]	0 to 10	3	10
15	W3: see [12]	0 to 20	4	10
16	W4: see [12]	0 to 100	10	10
17	W5: see [12]	0 to 100	7	10
18	W6: see [12]	0 to 100	20	10
19	reserved not documented yet
20	reserved not documented yet

For each element of the argument param, when a value is set to -999, the corresponding default value is used instead (without modifying the argument param). The default value of the standoff distance is deduced from the solar wind velocity and density when they are provided. Anyway, a warning is written in the summary table when a parameter is out of range.

As result, the lbext argument contains a string with the label of the selected external magnetic field model and a summary table is written on the file specified by argument kunit. The summary table includes the values of the parameters that will be used by the external magnetic field model.

The subroutines um522(), um523() and um524() can be used to modify the time and date of the external magnetic field without modifying the model choice kext or field parameters params (\(K_p\), \(D_{st}\),…), except for the Ostapenko & Maltsev [1997] model (kext=8) for which um520() must be called. The coefficients of mext.trans (common block uc140, type zemf) are expressed in the GSM coordinates with the Tsyganenko models (2, 3, 4 and 7) while the SM coordinates are used with the other models (1, 5 and 6).

Note

The value of \(K_p\) is also used by the subroutine um533() to determine the distance to the magnetopause, even when the selected model is not function of \(K_p\), e.g. Olson & Pfitzer quiet. The subroutine um533() is used to prevent the library the tracing of magnetic field line outside the magnetosphere. So, the subroutine is active only for large L values. Note that it is possible to inhibit the action of this subroutine.

References

[1]

Mead, G.D., and Fairfield, D.H., A quantitative magnetospheric model derived from spacecraft magnetometer data, JGR 80 (1975) 523-534, https://doi.org/10.1029/JA080i004p00523

[2]

Olson, W.P., A model of the distributed magnetospheric currents, JGR 79 (1974) 3731-3738

[3]

Olson, W.P. and Pfitzer, K.A., Magnetospheric magnetic field modeling, Annual Scientific Report, AFOSR Contract No. F44620-75-C-0033 (1977)

[4]

Ostapenko, A.A., and Maltsev, Y.P., Relation of the magnetic field in the magnetosphere to the geomagnetic and solar wind activity, JGR 102 (1997) 17467-17473

[5]

Pfitzer, K.A., Olson, W.P. and Mogstad, T., A time dependent source driven magnetospheric magnetic field model, EOS 69 (1988) 426

[6] (1,2,3)

Tsyganenko, N.A., Global quantitative models of the geomagnetic field in the cislunar magnetosphere for different disturbance levels, Planet.Space Sci. 35 (1987) 1347-1358

[7]

Tsyganenko, N.A., A magnetospheric magnetic field model with a wrapped tail current sheet, Planet.Space.Sci. 37 (1989) 5-20

[8]

Tsyganenko, N.A. and Stern, D.P., Modeling the global magnetic field the large-scale Birkeland current systems, J.Geophys.Res. 101 (1996) 27187-27198

[9]

Tsyganenko, N. A.: A model of the near magnetosphere with a dawn-dusk asymmetry: 1. Mathematical structure, J. Geophys. Res., 107, 1179, 2002. https://doi.org/10.1029/2001JA000219

[10]

Tsyganenko, N. A.: A model of the near magnetosphere with a dawn-dusk asymmetry: 2. Parametrization and fitting to observations, J. Geophys. Res., 107, 1176, 2002. https://doi.org/10.1029/2001JA000220

[11]

Tsyganenko, N.A., H. J. Singer, J. C. Kasper, Storm-time distortion of the inner magnetosphere: How severe can it get ? JGR v. 108(A5), 1209, doi:10.1029/2002JA009808, 2003.

[12] (1,2,3,4,5,6,7)

Tsyganenko, N.A., and M. I. Sitnov, Modeling the dynamics of the inner magnetosphere during strong geomagnetic storms, J. Geophys. Res., v. 110 (A3), A03208, doi: 10.1029/2004JA010798, 2005.

[13]

Alexeev, I., “Paraboloid magnetospheric magnetic field model and the status of the model as an ISO standard”, 36th COSPAR Scientific Assembly. Meeting abstract from the CDROM, #563, 2006.

History

In version 1.06 and earlier, the subroutine um520() includes only 7 models (kext = 0 to 6). The addition of other models has caused a modification of the synopsis of the subroutine um520(). The previous interface of the subroutine was:

UM520 (kext, amjd, dst, fkp, swd, swv, lbext, kunit, ifail)

where the arguments dst, fkp, swd and swv correspond to the disturbance storm-time index \(D_{st}\), the planetary magnetic activity index \(K_p\), the density of solar wind and the velocity of solar wind, respectively. In the new version, these parameters are passed through the argument param. The Tsyganenko [1996] model has been implemented in the version 1.07 of the library. The Ostapenko & Maltsev [1997] model has been implemented in the version 1.12.

In versions 1.07 to 1.12, the documentation did not include \(D_{st}\) as parameter of the Tsyganenko [1996] model and the subroutine um520() did not print the value of \(D_{st}\) when this model was selected. Note that, nevertheless, the value of \(D_{st}\) was used during computations of the Tsyganenko [1996] model.

In versions 1.07 to 1.13, the value of \(K_p\) was not correctly passed to the subroutine um533(). The distance to the magnetopause was always evaluated with \(K_p\) set to zero.

In versions 2.00 and 2.01, due to an oversight, the model parameters were forced to the default values instead of the values passed in the argument param. This erroneous behaviour affects user applications using external magnetic field models: Mead & Fairfield [1975], Tsyganenko short [1987], Tsyganenko long [1987], Tsyganenko [1989a], Olson & Pfitzer dynamic [1988], Tsyganenko [1996] and Ostapenko & Maltsev [1997]. It does not affect applications that do not use an external field model (kext=0) or that use the Olson & Pfitzer quiet [1977] model (kext=5).

In version 2.02, the Tsyganenko [1989a] model (kext=4) has been replaced by the Tsyganenko [1989c] model.

In version 3.00, the Tsyganenko models were removed from the distribution.

Diagnostics

• -52001, invalid model number.

• -52002, error on output device.

• -52003, Tsyganenko Models not installed.

Common Blocks

• uc140 - magnetic field

• uc160 - general constants

Dependencies

Called by

None

Calls

• um521 - ground disturbance from Kp

• um522 - position of the Sun

• um523 - GEO to GSM transformation

• um524 - GEO to SM transformation

• ext530 - set of external magnetic field models

See also

• um510 - select an internal field model

• um530 - evaluate the magnetic field vector

• ext530 - set of external magnetic field models

• magnetic activity indices at NOAA/NGDC

Reported Bugs

• 9-Jan-98 (v1.10 & v1.11), Anomalous return with error code -52002 when kunit and kext are greater than 0

Examples

• Ex #1. Evaluation of the magnetic field vector

• Ex #2. Evaluation of the (B-L) coordinates

• Ex #3. Evaluation of the third invariant

• Ex #4. Find the point with the lowest altitude on a magnetic drift shell

• Ex. #5. namelist to initialize UNILIB

• Ex. #7. iso-contour of the shell parameter

• G.06 - How to start using the UNILIB library ?

• G.10 - Are the Tsyganenko Models included?

• T.03 - How to customize the magnetic field model used by the library ?

• T.04 - Why are Roederer’s L* and McIlwain’s L parameters different ?

---

UNILIB/tags/v3.02