-------------------------
Ephemeris Tools in Python
-------------------------

Author: Ray Buvel
email:  rlbuvel@gmail.com
Last update: Jun 7, 2009

This tool set allows Python users to use the ephemerides made available by the
Jet Propulsion Laboratory (JPL) on their web site:

    http://ssd.jpl.nasa.gov/?planet_eph_export

These tools provide similar functionality to the Fortran tool set provided by
JPL.  However, the interface is a Python class which is easier to use from
within Python than an extension module that wraps the Fortran subroutines.

This tool set is completely implemented in Python so it can be used by anyone
with a functioning Python installation.  There is also an extension module
provided in Pyrex for those who have Pyrex and a C compiler available.  The
Pyrex version is approximately ten times faster than the pure Python
implementation.

---------------
Getting Started
---------------

These tools require Python version 2.2.1 or better and a compatible version of
the Numpy extensions.  If you don't have an appropriate version of Python
installed, go to http://python.org and download the latest.  Numpy can be found
at http://numpy.scipy.org.

The next thing you need to do is download the files corresponding to the
ephemeris you are interested in.  JPL provides these files in two formats:
Unix and ASCII.  The Unix format is a binary format created on a big endian
machine using IEEE-754 floating point numbers.  If your machine uses IEEE-754
floating point, you should be able to use the Unix files regardless of the type
of machine you are running on.  You also need to obtain the testpo.XXX file for
the selected ephemeris.  Please read the instructions on the JPL site.

Now that you have the files, you need to build the ephemeris using one of the
translator scripts.  Use xlatUnix.py for Unix files or xlatAscii.py for ASCII
files.  Note that these scripts automatically concatenate the files in the
correct time sequence based on the JPL naming convention.  You will need to
edit the script to set the ephemeris number and the directory holding the
files.  After editing the script, just run it.  The binary ephemeris file will
be created in your current directory.

Test the ephemeris by editing the script testEphem.py to set the ephemeris
number and specify the location of the test data file testpo.XXX.  This script
prints out progress information and the results of the test.  The important
quantity is the number of tests that fail.  Obviously, this should be zero.

After you have created a binary file for each ephemeris you want to use, it is
time to install the parts you will be using in some central location on your
machine.  Move the binary ephemeris files you created and the files
ephemUtils.py and ephemPy.py to a directory on your Python search path.  You
are now ready to use the ephemeris from your Python programs.

If for some reason (such as other programs not written in Python), you need to
store the binary ephemeris files in another location, you will need to edit
ephemUtils.py to indicate where the files are stored.  As delivered, the module
assumes that the binary files are in the same directory as ephemUtils.py.

-------------------
Using the Ephemeris
-------------------

The script testEphem.py provides a good example of how to use these tools.
Typically, you will want to sub-class the Ephemeris class from the ephemPy
module to provide the data in the form required by your program.  The user
classes and functions are all documented with Python doc strings so you can use
pydoc to get more information.  Normally, the module ephemUtils is not used
directly.  However, there are two functions for handling dates that may be
useful.

--------------------------
Using the Extension Module
--------------------------

Since the interpolation of Chebyshev polynomials requires iterative floating
point calculations, Python can be a little slow.  In the directory "extension",
there is a Pyrex implementation of the Ephemeris class that is a direct
replacement for the one in the ephemPy module.  This version is about ten
times faster than the pure Python implementation.  However, it is not for the
beginner!!  If you want to use this module, you should get some experience
building Python extension modules with Pyrex.  After you get some experience,
it should be obvious how to build the extension.

This version was tested with Pyrex 0.9.7.2 and Python 2.5 on Debian Lenny
(64-bit and 32-bit versions).

NOTE: Previous versions of the extension module do not work on 64-bit systems
due to some type declaration issues.  This was corrected in EphemPy1.3.


Pyrex can be obtained at

    http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex

