# ONERA-DESP library - user's guide

Version 2.2 - October 2004
Authors: D. Boscher, S. Bourdarie - ONERA-DESP, Toulouse France
For any questions or to report bugs please contact
Dr. Sebastien Bourdarie or Dr. Daniel Boscher

The following document describes how to use the ONERA-DESP fortran library to compute magnetic coordinates and drift shells using various external magnetic field models. Further routines are provided for various coordinate and time format transformations.

The package includes a sript to compile the library under a linux system. You might have to change it to build the library on your system. Currently the library is compiled using the standard gnu compiler (g77). An example calling the library from IDL is given in example directory of the distribution and can be run to test if the library has been built properly.

Two libraries are created, one for access from IDL and one for access from fortran or some other language.
-from IDL use lib_name='onera_desp_lib.so'
-from FORTRAN use liboneradesp.a

Notes:

1. When calling from IDL using call_external, ALL input and output variables have to be declared in the correct type. Failure to do this will result in a very ungracefull idl exit with no error messages or possibility of tracing! In general, integers need to be declared as longs and floats as double.

2. The bad value flag is set to -1.d31 throughout.

Caution: The library has so far been extensively tested with Olson Pfitzer quiet. Other magnetic field models should be used with caution, as there may be problems. Expect this message to evolve as we test more of the code.

Rule of use: The use of this library is free. If you want to fully refer to this library in publications or reports, use the following: "D. Boscher, S. Bourdarie, ONERA-DESP library V2.2, Toulouse-France, 2004".

Acknowledgments: The authors whish to thanks:

- K. Pfitzer, N. Tsyganenko and their co-authors for providing us magnetic field model source codes and for good discussions on how to use their model correctly.
- R. Friedel (LANL), Y. Dotan and M. Redding (Aerospace corporation) for good discussions, advices and bug reports which are always very helpfull when one attemps to develop such a tool.
- D. Bilitza for his help regarding the use of IGRF magnetic field model.

## Content of library

MAKE_LSTAR
MAKE_LSTAR_SHELL_SPLITTING
DRIFT_SHELL
FIND_MIRROR_POINT
FIND_MAGEQUATOR
GET_FIELD

GEO2GSM
GSM2GEO
GEO2GSE
GSE2GEO
GDZ2GEO
GEO2GDZ
GEO2GEI
GEI2GEO
GEO2SM
SM2GEO
GSM2SM
SM2GSM
GEO2MAG
MAG2GEO
SPH2CAR
CAR2SPH
RLL2GDZ

JULDAY
CALDAT
GET_DOY
DECY2DATE_AND_TIME

------------------------------------------------------------

## MAKE_LSTAR

### DESCRIPTION:

This function allows one to compute magnetic coordinate at any s/c position, i.e. L, L*, Blocal, Bequator ...
The internal magnetic field model is set to IGRF where parameters are can be computed for the month of june of the year or at any user defined frequency. The external magnetic field model can be selected (see inputs).

### INPUTS:

ntime: long integer number of time in arrays (max allowed is 100000)

kext: long integer to select external magnetic field

0 = no external field
1 = Mead & Fairfield [1975] (uses 0≤Kp≤9 - Valid for rGEO≤17. Re)
2 = Tsyganengo short [1987] (uses 0≤Kp≤9 - Valid for rGEO≤30. Re)
3 = Tsyganengo long [1987] (uses 0≤Kp≤9 - Valid for rGEO≤70. Re)
4 = Tsyganenko [1989c] (uses 0≤Kp≤9 - Valid for rGEO≤70. Re)
5 = Olson & Pfitzer quiet [1977] (default - Valid for rGEO≤15. Re)
6 = Olson & Pfitzer dynamic [1988] (uses 5.≤dens≤50., 300.≤velo≤500., -100.≤Dst≤20. - Valid for rGEO≤60. Re)
7 = Tsyganenko [1996] (uses -100.≤Dst (nT)≤20., 0.5≤Pdyn (nPa)≤10., |ByIMF| (nT)≤10., |BzIMF| (nT)≤10. - Valid for rGEO≤40. Re)
8 = Ostapenko & Maltsev [1997] (uses dst,Pdyn,BzIMF, Kp)
9 = Tsyganenko [2001] (uses -50.≤Dst (nT)≤20., 0.5≤Pdyn (nPa)≤5., |ByIMF| (nT)≤5., |BzIMF| (nT)≤5., 0.≤G1≤10., 0.≤G2≤10. - Valid for xGSM≥-15. Re)
10 =Tsyganenko [2001] storm (uses Dst, Pdyn, ByIMF, BzIMF, G2, G3 - there is no upper or lower limit for those inputs - Valid for xGSM≥-15. Re)
Notes:

1. when the magnetic field model inputs are outside the allowed range bad data values are returned.
2. When solar wind inputs are required they must be taken in the vicinity of the day side magnetopause and not at L1.

options: array(5) of long integer to set some control options on computed values

1. options(1st element): 0 - don't compute L*; 1 - compute L*
2. options(2nd element): 0 - initialize IGRF field once per year (year.5); n - n is the frequency (in days) starting on January 1st of each year (i.e. if options(2nd element)=15 then IGRF will be updated on the following days of the year: 1, 15, 30, 45 ...)
3. options(3rd element): resolution to compute L* (0 to 9) where 0 is the recomended value to ensure a good ratio precision/computation time (i.e. an error of ~2% at L=6). The higher the value the better will be the precision, the longer will be the computing time. Generally there is not much improvement for values larger than 4.
4. options(4th element): for future use
5. options(5th element): for future use

sysaxes: long integer to define which coordinate system is provided in

0: GDZ (alti, lati, longi - km,deg.,deg)
1: GEO (cartesian) - Re
2: GSM (cartesian) - Re
3: GSE (cartesian) - Re
4: SM (cartesian) - Re
5: GEI (cartesian) - Re
6: MAG (cartesian) - Re
7: SPH (geo in spherical) - (radial distance, lati, longi - Re, deg., deg.)
8: RLL (radial distance, lati, longi - Re, deg., deg. - prefered to 7)

iyear: array(100000) of long integer year when measurements are given

idoy: array(100000) of long integer doy when measurements are given

UT: array(100000) of double, UT in seconds

x1: array(100000) of double, first coordinate according to sysaxes. If sysaxes is 0 then altitude has to be in km otherwise use dimensionless variables (in Re)

x2: array(100000) of double, second coordinate according to sysaxes. If sysaxes is 0 then latitude has to be in degrees otherwise use dimensionless variables (in Re)

