- Introduction
- set_ephemeris_dir
- object track
- object doppler
- doppler fraction
- observer position and velocity
- pulse delay
- utc to tdb
- utc to last
- last to utc
- j2000 to epoch
- epoch to j2000
- add aberration
- remove aberration
- set observer coordinates
- geocentric observer XYZ coordinates
- barycentric observer XYZ coordinates
- barycentric earth XYZ coordinates
- barycentric object XYZ coordinates

This document briefly describes the events recognized by the python "jplephem" module. This module is based on the JPL solar system ephemerides and the SOFA C function set. The source code for this python module may be downloaded from this anonymous ftp directory. The SOFA source code should be obtained separately from their download site. The JPL ephemeris files may be found here. The routine, asc2bin in the code set may be used to convert the ASCII data file to a binary file used by the python module code.

The immediate purposes for "jplephem" are to track the moon and planets and to provide a few functions of general utility such as precession/nutation, aberration, UTC to LST and LST to UTC conversion, doppler calculation, and pulsar pulse delay. The module functions described in more detail below are

Event Name Input Values set_ephemeris_dir (directory_path, file_name) object_track (object, mjd, utc, num_pts, interval) object_doppler (object, mjd, utc, num_pts, interval) doppler_fraction (ra, dec, mjd, utc, num_pts, interval) observer_position_velocity (mjd, utc, num_pts, interval) pulse_delay (ra, dec, mjd, utc, num_pts, interval) utc_to_tdb (mjd, utc) utc_to_last (mjd, utc) last_to_utc (mjd, last) j2000_to_epoch (ra, dec, mjd, utc) epoch_to_j2000 (ra, dec, mjd, utc) add_aberration (ra, dec, mjd, utc) remove_aberration (ra, dec, mjd, utc) set_observer_coordinates (x, y, z) geocentric_observer_track (mjd, utc, num_pts, interval) barycentric_observer_track (mjd, utc, num_pts, interval) barycentric_earth_track (mjd, utc, num_pts, interval) barycentric_object_track (object, mjd, utc, num_pts, interval)

The "jplephem" module requires three data files in one directory: the binary solar system ephemeris, e.g. DEc403; a leap-second table called 'leapsec.tab'; and a UT1 - UTC offset table called 'iers.tab'. Copies of these tables can be found in

~rfisher/Applications/Python/lib/python2.3/site-packages/JPLEphem/

The python path to the module is

PYTHONPATH=~rfisher/Applications/Python/lib/python2.3/site-packages

The ephemeris file must cover the time range for which positions are to be extracted, and the leap-second and UT1 offset files must be updated periodically from IERS Bulletin A. As of this writing ephemeris file, DEc403, found in the above directory currently spans the years 2006 to 2020, but this could be updated at any time. Use the set_ephemeris_dir() function to point to your own 'leapsec.tab', 'iers.tab', and 'DExxx' files.

The module is initiated from python with a line like

>>> from jplephem import *The default directory for the 'iers.tab', 'leapsec.tab', and 'DExxx' data files is the same as the PYHTONPATH. To change this from within python and specify which JPL data file in this directory to use execute the following python command, for example,

>>> set_ephemeris_dir('/users/mylogin/SSdir', 'DEc403')

Most of the module functions return dictionary values unless a simpler python variable will suffice. For example,

>>> print object_track('Moon', 53849, 0.5, 2, 0.01) {'status': 2, 'ra_rate': [0.38198704428895247, 0.38198695356159146], 'dec': [-6.3726201725571467, -6.3726194037239363], 'ra': [23.383792030852653, 23.383792101595962], 'dec_rate': [0.27675745247981914, 0.27675746992724337]}Some requests return a python record with more than variable per named dictionary member, as described below.

This function returns topocentric, astrometric J2000 coordinates for the specified object and time(s). The astrometric position is the direction of the line between the observer's position at the specified time and the position of the object at the time the light began its journey, i.e. the object's position at the specified time less the light travel time. This is the location of the object relative to a background of stars plotted in J2000 coordinates.

Inputs:

- Object name string. Recognized, case-insensitive values are 'Sun', 'Moon', 'Mercury', 'Venus', 'Mars', 'Jupiter', 'Saturn', 'Uranus', 'Neptune', and 'Pluto'.
- Modified Julian Date (integer)
- UTC in fraction of a day for the first position
- Number of positions wanted
- Interval between positions in UTC seconds

Output: {ra:, dec:, ra_rate:, dec_rate:}

