Royal Belgian Institute for Aeronomy¶

unilib.h¶

Synopsis¶

INCLUDE 'unilib.h'

Description¶

The file unilib.h must be included in each FORTRAN program or subroutine that uses the UNILIB library. This file contains an IMPLICIT NONE statement, a list of structure definitions (as FORTRAN90 derived types) and the definitions of some global parameters. The global parameters are listed in the table below.

Parameters¶

nx120 [integer*4,parameter=500]¶: Size of the common block uc120 that determines the maximum number of magnetic field lines used to describe a magnetic drift shell

nx130 [integer*4,parameter=20000]¶: Size of the common block uc130 that determines the maximum number of stored points for a magnetic drift shell

nx140 [integer*4,parameter=16]¶: Maximum size for the spherical harmonic expansion of the geomagnetic field model, used in the definition of the TYPE zimf

nx170 [integer*4,parameter=500]¶: Size of the common block uc170 that determines the maximum number of geographic locations used to describe a magnetic field line segments

N_EXT_PARAMS [integer*4,parameter=20]¶: Size of the external parameter array passed to um520 - select an external magnetic field model.

Note

that after version 2.09, UNILIB uses FORTRAN 90 derived types instead of the STRUCTURE and RECORD extensions to the original DEC/VAX FORTRAN.

Internal Field Model Parameters¶

kint_igrf [integer*4,parameter=0]¶: KINT value to use for the IGRF magnetic field model in um510 - select an internal field model

kint_jensen_cain_62 [integer*4,parameter=1]¶: KINT value to use for the Jensen & Cain 1962 field model in um510 - select an internal field model.

kint_jensen_cain_62_saarot [integer*4,parameter=-1]¶: KINT value to use for the Jensen & Cain 1962 field model with compensation for the westward secular drift in um510 - select an internal field model.

kint_gsfc_12_66 [integer*4,parameter=2]¶: KINT value to use for the GSFC 12/66 field model in um510 - select an internal field model.

kint_gsfc_12_66_saarot [integer*4,parameter=-2]¶: KINT value to use for the GSFC 12/66 field model with compensation for the westward secular drift in um510 - select an internal field model.

kint_dipole [integer*4,parameter=3]¶: KINT value to use for the dipole magnetic field model in um510 - select an internal field model

kint_igrf_deprecated [integer*4,parameter=4]¶: KINT value to use for the deprecated IGRF model with the Kluge algorithm in um510 - select an internal field model.

As this model is deprecated, um510 - select an internal field model will throw an error if specified.

External Field Model Parameters¶

The external field model definitions can be implementation specific. In the current version of UNILIB the following are defined in the ext530 - set of external magnetic field models include file:

C####################################################################################
C                                                                                   #
C (C) Copyright European Space Agency, 2020                                         #
C                                                                                   #
C This file is subject to the terms and conditions defined in file 'LICENCE.txt',   #
C which is part of this source code package. No part of the package, including      #
C this file, may be copied, modified, propagated, or distributed except             #
C according to the terms contained in the file 'LICENCE.txt'.                       #
C                                                                                   #
C This file forms part of the UNILIB application, available from the                #
C European Space Software Repository (ESSR): https://essr.esa.int/                  #
C                                                                                   #
C####################################################################################

      INTEGER*4, PARAMETER :: N_EXT_MODELS = 12
      INTEGER*4, PARAMETER :: KEXT_NONE     = 0 
      INTEGER*4, PARAMETER :: KEXT_MEAD75   = 1 
      INTEGER*4, PARAMETER :: KEXT_TSYG87S  = 2 
      INTEGER*4, PARAMETER :: KEXT_TSYG87L  = 3 
      INTEGER*4, PARAMETER :: KEXT_TSYG89C  = 4 
      INTEGER*4, PARAMETER :: KEXT_OP77Q    = 5 
      INTEGER*4, PARAMETER :: KEXT_OP88D    = 6 
      INTEGER*4, PARAMETER :: KEXT_TSYG96   = 7 
      INTEGER*4, PARAMETER :: KEXT_OM97     = 8 
      INTEGER*4, PARAMETER :: KEXT_TSYG01   = 9 
      INTEGER*4, PARAMETER :: KEXT_TSYG04   = 10
      INTEGER*4, PARAMETER :: KEXT_ALEXEEV  = 11

      CHARACTER*32  lextmod(N_EXT_MODELS)
!
      DATA lextmod
     :       /'None                            ',
     :        'Mead-Fairfield 1975             ',
     :        'Tsyganenko 1987 short           ',
     :        'Tsyganenko 1987 long            ',
     :        'Tsyganenko 1989                 ',
     :        'Olson-Pfitzer 1977              ',
     :        'Olson-Pfitzer dynamic           ',
     :        'Tsyganenko 1996                 ',
     :        'Ostapenko-Maltsev 1997          ',
     :        'Tsyganenko 2001                 ',
     :        'Tsyganenko 2004                 ',
     :        'Alexeev Paraboloid 2000         '/

TYPE Definitions¶

In the next section, the different TYPE structures used in the UNILIB library are described. When declaring a TYPE without the help of the file unilib.h, be aware to check the order of the variable list.