x3: array(100000) of double, third coordinate according to sysaxes. If sysaxes is 0 then longitude has to be in degrees otherwise use dimensionless variables (in Re).

maginput: array (25,100000) of double to specify magnetic fields inputs such as:

1. maginput(1st element,*) =Kp: value of Kp as in OMNI2 files but has to be double instead of integer type
2. maginput(2nd element,*) =Dst: Dst index (nT)
3. maginput(3rd element,*) =dens: Solar Wind density (cm-3)
4. maginput(4th element,*) =velo: Solar Wind velocity (km/s)
5. maginput(5th element,*) =Pdyn: Solar Wind dynamic pressure (nPa)
6. maginput(6th element,*) =ByIMF: GSM y component of IMF mag. field (nT)
7. maginput(7th element,*) =BzIMF: GSM z component of IMF mag. field (nT)
8. maginput(8th element,*) =G1: G1=< Vsw*(Bperp/40)^2/(1+Bperp/40)*sin^3(theta/2) > where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Bperp is the transverse IMF component (GSM) and theta it's clock angle.
9. maginput(9th element,*) =G2: G2=< a*Vsw*Bs > where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0, a=0.005.
10. maginput(10th element,*) =G3: G3=< Vsw*Dsw*Bs /2000.>
    where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Dsw is the solar wind density, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0.
11. maginput(11th element,*) to maginput(25th element,*): for future use

IMPORTANT: all inputs must be present. For those which are not used a dummy value can be provided.

### OUTPUTS:

Lm: L McIlwain (array(100000) of double)
Lstar: L Roederer (array(100000) of double)
Blocal: magnitude of magnetic field at s/c (array(100000) of double) - nT
Bmin: magnitude of magnetic field at equator (array(100000) of double) - nT
XJ: I, related to second adiabatic invariant (array(100000) of double)
MLT: magnetic local time in hours, (array(100000) of double) - hour
Below is provided an chart explaining the logic for the coding of Lm and Lstar from the routine:

###

### CALLING SEQUENCE FROM IDL:

result = call_external(lib_name, 'make_lstar_', ntime,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,mlt, /f_value)

### CALLING SEQUENCE FROM FORTRAN:

call make_lstar1(ntime,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,mlt)

TOP
------------------------------------------------------------

## MAKE_LSTAR_SHELL_SPLITTING

### DESCRIPTION:

This function allows one to compute the magnetic coordinates at any s/c position and pitch-angle, i.e. L, L*, Blocal, Bequator ...
The internal magnetic field model is set to IGRF where parameters are can be computed for the month of June of the year or at any user defined frequency. The external magnetic field model can be selected (see inputs).

### INPUTS:

ntime: long integer number of time in arrays (max allowed is 100000)

Npa: long integer number of pitch-angle in array alpha (max allowed is 25)

kext: long integer to select external magnetic field

0 = no external field
1 = Mead & Fairfield [1975] (uses 0≤Kp≤9 - Valid for rGEO≤17. Re)
2 = Tsyganengo short [1987] (uses 0≤Kp≤9 - Valid for rGEO≤30. Re)
3 = Tsyganengo long [1987] (uses 0≤Kp≤9 - Valid for rGEO≤70. Re)
4 = Tsyganenko [1989c] (uses 0≤Kp≤9 - Valid for rGEO≤70. Re)
5 = Olson & Pfitzer quiet [1977] (default - Valid for rGEO≤15. Re)
6 = Olson & Pfitzer dynamic [1988] (uses 5.≤dens≤50., 300.≤velo≤500., -100.≤Dst≤20. - Valid for rGEO≤60. Re)
7 = Tsyganenko [1996] (uses -100.≤Dst (nT)≤20., 0.5≤Pdyn (nPa)≤10., |ByIMF| (nT)≤10., |BzIMF| (nT)≤10. - Valid for rGEO≤40. Re)
8 = Ostapenko & Maltsev [1997] (uses dst,Pdyn,BzIMF, Kp)
9 = Tsyganenko [2001] (uses -50.≤Dst (nT)≤20., 0.5≤Pdyn (nPa)≤5., |ByIMF| (nT)≤5., |BzIMF| (nT)≤5., 0.≤G1≤10., 0.≤G2≤10. - Valid for xGSM≥-15. Re)
10 =Tsyganenko [2001] storm (uses Dst, Pdyn, ByIMF, BzIMF, G2, G3 - there is no upper or lower limit for those inputs - Valid for xGSM≥-15. Re)
Notes:

1. when the magnetic field model inputs are outside the allowed range bad data values are returned.
2. When solar wind inputs are required they must be taken in the vicinity of the day side magnetopause and not at L1.

options: array(5) of long integer to set some control options on computed values

1. options(1st element): 0 - don't compute L*; 1 - compute L*
2. options(2nd element): 0 - initialize IGRF field once per year (year.5); n - n is the frequency (in days) starting on January 1st of each year (i.e. if options(2nd element)=15 then IGRF will be updated on the following days of the year: 1, 15, 30, 45 ...)
3. options(3rd element): resolution to compute L* (0 to 9) where 0 is the recomended value to ensure a good ratio precision/computation time (i.e. an error of ~2% at L=6). The higher the value the better will be the precision, the longer will be the computing time. Generally there is not much improvement for values larger than 4.
4. options(4th element): for future use
5. options(5th element): for future use

sysaxes: long integer to define which coordinate system is provided in

0: GDZ (alti, lati, longi - km,deg.,deg)
1: GEO (cartesian) - Re
2: GSM (cartesian) - Re
3: GSE (cartesian) - Re
4: SM (cartesian) - Re
5: GEI (cartesian) - Re
6: MAG (cartesian) - Re
7: SPH (geo in spherical) - (radial distance, lati, longi - Re, deg., deg.)
8: RLL (radial distance, lati, longi - Re, deg., deg. - prefered than 7)

iyear: array(100000) of long integer year when measurements are given

idoy: array(100000) of long integer doy when measurements are given

UT: array(100000) of double, UT in seconds

x1: array(100000) of double, first coordinate according to sysaxes. If sysaxes is 0 then altitude has to be in km otherwise use dimensionless variables (in Re)

x2: array(100000) of double, second coordinate according to sysaxes. If sysaxes is 0 then latitude has to be in degrees otherwise use dimensionless variables (in Re)

x3: array(100000) of double, third coordinate according to sysaxes. If sysaxes is 0 then longitude has to be in degrees otherwise use dimensionless variables (in Re).

