EPM User Manual

Introduction

This manual is for anybody who wants to use EPM (Ephemerides of Planets and Moon) for any purpose in their work. EPM are available through many ways that will suit different needs.

EPM contain the following data for the interval of 400+ years:

Barycentric positions and velocities of Sun, planets, five asteroids (Ceres, Pallas, Vesta, Iris, Bamberga) and four TNO (Eris, Haumea, Makemake, Sedna);
Geocentric position and velocity of the Moon;
Three Euler angles of lunar physical libration (phi, theta, psi) and their rates;
TT-TDB difference

All the data is stored in the TDB time scale as Chebyshev polynomials on equal time intervals. There are multiple tools, described in further sections, that allow users to obtain positions, velocities, libration angles and their rates, and TT-TDB from ephemeris files.

New users, please see Sections 1 or 2. Users who have previously set up their software to access ephemeris files can refer to Sections 3–7 to find suitable options.

Web access

The Online Ephemeris Service of IAA RAS is an interactive tool to obtain ephemeris data online. It provides not only rectangular positions of planets, but has plenty of options to view the coordinates in various reference systems, rectangular or spherical, relative to a specific observer, etc.

There is also an option to switch between EPM2008, EPM2011/m, EPM2015, EPM2017, EPM2021 or selected versions of DE and INPOP ephemeris.

“Show results in a new window” button gives the user a URL that can be reused (manually or programmatically from other software) to obtain the chosen ephemeris data again.

Access to SPICE files from C/C++, Fortran, Python, MATLAB, or IDL

For users who need to access EPM offline, the recommended way is to download the ephemeris files for the latest version of EPM provided in the formats of the SPICE toolkit. For EPM2021, the files can be found at http://ftp.iaaras.ru/pub/epm/EPM2021/SPICE/.

A short description of the files:

epm<VERSION>.bsp: binary file that contains ephemeris of celestial bodies and TT-TDB (for EPM2011/m, there is a separate file for TT-TDB).
moonlibr_epm<VERSION>.bpc: binary file that contains lunar physical libration angles.
moonlibr_epm<VERSION>.tf: ancillary text file that provides the description of the lunar frame. Can be loaded into the SPICE toolkit, though not necessarily.
epm<VERSION>.tpc: ancillary text file that provides the values of selected constants used during building of ephemerides (masses of celestial bodies etc). Not necessary for ephemeris access.

There exists several software libraries that are recommended to access the EPM files in the SPICE format:

Software created by IAA RAS: libephaccess (a C library) and ephcalculator (a command-line application based on the libephaccess). Both are available at the IAA RAS GitLab server. The C library is self-documented currently only in Russian, while the command-line application has built-in help provided in English. A Python wrapper for the library is provided.
CALCEPH library by IMCCE reads EPM or other ephemeris files presented in a number of formats, including SPICE. The library provides a C API, and optionally a Fortran 77 or 2003 program interface. A Python wrapper for the library is provided.
SPICE toolkit by NAIF is a rich toolkit to perform a wide variety of astronomical tasks, including ephemeris file access. The toolkit is offered for C, Fortran, MATLAB, and IDL languages.

Access to IAA binary files

In the past, IAA developed its own binary format for ephemeris file storage. In that format, each object is represented in a separate binary file. The files for the latest version of EPM can be downloaded from the BIN directory of each of the EPM distributions at the IAA RAS FTP server.

Short description of the files:

tdb.bin : TT-TDB
moonlibr.bin : lunar physical libration
moon.bin : Moon (geocentric)
earth_m.bin : Earth-Moon barycenter (barycentric)
sun.bin, mercury.bin, venus.bin, mars.bin, jupiter.bin, saturn.bin, uranus.bin, neptune.bin, pluto.bin, ceres.bin, pallas.bin, vesta.bin, eris.bin, sedna.bin, haumea.bin, makemake.bin : other bodies (barycentric)

C

An ANSI C library to access these files can be found at the IAA RAS GitLab server.

The library consists of a single module epm_bin_access.c plus a corresponding header epm_bin_access.h. There are just three functions exported by the library:

EpmFile * epm_file_open (const char *filename);

Opens a ".bin" file and returns a handler to it.

int epm_calc_raw_values (EpmFile *epmf, int jd, double jd_frac,
                         double *pos, double *vel);

Calculates position and/or velocity of the given object. The Julian date (TDB) is supplied in the input as the sum of two values: jd is the integer part, while jd_frac is the fractional part.

pos[] and vel[] must be allocated arrays of size at least 3 (1 in case of TT-TDB). If a given pos/vel is NULL, the corresponding values are not recorded.

In the case of the "moonlibr.bin", the three Euler angles (in radians) are stored in pos[], while their rates go to vel[].

In the case of the "tdb.bin", the TT-TDB (in seconds) will be stored in vel[0].

In other cases, rectangular position of the body (in AU) is recorded into pos[], while its velocity (in AU/day) goes to vel[].

void epm_file_close (EpmFile *epmf);

Closes a previously opened ".bin" file and releases other resources allocated for it.

Additionally to the C library, a command-line utility (epm-calculator.c) is provided that is built on top of the library. The following options can be passed to epm-calculator:

Usage: epm-calculator [parameters]
Obligatory parameters:
   -from-mjd <real>
      Modified Julian date to start from
   -body [tdb | earth | moon | moonlibr | EMB | sun | venus | ... ]
      Celestial body or another object:
        tdb = TT-TDB difference
        moonlibr = lunar libration angles (in radians) and rates
        EMB = Earth-Moon barycenter
   -interval-days <real>
      Interval length in days
Optional parameters:
   -step-days <real>
      Step size in days (default 1 day)
   -theory [epm2008|epm2011m|epm2015]
      Theory to use for the calculations (default epm2015)
   -frame [geocentric | barycentric | heliocentric]
      Reference frame (default barycentric)
   -width <integer>
      Width of output numbers, including sign, decimal point, and exponent
(default 20)
   -distance-units [au|km]
      Output positions in AU or km (default AU)
   -time-units [sec|day]
      Output velocities as a unit of distance per second or per day (default day)
   -only-pos
      Output only positions, skip velocities
   -directory <path>
      Directory containing the binary ephemeris files; default EPM2008/BIN,
      EPM2011m/BIN, or EPM2015/BIN depending of chosen theory

Java

A Java library and an example program to access IAA's binary EPM files is provided at the IAA RAS GitLab server.

The library consists of two modules:

org.iaaras.epm.EpmFile (low-level ".bin" file access)

EpmFile (String filename, boolean from_resource)

Opens a ".bin" file and returns a handler to it. If from_resource flag is set, the filename is treated as a path to resource rather than a file stored in a file system.

void calcRawValues (int jd, double jd_frac, double[] pos, double[] vel)

Calculates position and/or velocity of the given object. The Julian date (TDB) is supplied in the input as the sum of two values: jd is the integer part, while jd_frac is the fractional part.

pos[] and vel[] must be allocated arrays of size at least 3 (1 in case of TT-TDB).

In the case of the "moonlibr.bin", the three Euler angles (in radians) are stored in pos[], while their rates go to vel[].

In the case of the "tdb.bin", the TT-TDB (in seconds) will be stored in vel[0].

In other cases, rectangular position of the body (in AU) is recorded into pos[], while its velocity (in AU/day) goes to vel[].

void close ()

Closes a previously opened ".bin" file.

org.iaaras.epm.EpmCalculator (higher-level access to ephemeris via EpmFile)

EpmCalculator (String theory, String dir, boolean from_resource)

theory is "EPM", where is 2004, 2008, 2011, or 2015. dir is a directory containing all the ".bin" files. If from_resource flag is set, the directory is treated as a path to resource rather than a path in a file system.

void calcLibr (int jd, double jd_frac, double[] pos, double[] vel)

Calculate lunar libration angles (in radians) and their rates (in radians/day) for the given date.

double calcTDB (int jd, double jd_frac)

Calculate lunar libration angles (in seconds) for the given date.