zatm - atmospheric model configuration parameters¶

type zatm¶

Type fields:

% UT [real8] :: Universal Time in degrees
% RZSS [real8] :: Sun spot number
% F107A [real8] :: 81-day average of the radio flux F10.7
% F107 [real8] :: daily radio flux F10.7 of the previous day
% APIND (7) [real8] :: 3-hour Ap index for different times, see table below
% FKPX [real8] :: Maximum value of the 3-hour Kp index
% KATM [integer4] :: Number of the atmospheric model
% KION [integer4] :: Number of the ionospheric and/or plasmaspheric model
% KYEAR [integer4] :: Year
% KDAY [integer4] :: day of year [0..365]

APIND element description¶
Index	Description
1	Daily Ap index
2	3-Hour Ap index for the current time
3	3-Hour Ap index for the third hour before the current time
4	3-Hour Ap index for the sixth hour before the current time
5	3-Hour Ap index for the ninth hour before the current time
6	24-Hour average of the 3-hour Ap index from the 12th to the 35th hour prior to the current time
7	24-Hour average of the 3-hour Ap index from the 36th to the 59th hour prior to the current time

zdat - date and time¶

type zdat¶

date and time

Type fields:

% SECS [real8] :: Time
% AMJD [real8] :: Modified Julian Day based on the 1st of January 1950 00:00:00 UT
% IYEAR [integer4]
% IMONTH [integer4]
% IDAY [integer4]
% IHOUR [integer4]
% IMIN [integer4]
% IDUMMY [integer4]

zemf - parameters for the external magnetic field models¶

type zemf¶

Type fields:

% VDST [real8] :: Value of the storm activity index Dst in nT
% WDENS [real8] :: Value of the solar wind density in cm^-3
% WVEL [real8] :: Value of the solar wind velocity in km/s
% VKP [real8] :: Value of the planetary activity index Kp
% VAL [real8] :: Value for AL, see um520()
% PDYN [real8] :: Solar wind pressure (nanoPascal)
% BXIMF [real8] :: X component of the interplanetary magnetic field (nanotesla)
% BYIMF [real8] :: Y component of the interplanetary magnetic field (nanotesla)
% BZIMF [real8] :: Z component of the interplanetary magnetic field (nanotesla)
% STDOFF [real8] :: Standoff distance to the subsolar point
% G1 [real8] :: Tsyganenko model: value for G1, see um520
% G2 [real8] :: Tsyganenko model: value for G2, see um520
% W1 [real8] :: Tsyganenko model: value for W1, see um520
% W2 [real8] :: Tsyganenko model: value for W2, see um520
% W3 [real8] :: Tsyganenko model: value for W3, see um520
% W4 [real8] :: Tsyganenko model: value for W4, see um520
% W5 [real8] :: Tsyganenko model: value for W5, see um520
% W6 [real8] :: Tsyganenko model: value for W6, see um520
% TRANS (3,3) [real8] :: Transformation array from GEO to the LBLTNS coordinate system
% TILT [real8] :: Magnetic dipole tilt angle in degrees
% LABEL [CHARACTER20] :: Name of the model
% KOUTER [integer4] :: Number of the model
% IKP [integer4] :: Internal parameter based on VKP, see um521()
% LBLTNS [CHARACTER4] :: Coordinate system on which the model is based, e.g. SM or GSM

Note

The arguments PDYN, BXIMF, BYIMF, BZIMF and STDOFF were not present in version 1.06 and earlier.

zfln - magnetic field line segment¶

type zfln¶

Type fields:

% EQUAT [zpnt] :: Geographic point which corresponds to the lowest magnetic field intensity along the field line
% FOOTPN [zgeo] :: Geographic position of the northern foot point of the magnetic field line
% FOOTPS [zgeo] :: Geographic position of the southern foot point of the magnetic field line
% DRIFT [zvec] :: Vector proportional to the drift velocity evaluated at the point EQUAT
% DTDFT [real8] :: Value proportional to the time need by a particle to drift to the next field line segment
% INTEGER :: Index of the western previous magnetic field line segment of the drift shell
% INTEGER :: Index of the eastern next magnetic field line segment of the drift shell
% IND [zind] :: Indices of the magnetic field line segment

zgeo - geographic location¶

type zgeo¶

Type fields:

% RADIUS [real8] :: Geocentric radius in km
% COLAT [real8] :: Value of the co-latitude (90^o - latitude) in degrees
% ELONG [real8] :: Value of the longitude in degrees

Note

When the TYPE zgeo refers to geodetic coordinates (e.g. in subroutine um535()), the argument RADIUS corresponds to the geodetic altitude incremented by the mean Earth’s radius (stored in the argument RE of the common block uc160 and equal to 6371.2 km).

zimf - geomagnetic field model¶

type zimf¶

Type fields:

