Python Client for Computing Positions of Planets, Pulsar Pulse Delays, LST, Precession, Nutation and Aberration

Table of Contents

Introduction

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.

object_track(object, mjd, utc, num_pts, interval)

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:

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

object_doppler(object, mjd, utc, num_pts, interval)

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:

Output: {status:, frac:]

doppler_fraction(ra, dec, mjd, utc, num_pts, interval)

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:

Output: {status:, frac:]

observer_position_velocity(mjd, utc, num_pts, interval)

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

Inputs:

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

pulse_delay(ra, dec, mjd, utc, num_pts, interval)

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:

Output: {status:, delay:}

utc_to_tdb(mjd, utc)

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

Inputs:

Output: {tdb:, tdb_mjd:}

utc_to_last(mjd, utc)

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:

Output: simple double variable

last_to_utc(mjd, last)

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:

Output: {utc:, utc_alt:}

j2000_to_epoch(mjd, utc, ra, dec)

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

Inputs:

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

epoch_to_j2000(mjd, utc, ra, dec)

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

Inputs:

Output: {ra:, dec:}

add_aberration(mjd, utc, ra, dec)

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

Inputs:

Output: {ra:, dec:}

remove_aberration(mjd, utc, ra, dec)

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

Inputs:

Output: {ra:, dec:}

set_observer_coordinates(x, y, z)

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:

Output: always zero

geocentric_observer_track(mjd, utc, num_pts, interval)

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:

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

barycentric_observer_track(mjd, utc, num_pts, interval)

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:

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

barycentric_earth_track(mjd, utc, num_pts, interval)

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:

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

barycentric_object_track(object, mjd, utc, num_pts, interval)

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:

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

This document last updated January 7, 2010

rfisher@nrao.edu

Rick Fisher's Home Page