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 built the library on your system. Currently the library is compiled
using the portland group compiler (pgf77), and you may need some of
their
libraries to run it or using the 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 IDL and one for fortran or 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...
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.0, 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
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):
parameter to not compute
L* if set to 0 or compute L* otherwise
- options(2nd element): parameter
to initialize IGRF field one time per year (year.5) if set to 0 or at
the parameter frequency (in days) starting on January 1st of each years
(i.e. if options(2nd element)=15 then IGRF will be updated the
following days of year: 1, 15, 30, 45 ...)
- options(3rd element): parameter
to set the 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 1% at L=6). The highest is the value the better will be the
precision, the longer will be the computing time.
- 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.)
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 sysxes is 0 then altitude has to be
in km otherwise use dimensionless variables (in Re)
x2: array(100000) of double,
second
coordinate according to sysxes. If sysxes is 0 then latitude has to be
in degrees otherwise use dimensionless variables (in Re)
x3: array(100000) of double,
third
coordinate according to sysxes. If sysxes 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
magnetic
coordinate 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):
parameter to not compute
L* if set to 0 or compute L* otherwise
- options(2nd element): parameter
to initialize IGRF field one time per year (year.5) if set to 0 or at
the parameter frequency (in days) starting on January 1st of each years
(i.e. if options(2nd element)=15 then IGRF will be updated the
following days of year: 1, 15, 30, 45 ...)
- options(3rd element): parameter
to set the 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 1% at L=6). The highest is the value the better
will be the precision, the longer will be the computing time.
- 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.)
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 sysxes is 0 then altitude has to be
in km otherwise use dimensionless variables (in Re)
x2: array(100000) of double,
second
coordinate according to sysxes. If sysxes is 0 then latitude has to be
in degrees otherwise use dimensionless variables (in Re)
x3: array(100000) of double,
third
coordinate according to sysxes. If sysxes 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 see 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 allows to trace a drift
shell
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):
parameter to not compute
L* if set to 0 or compute L* otherwise
- options(2nd element): parameter
to initialize IGRF field one time per year (year.5) if set to 0 or at
the parameter frequency (in days) starting on January 1st of each years
(i.e. if options(2nd element)=15 then IGRF will be updated the
following days of year: 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.)
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 sysxes is 0 then altitude has to be in km otherwise use
dimentionless variables (in Re)
x2: double, second coordinate
according
to sysxes. If sysxes is 0 then latitude has to be in degre otherwise
use
dimentionless variables (in Re)
x3: double, third coordinate
according
to sysxes. If sysxes 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)
Nposit: long integer array (48)
providing the number of positon to be used in POSIT array
Note: Posit is organized as
follow:
array(xyz,along bounce,drift index). Nposit tells how many over 500
points
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 allows to find a the
magnitude
and location of mirror point for 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): 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 the
closest 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.)
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 sysxes is 0 then altitude has to be in km otherwise use
dimentionless variables (in Re)
x2: double, second coordinate
according
to sysxes. If sysxes is 0 then latitude has to be in degre otherwise
use
dimentionless variables (in Re)
x3: double, third coordinate
according
to sysxes. If sysxes 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 allows to find GEO
coordinate
of the magnetic equator along the field ligne 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): 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.)
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 sysxes is 0 then altitude has to be in km otherwise use
dimentionless variables (in Re)
x2: double, second coordinate
according
to sysxes. If sysxes is 0 then latitude has to be in degre otherwise
use
dimentionless variables (in Re)
x3: double, third coordinate
according
to sysxes. If sysxes 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 allows to compute 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.)
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 sysxes is 0 then altitude has to be in km otherwise use
dimentionless variables (in Re)
x2: double, second coordinate
according
to sysxes. If sysxes is 0 then latitude has to be in degre otherwise
use
dimentionless variables (in Re)
x3: double, third coordinate
according
to sysxes. If sysxes 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
---------------------------------------------------------------------------------------
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