-
Notifications
You must be signed in to change notification settings - Fork 19
/
README-PyPI
258 lines (194 loc) · 10 KB
/
README-PyPI
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
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/>`_
* `https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/planets/a_old_versions/ <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
<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.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," <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 [email protected] 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
.. _NOVAS FAQ: http://aa.usno.navy.mil/software/novas/novas_faq.php
.. _GitHub repository: https://github.com/brandon-rhodes/python-novas
.. _User’s Guide to NOVAS: https://github.com/brandon-rhodes/python-novas/raw/master/Cdist/NOVAS_C3.1_Guide.pdf
.. _Brandon Rhodes: https://rhodesmill.org/brandon/