- 4

Trapped Radiation ENvironment model Development


[ Name | Synopsis | Arguments | Description | Diagnostics | Common Blocks | Dependencies | See Also | Reported Bugs | Examples ]


    Subroutine UM520 - select an external magnetic field model


      REAL*8        amjd, param(10)
      INTEGER*4     kext, ifail, kunit
      CHARACTER*32  lbext
      UM520 (kext, amjd, param, lbext, kunit, ifail)     


    Index of the external magnetic field model (0 to 6) [in]
    Modified Julian Day [in]
    Set of parameters for the external magnetic field models [in]
    Label of the external magnetic field model [out]
    File unit for the summary table (see note of subroutine UT990) [in]
    Error flag (see diagnostics) [out]


    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 Kp. The dynamic Olson & Pfitzer model (kext = 6) depends on the disturbance storm-time index Dst, 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 Kp, the disturbance storm-time index Dst, 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).

    kextExternal magnetic field model
    1Mead & Fairfield [1975]
    2Tsyganenko short [1987]
    3Tsyganenko long [1987]
    4Tsyganenko [1989c]
    5Olson & Pfitzer quiet [1977]
    6Olson & Pfitzer dynamic [1988]
    7Tsyganenko [1996]
    8Ostapenko & Maltsev [1997]
    Note: Dr. Tsyganenko recommends not using the obsolete 1987 versions.

    paramDescriptionRange Default Used by
    Old argument
    1Planetary magnetic activity index Kp (see Note) 0 to 901, 2, 3, 4, 8 fkp
    2Disturbance storm-time index Dst (nT) -600 to 50-306, 7, 8 dst
    3Solar wind pressure (nP) 0.5 to 1037, 8 -
    4Solar wind density (cm-3) 1 to 100256 swd
    5Solar wind velocity (km/s) 100 to 12003006 swv
    6Interplanetary magnetic field X component (nT) -50 to 506- -
    7Interplanetary magnetic field Y component (nT) -50 to 5007 -
    8Interplanetary magnetic field Z component (nT) -50 to 5007, 8 -
    9Standoff distance to the subsolar point (Re) 4 to 1410- -
    10Reserved for future use ----

    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 (Kp, Dst,...), except for the Ostapenko & Maltsev [1997] model (kext=8) for which UM520 has to be called. Note that the coefficients of mext.trans (common block UC140) 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).


    The value of Kp is also used by the subroutine UM533 to determine the distance to the magnetopause, even when the selected model is not function of Kp, 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.


  • Olson, W.P., A model of the distributed magnetospheric currents, JGR 79 (1974) 3731-3738
  • Olson, W.P. and Pfitzer, K.A., Magnetospheric magnetic field modeling, Annual Scientific Report, AFOSR Contract No. F44620-75-C-0033 (1977)
  • 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
  • Pfitzer, K.A., Olson, W.P. and Mogstad, T., A time dependent source driven magnetospheric magnetic field model, EOS 69 (1988) 426
  • 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
  • Tsyganenko, N.A., A magnetospheric magnetic field model with a wrapped tail current sheet, Planet.Space.Sci. 37 (1989) 5-20
  • 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


    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 synopsis 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 Dst, the planetary magnetic activity index Kp, 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 Dst as parameter of the Tsyganenko [1996] model and the subroutine UM520 did not print the value of Dst when this model was selected. Note that, nevertheless, the value of Dst was used during computations of the Tsyganenko [1996] model.

    In versions 1.07 to 1.13, the value of Kp was not correctly passed to the subroutine UM533. The distance to the magnetopause was always evaluated with Kp 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.


    -52001, invalid model number
    -52002, error on output device

Common Blocks

    UC140, magnetic field description
    UC160, general constants


Called by



    UM521, ground disturbances from Kp
    UM522, position of the Sun
    UM523, GEO to GSM transformation
    UM524, GEO to SM transformation
    EXT530, set of external magnetic models:

See also

    UM510, select a geomagnetic field model
    UM530, evaluate the magnetic field vector
    EXT530, set of external magnetic models
    [@] magnetic activity indices at SpaceWeb

Reported Bugs

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


    #1, evaluation of the magnetic field vector
    #2, evaluation of the (B, L) coordinates
    #3, evaluation of the third invariant
    #4, search the point with the lowest altitude on a magnetic drift shell
    #5, namelist to initialize UNILIB
    #7, iso-contour of the shell parameter
    G.06 How to start using the UNILIB library ?
    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 ?