What is NOVAS?
--------------

NOVAS is an integrated package of functions for computing various
commonly needed quantities in positional astronomy.  The package can
supply, in one or two function calls, the instantaneous coordinates of
any star or solar system body in a variety of coordinate systems.  At a
lower level, NOVAS also provides astrometric utility transformations,
such as those for precession_, nutation_, aberration_, parallax_, and
gravitational `deflection of light`_.  The computations are accurate to
**better than one milliarcsecond.** The NOVAS library is an easy-to-use
facility that can be incorporated into data reduction programs,
telescope control systems, and simulations.  The U.S. parts of
*The Astronomical Almanac* are prepared using NOVAS.

This package is the official Python wrapper for the NOVAS C code, and is
released by the United States Naval Observatory on their own web site
under the name **NOVAS_Py**.

This package has been uploaded to the Python Package Index by Brandon
Rhodes <brandon@rhodesmill.org>. Please contact him about any problems
you encounter when trying to make it install, or ask on Stack Overflow,
where he watches for questions that involve Python and astronomy.

Quick Examples
--------------

Importing the library and opening the planetary ephemeris:

>>> from novas import compat as novas
>>> from novas.compat import eph_manager
>>> jd_start, jd_end, number = eph_manager.ephem_open()

Converting a calendar date to a Julian date:

>>> jd_tt = novas.julian_date(2012, 10, 2, 12.0)
>>> jd_tt
2456203.0

Asking where Mars is located in the sky on a given date,
in “astrometric” coordinates of the kind that are used
in printed sky atlases:

>>> mars = novas.make_object(0, 4, 'Mars', None)
>>> ra, dec, dis = novas.astro_planet(jd_tt, mars)
>>> print 'R.A. %d:%02f' % (ra, abs(ra) % 1. * 60.)
R.A. 15:36.176177
>>> print 'dec. %d:%02f' % (dec, abs(dec) % 1. * 60.)
dec. -20:11.951841
>>> print 'distance %f AU' % (dis,)
distance 1.947674 AU

There is more information at the `NOVAS home page`_
and in particular a
`full PDF manual that includes a “Sample Calculations” chapter
<http://aa.usno.navy.mil/software/novas/novas_c/NOVAS_C3.1_Guide.pdf>`_.
Even though the manual is for the C version,
you can generally puzzle out how to make the same calls from Python
if you compare the sample code
to the way that similar calculations are done
in the ``test`` package included inside of ``novas``!

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

Like other packages listed here on the Python Package Index, this
package can be installed with the ``pip`` command. You will need to
install both the library itself as well as a high-accuracy ephemeris
data set, with the DE405 ephemeris being the current default::

    $ pip install novas
    $ pip install novas_de405

Note that the second command may take several minutes to run, depending
on your Internet connection, because the JPL ephemeris that it has to
download is 55 MB in size!

If you are managing a Python project that has a ``setup.py`` or a
``requirements.txt`` file, then instead of running these ``pip``
commands manually you can simply list these two package names alongside
the other packages that you depend on, and let them be installed as part
of your normal project install.

Sanity check: running the tests
-------------------------------

Once the package is installed, you can run its tests with the new
test-discovery feature built-in to Python 2.7. If the tests pass to
extremely high accuracy, then the result should be::

    $ python -m unittest discover novas
    ........................................
    ........................................
    ...........
    ----------------------------------------
    Ran 191 tests in 0.022s

    OK

If you are using an older version of Python, then you can run the tests
with the ``unittest2`` compatibility package instead::

    $ pip install unittest2
    $ unit2 discover novas

Running the tests this way should also result in a pretty field of dots,
followed by the message “OK.”

Contents and Documentation
--------------------------

Successful installation will produce a ``novas`` package that contains
several namespaces full of functions:

``novas.compat``
    Main NOVAS functions.

``novas.constants``
    Important constants.

``novas.nutation``
    Nutation models.

``novas.compat.eph_manager``
    Functions from the NOVAS ``eph_manager.c`` module.

``novas.compat.solsys``
    Functions from the NOVAS ``solsys1.c`` module.

``novas.compat.nutation``
    Functions from the NOVAS ``nutation.c`` module.

You can find more information and documentation on the project's
official `NOVAS home page`_ at the Naval Observatory.

Changelog
---------

Version 3.1.1 — 2012 November 25
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Several improvements now take this version of the library beyond the
Naval Observatory's official “3.1” on which this release is based:
Python 3 compatibility; Python access to the ``ephem_close()`` routine
inside the ``eph_manager`` module; a fix for the ``eph_manager.state()``
function, which previously would always raise an exception if invoked;
and both C code fixes recommended in the `NOVAS FAQ`_, one that changes
the ``eph_manager.c`` file, and the other that changes the ``novas.c``
file.

.. _NOVAS FAQ: http://aa.usno.navy.mil/software/novas/novas_faq.php

Version 3.1 — 2012 September 19
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Initial release of the library on the Python Package Index.

License and Citation
--------------------

This software was produced by the United States Naval Observatory at the
expense of United States taxpayers, and is therefore not suseptible to
copyright, because a copyright would place taxpayer property under
private ownership. Since it is not copyrighted, it cannot be licensed;
it is simply free.

To credit the authors, you are invited to cite their work as follows:

**Barron, E. G., Kaplan, G. H., Bangert, J., Bartlett, J. L., Puatua, W., Harris, W., & Barrett, P. (2011)** `"Naval Observatory Vector Astrometry Software (NOVAS) Version 3.1, Introducing a Python Edition," <http://aa.usno.navy.mil/software/novas/novas_py/novas.pdf>`_ **Bull. AAS, 43, 2011.**

The authors of NOVAS ask that if you use their software in your work,
that you let them know at help@aa.usno.navy.mil since a record of who is
using their software helps them justify the excellent work that they are
doing by making the software available to the public.

.. _precession: http://asa.usno.navy.mil/SecM/Glossary.html#precession
.. _nutation: http://asa.usno.navy.mil/SecM/Glossary.html#nutation
.. _aberration: http://asa.usno.navy.mil/SecM/Glossary.html#aberration
.. _parallax: http://asa.usno.navy.mil/SecM/Glossary.html#parallax
.. _deflection of light: http://asa.usno.navy.mil/SecM/Glossary.html#deflection-light
.. _webpage: http://ssd.jpl.nasa.gov/?planet_eph_export
.. _unittest2 module: http://pypi.python.org/pypi/unittest2
.. _NOVAS home page: http://aa.usno.navy.mil/software/novas/novas_py/novaspy_intro.php