alpha: array(25) of double, pitch-angle at input location (in degres).

maginput: array (25,100000) of double to specify magnetic fields inputs such as:

1. maginput(1st element,*) =Kp: value of Kp as in OMNI2 files but has to be double instead of integer type
2. maginput(2nd element,*) =Dst: Dst index (nT)
3. maginput(3rd element,*) =dens: Solar Wind density (cm-3)
4. maginput(4th element,*) =velo: Solar Wind velocity (km/s)
5. maginput(5th element,*) =Pdyn: Solar Wind dynamic pressure (nPa)
6. maginput(6th element,*) =ByIMF: GSM y component of IMF mag. field (nT)
7. maginput(7th element,*) =BzIMF: GSM z component of IMF mag. field (nT)
8. maginput(8th element,*) =G1: G1=< Vsw*(Bperp/40)^2/(1+Bperp/40)*sin^3(theta/2) > where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Bperp is the transverse IMF component (GSM) and theta it's clock angle.
9. maginput(9th element,*) =G2: G2=< a*Vsw*Bs > where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0, a=0.005.
10. maginput(10th element,*) =G3: G3=< Vsw*Dsw*Bs /2000.>
    where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Dsw is the solar wind density, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0.
11. maginput(11th element,*) to maginput(25th element,*): for future use

IMPORTANT: all inputs must be present. For those which are not used a dummy value can be provided.

### OUTPUTS:

Lm: L McIlwain (array(100000,25) of double)
Lstar: L Roederer (array(100000,25) of double)
Blocal: magnitude of magnetic field at mirror point (array(100000,25) of double) - nT
Bmin: magnitude of magnetic field at equator (array(100000) of double) - nT
XJ: I, related to second adiabatic invariant (array(100000,25) of double)
MLT: magnetic local time in hours, (array(100000) of double) - hour
IMPORTANT: When using a non dipole field Lm is pitch-angle dependent because of the McIlwain L definition which has some limitation but this dependency has nothing to do with shell-splitting!
Below is provided an chart explaining the logic for the coding of Lm and Lstar from the routine:

### CALLING SEQUENCE FROM IDL:

result = call_external(lib_name, 'make_lstar_shell_splitting_', ntime,Npa,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,alpha,maginput,lm,lstar,blocal,bmin,xj,mlt, /f_value)

### CALLING SEQUENCE FROM FORTRAN:

call make_lstar1(ntime,Npa,kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, alpha,maginput,lm,lstar,blocal,bmin,xj,mlt)

TOP
------------------------------------------------------------

## DRIFT_SHELL

### DESCRIPTION:

This function traces a full drift shell for particles that have their mirror point at the input location. The output is a full array of positions of the drift shell, usefull for plotting and visualisation.
The internal magnetic field model is set to IGRF where the expansion parameters can be computed for the month of June of the year or at any user defined frequency. The external magnetic field model can be changed (see inputs).

### INPUTS:

kext: long integer to select external magnetic field

0 = no external field
1 = Mead & Fairfield [1975] (uses 0≤Kp≤9 - Valid for rGEO≤17. Re)
2 = Tsyganengo short [1987] (uses 0≤Kp≤9 - Valid for rGEO≤30. Re)
3 = Tsyganengo long [1987] (uses 0≤Kp≤9 - Valid for rGEO≤70. Re)
4 = Tsyganenko [1989c] (uses 0≤Kp≤9 - Valid for rGEO≤70. Re)
5 = Olson & Pfitzer quiet [1977] (default - Valid for rGEO≤15. Re)
6 = Olson & Pfitzer dynamic [1988] (uses 5.≤dens≤50., 300.≤velo≤500., -100.≤Dst≤20. - Valid for rGEO≤60. Re)
7 = Tsyganenko [1996] (uses -100.≤Dst (nT)≤20., 0.5≤Pdyn (nPa)≤10., |ByIMF| (nT)≤10., |BzIMF| (nT)≤10. - Valid for rGEO≤40. Re)
8 = Ostapenko & Maltsev [1997] (uses dst,Pdyn,BzIMF, Kp)
9 = Tsyganenko [2001] (uses -50.≤Dst (nT)≤20., 0.5≤Pdyn (nPa)≤5., |ByIMF| (nT)≤5., |BzIMF| (nT)≤5., 0.≤G1≤10., 0.≤G2≤10. - Valid for xGSM≥-15. Re)
10 =Tsyganenko [2001] storm (uses Dst, Pdyn, ByIMF, BzIMF, G2, G3 - there is no upper or lower limit for those inputs - Valid for xGSM≥-15. Re)
Notes:

1. when the magnetic field model inputs are outside the allowed range bad data values are returned.
2. When solar wind inputs are required they must be taken in the vicinity of the day side magnetopause and not at L1.

options: array(5) of long integer to set some control options on computed values

1. options(1st element): 0 - don't compute L*; 1 - compute L*
2. options(2nd element): 0 - initialize IGRF field once per year (year.5); n - n is the frequency (in days) starting on January 1st of each year (i.e. if options(2nd element)=15 then IGRF will be updated on the following days of the year: 1, 15, 30, 45 ...)
3. options(3rd element): resolution to compute L* (0 to 9) where 0 is the recomended value to ensure a good ratio precision/computation time (i.e. an error of ~2% at L=6). The higher the value the better will be the precision, the longer will be the computing time. Generally there is not much improvement for values larger than 4.
4. options(4th element): for future use
5. options(5th element): for future use

sysaxes: long integer to define which coordinate system is provided in

0: GDZ (alti, lati, longi - km,deg.,deg)
1: GEO (cartesian) - Re
2: GSM (cartesian) - Re
3: GSE (cartesian) - Re
4: SM (cartesian) - Re
5: GEI (cartesian) - Re
6: MAG (cartesian) - Re
7: SPH (geo in spherical) - (radial distance, lati, longi - Re, deg., deg.)
8: RLL (radial distance, lati, longi - Re, deg., deg. - prefered than 7)

iyear: long integer year when measurement is given

idoy: long integer doy when measurement is given

UT: double, UT in seconds

x1: double, first coordinate according to sysaxes. If sysaxes is 0 then altitude has to be in km otherwise use dimentionless variables (in Re)

x2: double, second coordinate according to sysaxes. If sysaxes is 0 then latitude has to be in degre otherwise use dimentionless variables (in Re)

x3: double, third coordinate according to sysaxes. If sysaxes is 0 then longitude has to be in degre otherwise use dimentionless variables (in Re).

