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()
.
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 not safe for two threads to call the functions with the same object of type t_calcephbin
. But 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_open¶
-
t_calcephbin*
calceph_open
(const char *filename)¶ Parameters: - filename – pathname of the file
Returns: ephemeris descriptor. This value is NULL if an error occurs, otherwise non-NULL value.
This function opens the file whose pathname is the string pointed to by filename, reads the two header blocks of this file and returns an ephemeris descriptor associated to it. This file must be compliant to the format specified by the ‘original JPL binary’ , ‘INPOP 2.0 binary’ or ‘SPICE’ ephemeris file. At the moment, supported SPICE files are the following :
- text Planetary Constants Kernel (KPL/PCK) files
- binary PCK (DAF/PCK) files.
- binary SPK (DAF/SPK) files containing segments of type 1, 2, 3, 12, 13, 20, 102, 103 and 120.
- meta kernel (KPL/MK) files.
- frame kernel (KPL/FK) files. Only a basic support is provided.
Just after the call of calceph_open()
, the function calceph_prefetch()
should be called to accelerate future computations.
The function calceph_close()
must be called to free allocated memory by this function.
The following example opens the ephemeris file example1.dat and example2.dat
t_calcephbin *peph1;
t_calcephbin *peph2;
peph1 = calceph_open("example1.dat");
peph2 = calceph_open("example2.dat");
if (peph1 && peph2)
{
calceph_prefetch(peph1);
calceph_prefetch(peph2);
/*
... computation ...
*/
}
/* close the files */
if (peph1) calceph_close(peph1);
if (peph2) calceph_close(peph2);
calceph_open_array¶
-
t_calcephbin*
calceph_open_array
(int n, const char *array_filename[])¶ Parameters: - n – number of files
- array_filename – array of pathname of the files
Returns: ephemeris descriptor. This value is NULL if an error occurs, otherwise non-NULL value.
This function opens n files whose pathnames are the string pointed to by array_filename, reads the header blocks of these files and returns an ephemeris descriptor associated to them.
These files must have the same type (e.g., all files are SPICE files or original JPL files). This file must be compliant to the format specified by the ‘original JPL binary’ , ‘INPOP 2.0 or 3.0 binary’ or ‘SPICE’ ephemeris file. At the moment, supported SPICE files are the following :
- text Planetary Constants Kernel (KPL/PCK) files
- binary PCK (DAF/PCK) files.
- binary SPK (DAF/SPK) files containing segments of type 1, 2, 3, 12, 13, 20, 102, 103 and 120.
- meta kernel (KPL/MK) files.
- frame kernel (KPL/FK) files. Only a basic support is provided.
Just after the call of calceph_open_array()
, the function calceph_prefetch()
should be called to accelerate future computations.
The function calceph_close()
must be called to free allocated memory by this function.
The following example opens the ephemeris file example1.bsp and example1.tpc
const char *filear[2]= {"example1.bsp", "example1.tpc"};
t_calcephbin *peph;
peph = calceph_open_array(2,filear);
if (peph)
{
/* ... computation ...*/
calceph_close(peph);
}
calceph_prefetch¶
-
int
calceph_prefetch
(t_calcephbin* eph)¶ Parameters: - eph – ephemeris descriptor
Returns: 0 if an error occurs, otherwise non-zero value.
This function prefetches to the main memory all files associated to the ephemeris descriptor eph.
This prefetching operation will accelerate the further computations performed with calceph_compute()
, calceph_compute_unit()
, calceph_compute_order()
, calceph_orient_unit()
, … .
It requires that the file is smaller than the main memory. If multiple threads (e.g. threads of openMP or Posix Pthreads) prefetch the data for the same ephemeris file, the used memory will remain the same as if the prefetch operation was done by a single thread if and if the endianess of the file is the same as the computer and if the operating system, such as Linux, MacOS X other unix, supports the function mmap.
calceph_compute¶
-
int
calceph_compute
(t_calcephbin* eph, double JD0, double time, int target, int center, double PV[6])¶ Parameters: - eph – ephemeris descriptor
- JD0 – Integer part of the Julian date
- time – Fraction part of the Julian date
- target – The body or reference point whose coordinates are required (see the list, below).
- center – The origin of the coordinate system (see the list, below). If target is 15, 16 or 17 (libration, TT-TDB or TCG-TCB), center must be 0.
- PV – An array to receive the cartesian position (x,y,z) and the velocity (xdot, ydot, zdot).The position is expressed in Astronomical Unit (au) and the velocity is expressed in Astronomical Unit per day (au/day).If the target is TT-TDB, only the first element of this array will get the result. The time scale transformation TT-TDB is expressed in seconds.If the target is TCG-TCB, only the first element of this array will get the result. The time scale transformation TCG-TCB is expressed in seconds.If the target is Librations, the angles of the librations of the Moon are expressed in radians and their derivatives are expressed in radians per day.
Returns: 0 if an error occurs, otherwise non-zero value.
This function reads, if needed, in the ephemeris file associated to eph and interpolates a single object, usually the position and velocity of one body (target) relative to another (center) 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()
.
To get the best precision for the interpolation, the time is splitted in two floating-point numbers. The argument JD0 should be an integer and time should be a fraction of the day. But you may call this function with time=0 and JD0, the desired time, if you don’t take care about precision.
The possible values for target and center are :
value | meaning |
---|---|
1 | Mercury Barycenter |
2 | Venus Barycenter |
3 | Earth |
4 | Mars Barycenter |
5 | Jupiter Barycenter |
6 | Saturn Barycenter |
7 | Uranus Barycenter |
8 | Neptune Barycenter |
9 | Pluto Barycenter |
10 | Moon |
11 | Sun |
12 | Solar Sytem barycenter |
13 | Earth-moon barycenter |
15 | Librations |
16 | TT-TDB |
17 | TCG-TCB |
asteroid number + CALCEPH_ASTEROID | asteroid |
These accepted values by this function are the same as the value for the JPL function PLEPH, except for the values TT-TDB, TCG-TCB and asteroids.
For example, the value “CALCEPH_ASTEROID+4” for target or center specifies the asteroid Vesta.
The following example prints the heliocentric coordinates of Mars at time=2442457.5 and at 2442457.9
int res;
int j;
double jd0=2442457;
double dt1=0.5E0;
double dt2=0.9E0;
t_calcephbin *peph;
double PV[6];
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
/* the heliocentric coordinates of Mars */
calceph_compute(peph, jd0, dt1, 4, 11, PV);
for(j=0; j<6; j++) printf("%23.16E\n", PV[j]);
calceph_compute(peph, jd0, dt2, 4, 11, PV);
for(j=0; j<6; j++) printf("%23.16E\n", PV[j]);
/* close the ephemeris file */
calceph_close(peph);
}
calceph_compute_unit¶
-
int
calceph_compute_unit
(t_calcephbin* eph, double JD0, double time, int target, int center, int unit, double PV[6])¶ Parameters: - eph – ephemeris descriptor
- JD0 – Integer part of the Julian date
- time – Fraction part of the Julian date
- target – The body or reference point whose coordinates are required. The numbering system depends on the parameter unit.
- center – The origin of the coordinate system. 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 constant
CALCEPH_USE_NAIFID
.If the unit containsCALCEPH_USE_NAIFID
, the NAIF identification numbering system is used for the target and the center (NAIF identification numbers for the list).If the unit doesnot containCALCEPH_USE_NAIFID
, the old number system is used for the target and the center (see the list in the functioncalceph_compute()
). - PV – An array to receive the cartesian position (x,y,z) and the velocity (xdot, ydot, zdot).The position and velocity are expressed in Astronomical Unit (au) if unit contains
CALCEPH_UNIT_AU
.The position and velocity are expressed in kilometers if unit containsCALCEPH_UNIT_KM
.The velocity, TT-TDB, TCG-TCB or the derivatives of the angles of the librations of the Moon are expressed in days if unit containsCALCEPH_UNIT_DAY
.The velocity, TT-TDB, TCG-TCB or the derivatives of the angles of the librations of the Moon are expressed in seconds if unit containsCALCEPH_UNIT_SEC
.The angles of the librations of the Moon are expressed in radians if unit containsCALCEPH_UNIT_RAD
.For example, to get the position and velocities expressed in kilometers and kilometers/seconds, the unit must be set toCALCEPH_UNIT_KM
+CALCEPH_UNIT_SEC
.
Returns: 0 if an error occurs, otherwise non-zero value.
This function is similar to the function calceph_compute()
, except that the units of the output are specified.
This function reads, if needed, in the ephemeris file associated to eph and interpolates a single object, usually the position and velocity of one body (target) relative to another (center) 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 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 following example prints the heliocentric coordinates of Mars at time=2442457.5
int res;
int j;
double jd0=2442457;
double dt1=0.5E0;
t_calcephbin *peph;
double PV[6];
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
/* the heliocentric coordinates of Mars in km and km/s */
calceph_compute_unit(peph, jd0, dt1, 4, 11,
CALCEPH_UNIT_KM+CALCEPH_UNIT_SEC,
PV);
for(j=0; j<6; j++) printf("%23.16E\n", PV[j]);
/* compute same quantity as the previous call using NAIF ID */
calceph_compute_unit(peph, jd0, dt1,
NAIFID_MARS_BARYCENTER,
NAIFID_SUN,
CALCEPH_USE_NAIFID+CALCEPH_UNIT_KM
+CALCEPH_UNIT_SEC,
PV);
for(j=0; j<6; j++) printf("%23.16E\n", PV[j]);
/* the heliocentric coordinates of Mars in AU and AU/day */
calceph_compute_unit(peph, jd0, dt1, 4, 11,
CALCEPH_UNIT_AU+CALCEPH_UNIT_DAY,
PV);
for(j=0; j<6; j++) printf("%23.16E\n", PV[j]);
/* close the ephemeris file */
calceph_close(peph);
}
calceph_orient_unit¶
-
int
calceph_orient_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
- time – Fraction part of the Julian date
- 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 constant
CALCEPH_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 euler angles and their derivatives for the orientation of the body.The derivatives of the angles are expressed in days if unit contains
CALCEPH_UNIT_DAY
.The derivatives of the angles are expressed in seconds if unit containsCALCEPH_UNIT_SEC
.The angles of the librations of the Moon are expressed in radians if unit containsCALCEPH_UNIT_RAD
.
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 orientation 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 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 following example prints the angles of libration of the Moon at time=2442457.5
int res;
int j;
double jd0=2442457;
double dt1=0.5E0;
t_calcephbin *peph;
double PV[6];
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
calceph_prefetch(peph);
calceph_orient_unit(peph, jd0, dt1, NAIFID_MOON,
CALCEPH_USE_NAIFID+CALCEPH_UNIT_RAD
+CALCEPH_UNIT_SEC,
PV);
for(j=0; j<6; j++) printf("%23.16E\n", PV[j]);
/* close the ephemeris file */
calceph_close(peph);
}
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
- time – Fraction part of the Julian date
- 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 constant
CALCEPH_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.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 containsCALCEPH_UNIT_SEC
.
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 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 following example prints the angular momentum, due to its rotation, for the Earth at time=2451419.5
int res;
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_compute_order¶
-
int
calceph_compute_order
(t_calcephbin* eph, double JD0, double time, int target, int center, int unit, int order, double *PVAJ)¶ Parameters: - eph – ephemeris descriptor
- JD0 – Integer part of the Julian date
- time – Fraction part of the Julian date
- target – The body or reference point whose coordinates are required. The numbering system depends on the parameter unit.
- center – The origin of the coordinate system. 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 constant
CALCEPH_USE_NAIFID
.If the unit containsCALCEPH_USE_NAIFID
, the NAIF identification numbering system is used for the target and the center (NAIF identification numbers for the list).If the unit doesnot containCALCEPH_USE_NAIFID
, the old number system is used for the target and the center (see the list in the functioncalceph_compute()
). - order –
The order of derivatives
- = 0 , only the position is computed. The first three numbers of PVAJ are valid for the results.
- = 1 , only the position and velocity are computed. The first six numbers of PVAJ are valid for the results.
- = 2 , only the position, velocity and acceleration are computed. The first nine numbers of PVAJ are valid for the results.
- = 3 , the position, velocity and acceleration and jerk are computed. The first twelve numbers of PVAJ are valid for the results.
If order equals to 1, the behavior of
calceph_compute_order()
is the same ascalceph_compute_unit()
. - PVAJ – An array to receive the cartesian position (x,y,z) and the derivatives.This array must be large enough to store the results. For the C interface, the size of this array must be equal to 3*(order+1).- PVAJ[0..2] contain the position (x,y,z) and is always valid.- PVAJ[3..5] contain the velocity (dx/dt,dy/dt,dz/dt) and is only valid if order is greater or equal to 1.- PVAJ[6..8] contain the acceleration (d^2x/dt^2,d^2y/dt^2,d^2z/dt^2) and is only valid if order is greater or equal to 2.- PVAJ[9..11] contain the jerk (d^3x/dt^3,d^3y/dt^3,d^3z/dt^3) and is only valid if order is equal to 3.The position, velocity, acceleration and jerk are expressed in Astronomical Unit (au) if unit contains
CALCEPH_UNIT_AU
.The position, velocity, acceleration and jerk are expressed in kilometers if unit containsCALCEPH_UNIT_KM
.The velocity, acceleration, jerk, TT-TDB, TCG-TCB or the derivatives of the angles of the librations of the Moon are expressed in days if unit containsCALCEPH_UNIT_DAY
.The velocity, acceleration, jerk, TT-TDB, TCG-TCB or the derivatives of the angles of the librations of the Moon are expressed in seconds if unit containsCALCEPH_UNIT_SEC
.The angles of the librations of the Moon are expressed in radians if unit containsCALCEPH_UNIT_RAD
.For example, to get the positions, velocities, accelerations and jerks expressed in kilometers and kilometers/seconds, the unit must be set toCALCEPH_UNIT_KM
+CALCEPH_UNIT_SEC
.
Returns: 0 if an error occurs, otherwise non-zero value.
This function is similar to the function calceph_compute_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 a single object, usually the position and their derivatives of one body (target) relative to another (center) for the time JD0+time and stores the results to PVAJ. The ephemeris file associated to eph must have been previously opened with the function calceph_open()
.
The order of the derivatives are specified by order. 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 following example prints the heliocentric coordinates of Mars at time=2442457.5
int res;
int j;
double jd0=2442457;
double dt1=0.5E0;
t_calcephbin *peph;
double PVAJ[12];
double P[3];
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
/* compute only the heliocentric position of Mars in km */
calceph_compute_order(peph, jd0, dt1,
NAIFID_MARS_BARYCENTER,
NAIFID_SUN,
CALCEPH_USE_NAIFID+CALCEPH_UNIT_KM
+CALCEPH_UNIT_SEC,
0, P);
for(j=0; j<3; j++) printf("%23.16E\n", P[j]);
/* compute positions, velocities, accelerations and jerks
of Mars in km and seconds */
calceph_compute_order(peph, jd0, dt1,
NAIFID_MARS_BARYCENTER,
NAIFID_SUN,
CALCEPH_USE_NAIFID+CALCEPH_UNIT_KM
+CALCEPH_UNIT_SEC,
3, PVAJ);
for(j=0; j<12; j++) printf("%23.16E\n", PVAJ[j]);
/* close the ephemeris file */
calceph_close(peph);
}
calceph_orient_order¶
-
int
calceph_orient_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
- time – Fraction part of the Julian date
- 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 constant
CALCEPH_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 angles is computed. The first three numbers of PVAJ are valid for the results.
- = 1 , only the angles and the first derivative are computed. The first six numbers of PVAJ are valid for the results.
- = 2 , only the angles and the first and second derivatives are computed. The first nine numbers of PVAJ are valid for the results.
- = 3 , the angles 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_orient_order()
is the same ascalceph_orient_unit()
. - PVAJ – An array to receive the euler angles and their different order of the derivatives for the orientation of the body.This array 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 angles 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 derivatives of the angles are expressed in days if unit contains
CALCEPH_UNIT_DAY
.The derivatives of the angles are expressed in seconds if unit containsCALCEPH_UNIT_SEC
.The angles of the orientation are expressed in radians if unit containsCALCEPH_UNIT_RAD
.
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 orientation of a single body (target) for the time JD0+time and stores the results to PVAJ.
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 following example prints only the angles of libration of the Moon at time=2442457.5
int res;
int j;
double jd0=2442457;
double dt1=0.5E0;
t_calcephbin *peph;
double P[3];
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
calceph_prefetch(peph);
calceph_orient_order(peph, jd0, dt1, NAIFID_MOON,
CALCEPH_USE_NAIFID+CALCEPH_UNIT_RAD+CALCEPH_UNIT_SEC,
0,
P);
for(j=0; j<3; j++) printf("%23.16E\n", P[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
- time – Fraction part of the Julian date
- 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 constant
CALCEPH_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.This array 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 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 containsCALCEPH_UNIT_SEC
.
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 following example prints only the angular momentum, due to its rotation, of the Earth at time=2451419.5
int res;
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);
}
calceph_getconstant¶
-
int
calceph_getconstant
(t_calcephbin* eph, const char* name, double *value)¶ Parameters: - eph – ephemeris descriptor
- name – name of the constant
- value – first value of the constant
Returns: returns 0 if an error occurs, otherwise the number of values associated to the constant.
This function returns the value associated to the constant name in the header of the ephemeris file associated to eph. Only the first value is returned if multiple values are associated to a constant, such as a list of values.
This function is the same function as calceph_getconstantsd()
.
The following example prints the value of the astronomical unit stored in the ephemeris file
double AU;
t_calcephbin *peph;
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
/* print the value of AU */
if (calceph_getconstant(peph, "AU", &AU))
printf("AU=%23.16E\n", AU);
/* close the ephemeris file */
calceph_close(peph);
}
calceph_getconstantsd¶
-
int
calceph_getconstantsd
(t_calcephbin* eph, const char* name, double *value)¶ Parameters: - eph – ephemeris descriptor
- name – name of the constant
- value – first value of the constant
Returns: returns 0 if an error occurs, otherwise the number of values associated to the constant.
This function returns, as a floating-point number, the value associated to the constant name in the header of the ephemeris file associated to eph. Only the first value is returned if multiple values are associated to a constant, such as a list of values. The value must be a floating-point or integer number, otherwise an error is reported.
This function is the same function as calceph_getconstant()
.
The following example prints the value of the astronomical unit stored in the ephemeris file
double AU;
t_calcephbin *peph;
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
/* print the value of AU */
if (calceph_getconstantsd(peph, "AU", &AU))
printf("AU=%23.16E\n", AU);
/* close the ephemeris file */
calceph_close(peph);
}
calceph_getconstantvd¶
-
int
calceph_getconstantvd
(t_calcephbin* eph, const char* name, double *arrayvalue, int nvalue)¶ Parameters: - eph – ephemeris descriptor
- name – name of the constant
- arrayvalue – array of values for the constant
- nvalue – number of elements of the array
Returns: returns 0 if an error occurs, otherwise the number of values associated to the constant.
This function stores, to the array arrayvalue as floating-point numbers, the nvalue first values associated to the constant name in the header of the ephemeris file associated to eph. The integer value returned by the function is equal to the number of valid entries in the arrayvalue if nvalue is greater or equal to that integer value..
The required value nvalue to store all values can be determinated with this previous call calceph_getconstantvd(eph, name, NULL, 0).
The values must be floating-point or integer numbers, otherwise an error is reported.
The following example prints the body radii of the earth stored in the ephemeris file
int nvalue, k;
double *radii;
t_calcephbin *peph;
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
/* get the number of values */
int nvalue = calceph_getconstantvd(peph, "BODY399_RADII", NULL, 0);
radii = (double*)malloc(sizeof(double)*nvalue);
/* fill the array radii */
if (calceph_getconstantvd(peph, "BODY399_RADII", radii, nvalue))
{
for (k=0; k<nvalue; k++)
printf("BODY399_RADII(%d)=%23.16E\n", k, radii[k]);
}
/* close the ephemeris file */
calceph_close(peph);
}
calceph_getconstantss¶
-
int
calceph_getconstantss
(t_calcephbin* eph, const char* name, t_calcephcharvalue value)¶ Parameters: - eph – ephemeris descriptor
- name – name of the constant
- value – first value of the constant
Returns: returns 0 if an error occurs, otherwise the number of values associated to the constant.
This function returns, as a string of character, the value associated to the constant name in the header of the ephemeris file associated to eph. Only the first value is returned if multiple values are associated to a constant, such as a list of values. The value must be a string, otherwise an error is reported.
The following example prints the value of the unit stored in the ephemeris file
t_calcephcharvalue unit;
t_calcephbin *peph;
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
/* print the value of UNIT */
if (calceph_getconstantss(peph, "UNIT", unit))
printf("UNIT=%s\n", unit);
/* close the ephemeris file */
calceph_close(peph);
}
calceph_getconstantvs¶
-
int
calceph_getconstantvs
(t_calcephbin* eph, const char* name, t_calcephcharvalue *arrayvalue, int nvalue)¶ Parameters: - eph – ephemeris descriptor
- name – name of the constant
- arrayvalue – array of values for the constant
- nvalue – number of elements of the array
Returns: returns 0 if an error occurs, otherwise the number of values associated to the constant.
This function stores, to the array arrayvalue as strings of characters, the nvalue first values associated to the constant name in the header of the ephemeris file associated to eph. The integer value returned by the function is equal to the number of valid entries in the arrayvalue if nvalue is greater or equal to that integer value.
The required value nvalue to store all values can be determinated with this previous call calceph_getconstantvs(eph, name, NULL, 0).
The values must be strings, otherwise an error is reported.
The following example prints the units of the mission stored in the ephemeris file
int nvalue, k;
t_calcephcharvalue *mission_units;
t_calcephbin *peph;
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
/* get the number of values */
int nvalue = calceph_getconstantvs(peph, "MISSION_UNITS", NULL, 0);
mission_units = (t_calcephcharvalue*)malloc(sizeof(t_calcephcharvalue)*nvalue);
/* fill the array radii */
if (calceph_getconstantvs(peph, "MISSION_UNITS", mission_units, nvalue))
{
for (k=0; k<nvalue; k++)
printf("MISSION_UNITS(%d)=%s\n", k, mission_units[k]);
}
free(mission_units);
/* close the ephemeris file */
calceph_close(peph);
}
calceph_getconstantcount¶
-
int
calceph_getconstantcount
(t_calcephbin* eph)¶ Parameters: - eph – ephemeris descriptor
Returns: number of constants. 0 if an error occurs, otherwise non-zero value.
This function returns the number of constants available in the header of the ephemeris file associated to eph.
The following example prints the number of available constants stored in the ephemeris file
int count;
t_calcephbin *peph;
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
/* print the number of constants */
count = calceph_getconstantcount(peph);
printf("number of constants : %d\n", count);
/* close the ephemeris file */
calceph_close(peph);
}
calceph_getconstantindex¶
-
int
calceph_getconstantindex
(t_calcephbin* eph, int index, char name[CALCEPH_MAX_CONSTANTNAME], double *value)¶ Parameters: - eph – ephemeris descriptor
- index – index of the constant, between 1 and
calceph_getconstantcount()
- name – name of the constant
- value – first value of the constant
Returns: returns 0 if an error occurs, otherwise the number of values associated to the constant.
This function returns the name and its value of the constant available at the specified index in the header of the ephemeris file associated to eph. The value of index must be between 1 and calceph_getconstantcount()
.
Only the first value is returned if multiple values are associated to a constant, such as a list of values.
The following example displays the name of the constants, stored in the ephemeris file, and their values
int j;
int res;
char nameconstant[CALCEPH_MAX_CONSTANTNAME];
double valueconstant;
t_calcephbin *peph;
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
for (j=1; j<=calceph_getconstantcount(peph); j++)
{
calceph_getconstantindex(peph, j, nameconstant, &valueconstant);
printf("'%s'\t= %23.16E\n", nameconstant, valueconstant);
}
/* close the ephemeris file */
calceph_close(peph);
}
calceph_gettimescale¶
-
int
calceph_gettimescale
(t_calcephbin* eph)¶ Parameters: - eph – ephemeris descriptor
Returns: 0 if an error occurs, otherwise non-zero value.
- This function returns the timescale of the ephemeris file associated to eph :
- 1 if the quantities of all bodies are expressed in the TDB time scale.
- 2 if the quantities of all bodies are expressed in the TCB time scale.
The following example prints the time scale available in the ephemeris file
t_calcephbin *peph;
int timescale;
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
/* print the time scale */
timescale = calceph_gettimescale(peph);
if (timescale==1) printf("timescale=TDB\n");
if (timescale==2) printf("timescale=TCB\n");
/* close the ephemeris file */
calceph_close(peph);
}
calceph_gettimespan¶
-
int
calceph_gettimespan
(t_calcephbin* eph, double* firsttime, double* lasttime, int* continuous)¶ Parameters: - eph – ephemeris descriptor
- firsttime – Julian date of the first time
- lasttime – Julian date of the last time
- continuous – information about the availability of the quantities over the time span
Returns: 0 if an error occurs, otherwise non-zero value.
This function returns the first and last time available in the ephemeris file associated to eph. The Julian date for the first and last time are expressed in the time scale returned by calceph_gettimescale()
.
It returns the following value in the parameter continuous :
- 1 if the quantities of all bodies are available for any time between the first and last time.
- 2 if the quantities of some bodies are available on discontinuous time intervals between the first and last time.
- 3 if the quantities of each body are available on a continuous time interval between the first and last time, but not available for any time between the first and last time.
The following example prints the first and last time available in the ephemeris file
double firsttime, lasttime;
int countinuous;
t_calcephbin *peph;
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
if (calceph_gettimespan(peph, &firsttime, &lasttime, &countinuous))
printf("%23.16E %23.16E %d\n", firsttime, lasttime, countinuous);
/* close the ephemeris file */
calceph_close(peph);
}
calceph_getpositionrecordcount¶
-
int
calceph_getpositionrecordcount
(t_calcephbin* eph)¶ Parameters: - eph – ephemeris descriptor
Returns: number of position’s records. 0 if an error occurs, otherwise non-zero value.
This function returns the number of position’s records available in the ephemeris file associated to eph. Usually, the number of records is equal to the number of bodies in the ephemeris file if the timespan is continuous. If the timespan is discontinuous for the target and center bodies, then each different timespan is counted as a different record. If the ephemeris file contain timescale transformations’ records, such as TT-TDB or TCG-TCB, then these records are included in the returned value.
The following example prints the number of position’s records available in the ephemeris file
int count;
t_calcephbin *peph;
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
/* print the number of position's record */
count = calceph_getpositionrecordcount(peph);
printf("number of position's record : %d\n", count);
/* close the ephemeris file */
calceph_close(peph);
}
calceph_getpositionrecordindex¶
-
int
calceph_getpositionrecordindex
(t_calcephbin* eph, int index, int* target, int* center, double* firsttime, double* lasttime, int* frame)¶ Parameters: - eph – ephemeris descriptor
- index – index of the position’s record, between 1 and
calceph_getpositionrecordcount()
- target – The target body
- center – The origin body
- firsttime – Julian date of the first time
- lasttime – Julian date of the last time
- frame – reference frame (see the list, below)
Returns: 0 if an error occurs, otherwise non-zero value.
This function returns the target and origin bodies, the first and last time, and the reference frame available at the specified index for the position’s records of the ephemeris file associated to eph.
The NAIF identification numbering system is used for the target and center integers (NAIF identification numbers for the list).
The Julian date for the first and last time are expressed in the time scale returned by calceph_gettimescale()
.
It returns the following value in the parameter frame :
value | Name |
---|---|
1 | ICRF |
The following example displays the position’s records stored in the ephemeris file.
int j;
int res;
double firsttime, lasttime;
int itarget, icenter, iframe;
t_calcephbin *peph;
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
for (j=1; j<=calceph_getpositionrecordcount(peph); j++)
{
calceph_getpositionrecordindex(peph, j, &itarget, &icenter, &firsttime, &lasttime, &iframe);
printf("record %d : target=%d center=%d start=%23.16E end=%23.16E frame=%d\n",
j, itarget, icenter, firsttime, lasttime, iframe);
}
/* close the ephemeris file */
calceph_close(peph);
}
calceph_getorientrecordcount¶
-
int
calceph_getorientrecordcount
(t_calcephbin* eph)¶ Parameters: - eph – ephemeris descriptor
Returns: number of orientation’s records. 0 if an error occurs, otherwise non-zero value.
This function returns the number of orientation’s records available in the ephemeris file associated to eph. Usually, the number of records is equal to the number of bodies in the ephemeris file if the timespan is continuous. If the timespan is discontinuous for the target body, then each different timespan is counted as a different record.
The following example prints the number of orientation’s records available in the ephemeris file
int count;
t_calcephbin *peph;
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
/* print the number of orientation's record */
count = calceph_getorientrecordcount(peph);
printf("number of orientation's record : %d\n", count);
/* close the ephemeris file */
calceph_close(peph);
}
calceph_getorientrecordindex¶
-
int
calceph_getorientrecordindex
(t_calcephbin* eph, int index, int* target, double* firsttime, double* lasttime, int* frame)¶ Parameters: - eph – ephemeris descriptor
- index – index of the orientation’s record, between 1 and
calceph_getorientrecordcount()
- target – The target body
- firsttime – Julian date of the first time
- lasttime – Julian date of the last time
- frame – reference frame (see the list, below)
Returns: 0 if an error occurs, otherwise non-zero value.
This function returns the target body, the first and last time, and the reference frame available at the specified index for the orientation’s records of the ephemeris file associated to eph.
The NAIF identification numbering system is used for the target body (NAIF identification numbers for the list).
The Julian date for the first and last time are expressed in the time scale returned by calceph_gettimescale()
.
It returns the following value in the parameter frame :
value | Name |
---|---|
1 | ICRF |
The following example displays the orientation’s records stored in the ephemeris file.
int j;
int res;
double firsttime, lasttime;
int itarget, iframe;
t_calcephbin *peph;
/* open the ephemeris file */
peph = calceph_open("example1.dat");
if (peph)
{
for (j=1; j<=calceph_getorientrecordcount(peph); j++)
{
calceph_getorientrecordindex(peph, j, &itarget, &firsttime, &lasttime, &iframe);
printf("record %d : target=%d start=%23.16E end=%23.16E frame=%d\n",
j, itarget, firsttime, lasttime, iframe);
}
/* close the ephemeris file */
calceph_close(peph);
}
calceph_close¶
-
void
calceph_close
(t_calcephbin* eph)¶ Parameters: - eph – ephemeris descriptor
This function closes the access associated to the ephemeris descriptor eph and frees allocated memory for it.