- RA(J2000) (fractional hours),
- Dec(J2000) (fractional degrees),
- RA rate (arcmin/min)
- Dec rate (arcmin/min)
- note: The directory entry values are lists whose lengths are equal to the number of positions requested.

This function returns the observer's radial velocity component with respect to the specified object as a fraction of the speed of light. The velocity is in the sense that

object's rest velocity = observed velocity + (v / c) * c

Inputs:

- Object name string. Recognized, case-insensitive values are 'Sun', 'Moon', 'Mercury', 'Venus', 'Mars', 'Jupiter', 'Saturn', 'Uranus', 'Neptune', and 'Pluto'.
- Modified Julian Date (integer)
- UTC in fraction of a day for the first position
- Number of velocities wanted
- Interval between velocities in UTC seconds
- note: The directory entry values are lists whose lengths are equal to the number of velocities requested.

Output: {status:, frac:]

- status: number of values returned
- frac: v/c for each time requested

This function returns the observer's radial velocity component with respect to the solar system barycenter as a fraction of the speed of light for the specified J2000 coordinates and time(s). The velocity is in the sense that

barycentric velocity = observed velocity + (v / c) * c

Inputs:

- RA(J2000) in fractional hours
- Dec(J2000) in fractional degrees
- Modified Julian Date (integer)
- UTC in fraction of a day for the first value
- Number of values wanted
- Interval between values in UTC seconds
- note: The directory entry values are lists whose lengths are equal to the number of velocities requested.

Output: {status:, frac:]

- status: number of values returned
- frac: v/c for each time requested

This function returns the observer's position and velocity with respect to the solar system barycenter in J2000 rectangular coordinates.

Inputs:

- Modified Julian Date (integer)
- UTC in fraction of a day for the first value
- Number of values wanted
- Interval between values in UTC seconds
- note: The directory entry values are lists whose lengths are equal to the number of positions requested.

Output: {status:, x:, y:, z:, dx:, dy:, dz:}

- status: number of values returned
- x, y, x in kilometers and dx/dt, dy/dt, dz/dt in km/s

This function returns the topocentric pulse delay with respect to the solar system barycenter for the specified J2000 coordinates and time(s). The delay is in the sense that the time of arrival (TOA) of a pulse is

barycentric TOA = observed TOA + delay

Inputs:

- RA(J2000) in fractional hours
- Dec(J2000) in fractional degrees
- Modified Julian Date (integer)
- UTC in fraction of a day for the first delay
- Number of delays wanted
- Interval between delays in UTC seconds
- note: The directory entry values are lists whose lengths are equal to the number of delays requested.

Output: {status:, delay:}

- status: number of values returned
- delay: Delay in UTC seconds

This function returns the solar system barycentric dynamical time (TDB). This is the time used most often in pulsar timing measurement reductions.

Inputs:

- Modified Julian Date (integer)
- UTC in fraction of a day

Output: {tdb:, tdb_mjd:}

- tdb: TDB in fraction of a day
- tdb_mjd: Corresponding MJD

This function returns the local apparent sidereal time for the specified UTC and date. The observer's longitude is derived from the observer's coordinates as set by set observer coordinates. The default location is the Green Bank Telescope.

Inputs:

- Modified Julian Date (integer)
- UTC in fraction of a day

Output: simple double variable

- LAST in fraction of a day

This function returns the UTC for the specified local apparent sidereal time and date. The observer's longitude is derived from the observaer's coordinates as set by set_observer_coordinates. The default location is the Green Bank Telescope.

Inputs:

- Modified Julian Date (integer)
- LAST in fraction of a day

Output: {utc:, utc_alt:}

- UTC in fraction of a day. Two double precisions numbers are returned since, for 4 minutes out of each day, two UTC's can satisfy the MJD/LAST combination. If the second number, utc_alt, is non-negative, the ambiguity exists, and it contains the second possibility.

This function returns the RA and Dec for the specified epoch and given J2000 coordinates. The correction is for precession and nutation.

Inputs:

- Modified Julian date (integer)
- UTC in fraction of a day
- RA (J2000) in fractional hours
- Dec (J2000) in fractional degrees

Output: {epoch:, ra:, dec:}

- epoch: epoch of returned position in fractions of a year
- ra: RA of epoch in fractional hours
- dec: Dec of epoch in fractional degrees

This function returns the J2000 RA and Dec given the coordinates for the specified epoch. The correction is for precession and nutation.

Inputs:

- Modified Julian date (integer)
- UTC in fraction of a day
- RA (epoch) in fractional hours
- Dec (epoch) in fractional degrees

Output: {ra:, dec:}