maginput: array (25) of double to specify magnetic fields inputs such as:

1. maginput(1st element) =Kp: value of Kp as in OMNI2 files but has to be double instead of integer type
2. maginput(2nd element) =Dst: Dst index (nT)
3. maginput(3rd element) =dens: Solar Wind density (cm-3)
4. maginput(4th element) =velo: Solar Wind velocity (km/s)
5. maginput(5th element) =Pdyn: Solar Wind dynamic pressure (nPa)
6. maginput(6th element) =ByIMF: GSM y component of IMF mag. field (nT)
7. maginput(7th element) =BzIMF: GSM z component of IMF mag. field (nT)
8. maginput(8th element) =G1: G1=< Vsw*(Bperp/40)^2/(1+Bperp/40)*sin^3(theta/2) > where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Bperp is the transverse IMF component (GSM) and theta it's clock angle.
9. maginput(9th element) =G2: G2=< a*Vsw*Bs > where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0, a=0.005.
10. maginput(10th element) =G3: G3=< Vsw*Dsw*Bs /2000.>
    where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Dsw is the solar wind density, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0.
11. maginput(11th element) to maginput(25th element): for future use

<>
IMPORTANT: all inputs must be present. For those which are not used a dummy value can be provided.

### OUTPUTS:

Lm: L McIlwain (double)
Lstar: L Roederer (double)
Blocal: magnitude of magnetic field at each drift shell point - see posit (array(1000,48) of double)
Bmin: magnitude of magnetic field at equator (double)
XJ: I, related to second adiabatic invariant (double)
POSIT: xGEO,yGEO and zGEO along the drift shell, (array(3,1000,48) of double)
1st element: x, y, z GEO coord, 2nd element: points along field line, 3rd element: number of field lines.
Nposit: long integer array (48) providing the number of points along the field line for each field line traced in 2nd element of POSIT array (max 1000).

Note: Posit is organized as follow: array(xyz,along bounce,drift index). Nposit tells how many of the 1000 points available are used to described one bounce.

Below is provided an chart explaining the logic for the coding of Lm and Lstar from the routine:

### CALLING SEQUENCE FROM IDL:

result = call_external(lib_name, 'drift_shell_', kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,posit,Nposit, /f_value)

### CALLING SEQUENCE FROM FORTRAN:

call drift_shell1(kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput, lm,lstar,blocal,bmin,xj,posit,Nposit)

TOP
------------------------------------------------------------

## FIND_MIRROR_POINT

### DESCRIPTION:

This function finds the magnitude and location of the mirror point along a field line traced from any given location and local pitch-angle.
The internal magnetic field model is set to IGRF where parameters are can be computed for the month of june of the year or at any user defined frequency. The external magnetic field model can be changed (see inputs).

### INPUTS:

kext: long integer to select external magnetic field

0 = no external field
1 = Mead & Fairfield [1975] (uses 0≤Kp≤9 - Valid for rGEO≤17. Re)
2 = Tsyganengo short [1987] (uses 0≤Kp≤9 - Valid for rGEO≤30. Re)
3 = Tsyganengo long [1987] (uses 0≤Kp≤9 - Valid for rGEO≤70. Re)
4 = Tsyganenko [1989c] (uses 0≤Kp≤9 - Valid for rGEO≤70. Re)
5 = Olson & Pfitzer quiet [1977] (default - Valid for rGEO≤15. Re)
6 = Olson & Pfitzer dynamic [1988] (uses 5.≤dens≤50., 300.≤velo≤500., -100.≤Dst≤20. - Valid for rGEO≤60. Re)
7 = Tsyganenko [1996] (uses -100.≤Dst (nT)≤20., 0.5≤Pdyn (nPa)≤10., |ByIMF| (nT)≤10., |BzIMF| (nT)≤10. - Valid for rGEO≤40. Re)
8 = Ostapenko & Maltsev [1997] (uses dst,Pdyn,BzIMF, Kp)
9 = Tsyganenko [2001] (uses -50.≤Dst (nT)≤20., 0.5≤Pdyn (nPa)≤5., |ByIMF| (nT)≤5., |BzIMF| (nT)≤5., 0.≤G1≤10., 0.≤G2≤10. - Valid for xGSM≥-15. Re)
10 =Tsyganenko [2001] storm (uses Dst, Pdyn, ByIMF, BzIMF, G2, G3 - there is no upper or lower limit for those inputs - Valid for xGSM≥-15. Re)
Notes:

1. when the magnetic field model inputs are outside the allowed range bad data values are returned.
2. When solar wind inputs are required they must be taken in the vicinity of the day side magnetopause and not at L1.

options: array(5) of long integer to set some control options on computed values

1. options(1st element): not used
2. options(2nd element): 0 - initialize IGRF field once per year (year.5); n - n is the frequency (in days) starting on January 1st of each year (i.e. if options(2nd element)=15 then IGRF will be updated on the following days of the year: 1, 15, 30, 45 ...)
3. options(3rd element): not used
4. options(4th element): for future use
5. options(5th element): for future use

sysaxes: long integer to define which coordinate system is provided in

0: GDZ (alti, lati, longi - km,deg.,deg)
1: GEO (cartesian) - Re
2: GSM (cartesian) - Re
3: GSE (cartesian) - Re
4: SM (cartesian) - Re
5: GEI (cartesian) - Re
6: MAG (cartesian) - Re
7: SPH (geo in spherical) - (radial distance, lati, longi - Re, deg., deg.)
8: RLL (radial distance, lati, longi - Re, deg., deg. - prefered than 7)

iyear: long integer year when measurement is given

idoy: long integer doy when measurement is given

UT: double, UT in seconds

x1: double, first coordinate according to sysaxes. If sysaxes is 0 then altitude has to be in km otherwise use dimentionless variables (in Re)

x2: double, second coordinate according to sysaxes. If sysaxes is 0 then latitude has to be in degre otherwise use dimentionless variables (in Re)

x3: double, third coordinate according to sysaxes. If sysaxes is 0 then longitude has to be in degre otherwise use dimentionless variables (in Re).

alpha: double, particle pitch-angle in degres at input location.

maginput: array (25) of double to specify magnetic fields inputs such as:

