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
|
======
PyERFA
======
PyERFA is the Python_ wrapper for the ERFA_ library (Essential Routines for
Fundamental Astronomy), a C library containing key algorithms for astronomy,
which is based on the SOFA library published by the International Astronomical
Union (IAU). All C routines are wrapped as Numpy_ `universal functions
<https://numpy.org/devdocs/reference/ufuncs.html>`_, so that they can be
called with scalar or array inputs.
The project is a split of ``astropy._erfa`` module, developed in the
context of Astropy_ project, into a standalone package. It contains
the ERFA_ C source code as a git submodule. The wrapping is done
with help of the Jinja2_ template engine.
If you use this package in your research, please cita it via DOI
`10.5281/zenodo.3940699 <https://doi.org/10.5281/zenodo.3940699>`_.
.. Installation
Installation instructions
-------------------------
The package can be installed from the package directory using a simple::
$ pip install .
and similarly a wheel_ can be created with::
$ pip wheel .
.. note:: If you already have the C library ``liberfa`` on your
system, you can use that by setting environment variable
``PYERFA_USE_SYSTEM_LIBERFA=1``.
.. _wheel: https://github.com/pypa/wheel
The package can be obtained from PyPI_ or directly from the git repository::
$ git clone --recursive https://github.com/liberfa/pyerfa/
The package also has nightly wheel that can be obtained as follows::
$ pip install --upgrade --index-url https://pypi.anaconda.org/liberfa/simple pyerfa --pre
Testing
-------
For testing, one can install the packages together with its testing
dependencies and then test it with::
$ pip install .[test]
$ pytest
Alternatively, one can use ``tox``, which will set up a separate testing
environment for you, with::
$ tox -e test
Usage
-----
The package can be imported as ``erfa`` which has all ERFA_ ufuncs wrapped with
python code that tallies errors and warnings. Also exposed are the constants
defined by ERFA_ in `erfam.h
<https://github.com/liberfa/erfa/blob/master/src/erfam.h>`_, as well
as `numpy.dtype` corresponding to structures used by ERFA_. Examples::
>>> import erfa
>>> erfa.jd2cal(2460000., [0, 1, 2, 3])
(array([2023, 2023, 2023, 2023], dtype=int32),
array([2, 2, 2, 2], dtype=int32),
array([24, 25, 26, 27], dtype=int32),
array([0.5, 0.5, 0.5, 0.5]))
>>> erfa.plan94(2460000., [0, 1, 2, 3], 1)
array([([ 0.09083713, -0.39041392, -0.21797389], [0.02192341, 0.00705449, 0.00149618]),
([ 0.11260694, -0.38275202, -0.21613731], [0.02160375, 0.00826891, 0.00217806]),
([ 0.13401992, -0.37387798, -0.21361622], [0.0212094 , 0.00947838, 0.00286503]),
([ 0.15500031, -0.36379788, -0.21040601], [0.02073822, 0.01068061, 0.0035561 ])],
dtype={'names': ['p', 'v'], 'formats': [('<f8', (3,)), ('<f8', (3,))], 'offsets': [0, 24], 'itemsize': 48, 'aligned': True})
>>> erfa.dt_pv
dtype([('p', '<f8', (3,)), ('v', '<f8', (3,))], align=True)
>>> erfa.dt_eraLDBODY
dtype([('bm', '<f8'), ('dl', '<f8'), ('pv', [('p', '<f8', (3,)), ('v', '<f8', (3,))])], align=True)
>>> erfa.DAYSEC
86400.0
It is also possible to use the ufuncs directly, though then one has to
deal with the warning and error states explicitly. For instance, compare::
>>> erfa.jd2cal(-600000., [0, 1, 2, 3])
Traceback (most recent call last):
...
ErfaError: ERFA function "jd2cal" yielded 4 of "unacceptable date (Note 1)"
>>> erfa.ufunc.jd2cal(-600000., [0, 1, 2, 3])
(array([-1, -1, -1, -1], dtype=int32),
...,
array([-1, -1, -1, -1], dtype=int32))
License
-------
PyERFA is licensed under a 3-clause BSD style license - see the
`LICENSE.rst <LICENSE.rst>`_ file.
.. References
.. _Python: https://www.python.org/
.. _ERFA: https://github.com/liberfa/erfa
.. _Numpy: https://numpy.org/
.. _Astropy: https://www.astropy.org
.. _PyPI: https://pypi.org/project/pyerfa/
.. _Jinja2: https://palletsprojects.com/p/jinja/
|
