API

CALCEPH

This module is a wrapper of CALCEPH, IMCCE planetary ephemeris access library. It supports INPOPxx, JPL DExxx and SPICE ephemeris.

https://www.imcce.fr/inpop/calceph

naifId

NAIF identification numbers

Examples:

julia> using CALCEPH

julia> naifId.id[:sun]
10

julia> naifId.id[:mars]
499

julia> naifId.names[0]
Set(Symbol[:ssb, :solar_system_barycenter])

outputEulerAngles

has to be added to the unit argument for orient to output Euler angles

outputNutationAngles

has to be added to the unit argument for orient to output nutation angles

unitAU

Astronomical unit: distance unit

unitDay

day: time unit

unitKM

kilometer: distance unit

unitRad

radian: angle unit

unitSec

second: time unit

useNaifId

has to be added to the unit argument when using NAIF integer codes for identification of center and target

Ephem

Ephemeris descriptor. Create with:

eph = Ephem(filename)
eph = Ephem([filename1,filename2...])

The ephemeris descriptor will be used to access the ephemeris and related data stored in the specified files.

Because, Julia GC is lazy, you may want to free the memory managed by eph before you get rid of the reference to eph with:

finalize(eph)

or after by forcing the GC to run:

gc()

compute(eph,jd0,time,target,center,unit,order)

Compute position and derivatives up to order of target with respect to center at epoch jd0+time. To get the best precision for the interpolation, the time is split 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 care about precision.

Arguments

• eph: ephemeris
• jd0::Float64: jd0+time must be equal to the Julian Day for the time coordinate corresponding to the ephemeris (usually TDB or TCB)
• time::Float64: jd0+time must be equal to the Julian Day for the time coordinate corresponding to the ephemeris (usually TDB or TCB)
• target::Integer: The body or reference point whose coordinates are required. The numbering system depends on the parameter unit.
• center::Integer: The origin of the coordinate system. The numbering system depends on the parameter unit.
• unit::Integer : The units of the result. This integer is a sum of some unit constants (unit*) and/or the constant useNaifId. If the unit contains useNaifId, the NAIF identification numbering system is used for the target and the center. If the unit does not contain useNaifId, the old number system is used for the target and the center.
• order::Integer : The order of derivatives
  • 0: only the position is computed.
  • 1: only the position and velocity are computed.
  • 2: only the position, velocity and acceleration are computed.
  • 3: the position, velocity and acceleration and jerk are computed.

compute(eph,jd0,time,target,center,unit)

Compute position and velocity of target with respect to center at epoch jd0+time. To get the best precision for the interpolation, the time is split 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 care about precision.

Arguments

• eph: ephemeris
• jd0::Float64: jd0+time must be equal to the Julian Day for the time coordinate corresponding to the ephemeris (usually TDB or TCB)
• time::Float64: jd0+time must be equal to the Julian Day for the time coordinate corresponding to the ephemeris (usually TDB or TCB)
• target::Integer: The body or reference point whose coordinates are required. The numbering system depends on the parameter unit.
• center::Integer: The origin of the coordinate system. The numbering system depends on the parameter unit.
• unit::Integer : The units of the result. This integer is a sum of some unit constants (unit*) and/or the constant useNaifId. If the unit contains useNaifId, the NAIF identification numbering system is used for the target and the center. If the unit does not contain useNaifId, the old number system is used for the target and the center.

compute(eph,jd0,time,target,center)

Compute position and velocity of target with respect to center at epoch jd0+time. This method does not support the NAIF numbering scheme. To get the best precision for the interpolation, the time is split 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 care about precision.

This method does not support the NAIF body identification scheme.

Output units are:

• AU and AU/day for position and velocity
• rad and rad/day for librations
• second and unitless for time ephemeris and time ephemeris rate

Arguments

• eph: ephemeris
• jd0::Float64: jd0+time must be equal to the Julian Day for the time coordinate corresponding to the ephemeris (usually TDB or TCB)
• time::Float64: jd0+time must be equal to the Julian Day for the time coordinate corresponding to the ephemeris (usually TDB or TCB)
• target::Integer: The body or reference point whose coordinates are required.
• center::Integer: The origin of the coordinate system.

The possible values for target and center are :

• 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
• 14 : Nutation angles
• 15 : Librations
• 16 : TT-TDB
• 17 : TCG-TCB
• asteroid number + 2000000 : asteroid

constants(eph)

Retrieve the constants stored in the ephemeris associated to handle eph as a dictionary

orient(eph,jd0,time,target,unit,order)

Compute Euler angles and derivatives up to order for the orientation of target at epoch jd0+time. To get the best precision for the interpolation, the time is split 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.

Arguments