1. maginput(1st element) =Kp: value of Kp as in OMNI2 files but has to be double instead of integer type
2. maginput(2nd element) =Dst: Dst index (nT)
3. maginput(3rd element) =dens: Solar Wind density (cm-3)
4. maginput(4th element) =velo: Solar Wind velocity (km/s)
5. maginput(5th element) =Pdyn: Solar Wind dynamic pressure (nPa)
6. maginput(6th element) =ByIMF: GSM y component of IMF mag. field (nT)
7. maginput(7th element) =BzIMF: GSM z component of IMF mag. field (nT)
8. maginput(8th element) =G1: G1=< Vsw*(Bperp/40)^2/(1+Bperp/40)*sin^3(theta/2) > where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Bperp is the transverse IMF component (GSM) and theta it's clock angle.
9. maginput(9th element) =G2: G2=< a*Vsw*Bs > where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0, a=0.005.
10. maginput(10th element) =G3: G3=< Vsw*Dsw*Bs /2000.>
    where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Dsw is the solar wind density, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0.
11. maginput(11th element) to maginput(25th element): for future use

IMPORTANT: all inputs must be present. For those which are not used a dummy value can be provided.

### OUTPUTS:

Blocal: magnitude of magnetic field at input location - nT (double)
Bmir: magnitude of magnetic field at mirror point - nT (double)
POSIT: xGEO,yGEO and zGEO at mirror point in Re, (array(3) of double)

### CALLING SEQUENCE FROM IDL:

result = call_external(lib_name, 'find_mirror_point_', kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,alpha,maginput, blocal,bmir,posit, /f_value)

### CALLING SEQUENCE FROM FORTRAN:

call find_mirror_point1(kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3,alpha, maginput,blocal,bmir,posit)

TOP
------------------------------------------------------------

## FIND_MAGEQUATOR

### DESCRIPTION:

This function finds the GEO coordinates of the magnetic equator along the field line starting from input location.
The internal magnetic field model is set to IGRF where parameters are can be computed for the month of june of the year or at any user defined frequency. The external magnetic field model can be changed (see inputs).

### INPUTS:

kext: long integer to select external magnetic field

0 = no external field
1 = Mead & Fairfield [1975] (uses 0≤Kp≤9 - Valid for rGEO≤17. Re)
2 = Tsyganengo short [1987] (uses 0≤Kp≤9 - Valid for rGEO≤30. Re)
3 = Tsyganengo long [1987] (uses 0≤Kp≤9 - Valid for rGEO≤70. Re)
4 = Tsyganenko [1989c] (uses 0≤Kp≤9 - Valid for rGEO≤70. Re)
5 = Olson & Pfitzer quiet [1977] (default - Valid for rGEO≤15. Re)
6 = Olson & Pfitzer dynamic [1988] (uses 5.≤dens≤50., 300.≤velo≤500., -100.≤Dst≤20. - Valid for rGEO≤60. Re)
7 = Tsyganenko [1996] (uses -100.≤Dst (nT)≤20., 0.5≤Pdyn (nPa)≤10., |ByIMF| (nT)≤10., |BzIMF| (nT)≤10. - Valid for rGEO≤40. Re)
8 = Ostapenko & Maltsev [1997] (uses dst,Pdyn,BzIMF, Kp)
9 = Tsyganenko [2001] (uses -50.≤Dst (nT)≤20., 0.5≤Pdyn (nPa)≤5., |ByIMF| (nT)≤5., |BzIMF| (nT)≤5., 0.≤G1≤10., 0.≤G2≤10. - Valid for xGSM≥-15. Re)
10 =Tsyganenko [2001] storm (uses Dst, Pdyn, ByIMF, BzIMF, G2, G3 - there is no upper or lower limit for those inputs - Valid for xGSM≥-15. Re)
Notes:

1. when the magnetic field model inputs are outside the allowed range bad data values are returned.
2. When solar wind inputs are required they must be taken in the vicinity of the day side magnetopause and not at L1.

options: array(5) of long integer to set some control options on computed values

1. options(1st element): not used
2. options(2nd element): 0 - initialize IGRF field once per year (year.5); n - n is the frequency (in days) starting on January 1st of each year (i.e. if options(2nd element)=15 then IGRF will be updated on the following days of the year: 1, 15, 30, 45 ...)
3. options(3rd element): not used
4. options(4th element): for future use
5. options(5th element): for future use

sysaxes: long integer to define which coordinate system is provided in

0: GDZ (alti, lati, longi - km,deg.,deg)
1: GEO (cartesian) - Re
2: GSM (cartesian) - Re
3: GSE (cartesian) - Re
4: SM (cartesian) - Re
5: GEI (cartesian) - Re
6: MAG (cartesian) - Re
7: SPH (geo in spherical) - (radial distance, lati, longi - Re, deg., deg.)
8: RLL (radial distance, lati, longi - Re, deg., deg. - prefered than 7)

iyear: long integer year when measurement is given

idoy: long integer doy when measurement is given

UT: double, UT in seconds

x1: double, first coordinate according to sysaxes. If sysaxes is 0 then altitude has to be in km otherwise use dimentionless variables (in Re)

x2: double, second coordinate according to sysaxes. If sysaxes is 0 then latitude has to be in degre otherwise use dimentionless variables (in Re)

x3: double, third coordinate according to sysaxes. If sysaxes is 0 then longitude has to be in degre otherwise use dimentionless variables (in Re).

maginput: array (25) of double to specify magnetic fields inputs such as:

1. maginput(1st element) =Kp: value of Kp as in OMNI2 files but has to be double instead of integer type
2. maginput(2nd element) =Dst: Dst index (nT)
3. maginput(3rd element) =dens: Solar Wind density (cm-3)
4. maginput(4th element) =velo: Solar Wind velocity (km/s)
5. maginput(5th element) =Pdyn: Solar Wind dynamic pressure (nPa)
6. maginput(6th element) =ByIMF: GSM y component of IMF mag. field (nT)
7. maginput(7th element) =BzIMF: GSM z component of IMF mag. field (nT)
8. maginput(8th element) =G1: G1=< Vsw*(Bperp/40)^2/(1+Bperp/40)*sin^3(theta/2) > where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Bperp is the transverse IMF component (GSM) and theta it's clock angle.
9. maginput(9th element) =G2: G2=< a*Vsw*Bs > where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0, a=0.005.
10. maginput(10th element) =G3: G3=< Vsw*Dsw*Bs /2000.>
    where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Dsw is the solar wind density, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0.
11. maginput(11th element) to maginput(25th element): for future use

IMPORTANT: all inputs must be present. For those which are not used a dummy value can be provided.

### OUTPUTS:

Bmin: magnitude of magnetic field at equator (double)

POSIT: xGEO,yGEO and zGEO of the magnetic equator location, (array(3) of double)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'find_magequator_', kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput, bmin,posit, /f_value)

