========================================================
README file for the ephemeris.com JPL ephemeris software

                      Version 1.0
                      22 May 2004
========================================================


This package is a set of C routines and example programs
to access and use the data in the JPL ephemerides.  For
the latest version, check

     http://www.ephemeris.com/software/

The JPL DE405 ephemeris is available online at

     ftp://ssd.jpl.nasa.gov/pub/eph/export/

JPL ephemerides DE200, DE405, and DE406 are available on
CD from Willmann-Bell publishers, at

     http://www.willbell.com/

This software should run as is on any Unix/Linux or other
platform with Gnu's C compiler (gcc), as long as it uses IEEE
floating point representation for double precision numbers.
That is the floating point format of the binary ephemeris files.
If you're not sure about your machine, see the "make test" section
below.  If your machine uses a Pentium or Power PC processor,
it uses IEEE floating point.

This is free software; you can redistribute it and/or modify it under
the terms of version 2.1 of the GNU Lesser General Public License as
published by the Free Software Foundation.

This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MER-
CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
General Public License for more details.  This is in the LICENSE.txt
file in this software distribution.

You should have received a copy of the GNU Lesser General Public
License along with this package; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
USA or see http://www.gnu.org/copyleft/lesser.html on the web.

If you do use this software in your own product, I'd appreciate your
mentioning that you use "the ephmeris.com software library" in your
documentation.

Please send mail to bugs@ephemeris.com to report any bugs.


=====================
SOFTWARE INSTALLATION
=====================
To compile all programs, just type

     make

There is no need to edit any files.  The programs should
run as is with any binary JPL ephemeris.

To both compile and install the software and Unix man pages:

1) Set the variable INSTALLDIR in file Makefile to
   the installation directory (by default, this is
   /usr/local/bin).
2) Set the variable MAN1DIR in file Makefile to the 
   directory where you want section 1 Unix man pages
   installed (by default ths is /usr/local/man/man1).
3) Type

     make install

4) To then remove object files (if you want), type

     make clean

To fully test software operation, you'll need the JPL
ephemeris CD from Willmann-Bell (and about 1.3 Gigabytes more
of free disk space for test output files).  Set the variable
JPLDIR to the directory containing the JPL ephemeris
files from the CD.  Then type

     make test

This will test operation with DE200, DE405, and DE406,
storing the results in a subdirectory named 'test'.
The Makefile creates this directory if it doesn't exist,
and removes files that were there if it does exist.
On a 1.7 GHz Pentium running Linux, this takes 11 minutes.

The tests convert all JPL binary ephemeris files into
ASCII files, back into binary files, and compare the results.
The tests also read the JPL TESTPO files to test for proper
interpolation.

If all you have is DE405 from the JPL FTP site, type

     make test405


====================
STAND ALONE PROGRAMS
====================
The following standalone programs are in this distribution.
They are compiled if you type 'make', and compiled and
installed along with man pages if you type 'make install'.
Consult the man pages or converted HTML pages for more
information on how to use these programs.

     eph2eph  - converts one or two binary ephemeris files
                into a third binary ephemeris file (this
                is similar to JPL's binshort.f and binmerge.f
                combined).
     eph2asc  - converts a binary ephemeris file into an ASCII
                header file and an ASCII data block file.
     asc2eph  - converts an ASCII header file and ASCII data
                block file to a binary ephemeris file.
     testeph  - interpolates positions in an ephemeris and
                compares results with JPL's TESTPO files from
                the JPL CD.
     headcmp  - prints two binary ephemeris headers formatted
                side by side to check for differences.
     ephcmp   - checks two binary ephemeris files for differences
                between constant values and data block values.
     ephcoeff - prints a binary ephemeris data block for a given
                Julian Day, printing a parsed, formatted output.
     vtransit - example program to adjust for Delta T and
                interpolate position of the 8 June 2004 Venus
                transit at mid-transit in rectangular coordinates.

