solar-system-ephemerides 1.1.0

Solar system ephemeris files

Solar System ephemerides

A package holding solar system ephemeris files, storing positions (in light seconds), velocities (lts/s) and accelerations (lts/s²) of the Earth and Sun for a range of JPL development ephemeris versions. These can be used, for example, for calculating Doppler modulations and relativistic corrections for continuous gravitational-wave signals. The package contains a command line script and Python API for generating these files, which makes use of the Astropy and jplephem packages. The script can more generally be used to create ephemeris files for any major planet within the solar system.

Along with ephemerides for the Earth and Sun, the package also contains two files providing time corrections between Terrestrial Time (TT) and Barycentric Coordinate Time (TCB) or Barycentric Dynamical Time (TDB). These were created using a script within LALSuite, called lalpulsar_create_time_correction_ephemeris, which uses the TIMEEPH_short.te405 (for TCB conversions) TDB.1950.2050 (for TDB conversions) within Tempo2.

Installation

This package can be installed, along with its requirements, from PyPI via pip with:

pip install solar-system-ephemerides

or, within a conda environment, from conda-forge with:

conda install -c conda-forge solar_system_ephemerides

It can be installed from source with:

git clone [e-mail]:cwinpy/solar-system-ephemerides.git
cd solar-system-ephemerides
pip install .

Usage

Once installed, to get the path to an ephemeris file, e.g., the DE405 file for Earth, within Python, you can do:

from solar_system_ephemerides import body_ephemeris_path

path = body_ephemeris_path("earth", DE405)

Or, the paths can be output using the ephemeris_path command line script, e.g., with:

ephemeris_path --body earth --ephem DE405

The full usage of ephemeris_path is shown with the --help flag:

$ ephemeris_path --help
usage: ephemeris_path [-h] [--body [BODY [BODY ...]]]
                      [--ephem [EPHEM [EPHEM ...]]]
                      [--units [UNITS [UNITS ...]]] [--return-dir]
                      [--rel-path REL_PATH]

Return the path to an ephemeris file or directory containing ephemeris files

optional arguments:
  -h, --help            show this help message and exit
  --body [BODY [BODY ...]], -b [BODY [BODY ...]]
                        The solar system body[ies] to return the path for.
                        These must be in "earth" or "sun".
  --ephem [EPHEM [EPHEM ...]], -e [EPHEM [EPHEM ...]]
                        The JPL development ephemeris version(s) to use. These
                        must be in "DE200", "DE405", "DE421", "DE430", "DE435"
                        or "DE436".
  --units [UNITS [UNITS ...]], -u [UNITS [UNITS ...]]
                        The time system units to return the path for. This
                        must be "TCB" or "TDB".
  --return-dir, -d      Return the ephemeris directory for a given body/time
                        system unit rather than the file path.
  --rel-path REL_PATH, -r REL_PATH
                        Return paths relative to this given path.

which also shows the JPL development ephemeris versions and solar system bodies for which there are ephemeris files available within the package.

Ephemeris generation

The package come with a script called create_solar_system_ephemeris that can be used to generate new ephemeris files.

Note: this script is based on the LALSuite script, lalpulsar_create_solar_system_ephemeris_python, and is designed to supersede it and the equivalent C script lalpulsar_create_solar_system_ephemeris.

For example, to create an ephemeris file for the Sun using the JPL DE421 spanning from 2015 to 2035, with 20 hours between each value, one would do:

create_solar_system_ephemeris --target SUN --year-start 2015 --interval 20 --num-years 20 --ephemeris DE421 --output-file sun15-35-DE421.dat.gz

Full usage of the script can be shown with the --help flag:

$ create_solar_system_ephemeris --help
usage: create_solar_system_ephemeris [-h] -e EPHEMERIS -o OUTPUT [-g GPSSTART]
                                     [-y YEARSTART] -n NYEARS -i INTERVAL -t
                                     TARGET

optional arguments:
  -h, --help            show this help message and exit
  -e EPHEMERIS, --ephemeris EPHEMERIS, --jplde EPHEMERIS, --ephem EPHEMERIS
                        Set the ephemeris to use (e.g. DE405)
  -o OUTPUT, --output-file OUTPUT
                        Set the output file. If this ends in '.gz' it will be
                        gzipped.
  -g GPSSTART, --gps-start GPSSTART
                        Set the GPS time at which to start generating the
                        ephemeris
  -y YEARSTART, --year-start YEARSTART
                        Set the (decimal) year at which to start generating
                        the ephemeris
  -n NYEARS, --num-years NYEARS
                        Set the number of years over which to generate the
                        ephemeris
  -i INTERVAL, --interval INTERVAL
                        Set the time step (in hours) between successive output
                        points
  -t TARGET, --target TARGET, --body TARGET
                        Set the solar system body to generate the ephemeris
                        for

Ephemeris access within Python

A convenience class for reading and manipulating the ephemeris file information within Python is provided with the BodyEphemeris class. This has attributes that return the positions, velocities and accelerations (with the distance in light seconds as stored in the files, or output in SI units). It can also convert the ephemeris into an Astropy QTable or Pandas DataFrame.

from solar_system_ephemerides.ephemeris import BodyEphemeris

# load the DE405 ephemeris for the Earth
earth = BodyEphemeris(body="earth", jplde="DE405")

# return a NumPy array of the 3D cartesian positions of Earth (in light seconds)
# for all time steps. Equivalently use .vel and .acc for velocities and
# accelerations. To return, e.g., just the x-positions use .pos_x.
earth.pos

# return the positions (in SI units)
earth.pos_si

# return the GPS seconds time stamp for each ephemeris valie
earth.times

# return the ephemeris as an Astropy QTable
earth.to_table()

# return the ephemeris as a Pandas DataFrame
earth.to_pandas()

To get the Earth and Sun ephemerides within a SWIG LALSuite EphemerisData object, you can use the lal_ephemeris_data function, e.g.,:

from solar_system_ephemerides.ephemeris import lal_ephemeris_data

# get Sun and Earth ephemerides for DE421
edat = lal_ephemeris_data(jplde="DE421")

Equivalently, to get the time correction file information within a SWIG LALSuite TimeCorrectionData object, you can use the lal_time_ephemeris_data function, e.g.,:

from solar_system_ephemerides.ephemeris import lal_time_ephemeris_data

# get the TT to TDB time correction data
tdat = lal_time_ephemeris_data(units="TDB")

|