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.GThese 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.