The programs use three auxiliary files.

     gnulliver.c - routines to figure out the Big-endian/
                   Little-endian (and probably even VAX-endian)
                   byte order of a machine and swap bytes
                   to match network/Big-endian order (the
                   order of JPL's binary data).  These
                   routines are called within ephcom.c
                   library routines.  To write standalone
                   programs of your own, you won't need to
                   separately call any gnulliver routines.

     ephcom.h    - common definitions and structures.  Two
                   structures are defined here that are used
                   throughout the software:

                   ephcom_Header - data in an ephemeris header.
                   ephcom_Coords - interpolated positions of
                                   all bodies for a given time.

     ephcom.c    - the library of ephemeris routines (see the
                   ephcom.c file and example programs for more
                   on using these routines):

                   ephcom_readascii_header()   - read an ASCII header
                   ephcom_readascii_block()    - read an ASCII data block
                   ephcom_writeascii_header()  - write an ASCII header
                   ephcom_writeascii_block()   - write an ASCII data block
                   ephcom_readbinary_header()  - read a binary header
                   ephcom_readbinary_block()   - read a binary data block
                   ephcom_writebinary_header() - write a binary header
                   ephcom_writebinary_block()  - write a binary data block
                   ephcom_parse_block()        - print parsed binary data block
                   ephcom_nxtgrp()             - get next GROUP in ASCII header
                   ephcom_outdouble()          - write binary double precision
                   ephcom_outint()             - write binary integer
                   ephcom_indouble()           - read binary double precision
                   ephcom_inint()              - read binary integer
                   ephcom_doublstrc2f()        - convert C double format to FORTRAN
                   ephcom_pleph()              - compute object position & velocity
                   ephcom_get_coords()         - get all coordinates for a date
                   ephcom_cheby()              - perform Chebyshev interpolation
                   ephcom_jd2cal()             - convert Julian Day to calendar date
                   ephcom_cal2jd()             - convert calendar date to Julian Day


=============================
CHANGES FROM THE JPL SOFTWARE
=============================
If you've been using the JPL FORTRAN software, you will
notice a little similarity and a lot of difference between
this package and the JPL routines.  Some were necessary
by the nature of C, but most were design changes.

* COMMON blocks and many FORTRAN subroutine parameters
  have been converted to two C structures, ephcom_Header and
  ephcom_Coords, and they are defined in 'ephcom.h'.  There
  are no global variables.

* There is no FSIZER1(), FSIZER2(), or FSIZER3().  The ephcom.c
  routines read the ipt[][] and lpt[] index pointers in a header to
  determine the number of coefficients in an ephemeris, so you
  don't need to modify anything to read a new ephemeris file.

* There is no LIST array.  All positions and velocities for all
  objects on a given Julian Day are calculated at the same time.
  This takes less than 1 millisecond on a 1.5 GHz Pentium running
  Linux.

* There is no SPLIT().  Time in coords.et2[] is stored as
  coords.et2[0] = whole Julian Day, coords.et2[1] = fractional JD.

* There are no PVSUN or PNUT arrays.  Their coordinates are stored
  in pv[EPHCOM_SUN][] and pv[EPHCOM_NUTATION][], respectively.
  Libration is stored in pv[EPHCOM_LIBRATION][].

* CONST() has become ephcom_readascii_header() and
  ephcom_readbinary_header().

* There is no SELCON() subroutine; all constant names and values
  for a given header are stored in the header structure.

* STATE() and INTERP() have become ephcom_get_coords() and
  ephcom_cheby().  Whereas INTERP() is given an entire data block,
  ephcom_cheby() is only given coefficients for the current
  subinterval for the desired object.

* ephcom_cheby(), the Chebyshev interpolation routine, is given
  one double precision time normalized over the interval [-1,1],
  calculated from two double precision numbers stored in coords.et2[].
  It is not given two double precision numbers for time as in JPL's
  INTERP(), but the time only spans the desired subinterval, whereas
  with JPL's software the time is the entire Julian Day number.  For
  DE405 (with 32 day block spans), passing the entire date requires

       ceiling(log2(2500000 / 32)) = 17 bits more.

  For a 32-day subinterval using IEEE double precision floating point
  (1 sign bit + implied leading '1' bit + 52 mantissa bits), ephcom_cheby()
  time represents the limits of +/- 16 days (+/- 2^4 days) as:

       one sign bit
     + an implied leading '1' for the high order day bit
     + 3 remaining bits for the day, taken from the mantissa

  This leaves 52 - 3 = 49 mantissa bits for a fractional day.

       2^(-49) * 24 * 60 * 60 seconds = 0.153 nanoseconds.

  The worst-case time granularity of the interpolation should
  therefore be 0.153 nanoseconds.  If this does not suffice for
  some application, send a report to bugs@ephemeris.com.

* All coordinates (including those of the Moon) are converted to
  Solar System Barycentric coordinates, except of course nutations
  and librations.  The original geocentric Moon position and
  velocity is preserved in pv[EPHCOM_GEOMOON][] but never used
  by any of the example programs.  The 'testeph' program passes
  perfectly with the converted Solar System Barycentric Moon
  positions, but that only checks differences to 10^(-13).

* There are two unit conversion parameters for coordinates, not
  one (KM) as with JPL's software (note that the default is AU/day
  if both are zero):

     km=0: length is AU;          km=1: length is kilometers
     seconds=0: time is in days;  seconds=1: time is in seconds

  In JPL's software, setting KM to .TRUE. would convert length to
  kilometers and time to seconds.  The raw JPL ephemeris data itself
  is in kilometers/day (not kilometers/second).

