ONERA-DESP library - user's guide


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


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

The package includes a sript to compile the library under a linux system. You might have to change it to 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:

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 rGEO17. Re)
2   = Tsyganengo short [1987] (uses 0≤Kp≤9 - Valid for rGEO30. Re)
3   = Tsyganengo long [1987] (uses 0≤Kp≤9 - Valid for rGEO70. Re)
4   = Tsyganenko [1989c] (uses 0≤Kp≤9 - Valid for rGEO70. Re)
5   = Olson & Pfitzer quiet [1977] (default - Valid for rGEO15. Re)
6   = Olson & Pfitzer dynamic [1988] (uses 5.dens≤50., 300.velo500., -100.Dst≤20. - Valid for rGEO60. Re)
7   = Tsyganenko [1996] (uses -100.Dst (nT)≤20., 0.5≤Pdyn (nPa)≤10., |ByIMF| (nT)10., |BzIMF| (nT)10. - Valid for rGEO40. 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.G110., 0.G210. - Valid for xGSM-15. Re)
10 =Tsyganenko [2001] storm  (uses Dst, Pdyn, ByIMF, BzIMF, G2, G3 - there is no upper or lower limit for those inputs - Valid for xGSM-15. Re)

Notes:

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


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

  1. options(1st element):  parameter to not compute L* if set to 0 or compute L* otherwise
  2. 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 ...)
  3. options(3rd element): for future use
  4. options(4th element): for future use
  5. options(5th element): for future use

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

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

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:

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

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

OUTPUTS:

Lm: L McIlwain (array(100000) of double)
Lstar: L Roederer (array(100000) of double)
Blocal: magnitude of magnetic field at s/c (array(100000) of double) - nT
Bmin: magnitude of magnetic field at equator (array(100000) of double) - nT
XJ: I, related to second adiabatic invariant (array(100000) of double)
MLT: magnetic local time in hours, (array(100000) of double) - hour


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

 


CALLING SEQUENCE FROM IDL:

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

CALLING SEQUENCE FROM FORTRAN:

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

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

MAKE_LSTAR_SHELL_SPLITTING

DESCRIPTION:

This function allows one to compute 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 rGEO17. Re)
2   = Tsyganengo short [1987] (uses 0≤Kp≤9 - Valid for rGEO30. Re)
3   = Tsyganengo long [1987] (uses 0≤Kp≤9 - Valid for rGEO70. Re)
4   = Tsyganenko [1989c] (uses 0≤Kp≤9 - Valid for rGEO70. Re)
5   = Olson & Pfitzer quiet [1977] (default - Valid for rGEO15. Re)
6   = Olson & Pfitzer dynamic [1988] (uses 5.dens≤50., 300.velo500., -100.Dst≤20. - Valid for rGEO60. Re)
7   = Tsyganenko [1996] (uses -100.Dst (nT)≤20., 0.5≤Pdyn (nPa)≤10., |ByIMF| (nT)10., |BzIMF| (nT)10. - Valid for rGEO40. 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.G110., 0.G210. - Valid for xGSM-15. Re)
10 =Tsyganenko [2001] storm  (uses Dst, Pdyn, ByIMF, BzIMF, G2, G3 - there is no upper or lower limit for those inputs - Valid for xGSM-15. Re)

Notes:

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


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

  1. options(1st element):  parameter to not compute L* if set to 0 or compute L* otherwise
  2. 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 ...)
  3. options(3rd element): for future use
  4. options(4th element): for future use
  5. options(5th element): for future use

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

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

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:

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


 

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

OUTPUTS:

