*************************************************************************
* README file for the kepler library					*
* Copyright (C) 2010 Shiva Iyer <shiva.iyer AT g m a i l DOT c o m>    	*
*								      	*
* This program is free software: you can redistribute it and/or modify	*
* it under the terms of the GNU General Public License as published by	*
* the Free Software Foundation, either version 3 of the License, or   	*
* (at your option) any later version.  	       	    		      	*
*									*
* This program is distributed in the hope that it will be useful,	*
* but WITHOUT ANY WARRANTY; without even the implied warranty of	*
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the		*
* GNU General Public License for more details.		    		*
*									*
* You should have received a copy of the GNU General Public License	*
* along with this program.  If not, see <http://www.gnu.org/licenses/>.	*
*************************************************************************

Introduction
------------

This is the kepler library, version 1.0.0. kepler provides a set of routines for
performing astronomical calculations. The library is implemented in ANSI C and
the optional pykepler package provides support for programs written in Python.

The intent is to provide the basic building blocks necessary for more advanced
applications. Consequently, no attempt has been made to provide an user interface
or to write programs that meet various needs (observation, historical research
etc.).

The kepler library is free software, distributed under the terms of the GNU
General Public License <http://www.gnu.org/licenses/gpl.html>.

Prerequisites
-------------

Make sure your Unix installation has the GNU C compiler and build tools
installed. The following are the minimum version requirements.

      * GNU gcc 	4.4.1
      * GNU Make	3.81
      * Python		2.5.5 (needed only if you use the Python interface)

Installation
------------

Instructions for downloading the source archives and accessing the development
repository may be found at <http://savannah.nongnu.org/projects/kepler>.

Run 'make' in the kepler installation directory to compile all the library
files and example programs. In order to call kepler's functions from your own
applications, you will need to create your own makefile along the lines of the
one in the 'examples' subdirectory.

Run 'make install' to deploy the shared library that is created in the previous
step. On most systems, you will need to run this as root. You will need to do
this before you run the example programs or use the pykepler Python package.

Run 'make clean' to remove all the files created by running 'make'. This will not
remove the shared libraries or symbolic links in /usr/lib.

The 'pykepler' subdirectory contains the sources for the pykepler Python package.
This package allows you to call kepler routines from Python.

Documentation
-------------

The C library is documented in the file kepler.html under the 'doc' subdirectory.

The 'pydoc' utility or the help() function in the interactive Python interpreter
may be used to view the documentation for the Python interface.

Examples
--------

The following sample programs may be found in the 'examples' subdirectory:

kepler_test.c calls most of the functions in kepler and displays the results in a
terminal window. To test the routines in mpc_file.c, you must download the MPC
Orbit Database files from <http://www.cfa.harvard.edu/iau/MPCORB.html>.

rise_set.c is a program that accepts some command line arguments and displays
the rise, upper transit and set times for the Sun, Moon, planets and Pluto.
No corrections are made for planetary aberration, nutation, geocentric parallax
or for the motion of the swifter objects (Moon, Mercury, Venus and Mars).
Consequently, the displayed times could be between 3 to 6 minutes in error.

References
----------

kepler is targeted towards users with a sound grasp of positional astronomy.
However, it has been thought fit to include references to the relevant
astronomical literature in the source code.

No work of this nature would be possible without the following standard works on
astronomical algorithms:

  * Explanatory supplement to the Astronomical Almanac by P. Kenneth Seidelmann
  * Astronomical Algorithms by Jean Meeus

Bugs
----

Comments, criticisms and bug reports are very welcome and may be sent to the
kepler maintainer by email or the project's website.

Shiva Iyer
shiva.iyer AT g m a i l DOT c o m