### CALLING SEQUENCE from FORTRAN:

call find_magequator1(kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput,bmin,posit)

TOP
------------------------------------------------------------

## GET_FIELD

### DESCRIPTION:

This function computes the GEO vector of the magnetic field at input location.
The internal magnetic field model is set to IGRF where parameters are can be computed for the month of june of the year or at any user defined frequency. The external magnetic field model can be changed (see inputs).

### INPUTS:

kext: long integer to select external magnetic field

0 = no external field
1 = Mead & Fairfield [1975] (uses 0≤Kp≤9 - Valid for rGEO≤17. Re)
2 = Tsyganengo short [1987] (uses 0≤Kp≤9 - Valid for rGEO≤30. Re)
3 = Tsyganengo long [1987] (uses 0≤Kp≤9 - Valid for rGEO≤70. Re)
4 = Tsyganenko [1989c] (uses 0≤Kp≤9 - Valid for rGEO≤70. Re)
5 = Olson & Pfitzer quiet [1977] (default - Valid for rGEO≤15. Re)
6 = Olson & Pfitzer dynamic [1988] (uses 5.≤dens≤50., 300.≤velo≤500., -100.≤Dst≤20. - Valid for rGEO≤60. Re)
7 = Tsyganenko [1996] (uses -100.≤Dst (nT)≤20., 0.5≤Pdyn (nPa)≤10., |ByIMF| (nT)≤10., |BzIMF| (nT)≤10. - Valid for rGEO≤40. Re)
8 = Ostapenko & Maltsev [1997] (uses dst,Pdyn,BzIMF, Kp)
9 = Tsyganenko [2001] (uses -50.≤Dst (nT)≤20., 0.5≤Pdyn (nPa)≤5., |ByIMF| (nT)≤5., |BzIMF| (nT)≤5., 0.≤G1≤10., 0.≤G2≤10. - Valid for xGSM≥-15. Re)
10 =Tsyganenko [2001] storm (uses Dst, Pdyn, ByIMF, BzIMF, G2, G3 - there is no upper or lower limit for those inputs - Valid for xGSM≥-15. Re)
Notes:

1. when the magnetic field model inputs are outside the allowed range bad data values are returned.
2. When solar wind inputs are required they must be taken in the vicinity of the day side magnetopause and not at L1.

options: array(5) of long integer to set some control options on computed values

1. options(1st element): not used
2. options(2nd element): parameter to initialize IGRF field in June of the year (year.5) if set to 0 or at the day of year corresponding to the closest lower or equal day of year for a frequency of update equal to this parameter (in days) starting on January 1st of each years (i.e. if options(2nd element)=15 then IGRF will be initialize to theclosest lower or equal day of year between those:1, 15, 30, 45 ...)
3. options(3rd element): for future use
4. options(4th element): for future use
5. options(5th element): for future use

sysaxes: long integer to define which coordinate system is provided in

0: GDZ (alti, lati, longi - km,deg.,deg)
1: GEO (cartesian) - Re
2: GSM (cartesian) - Re
3: GSE (cartesian) - Re
4: SM (cartesian) - Re
5: GEI (cartesian) - Re
6: MAG (cartesian) - Re
7: SPH (geo in spherical) - (radial distance, lati, longi - Re, deg., deg.)
8: RLL (radial distance, lati, longi - Re, deg., deg. - prefered than 7)

iyear: long integer year when measurement is given

idoy: long integer doy when measurement is given

UT: double, UT in seconds

x1: double, first coordinate according to sysaxes. If sysaxes is 0 then altitude has to be in km otherwise use dimentionless variables (in Re)

x2: double, second coordinate according to sysaxes. If sysaxes is 0 then latitude has to be in degre otherwise use dimentionless variables (in Re)

x3: double, third coordinate according to sysaxes. If sysaxes is 0 then longitude has to be in degre otherwise use dimentionless variables (in Re).

maginput: array (25) of double to specify magnetic fields inputs such as:

1. maginput(1st element) =Kp: value of Kp as in OMNI2 files but has to be double instead of integer type
2. maginput(2nd element) =Dst: Dst index (nT)
3. maginput(3rd element) =dens: Solar Wind density (cm-3)
4. maginput(4th element) =velo: Solar Wind velocity (km/s)
5. maginput(5th element) =Pdyn: Solar Wind dynamic pressure (nPa)
6. maginput(6th element) =ByIMF: GSM y component of IMF mag. field (nT)
7. maginput(7th element) =BzIMF: GSM z component of IMF mag. field (nT)
8. maginput(8th element) =G1: G1=< Vsw*(Bperp/40)^2/(1+Bperp/40)*sin^3(theta/2) > where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Bperp is the transverse IMF component (GSM) and theta it's clock angle.
9. maginput(9th element) =G2: G2=< a*Vsw*Bs > where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0, a=0.005.
10. maginput(10th element) =G3: G3=< Vsw*Dsw*Bs /2000.>
    where the <> mean an average over the previous 1 hour, Vsw is the solar wind speed, Dsw is the solar wind density, Bs=|IMF Bz| when IMF Bz < 0 and Bs=0 when IMF Bz > 0.
11. maginput(11th element) to maginput(25th element): for future use

IMPORTANT: all inputs must be present. For those which are not used a dummy value can be provided.

### OUTPUTS:

Bgeo: BxGEO,ByGEO and BzGEO of the magnetic field (nT), (array(3) of double)
Bl: magnitude of magnetic field (double) (nT)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'get_field_', kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput,Bgeo, Bl, /f_value)

### CALLING SEQUENCE from FORTRAN:

call GET_FIELD1(kext,options,sysaxes,iyear,idoy,ut, x1,x2,x3, maginput,Bgeo,Bl)

TOP
---------------------------------------------------------------------------------------

## GEO2GSM

### DESCRIPTION:

Routine to transform Cartesian GEO to cartesian GSM coordinates

### INPUTS:

iyr : long integer year
idoy : long integer day of year
secs : UT in seconds - double
xGEO : 3D array (double) of cartesian position in GEO (Re)

### OUTPUTS:

psi : angle for GSM coordinate - double xGSM : 3D array (double) of cartesian position in GSM (Re)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'geo2gsm_', iyr,idoy,secs,psi,xGEO,xGSM, /f_value)

### CALLING SEQUENCE from FORTRAN:

call geo2gsm1(iyr,idoy,secs,psi,xGEO,xGSM)

TOP
---------------------------------------------------------------------------------------