• eph: ephemeris
• jd0::Float64: jd0+time must be equal to the Julian Day for the time coordinate corresponding to the ephemeris (usually TDB or TCB)
• time::Float64: jd0+time must be equal to the Julian Day for the time coordinate corresponding to the ephemeris (usually TDB or TCB)
• target::Integer: The body whose orientation is required. The numbering system depends on the parameter unit.
• unit::Integer : The units of the result. This integer is a sum of some unit constants (unit*) and/or the constant useNaifId. If the unit contains useNaifId, the NAIF identification numbering system is used for the target and the center. If the unit does not contain useNaifId, the old number system is used for the target and the center (see the list in the documentation of function compute). If the unit contains outputNutationAngles, the nutation angles are computed rather than the Euler angles.
• order::Integer : The order of derivatives
  • 0: only the angles are computed.
  • 1: only the angles and 1st derivatives are computed.
  • 2: only the angles, the 1st derivatives and 2nd derivatives are computed.
  • 3: the angles, the 1st derivatives, 2nd derivatives and 3rd derivatives are computed.

orient(eph,jd0,time,target,unit)

Compute Euler angles and first derivative for the orientation of target at epoch jd0+time. To get the best precision for the interpolation, the time is split 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.

Arguments

• eph: ephemeris
• jd0::Float64: jd0+time must be equal to the Julian Day for the time coordinate corresponding to the ephemeris (usually TDB or TCB)
• time::Float64: jd0+time must be equal to the Julian Day for the time coordinate corresponding to the ephemeris (usually TDB or TCB)
• target::Integer: The body whose orientation is required. The numbering system depends on the parameter unit.
• unit::Integer : The units of the result. This integer is a sum of some unit constants (unit*) and/or the constant useNaifId. If the unit contains useNaifId, the NAIF identification numbering system is used for the target and the center. If the unit does not contain useNaifId, the old number system is used for the target and the center (see the list in the documentation of function compute). The angles are expressed in radians if unit contains unitRad. If the unit contains outputNutationAngles, the nutation angles are computed rather than the Euler angles.

orientationRecords(eph)

Retrieve orientation records metadata in ephemeris associated to handler eph .

positionRecords(eph)

Retrieve position records metadata in ephemeris associated to handler eph .

prefetch(eph)

This function prefetches to the main memory all files associated to the ephemeris descriptor eph.

rotAngMom(eph,jd0,time,target,unit,order)

Compute angular momentum due to rotation and derivatives up to order of target at epoch jd0+time. To get the best precision for the interpolation, the time is split 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.

Arguments

• eph: ephemeris
• jd0::Float64: jd0+time must be equal to the Julian Day for the time coordinate corresponding to the ephemeris (usually TDB or TCB)
• time::Float64: jd0+time must be equal to the Julian Day for the time coordinate corresponding to the ephemeris (usually TDB or TCB)
• target::Integer: The body whose angular momentum is required. The numbering system depends on the parameter unit.
• unit::Integer : The units of the result. This integer is a sum of some unit constants (unit*) and/or the constant useNaifId. If the unit contains useNaifId, the NAIF identification numbering system is used for the target and the center. If the unit does not contain useNaifId, the old number system is used for the target and the center (see the list in the documentation of function compute).
• order::Integer : The order of derivatives
  • 0: only the angles are computed.
  • 1: only the angles and 1st derivatives are computed.
  • 2: only the angles, the 1st derivatives and 2nd derivatives are computed.
  • 3: the angles, the 1st derivatives, 2nd derivatives and 3rd derivatives are computed.

rotAngMom(eph,jd0,time,target,unit)

Compute angular momentum due to rotation and first derivative of target at epoch jd0+time. To get the best precision for the interpolation, the time is split 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.

Arguments

• eph: ephemeris
• jd0::Float64: jd0+time must be equal to the Julian Day for the time coordinate corresponding to the ephemeris (usually TDB or TCB)
• time::Float64: jd0+time must be equal to the Julian Day for the time coordinate corresponding to the ephemeris (usually TDB or TCB)
• target::Integer: The body whose angular momentum is required. The numbering system depends on the parameter unit.
• unit::Integer : The units of the result. This integer is a sum of some unit constants (unit*) and/or the constant useNaifId. If the unit contains useNaifId, the NAIF identification numbering system is used for the target and the center. If the unit does not contain useNaifId, the old number system is used for the target and the center (see the list in the documentation of function compute). The angles are expressed in radians if unit contains unitRad.

timeScale(eph)

Retrieve the timescale associated with ephemeris handler eph Returns 1 for TDB and 2 for TCB.

timespan(eph::Ephem)

This function returns the first and last time available in the ephemeris file associated to eph.

Arguments:

• eph : ephemeris

Return:

a tuple containing: * 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

    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.

See: https://www.imcce.fr/content/medias/recherche/equipes/asd/calceph/html/c/calceph.multiple.html#menu-calceph-gettimespan