====== PyERFA

|PyPI Status| |Zenodo| |CI Status| |Documentation Status|

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/ .. |PyPI Status| image:: https://img.shields.io/pypi/v/pyerfa.svg :target: https://pypi.python.org/pypi/pyerfa :alt: PyPI Status .. |Zenodo| image:: https://zenodo.org/badge/261332899.svg :target: https://zenodo.org/badge/latestdoi/261332899 :alt: DOI 10.5281/zenodo.3940699 .. |CI Status| image:: https://github.com/liberfa/pyerfa/workflows/CI/badge.svg :target: https://github.com/liberfa/pyerfa/actions :alt: GitHub Actions CI Status .. |Documentation Status| image:: https://img.shields.io/readthedocs/pyerfa/latest.svg?logo=read%20the%20docs&logoColor=white&label=Docs&version=stable :target: https://pyerfa.readthedocs.io/en/stable/?badge=stable :alt: Documentation Status