void calcBarycentric (int pl_num, int jd, double jd_frac, double[] pos, double[] vel)

Calculates barycentric coordinates and velocities of one of the following objects (corresponding pl_num values listed): 1 - Mercury, 2 - Venus, 3 - Earth, 4 - Mars, 5 - Jupiter, 6 - Saturn, 7 - Uranus, 8 - Neptune, 9 - Pluto, 10 - Moon, 11 - Sun, 12 - EMB.

void calcWrt (int pl_num, int centr_num, int jd, double jd_frac, double[] pos, double[] vel)

Calculates coordinates and velocities of one object (pl_num) with respect to another (centr_num). See the description of calcBarycentris for the allowed values

void calcBarycentricDwarf (int dnum, int jd, double jd_frac, double[] pos, double[] vel)

Calculates barycentric coordinates and velocities of one of the following objects (corresponding dnum values listed): 1 - Ceres, 2 - Pallas, 4 - Vesta, 136199 - Eris, 136108 - Haumea, 136472 - Makemake, 90377 - Sedna

public void close ()

Closes opened ephemeris files.

The test module org.iaaras.epm.test.EpmCalculatorTest is an example command-line program built on top of EpmCalculator.

Fortran

The Fortran module (calc_epm_bin.f90) and an example program (demo_bin.f90) can be found at the IAA RAS GitLab server.

IAA text files

IAA provides ASCII files similar to binary files described in the previous section. The files can be downloaded from the TXT directory of each of the EPM distributions at the IAA RAS FTP server.

A Fortran library for accessing those files (calc_epm_txt.F) and an example program (demo_txt.F) can be found at the IAA RAS GitLab server.

Files in DE format

Versions of EPM starting from EPM2011m have been converted to the text and binary formats traditionally used for DE ephemeris developed by NASA JPL.

The files can be downloaded from the DE directory of each of the EPM distributions at the IAA RAS FTP server.

Users who currently use some software to read ephemeris in DE format can try EPM without changing their software.

The following parameters should be set in the ephemeris access library:

NCOEF = 1018
KSIZE = 2036
record length = 8144

Additional periodic variation of the lunar libration angle psi

The EPM2015 lunar theory includes three additional periodic terms for longitude libration to account for small effects related to frequency dependent tidal dissipation. Those terms are not included in the ephemeris files nor into any of the software for access. The corresponding effect is small (~ 0.1 m) and will be significant only to users who work with very precise lunar laser ranging observations. Such users will have to introduce the following change to the lunar libration angle psi:

$$\Delta\psi = A_1 \cos(l') + A_2 \cos(2l - 2D) + A_3 \cos(2F - 2l)$$

where:

l is the lunar mean anomaly
l′ is the solar mean anomaly
F is the argument of latitude
D is the elongation of Moon from Sun

The Delaunay arguments l, l', F, and D can be calculated using e.g. the SOFA library.

For EPM2015, A₁ = 4.5 mas, A₂ = 1.4 mas, A₃ = −7.3 mas.

For EPM2017, A₁ = 4.4 mas, A₂ = 1.6 mas, A₃ = −5.2 mas.

For EPM2021, A₁ = 4.1 mas, A₂ = 1.5 mas, A₃ = 1.7 mas.

Usage and licensing information

IAA RAS holds the authorship and copyright for the EPM ephemeris files. These files are provided for free usage for scientific, commercial, or other purposes that do not break Russian or international laws.

The program code for accessing EPM in obsolete formats (see sections 3–6) has been created at the IAA RAS and is in public domain.

The CALCEPH library is copyright the National Center for Scientific Research (CNRS), France. Licensing information can be found at http://www.imcce.fr/fr/presentation/equipes/ASD/inpop/calceph/.

The SPICE toolkit is copyright the Navigational and Ancillary Information Facility (NAIF), USA. Licensing information can be found at https://naif.jpl.nasa.gov/naif/rules.html.

Some references related to the Online Ephemeris Service can be found here: http://iaaras.ru/en/dept/ephemeris/online/references/.

Contact

Dmitry Pavlov dpavlov@iaaras.ru