*************************************************************************
* README file for the kepler library					*
* Copyright (C) 2016 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.6.5 (needed only if you use the Python interface)

kepler can also be used with Microsoft Windows provided you have MinGW and
MSYS installed. These tools may be downloaded from <http://www.mingw.org/>.

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

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

Run 'make target={posix|windows}' 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 target={posix|windows} 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. On Windows, please copy src/libkepler.dll manually to your
application or Windows system directory.

Run 'make target={posix|windows} 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 command-line arguments and displays
the rise, transit and setting times for the Sun, Moon, planets and Pluto.

planpos.py demonstrates the Python wrapper by calling routines in the
VSOP, ELP and Pluto modules to display the positions of the Sun, Moon,
planets and Pluto at the time specified on the command-line.

flightseg.py displays the great circle distance and bearing angles for
flight segments between the airports specified on the command line.
The airport database from <http://openflights.org/data.html> must be
downloaded into the examples folder.

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
  * "Celestial Mechanics" by Forest Ray Moulton
  * "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