ONERA-DESP
library - user's guide
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:
- when
the magnetic field model inputs are outside the allowed range bad data
values are returned.
- 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
- options(1st element):
0 - don't compute L*; 1 - compute L*
- 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 ...)
- 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.
- options(4th element): for
future use
- 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:
- maginput(1st element,*) =Kp: value
of Kp as in OMNI2 files but has to be double instead of integer type
- maginput(2nd element,*) =Dst: Dst
index (nT)
- maginput(3rd element,*) =dens: Solar Wind density (cm-3)
- maginput(4th element,*) =velo: Solar Wind velocity (km/s)
- maginput(5th element,*) =Pdyn: Solar Wind dynamic pressure (nPa)
- maginput(6th element,*) =ByIMF: GSM y component of IMF mag.
field (nT)
- maginput(7th element,*) =BzIMF: GSM z component of IMF mag.
field (nT)
- 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.
- 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.
- 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.
- 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:
- when
the magnetic field model inputs are outside the allowed range bad data
values are returned.
- 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
- options(1st element):
0 - don't compute L*; 1 - compute L*
- 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 ...)
- 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.
- options(4th element): for
future use
- 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:
- maginput(1st element,*) =Kp: value
of Kp as in OMNI2 files but has to be double instead of integer type
- maginput(2nd element,*) =Dst: Dst
index (nT)
- maginput(3rd element,*) =dens: Solar Wind density (cm-3)
- maginput(4th element,*) =velo: Solar Wind velocity (km/s)
- maginput(5th element,*) =Pdyn: Solar Wind dynamic pressure (nPa)
- maginput(6th element,*) =ByIMF: GSM y component of IMF mag.
field (nT)
- maginput(7th element,*) =BzIMF: GSM z component of IMF mag.
field (nT)
- 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.
- 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.
- 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.
- 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:
- when
the magnetic field model inputs are outside the allowed range bad data
values are returned.
- 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
- options(1st element):
0 - don't compute L*; 1 - compute L*
- 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 ...)
- 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.
- options(4th element): for
future use
- 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:
- maginput(1st element) =Kp: value
of Kp as in OMNI2 files but has to be double instead of integer type
- maginput(2nd element) =Dst: Dst
index (nT)
- maginput(3rd element) =dens: Solar Wind density (cm-3)
- maginput(4th element) =velo: Solar Wind velocity (km/s)
- maginput(5th element) =Pdyn: Solar Wind dynamic pressure (nPa)
- maginput(6th element) =ByIMF: GSM y component of IMF mag.
field (nT)
- maginput(7th element) =BzIMF: GSM z component of IMF mag.
field (nT)
- 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.
- 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.
- 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.
- 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:
- when
the magnetic field model inputs are outside the allowed range bad data
values are returned.
- 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
- options(1st element):
not used
- 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 ...)
- options(3rd element): not
used
- options(4th element): for
future use
- 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:
- maginput(1st element) =Kp: value
of Kp as in OMNI2 files but has to be double instead of integer type
- maginput(2nd element) =Dst: Dst
index (nT)
- maginput(3rd element) =dens: Solar Wind density (cm-3)
- maginput(4th element) =velo: Solar Wind velocity (km/s)
- maginput(5th element) =Pdyn: Solar Wind dynamic pressure (nPa)
- maginput(6th element) =ByIMF: GSM y component of IMF mag.
field (nT)
- maginput(7th element) =BzIMF: GSM z component of IMF mag.
field (nT)
- 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.
- 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.
- 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.
- 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:
- when
the magnetic field model inputs are outside the allowed range bad data
values are returned.
- 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
- options(1st element):
not used
- 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 ...)
- options(3rd element): not
used
- options(4th element): for
future use
- 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:
- maginput(1st element) =Kp: value
of Kp as in OMNI2 files but has to be double instead of integer type
- maginput(2nd element) =Dst: Dst
index (nT)
- maginput(3rd element) =dens: Solar Wind density (cm-3)
- maginput(4th element) =velo: Solar Wind velocity (km/s)
- maginput(5th element) =Pdyn: Solar Wind dynamic pressure (nPa)
- maginput(6th element) =ByIMF: GSM y component of IMF mag.
field (nT)
- maginput(7th element) =BzIMF: GSM z component of IMF mag.
field (nT)
- 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.
- 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.
- 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.
- 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:
- when
the magnetic field model inputs are outside the allowed range bad data
values are returned.
- 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
- options(1st element):
not used
- 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 ...)
- options(3rd element): for
future use
- options(4th element): for
future use
- 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:
- maginput(1st element) =Kp: value
of Kp as in OMNI2 files but has to be double instead of integer type
- maginput(2nd element) =Dst: Dst
index (nT)
- maginput(3rd element) =dens: Solar Wind density (cm-3)
- maginput(4th element) =velo: Solar Wind velocity (km/s)
- maginput(5th element) =Pdyn: Solar Wind dynamic pressure (nPa)
- maginput(6th element) =ByIMF: GSM y component of IMF mag.
field (nT)
- maginput(7th element) =BzIMF: GSM z component of IMF mag.
field (nT)
- 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.
- 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.
- 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.
- 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