novas 3.1.1.6

The United States Naval Observatory NOVAS astronomy library

Welcome

This is United States Naval Observatory software, which they have happily made available for use by the public.

It has been packaged and released on PyPI by Brandon Rhodes to make it easier to install, built from a GitHub repository mirror of the project’s original source code. None of the library’s actual authors are involved with the repository or package; their work is released only through the official NOVAS home page and their official documentation is the User’s Guide to NOVAS PDF.

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 Python package includes both the NOVAS library and the Python wrapper that are available from the NOVAS home page at the United States Naval Observatory. This version includes a few bug fixes and packaging adjustments that are not in the most recent June 2011 release of the software from the Naval Observatory itself. You can find these changes described at the bottom of this page in the Changelog, and you can also review them yourself at the GitHub repository.

Quick Examples

You can download planetary ephemerides from several sources online, including:

• https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/

• https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/a_old_versions/

You can then import the NOVAS Python library and open a planetary ephemeris with:

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

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. 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.6 — 2024 April 27

• Declare compatibility with Python versions through Python 3.12.

• Add arm64 to compile arguments, to support Apple’s M1 platform.

• Fix: equ2hor() docstring said that dec argument should be in hours, whereas it should, in fact, be in degrees.

Version 3.1.1.5 — 2016 December 1

• Declare compatibility with Python versions through Python 3.7.

• Fix: cel_pole() now correctly limits its type argument to the integers 1 and 2, rather than the integers 0 and 1.

Version 3.1.1.3 — 2015 January 23

• Fixed a fatal typo in astro_star() that caused it to always raise ArgumentError: argument 3: <class 'TypeError'>: wrong type

Version 3.1.1.2 — 2013 July 31

• The top-level __init__.py now attempts to load the NOVAS C library from several different filenames under Python 3, instead of only trying filenames with an ABI identifier. (On my Ubuntu 13.04 laptop, Python 3.3 is not in fact including such an identifier, which was causing an ImportError: cannot import name novaslib failure.)

Version 3.1.1.1 — 2013 March 2

Further fixes have been provided by users, so I am making this interim release while the official version still sits at 3.1.

• Leo Singer fixed the wrappers for cal_date() and limb_angle() so these two NOVAS functions can now be used from Python code.

• The example test file checkout-stars-full.py now uses syntax compatible with Python 3, eliminating a warning during install.

• The setup.py now specifies the encoding for this readme, so the package can install on systems where UTF-8 is not the default.

Version 3.1.1 — 2012 November 25

The Naval Observatory has not released a new version of NOVAS since June 2011, but reports and requests from users convinced me to make several small fixes to the code and make an interim release here on the Python Package Index:

• The library is now Python 3 compatible!

• Python code can now access the ephem_close() routine inside the eph_manager module.

• Bugfix: the eph_manager.state() function was always raising an exception if invoked.

• Bugfix: to eph_manager.c as recommended in the NOVAS FAQ.

• Bugfix: to novas.c as recommended in the NOVAS FAQ.

To examine the code changes yourself, visit the GitHub repository.

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,” Bull. AAS, 43, 2011.

The authors of NOVAS ask that if you use their software in your work, that you let them know at [e-mail] 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.