* Before calling pleph() to compute rectangular coordinate
  distance and velocity between two objects, you must first call
  ephcom_get_coords(), which computes Solar System Barycentric
  positions and velocities at a given time.  This differs from
  JPL's PLEPH(), which itself directly calls STATE().

* FORTRAN double precision values are written in ASCII with an
  exponent indicator of 'D', not 'E'.  C uses 'E' for both single
  and double precision.  There is no way to reconcile these two.
  All ASCII ephemeris files write floating point numbers with a
  'D' exponent indicator, for compatibility with FORTRAN routines
  that might read the data.


===========================
JPL EPHEMERIS MODIFICATIONS
===========================
Some changes can be made to the original JPL header files.  All
changes were sanctioned by the creator of the JPL ephemerides,
Myles Standish.

* The last data block in a JPL binary ephemeris file is repeated
  once.  The ephemeris.com routines see that the time is the same
  as the next to last block, and ignore the final block.

* Most JPL ephemeris files give the ephemeris number as both the
  DE number and the Lunar Ephemeris (LE) number.  Some just use
  DE for both.  The ephemeris.com software writes the first title
  line as 'DEaaa/LEbbb', where aaa is taken from header.denum, and
  bbb is taken from header.lenum.

* The third header title line, which gives the ending Julian Day,
  ends exactly one block (32 or 64 days) after the actual ending
  day of the file.  The ephemeris.com routines that write binary
  and ASCII ephemeris headers regenerate the three title lines
  before writing them, by using the start and stop Julian Days
  in header.ss[0] and header.ss[1].  You'll notice this difference
  in the ASCII header files -- it is not a bug in the ephemeris.com
  routines.

* If there are no coefficients for an object in ipt[] or in lpt,
  then the first number in ipt or lpt for that object is set to the
  next available index location; it is not zero.  Some of the ephemeris
  files from JPL have zero in this location, and some have the next
  available index location.  Myles Standish indicated that the
  preferred format is to contain the next available location.

* Locations that aren't used at the end of the first and second block
  of a binary ephemeris file (the two header blocks) are filled with
  zeroes.  Some JPL binary ephemeris files contain non-zero data
  in these locations.

* The ephemeris.com eph2eph program can be used to remove the
  inconsistencies in an original JPL binary ephemeris file.  For
  example,

       eph2eph UNIX.405 UNIX.405 neweph.405

  will use JPL's UNIX.405 binary DE405 ephemeris from beginning to
  end as the single ephemeris file for input, and write a new ephemeris
  to neweph.405.


==========
WHAT NEXT?
==========
You've got a bunch of ultra-accurate rectangular coordinates -- now what?

More software exists, but hasn't been rigorously tested.  If you've
written software that uses the ephemeris.com package and would like
to contribute to it, send a report to bugs@ephemeris.com.  Also look
for new developments at

     http://www.ephemeris.com/software/

In the meantime, the U.S. Naval Observatory's "The Astronomical Almanac"
for the current year now gives instructions on converting rectangular
coordinates to topocentric coordinates, adjusted for light travel,
relativistic effects of the Sun, refraction, etc., along with tables of
positions for you to compare your results.  You can order the Almanac
online at http://www.amazon.com/.

Willmann-Bell also sells the book "Fundamental Ephemeris Computations"
that includes another (non-free) software package written in BASIC and C.
Their website is http://www.willbell.com/.