% LABEL [CHARACTER(32)] :: Name of the geomagnetic field model
% KINNER [integer4] :: Number of the geomagnetic field model
% NORDER [integer4] :: Order of the spherical harmonic expansion increased by one
% COEF (nx140, nx140) [real8] :: Spherical harmonic expansion coefficients
% COLAT [real8] :: Co-latitude of the boreal dipole pole, in degrees
% ELONG [real8] :: East longitude of the boreal dipole pole, in degrees
% GMMO [real8] :: Moment of the magnetic dipole, in Gauss Re3
% TZERO [real8] :: Base epoch of the model
% EPOCH [real8] :: Epoch of the geomagnetic field evaluation, in years
% SAAROT [real8] :: Longitude correction for the secular drift of the South Atlantic Anomaly, in degrees

zind - pointers into an array of zseg - element of a magnetic field line segment ¶

type zind¶

Type fields:

% JBEG [integer4] :: Index of the first element of the field line segment
% JEND [integer4] :: Index of the last element of the field line segment
% JMIRPN [integer4] :: Index of the northern mirror point
% JMIRPS [integer4] :: Index of the southern mirror point

zlbl - magnetic drift shell labels¶

type zlbl¶

Type fields:

% FINV [real8] :: Value of the integral invariant I
% FBMP [real8] :: Value of the magnetic field intensity at the mirror points
% FKAUF [real8] :: Value of the Kaufmann’s adiabatic invariant K
% FLMI [real8] :: Value of the McIlwain parameter L
% FALP0 [real8] :: Value of the equatorial pitch angle
% FPHI [real8] :: Value of the third adiabatic invariant
% FTIM [real8] :: Not defined
% LABEL [CHARACTER(1)] :: User’s label of the drift shell
% LINV [LOGICAL1] :: FINV value validated
% LBMP [LOGICAL1] :: FBMP value validated
% LKAUF [LOGICAL1] :: FKAUF value validated
% LLMI [LOGICAL1] :: FLMI value validated
% LALP0 [LOGICAL1] :: FALP0 value validated
% LPHI [LOGICAL1] :: FPHI value validated
% LTIM [LOGICAL1] :: FTIM value validated

zpnt - location on a magnetic field line¶

type zpnt¶

Type fields:

% COORD [zgeo] :: Geographic position of the point
% B [zvec] :: Magnetic field vector at the point
% RCURV [real8] :: Radius of curvature of the magnetic field line at the point

zseg - element of a magnetic field line segment¶

type zseg¶

Type fields:

% BEG [zpnt] :: Start location of the segment
% ARCL [real8] :: Arc length along the field line
% CSALP [real8] :: Cosine of the local pitch-angle
% DTBND [real8] :: Not defined
% RKSTP (3) [real8] :: Intermediate values of the magnetic field intensity obtained during the Runge-Kutta integration

zsun - Sun’s location¶

type zsun¶

Type fields:

% UTDEG [real8] :: Universal Time in degrees
% GHA [real8] :: Greenwich angle of equinox in degrees
% DIR [zxyz] :: Cartesian GEO direction of the Sun, normalized to unity

zvec - spherical components of a vector¶

type zvec¶

refer to the spherical components of a vector

Type fields:

% DNRM [real8] :: Norm of the vector
% RHO [real8] :: Radial component
% THETA [real8] :: Component along the co-latitude
% PHI [real8] :: Component along the longitude

Note

Both values of DNRM, RHO, THETA and PHI are expressed in the same units. For example, they are all given in Gauss when they are used to characterize the magnetic field vector.

zxyz - cartesian vector components.¶

type zxyz¶

Type fields:

% X [real8] :: x component of the cartesian coordinates
% Y [real8] :: y component of the cartesian coordinates
% Z [real8] :: z component of the cartesian coordinates

Examples¶

None

UNILIB/tags/v3.03

unilib.h¶

Synopsis¶

Description¶

Parameters¶

Internal Field Model Parameters¶

External Field Model Parameters¶

TYPE Definitions¶

zatm - atmospheric model configuration parameters¶

zdat - date and time¶

zemf - parameters for the external magnetic field models¶

zfln - magnetic field line segment¶

zgeo - geographic location¶

zimf - geomagnetic field model¶

zind - pointers into an array of zseg - element of a magnetic field line segment ¶

zlbl - magnetic drift shell labels¶

zpnt - location on a magnetic field line¶

zseg - element of a magnetic field line segment¶

zsun - Sun’s location¶

zvec - spherical components of a vector¶

zxyz - cartesian vector components.¶

See also¶

Examples¶

Table of Contents

unilib.h¶

Synopsis¶

Description¶

Parameters¶

Internal Field Model Parameters¶

External Field Model Parameters¶

TYPE Definitions¶

zatm - atmospheric model configuration parameters¶

zdat - date and time¶

zemf - parameters for the external magnetic field models¶

zfln - magnetic field line segment¶

zgeo - geographic location¶

zimf - geomagnetic field model¶

zind - pointers into an array of zseg - element of a magnetic field line segment¶

zlbl - magnetic drift shell labels¶

zpnt - location on a magnetic field line¶

zseg - element of a magnetic field line segment¶

zsun - Sun’s location¶

zvec - spherical components of a vector¶

zxyz - cartesian vector components.¶

See also¶

Examples¶

zind - pointers into an array of zseg - element of a magnetic field line segment ¶