Lm: L McIlwain (array(100000) of double)
Lstar: L Roederer (array(100000,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
 

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 rGEO17. Re)
2   = Tsyganengo short [1987] (uses 0≤Kp≤9 - Valid for rGEO30. Re)
3   = Tsyganengo long [1987] (uses 0≤Kp≤9 - Valid for rGEO70. Re)
4   = Tsyganenko [1989c] (uses 0≤Kp≤9 - Valid for rGEO70. Re)
5   = Olson & Pfitzer quiet [1977] (default - Valid for rGEO15. Re)
6   = Olson & Pfitzer dynamic [1988] (uses 5.dens≤50., 300.velo500., -100.Dst≤20. - Valid for rGEO60. Re)
7   = Tsyganenko [1996] (uses -100.Dst (nT)≤20., 0.5≤Pdyn (nPa)≤10., |ByIMF| (nT)10., |BzIMF| (nT)10. - Valid for rGEO40. 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.G110., 0.G210. - Valid for xGSM-15. Re)
10 =Tsyganenko [2001] storm  (uses Dst, Pdyn, ByIMF, BzIMF, G2, G3 - there is no upper or lower limit for those inputs - Valid for xGSM-15. Re)

Notes:

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


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

  1. options(1st element):  parameter to not compute L* if set to 0 or compute L* otherwise
  2. 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 ...)
  3. options(3rd element): for future use
  4. options(4th element): for future use
  5. options(5th element): for future use

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

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

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:

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


 

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

OUTPUTS:

Lm: L McIlwain (double)
Lstar: L Roederer (double)
Blocal: magnitude of magnetic field at each drift shell point - see posit (array(1000,48) of double)
Bmin: magnitude of magnetic field at equator (double)
XJ: I, related to second adiabatic invariant (double)
POSIT: xGEO,yGEO and zGEO along the drift shell, (array(3,1000,48) of double)
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 rGEO17. Re)
2   = Tsyganengo short [1987] (uses 0≤Kp≤9 - Valid for rGEO30. Re)
3   = Tsyganengo long [1987] (uses 0≤Kp≤9 - Valid for rGEO70. Re)
4   = Tsyganenko [1989c] (uses 0≤Kp≤9 - Valid for rGEO70. Re)
5   = Olson & Pfitzer quiet [1977] (default - Valid for rGEO15. Re)
6   = Olson & Pfitzer dynamic [1988] (uses 5.dens≤50., 300.velo500., -100.Dst≤20. - Valid for rGEO60. Re)
7   = Tsyganenko [1996] (uses -100.Dst (nT)≤20., 0.5≤Pdyn (nPa)≤10., |ByIMF| (nT)10., |BzIMF| (nT)10. - Valid for rGEO40. 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.G110., 0.G210. - Valid for xGSM-15. Re)
10 =Tsyganenko [2001] storm  (uses Dst, Pdyn, ByIMF, BzIMF, G2, G3 - there is no upper or lower limit for those inputs - Valid for xGSM-15. Re)

Notes:

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


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

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

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

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

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:

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


 

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

OUTPUTS:

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

CALLING SEQUENCE FROM IDL:

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

CALLING SEQUENCE FROM FORTRAN:

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

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

FIND_MAGEQUATOR

DESCRIPTION:

This function 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 rGEO17. Re)
2   = Tsyganengo short [1987] (uses 0≤Kp≤9 - Valid for rGEO30. Re)
3   = Tsyganengo long [1987] (uses 0≤Kp≤9 - Valid for rGEO70. Re)
4   = Tsyganenko [1989c] (uses 0≤Kp≤9 - Valid for rGEO70. Re)
5   = Olson & Pfitzer quiet [1977] (default - Valid for rGEO15. Re)
6   = Olson & Pfitzer dynamic [1988] (uses 5.dens≤50., 300.velo500., -100.Dst≤20. - Valid for rGEO60. Re)
7   = Tsyganenko [1996] (uses -100.Dst (nT)≤20., 0.5≤Pdyn (nPa)≤10., |ByIMF| (nT)10., |BzIMF| (nT)10. - Valid for rGEO40. 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.G110., 0.G210. - Valid for xGSM-15. Re)
10 =Tsyganenko [2001] storm  (uses Dst, Pdyn, ByIMF, BzIMF, G2, G3 - there is no upper or lower limit for those inputs - Valid for xGSM-15. Re)

