Multiple file access functions
The following group of functions should be the preferred method to access to the library. They allow to access to multiple ephemeris files at the same time, even by multiple threads.
When an error occurs, these functions execute error handlers according to the behavior defined by the function calceph_seterrorhandler().
Time notes
The functions calceph_compute(), calceph_compute_unit(), calceph_compute_order(), calceph_orient_unit(), ... only accept a date expressed in the same timescale as the ephemeris files, which can be retrieved using the function calceph_gettimescale(). Ephemeris files are generally expressed using the timescale TDB.
If a date, expressed in the TT (Terrestrial Time) timescale, is supplied to them, these functions will return an erroneous position of the order of several tens of meters for the planets.
If a date, expressed in the Coordinated Universal Time (UTC), is supplied to them, these functions will return a very large erroneous position over several thousand kilometers for the planets.
Thread notes
If the standard I/O functions such as fread are not reentrant then the CALCEPH I/O functions using them will not be reentrant either.
It's safe for two threads to call the functions with the same object of type t_calcephbin if and only if the function calceph_isthreadsafe() returns a non-zero value. A previous call to the function calceph_prefetch() is required for the function calceph_isthreadsafe() to return a non-zero value.
It's safe for two threads to access simultaneously to the same ephemeris file with two different objects of type t_calcephbin. In this case, each thread must open the same file.
Usage
The following examples, that can be found in the directory examples of the library sources, show the typical usage of this group of functions.
The example in C language is cmultiple.c.
Functions
calceph_rotangmom_unit
-
int calceph_rotangmom_unit(t_calcephbin *eph, double JD0, double time, int target, int unit, double PV[6])
- Parameters:
eph -- ephemeris descriptor
JD0 -- Integer part of the Julian date (TDB or TCB)
time -- Fraction part of the Julian date (TDB or TCB)
target -- The body whose orientations are requested. The numbering system depends on the parameter unit.
unit --
The units of PV.This integer is a sum of some unit constants (CALCEPH_UNIT_???) and/or the constantCALCEPH_USE_NAIFID.If the unit containsCALCEPH_USE_NAIFID, the NAIF identification numbering system is used for the target (NAIF identification numbers for the list).If the unit does not containCALCEPH_USE_NAIFID, the old number system is used for the target (see the list in the functioncalceph_compute()).PV -- An array to receive the angular momentum due to its rotation, divided by the product of the mass and of the square of the radius, and the derivatives, of the body.
- Returns:
0 if an error occurs, otherwise non-zero value.
This function reads, if needed, in the ephemeris file associated to eph and interpolates the angular momentum vector due to the rotation of the body, divided by the product of the mass 
and of the square of the radius 
, of a single body (target) for the time JD0+time and stores the results to PV. The ephemeris file associated to eph must have been previously opened with the function calceph_open(). The angular momentum 
, due to the rotation of the body, is defined as the product of the inertia matrix 
by the angular velocity vector 
. So the returned value is 
The date (JD0, time) should be expressed in the same timescale as the ephemeris files, which can be retrieved using the function calceph_gettimescale().
The output values are expressed in the units specified by unit.
This function checks the units if invalid combinations of units are given to the function.
The values stored in the array PV are expressed in the following units
The angular momentum and its derivative are expressed in days if unit contains
CALCEPH_UNIT_DAY.The angular momentum and its derivative are expressed in seconds if unit contains
CALCEPH_UNIT_SEC.
The following example prints the angular momentum, due to its rotation, for the Earth at time=2451419.5
int j;
double jd0=2451419;
double dt1=0.5E0;
t_calcephbin *peph;
double G[6];
/* open the ephemeris file */
peph = calceph_open("example2_rotangmom.dat");
if (peph)
{
calceph_prefetch(peph);
calceph_rotangmom_unit(peph, jd0, dt1, NAIFID_EARTH,
CALCEPH_USE_NAIFID+CALCEPH_UNIT_SEC,
G);
for(j=0; j<6; j++) printf("%23.16E\n", G[j]);
/* close the ephemeris file */
calceph_close(peph);
}
calceph_rotangmom_order
-
int calceph_rotangmom_order(t_calcephbin *eph, double JD0, double time, int target, int unit, int order, double *PVAJ)
- Parameters:
eph -- ephemeris descriptor
JD0 -- Integer part of the Julian date (TDB or TCB)
time -- Fraction part of the Julian date (TDB or TCB)
target -- The body whose orientations are requested. The numbering system depends on the parameter unit.
unit --
The units of PV.This integer is a sum of some unit constants (CALCEPH_UNIT_???) and/or the constantCALCEPH_USE_NAIFID.If the unit containsCALCEPH_USE_NAIFID, the NAIF identification numbering system is used for the target (NAIF identification numbers for the list).If the unit does not containCALCEPH_USE_NAIFID, the old number system is used for the target (see the list in the functioncalceph_compute()).order --
The order of derivatives.
= 0 , only the angular momentum is computed. The first three numbers of PVAJ are valid for the results.
= 1 , only the angular momentum and the first derivative are computed. The first six numbers of PVAJ are valid for the results.
= 2 , only the angular momentum and the first and second derivatives are computed. The first nine numbers of PVAJ are valid for the results.
= 3 , the angular momentum and the first, second and third derivatives are computed. The first twelve numbers of PVAJ are valid for the results.
If order equals to 1, the behavior of
calceph_rotangmom_order()is the same ascalceph_rotangmom_unit().PVAJ -- An array to receive the angular momentum due to its rotation, divided by the product of the mass and of the square of the radius, and their different order of the derivatives, of the body.
- Returns:
0 if an error occurs, otherwise non-zero value.
This function is similar to the function calceph_orient_unit(), except that the order of the computed derivatives is specified.
This function reads, if needed, in the ephemeris file associated to eph and interpolates the angular momentum vector due to the rotation of the body, divided by the product of the mass and of the square of the radius , of a single body (target) for the time JD0+time and stores the results to PVAJ. The angular momentum , due to the rotation of the body, is defined as the product of the inertia matrix by the angular velocity vector . So the returned value is
The order of the derivatives are specified by order. The ephemeris file associated to eph must have been previously opened with the function calceph_open().
The output values are expressed in the units specified by unit.
This function checks the units if invalid combinations of units are given to the function.
The returned array PVAJ must be large enough to store the results. The size of this array must be equal to 3*(order+1).
PVAJ[0..2] contain the angular momentum and is always valid.
PVAJ[3..5] contain the first derivative and is only valid if order is greater or equal to 1.
PVAJ[6..8] contain the second derivative and is only valid if order is greater or equal to 2.
PVAJ[9..11] contain the third derivative and is only valid if order is equal to 3.
The values stored in the array PVAJ are expressed in the following units
The angular momentum and its derivatives are expressed in days if unit contains
CALCEPH_UNIT_DAY.The angular momentum and its derivatives are expressed in seconds if unit contains
CALCEPH_UNIT_SEC.
The date (JD0, time) should be expressed in the same timescale as the ephemeris files, which can be retrieved using the function calceph_gettimescale().
The following example prints only the angular momentum, due to its rotation, of the Earth at time=2451419.5
int j;
double jd0=2451419;
double dt1=0.5E0;
t_calcephbin *peph;
double G[3];
/* open the ephemeris file */
peph = calceph_open("example2_rotangmom.dat");
if (peph)
{
calceph_prefetch(peph);
calceph_rotangmom_order(peph, jd0, dt1, NAIFID_EARTH,
CALCEPH_USE_NAIFID+CALCEPH_UNIT_SEC,
0,
G);
for(j=0; j<3; j++) printf("%23.16E\n", G[j]);
/* close the ephemeris file */
calceph_close(peph);
}