European Space Agency

European Space Agency

Royal Belgian Institute for Space Aeronomy

Royal Belgian Institute for Space Aeronomy

_images/whiteSpace.png

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.

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.

Definitions [ zatm | zdat | zemf | zfln | zgeo | zimf | zind | zlbl | zpnt | zseg | zsun | zvec | zxyz ]

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]

see also ut540() and ut545()

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 (90o - 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

See also

  • uc110, magnetic drift shell description

  • uc120, magnetic field line description

  • uc120, set of magnetic field line segments

  • uc140, magnetic field description

  • uc150, atmospheric model description

  • uc170, temporary magnetic field line

Examples

None

UNILIB/trunk/