- epoch: epoch of returned position (always 2000.0)
- ra: RA of epoch in fractional hours
- dec: Dec of epoch in fractional degrees

This function returns the apparent RA and Dec (corrected for diurinal and annual aberration) given RA and Dec of the present epoch.

Inputs:

- Modified Julian Date (integer)
- UTC in fraction of a day
- RA (present epoch) in fractional hours
- Dec (present epoch) in fractional degrees

Output: {ra:, dec:}

- ra: Apparent RA in fractional hours
- dec: Apparent Dec in fractional degrees

This function returns the RA and Dec of the present epoch corrected for diurinal and annual aberration) given the apparent RA and Dec.

Inputs:

- Modified Julian Date (integer)
- UTC in fraction of a day
- Apparent RA in fractional hours
- Apparent Dec in fractional degrees

Output: {ra:, dec:}

- ra: RA (present epoch) in fractional hours
- dec: Dec (present epoch) in fractional degrees

Sets the observer's (x, y, z) coordinates in meters with respect to the IERS coordinate system. The defaults are the 140-ft coordinates. These coordinates are used whenever the observer's location or velocity is required for a calculation in one of the events described above. The new coordinates are effective until the next set_observer_coordinates call is made or until the module is terminated.

Inputs:

- x component in meters from the earth's center toward the equator/Greenwich meridian intersection
- y component toward the equator 90 degrees east of the Greenwich meridian
- z component from the equatorial plane toward the north pole.

Output: always zero

This function returns the rectangular coordinates of the observer with respect to the earth's center in the J2000 coordinate system. The observer's coordinates on the earth, in the IERS coordinate system, must first be set with the set_observer_coordinates function. The default observer position is Green Bank. A successive series of coordinates may be obtained by specifying the number of points requested and the time interval between the points.

Inputs:

- Modified Julian Date (integer)
- UTC in fraction of a day for the first position
- Number of positions wanted
- Interval between positions in UTC seconds

Output: {x:, y:, z:, x_rate:, y_rate:, z_rate:}

- x component in km from the earth's center toward the vernal equinox
- y component toward the equator 90 degrees east of the vernal equinox
- z component from the equatorial plane toward the north pole.
- x_rate in km per second
- y_rate in km per second
- z_rate in km per second

This function returns the rectangular coordinates of the observer with respect to the solar system barycenter in the J2000 coordinate system. The observer's coordinates on the earth, in the IERS coordinate system, must first be set with the set_observer_coordinates function. The default observer position is Green Bank. A successive series of coordinates may be obtained by specifying the number of points requested and the time interval between the points.

Inputs:

- Modified Julian Date (integer)
- UTC in fraction of a day for the first position
- Number of positions wanted
- Interval between positions in UTC seconds

Output: {x:, y:, z:, x_rate:, y_rate:, z_rate:}

- x component in km from the barycenter toward the vernal equinox
- y component toward the equator 90 degrees east of the vernal equinox
- z component from the equatorial plane toward the north pole.
- x_rate in km per second
- y_rate in km per second
- z_rate in km per second

This function returns the rectangular coordinates of the earth's center with respect to the solar system barycenter in the J2000 coordinate system. A successive series of coordinates may be obtained by specifying the number of points requested and the time interval between the points.

Inputs:

- Modified Julian Date (integer)
- UTC in fraction of a day for the first position
- Number of positions wanted
- Interval between positions in UTC seconds

Output: {x:, y:, z:, x_rate:, y_rate:, z_rate:}

- x component in km from the barycenter toward the vernal equinox
- y component toward the equator 90 degrees east of the vernal equinox
- z component from the equatorial plane toward the north pole.
- x_rate in km per second
- y_rate in km per second
- z_rate in km per second

This function returns the rectangular coordinates of a selected object with respect to the solar system barycenter in the J2000 coordinate system. A successive series of coordinates may be obtained by specifying the number of points requested and the time interval between the points.

Inputs:

- Object name string. Recognized, case-insensitive values are 'Sun', 'Moon', 'Mercury', 'Venus', 'Mars', 'Jupiter', 'Saturn', 'Uranus', 'Neptune', and 'Pluto'.
- Modified Julian Date (integer)
- UTC in fraction of a day for the first position
- Number of positions wanted
- Interval between positions in UTC seconds

Output: {x:, y:, z:, x_rate:, y_rate:, z_rate:}

- x component in km from the barycenter toward the vernal equinox
- y component toward the equator 90 degrees east of the vernal equinox
- z component from the equatorial plane toward the north pole.
- x_rate in km per second
- y_rate in km per second
- z_rate in km per second

This document last updated January 7, 2010