New in PixInsight 1.8.6: Integrated Solar System Ephemerides

[Juan Conejero]

One of the most important new features in PixInsight 1.8.6 is the integration of a standardized system for calculation of ephemerides of solar system bodies. In this document I am going to describe the fundamentals of this implementation and how it can be exploited from the core JavaScript engine (PJSR) at a basic level. The C++ implementation, which is now part of the PixInsight Class Library (PCL), is very similar—is it actually the back end of the JavaScript implementation—and is already described in the official PCL documentation.

The PJSR front end of the integrated ephemerides system consists of a set of files and JavaScript objects that I'll describe briefly below.


EphemerisFile

This object provides access to ephemerides of solar system bodies stored in XEPH (Extensible Ephemeris Data format) files. On the PixInsight/PCL platform, XEPH is the standard file format for serialization and storage of ephemerides data. An XEPH file is similar to a monolithic XISF file: it consists of an XML file header document followed by a series of binary data blocks, where ephemerides data are stored as Chebyshev polynomial expansions. The XEPH header defines, along with ancillary data and properties describing the objects for which ephemerides can be calculated, a special file index for fast access to the Chebyshev coefficients required to compute ephemerides within a given time span.

XEPH files allow for calculation of rectangular coordinates (with the EphemerisHandle object, which I'll describe later) referred to the axes of the International Celestial Reference System (ICRS/J2000.0). Positions are given in au and velocities in au/day for all solar system objects, except planetocentric coordinates of natural satellites, including the geocentric Moon, for which positions and velocities are given in kilometers and km/day, respectively. Angles (nutations and librations) are given in radians, and time differences (such as TT-TDB), in seconds.

An XEPH file storing up-to-date JPL DE/LE ephemeris data is now part of all standard PixInsight distributions. As of writing this document, the standard XEPH file provides the complete JPL DE438/LE438 ephemerides.

In the following sections I'll describe just a few properties of the EphemerisFile object, which are the minimal set of elements required for a basic application. For a complete and detailed description of all properties and methods available for this object, see the corresponding documentation for the C++/PCL implementation.


Object Identifiers and Names

In an XEPH file, objects can be referenced in two ways:

• By identifier. An object identifier is a short ASCII string, typically with three or four characters, which is treated as a case-sensitive string.
  
  
• By name (optional, not always available). An object's name is an arbitrary Unicode string, normally the readable name of an object, treated as a case-insensitive string.

   
For example, all of 'Ju', 'Jupiter', 'jupiter' and 'JUPITER' refer to Jupiter in a standard XEPH file storing fundamental JPL DE/LE ephemerides. In this example, 'Ju' is a case-sensitive object identifier, thus 'ju' and 'JU' are not valid. 'SSB' is the special identifier reserved for the solar system barycenter.


Ephemeris Time Span

Each XEPH file provides ephemerides for a limited time span, which can be retrieved with the following properties:

   Date EphemerisFile.startTime

Starting point of the time span covered by the ephemerides file, or the earliest time point for which ephemerides can be calculated.

   Date EphemerisFile.endTime

Ending point of the time span covered by the ephemerides file, or the latest time point for which ephemerides can be calculated.


Retrieving the Set of Objects Available

To know the set of objects available in an XEPH file, one should use the following property:

   Array EphemerisFile.objects

The value of this property is an array where each element is an array A with the following elements:

A[0] : Object identifier
A[1] : Center identifier
A[2] : Object name (can be empty)

For example, one of the arrays in the value of this property for the standard fundamental ephemerides file is ["Ju","SSB","Jupiter"], which tells us that Jupiter (identifier 'Ju' and name 'Jupiter') is available for calculation of barycentric (origin='SSB') rectangular ICRS coordinates.


Standard Ephemeris Files

The following static properties of the EphemerisFile object provide access to essential XEPH files that should be available in every PixInsight 1.8.6 installation. There are more ephemeris files and databases in the integrated ephemerides system, but I'll describe here just the files necessary for practical ephemerides calculations.

   EphemerisFile EphemerisFile.fundamentalEphemerides

The global fundamental ephemerides file currently defined by the running PixInsight platform. Under normal working conditions, the returned object provides ephemeris data for at least the following objects:

Identifier	Name	Description
Me	Mercury	Mercury's barycenter
Ve	Venus	Venus' barycenter
EMB		Earth-Moon barycenter
Ma	Mars	Mars' barycenter
Ju	Jupiter	Jupiter's barycenter
Sa	Saturn	Saturn's barycenter
Ur	Uranus	Uranus' barycenter
Ne	Neptune	Neptune's barycenter
Pl	Pluto	Pluto's barycenter
Mn	Moon	Moon's geometric center with respect to Earth's center.
Sn	Sun	Sun's geometric center
Ea	Earth	Earth's geometric center

With the only exception of the Moon ("Mn" identifier), ephemeris data for all of the objects above are provided relative to the solar system barycenter ("SSB" identifier). Additional items may also be available, depending on specific file versions and compilations:

Identifier	Description
Lbr	Lunar librations (Euler angles) in radians
Nut	Nutation angles in radians
TT_TDB	TT-TDB difference at the geocenter in seconds.

As of writing this document, the standard fundamental ephemerides file provides JPL's DE438/LE438 ephemerides, but nutations, librations and time differences are not included.

   EphemerisFile EphemerisFile.asteroidEphemerides

The global asteroid ephemerides file currently defined by the running PixInsight platform. Under normal working conditions, the returned object provides ephemeris data for a set of asteroids with relevant masses. In a standard asteroid ephemeris file, object identifiers are asteroid numbers and object names are asteroid designations; for example:

Identifier	Name
1	Ceres
2	Pallas
3	Juno
4	Vesta
5	Astraea
...	...
702	Alauda
703	Noemi
704	Interamnia
...	...

Asteroid ephemeris data are provided relative to the solar system barycenter ("SSB" identifier), with position and velocity coordinates coherent with global fundamental ephemerides. As of writing this document, the standard asteroid ephemerides file provides the complete set of 343 asteroids used for the numerical integration of DE430 ephemerides, with barycentric coordinates calculated to be coherent with DE438.


EphemerisHandle

This object provides access to ephemeris data for a specific object available in an XEPH file. It can perform basic ephemeris calculations, including state vectors and its first derivatives, such as position and velocity vectors, and performs all the low-level file search, seek and read operations transparently and efficiently. This object is the JavaScript version of the C++ implementation in the pcl::EphemerisFile::Handle subclass.

Data stored in an XEPH ephemeris file generates rectangular coordinates referred to the axes of the International Celestial Reference System (ICRS/J2000.0). Positions are given in au and velocities in au/day for all solar system objects, except planetocentric coordinates of natural satellites, including the geocentric Moon, for which positions and velocities are given in kilometers and km/day, respectively. When available, angles (nutations and librations) are given in radians, and time differences (such as TT-TDB) in seconds.

For practical ephemeris calculations, the EphemerisHandle object is normally not used directly to compute celestial coordinates. The Position object, which I'll describe in a second article dedicated to reduction of astronomical positions, is much more efficient and versatile for calculation of places of solar system bodies and stars, including astrometric, proper and apparent positions, among others. The state vectors computed directly with EphemerisHandle are more appropriate for low-level applications, such as generation of ephemerides by numerical integration. These are more advanced topics that should be covered in separate documents.


Constructor

   new EphemerisHandle( EphemerisFile parent, String object, String origin )

Constructs a new EphemerisHandle object for calculation of state vectors for the specified object, with the specified origin of rectangular coordinates, with data retrieved from the specified parent ephemerides file. object and origin can be object identifiers or names, although the use of identifiers is recommended for robustness.


State Vectors

   Vector EphemerisHandle.stateVector( Date )
   Vector EphemerisHandle.stateVector( String isoTime )
   Vector EphemerisHandle.stateVector( Number jd1[, Number jd2=0] )

This method computes a state vector (typically a position vector) for the specified time point in the Barycentric Dynamical Time (TDB) timescale. The calculation time can be specified as a Date object, as an ISO 8601 date/time string representation, or as a Julian date, which can be specified as one or two components, JD=jd1+jd2 ( (specifying a JD as two components greatly improves the accuracy of time representation by increasing the effective bit length used to store time points).

The components of returned position vectors are ICRS rectangular equatorial coordinates in au, except planetocentric coordinates of natural satellites (including the geocentric Moon), for which positions are provided in km. Angles are provided in radians. TT-TDB differences are provided in seconds.

   Array EphemerisHandle.stateVectors( Date )
   Array EphemerisHandle.stateVectors( String isoTime )
   Array EphemerisHandle.stateVectors( Number jd1[, Number jd2=0] )

Computes state vectors (typically position and velocity vectors) for the specified time point in the Barycentric Dynamical Time (TDB) timescale. The calculation time can be specified as in the above stateVector() method.

The returned object is an Array with two elements, where the first element is the function value as a Vector object, and the second element is the first derivative, also as a Vector object. The components of returned position and velocity vectors are ICRS rectangular equatorial coordinates in au and au/day, respectively, except planetocentric coordinates of natural satellites (including the geocentric Moon), for which positions and velocities are provided in km and km/day, respectively. Angles and their variations are provided in radians and radians/day. TT-TDB differences and their variations are provided in seconds and seconds/day.


Asteroid Photometric and Diameter Data

   Number|null EphemerisHandle.H
   Number|null EphemerisHandle.G

These properties return the absolute magnitude and slope parameter, respectively, for the body represented by this EphemerisHandle object. These properties are only available for asteroids. If the corresponding data are unavailable in the parent ephemeris file, the value of each of these properties is null.

H is the visual magnitude of the object as seen at 1 au of the Earth, 1 au from the Sun, and with a phase angle of 0 degrees. G, the slope parameter, is used to compute phase angle corrections. For a detailed description and the algorithm for calculation of asteroid visual magnitudes, see:

• E. Bowell et al., Asteroids II, R. P. Binzel et al. (eds.), The University of Arizona Press, Tucson, 1989, pp. 549-554.
  
  
• Urban, Sean E., Kenneth Seidelmann, P., ed. (2013), The Explanatory Supplement to the Astronomical Almanac, 3rd Edition, Section 10.4.3.

The Position JavaScript object (which I describe in a separate document) provides implementations of the rigorous algorithms for calculation of visual magnitudes of planets and asteroids.

   Number|null EphemerisHandle.B_V

Johnson B-V color index in magnitudes. If the corresponding data are unavailable in the parent ephemeris file, the value of this property is null.

   Number|null EphemerisHandle.D

Diameter in km. When available, this is normally an IRAS asteroid diameter. If the corresponding data are unavailable in the parent ephemeris file, the value of this property is null.