Notes:

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


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

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

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

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

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:

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


 

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

OUTPUTS:

Bmin: magnitude of magnetic field at equator (double)

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

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

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

GET_FIELD

DESCRIPTION:

This function 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 rGEO17. Re)
2   = Tsyganengo short [1987] (uses 0≤Kp≤9 - Valid for rGEO30. Re)
3   = Tsyganengo long [1987] (uses 0≤Kp≤9 - Valid for rGEO70. Re)
4   = Tsyganenko [1989c] (uses 0≤Kp≤9 - Valid for rGEO70. Re)
5   = Olson & Pfitzer quiet [1977] (default - Valid for rGEO15. Re)
6   = Olson & Pfitzer dynamic [1988] (uses 5.dens≤50., 300.velo500., -100.Dst≤20. - Valid for rGEO60. Re)
7   = Tsyganenko [1996] (uses -100.Dst (nT)≤20., 0.5≤Pdyn (nPa)≤10., |ByIMF| (nT)10., |BzIMF| (nT)10. - Valid for rGEO40. 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.G110., 0.G210. - Valid for xGSM-15. Re)
10 =Tsyganenko [2001] storm  (uses Dst, Pdyn, ByIMF, BzIMF, G2, G3 - there is no upper or lower limit for those inputs - Valid for xGSM-15. Re)

Notes:

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


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

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

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

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

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:

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


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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

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

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

GEO2GSM

DESCRIPTION:

Routine to transform Cartesian GEO to cartesian GSM coordinates
 

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

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

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

GSM2GEO

DESCRIPTION:

Routine to transform Cartesian GSM to cartesian GEO coordinates

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

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

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

GEO2GSE

DESCRIPTION:

Routine to transform Cartesian GEO to cartesian GSM coordinates

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

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

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

GSE2GEO

DESCRIPTION:

Routine to transform Cartesian GSE to cartesian GEO coordinates
 

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

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

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

GDZ2GEO

DESCRIPTION:

Routine to transform GEODEZIC coordinates to cartesian GEO coordinates
 

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

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

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

GEO2GDZ

DESCRIPTION:

Routine to transform cartesian GEO coordinates to GEODEZIC coordinates
 

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

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

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

GEO2GEI

DESCRIPTION:

Routine to transform Cartesian GEO to cartesian GEI coordinates
 

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

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

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

GEI2GEO

DESCRIPTION:

Routine to transform Cartesian GEI to cartesian GEO coordinates
 

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

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

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

GEO2SM

DESCRIPTION:

Routine to transform Cartesian GEO to cartesian SM coordinates
 

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

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

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

SM2GEO

DESCRIPTION:

Routine to transform Cartesian SM to cartesian GEO coordinates
 

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

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

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

GSM2SM

DESCRIPTION:

Routine to transform Cartesian GSM to cartesian SM coordinates
 

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

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

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

SM2GSM

DESCRIPTION:

Routine to transform Cartesian SM to cartesian GSM coordinates
 

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

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

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

GEO2MAG

DESCRIPTION:

Routine to transform Cartesian GEO to cartesian MAG coordinates
 

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

call geo2mag1(iyr,xGEO,xMAG)

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

MAG2GEO

DESCRIPTION:

Routine to transform Cartesian MAG to cartesian GEO coordinates
 

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

call mag2geo1(iyr,xMAG,xGEO)

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

SPH2CAR

DESCRIPTION:

Routine to transform spherical coordinates to cartesian
 

INPUTS:

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

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

call SPH_CAR(r,lati,longi,x)

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

CAR2SPH

DESCRIPTION:

Routine to transform cartesian coordinates to spherical
 

INPUTS:

x : 3D array (double) of cartesian position
 

OUTPUTS:

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

CALLING SEQUENCE from IDL:

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

CALLING SEQUENCE from FORTRAN:

call CAR_SPH(x,r,lati,longi)

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

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