## GSM2GEO

### DESCRIPTION:

Routine to transform Cartesian GSM to cartesian GEO coordinates

### INPUTS:

iyr : long integer year
idoy : long integer day of year
secs : UT in seconds - double
xGSM : 3D array (double) of cartesian position in GSM (Re)

### OUTPUTS:

psi : angle for GSM coordinate - double
xGEO : 3D array (double) of cartesian position in GEO (Re)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'gsm2geo_', iyr,idoy,secs,psi,xGSM,xGEO, /f_value)

### CALLING SEQUENCE from FORTRAN:

call gsm2geo1(iyr,idoy,secs,psi,xGSM,xGEO)

TOP
---------------------------------------------------------------------------------------

## GEO2GSE

### DESCRIPTION:

Routine to transform Cartesian GEO to cartesian GSM coordinates

### INPUTS:

iyr : long integer year
idoy : long integer day of year
secs : UT in seconds - double
xGEO : 3D array (double) of cartesian position in GEO (Re)

### OUTPUTS:

xGSE : 3D array (double) of cartesian position in GSE (Re)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'geo2gse_', iyr,idoy,secs,xGEO,xGSE, /f_value)

### CALLING SEQUENCE from FORTRAN:

call geo2gse1(iyr,idoy,secs,xGEO,xGSE)

TOP
---------------------------------------------------------------------------------------

## GSE2GEO

### DESCRIPTION:

Routine to transform Cartesian GSE to cartesian GEO coordinates

### INPUTS:

iyr : long integer year
idoy : long integer day of year
secs : UT in seconds - double
xGSE : 3D array (double) of cartesian position in GSE (Re)

### OUTPUTS:

xGEO : 3D array (double) of cartesian position in GEO (Re)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'gse2geo_', iyr,idoy,secs,xGSE,xGEO, /f_value)

### CALLING SEQUENCE from FORTRAN:

call gse2geo1(iyr,idoy,secs,xGSE,xGEO)

TOP
---------------------------------------------------------------------------------------

## GDZ2GEO

### DESCRIPTION:

Routine to transform GEODEZIC coordinates to cartesian GEO coordinates

### INPUTS:

lati : latitude (degres) (double)
longi : longitude (degres) (double)
alti : altitude (km) (double)

### OUTPUTS:

xx : xGEO (Re) (double)
yy : yGEO (Re) (double)
zz : zGEO (Re) (double)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'gdz2geo_', lati,longi,alti,xx,yy,zz, /f_value)

### CALLING SEQUENCE from FORTRAN:

call gdz2geo(lati,longi,alti,xx,yy,zz)

TOP
---------------------------------------------------------------------------------------

## GEO2GDZ

### DESCRIPTION:

Routine to transform cartesian GEO coordinates to GEODEZIC coordinates

### INPUTS:

xx : xGEO (Re) (double)
yy : yGEO (Re) (double)
zz : zGEO (Re) (double)

### OUTPUTS:

lati : latitude (degres) (double)
longi : longitude (degres) (double)
alti : altitude (km) (double)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'geo2gdz_', xx,yy,zz,lati,longi,alti, /f_value)

### CALLING SEQUENCE from FORTRAN:

call geo2gdz(xx,yy,zz,lati,longi,alti)

TOP
---------------------------------------------------------------------------------------

## GEO2GEI

### DESCRIPTION:

Routine to transform Cartesian GEO to cartesian GEI coordinates

### INPUTS:

iyr : long integer year
idoy : long integer day of year
secs : UT in seconds -double
xGEO : 3D array (double) of cartesian position in GEO (Re)

### OUTPUTS:

xGEI: 3D array (double) of cartesian position in GEI (Re)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'geo2gei_', iyr,idoy,secs,xGEO,xGEI, /f_value)

### CALLING SEQUENCE from FORTRAN:

call geo2gei1(iyr,idoy,secs,xGEO,xGEI)

TOP
---------------------------------------------------------------------------------------

## GEI2GEO

### DESCRIPTION:

Routine to transform Cartesian GEI to cartesian GEO coordinates

### INPUTS:

iyr : long integer year
idoy : long integer day of year
secs : UT in seconds - double
xGEI : 3D array (double) of cartesian position in GEI (Re)

### OUTPUTS:

xGEO: 3D array (double) of cartesian position in GEO (Re)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'gei2geo_', iyr,idoy,secs,xGEI,xGEO, /f_value)

### CALLING SEQUENCE from FORTRAN:

call gei2geo1(iyr,idoy,secs,xGEI,xGEO)

TOP
---------------------------------------------------------------------------------------

## GEO2SM

### DESCRIPTION:

Routine to transform Cartesian GEO to cartesian SM coordinates

### INPUTS:

iyr : long integer year
idoy : long integer day of year
secs : UT in seconds - double
xGEO : 3D array (double) of cartesian position in GEO (Re)

### OUTPUTS:

xSM: 3D array (double) of cartesian position in SM (Re)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'geo2sm_', iyr,idoy,secs,xGEO,xSM, /f_value)

### CALLING SEQUENCE from FORTRAN:

call geo2sm1(iyr,idoy,secs,xGEO,xSM)

TOP
---------------------------------------------------------------------------------------

## SM2GEO

### DESCRIPTION:

Routine to transform Cartesian SM to cartesian GEO coordinates

### INPUTS:

iyr : long integer year
idoy : long integer day of year
secs : UT in seconds - double
xSM : 3D array (double) of cartesian position in SM (Re)

### OUTPUTS:

xGEO: 3D array (double) of cartesian position in GEO (Re)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'sm2geo_', iyr,idoy,secs,xSM,xGEO, /f_value)

### CALLING SEQUENCE from FORTRAN:

call sm2geo1(iyr,idoy,secs,xSM,xGEO)

TOP
---------------------------------------------------------------------------------------

## GSM2SM

### DESCRIPTION:

Routine to transform Cartesian GSM to cartesian SM coordinates

### INPUTS:

iyr : long integer year
idoy : long integer day of year
secs : UT in seconds - double
xGSM : 3D array (double) of cartesian position in GSM (Re)

### OUTPUTS:

xSM: 3D array (double) of cartesian position in SM (Re)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'gsm2sm_', iyr,idoy,secs,xGSM,xSM, /f_value)

### CALLING SEQUENCE from FORTRAN:

call gsm2sm1(iyr,idoy,secs,xGSM,xSM)

TOP
---------------------------------------------------------------------------------------

## SM2GSM

### DESCRIPTION:

