# 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, 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.

## 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`

.

## 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, 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 file.