Routine to transform Cartesian SM to cartesian GSM coordinates

### INPUTS:

iyr : long integer year
idoy : long integer day of year
secs : UT in seconds - double
xSM : 3D array (double) of cartesian position in SM (Re)

### OUTPUTS:

xGSM: 3D array (double) of cartesian position in GSM (Re)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'sm2gsm_', iyr,idoy,secs,xSM,xGSM, /f_value)

### CALLING SEQUENCE from FORTRAN:

call sm2gsm1(iyr,idoy,secs,xSM,xGSM)

TOP
---------------------------------------------------------------------------------------

## GEO2MAG

### DESCRIPTION:

Routine to transform Cartesian GEO to cartesian MAG coordinates

### INPUTS:

iyr : long integer year
xGEO : 3D array (double) of cartesian position in GEO (Re)

### OUTPUTS:

xMAG: 3D array (double) of cartesian position in MAG (Re)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'geo2mag_', iyr,xGEO,xMAG, /f_value)

### CALLING SEQUENCE from FORTRAN:

call geo2mag1(iyr,xGEO,xMAG)

TOP
---------------------------------------------------------------------------------------

## MAG2GEO

### DESCRIPTION:

Routine to transform Cartesian MAG to cartesian GEO coordinates

### INPUTS:

iyr : long integer year
xMAG : 3D array (double) of cartesian position in MAG (Re)

### OUTPUTS:

xGEO: 3D array (double) of cartesian position in GEO (Re)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'mag2geo_', iyr,xMAG,xGEO, /f_value)

### CALLING SEQUENCE from FORTRAN:

call mag2geo1(iyr,xMAG,xGEO)

TOP
---------------------------------------------------------------------------------------

## SPH2CAR

### DESCRIPTION:

Routine to transform spherical coordinates to cartesian

### INPUTS:

r : radial distance (double)
lati: (degree)
longi: (degree)

### OUTPUTS:

x: 3D array (double) of cartesian position (same unit as r)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'sph2car_', r,lati,longi,x, /f_value)

### CALLING SEQUENCE from FORTRAN:

call SPH_CAR(r,lati,longi,x)

TOP
---------------------------------------------------------------------------------------

## CAR2SPH

### DESCRIPTION:

Routine to transform cartesian coordinates to spherical

### INPUTS:

x : 3D array (double) of cartesian position

### OUTPUTS:

r : radial distance (double) - same unit as x
lati : (degree)
longi : (degree)

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'car2sph_', x,r,lati,longi, /f_value)

### CALLING SEQUENCE from FORTRAN:

call CAR_SPH(x,r,lati,longi)

TOP

---------------------------------------------------------------------------------------

## RLL2GDZ

### DESCRIPTION:

Routine to transform radial distance, latitude, longitude to altitude, latitude, longitude

### INPUTS:

r : radial distance (double) - Re
lati : (double- degree)
longi : (double- degree)

### OUTPUTS:

alti : altitude (double) - km

### CALLING SEQUENCE from IDL:

result = call_external(lib_name, 'rll2gdz_', r,lati,longi,alti, /f_value)

### CALLING SEQUENCE from FORTRAN:

call RLL_GDZ(r,lati,longi,alti) TOP

---------------------------------------------------------------------------------------

## JULDAY

### DESCRIPTION:

Calculate the Julian Day Number for a given month, day, and year.

### INPUTS:

MONTH: Number of the desired month (1 = January, ..., 12 = December). - long

DAY: Number of day of the month. - long

YEAR: Number of the desired year.Year parameters must be valid values from the civil calendar. Years B.C.E. are represented as negative integers. Years in the common era are represented as positive integers. In particular, note that there is no year 0 in the civil calendar. 1 B.C.E. (-1) is followed by 1 C.E. (1). - long

### OUTPUTS:

JULDAY returns the Julian Day Number (which begins at noon) of the specified calendar date. - long

### CALLING SEQUENCE from IDL:

Not available

### CALLING SEQUENCE from FORTRAN:

Result = JULDAY(Year,Month, Day)

TOP
---------------------------------------------------------------------------------------

## CALDAT

### DESCRIPTION:

Return the calendar date given julian day. This is the inverse of the function JULDAY.

### INPUTS:

JULIAN contains the Julian Day Number (which begins at noon) of the specified calendar date. It should be a long integer.

### OUTPUTS:

MONTH: Number of the desired month (1 = January, ..., 12 = December). - long

DAY: Number of day of the month. - long

YEAR: Number of the desired year. - long

### CALLING SEQUENCE from IDL:

Not available

### CALLING SEQUENCE from FORTRAN:

CALL CALDAT(julian, year,month, day)

TOP
---------------------------------------------------------------------------------------

## GET_DOY

### DESCRIPTION:

Calculate the day of year for a given month, day, and year.

### INPUTS:

MONTH: Number of the desired month (1 = January, ..., 12 = December).

DAY: Number of day of the month.

YEAR: Number of the desired year.Year parameters must be valid values from the civil calendar. Years B.C.E. are represented as negative integers. Years in the common era are represented as positive integers. In particular, note that there is no year 0 in the civil calendar. 1 B.C.E. (-1) is followed by 1 C.E. (1).

### OUTPUTS:

GET_DOY returns the day of year of the specified calendar date.

### CALLING SEQUENCE from IDL:

Not available

### CALLING SEQUENCE from FORTRAN:

Result = GET_DOY(Year,Month, Day)

TOP
---------------------------------------------------------------------------------------

## DECY2DATE_AND_TIME

### DESRIPTION:

Calculate the date and time (yeay,month,day of month, day of year, hour, minute and second and Universal Time)

### INPUTS:

DEC_Y : Decimal year where yyyy.0d0 is January 1st at 00:00:00 - double

### OUTPUTS:

YEAR: Number year.Year parameters must be valid values from the civil calendar. Years B.C.E. are represented as negative integers. Years in the common era are represented as positive integers. In particular, note that there is no year 0 in the civil calendar. 1 B.C.E. (-1) is followed by 1 C.E. (1). - long

MONTH: Number month (1 = January, ..., 12 = December). - long

DAY: Number of day of the month. - long

DOY: Number of day of year (DOY=1 is for January 1st) - long

HOUR, MINUTE and SECOND: Universal time in the day - long

UT: Univeral time in seconds - double

### CALLING SEQUENCE from IDL:

Not available

### CALLING SEQUENCE from FORTRAN:

CALL DECY2DATE_AND_TIME(Dec_y,Year,Month, Day, doy, hour,minute,second)

TOP