1====== 2PyERFA 3====== 4 5|PyPI Status| |Zenodo| |Travis Status| |Documentation Status| 6 7PyERFA is the Python_ wrapper for the ERFA_ library (Essential Routines for 8Fundamental Astronomy), a C library containing key algorithms for astronomy, 9which is based on the SOFA library published by the International Astronomical 10Union (IAU). All C routines are wrapped as Numpy_ `universal functions 11<https://numpy.org/devdocs/reference/ufuncs.html>`_, so that they can be 12called with scalar or array inputs. 13 14The project is a split of ``astropy._erfa`` module, developed in the 15context of Astropy_ project, into a standalone package. It contains 16the ERFA_ C source code as a git submodule. The wrapping is done 17with help of the Jinja2_ template engine. 18 19If you use this package in your research, please cita it via DOI 20`10.5281/zenodo.3940699 <https://doi.org/10.5281/zenodo.3940699>`_. 21 22.. Installation 23 24Installation instructions 25------------------------- 26 27The package can be installed from the package directory using a simple:: 28 29 $ pip install . 30 31and similarly a wheel_ can be created with:: 32 33 $ pip wheel . 34 35.. note:: If you already have the C library ``liberfa`` on your 36 system, you can use that by setting environment variable 37 ``PYERFA_USE_SYSTEM_LIBERFA=1``. 38 39 40.. _wheel: https://github.com/pypa/wheel 41 42 43Testing 44------- 45 46For testing, one can install the packages together with its testing 47dependencies and then test it with:: 48 49 $ pip install .[test] 50 $ pytest 51 52Alternatively, one can use ``tox``, which will set up a separate testing 53environment for you, with:: 54 55 $ tox -e test 56 57 58Usage 59----- 60 61The package can be imported as ``erfa`` which has all ERFA_ ufuncs wrapped with 62python code that tallies errors and warnings. Also exposed are the constants 63defined by ERFA_ in `erfam.h 64<https://github.com/liberfa/erfa/blob/master/src/erfam.h>`_, as well 65as `numpy.dtype` corresponding to structures used by ERFA_. Examples:: 66 67 >>> import erfa 68 >>> erfa.jd2cal(2460000., [0, 1, 2, 3]) 69 (array([2023, 2023, 2023, 2023], dtype=int32), 70 array([2, 2, 2, 2], dtype=int32), 71 array([24, 25, 26, 27], dtype=int32), 72 array([0.5, 0.5, 0.5, 0.5])) 73 >>> erfa.plan94(2460000., [0, 1, 2, 3], 1) 74 array([([ 0.09083713, -0.39041392, -0.21797389], [0.02192341, 0.00705449, 0.00149618]), 75 ([ 0.11260694, -0.38275202, -0.21613731], [0.02160375, 0.00826891, 0.00217806]), 76 ([ 0.13401992, -0.37387798, -0.21361622], [0.0212094 , 0.00947838, 0.00286503]), 77 ([ 0.15500031, -0.36379788, -0.21040601], [0.02073822, 0.01068061, 0.0035561 ])], 78 dtype={'names':['p','v'], 'formats':[('<f8', (3,)),('<f8', (3,))], 'offsets':[0,24], 'itemsize':48, 'aligned':True}) 79 >>> erfa.dt_pv 80 dtype([('p', '<f8', (3,)), ('v', '<f8', (3,))], align=True) 81 >>> erfa.dt_eraLDBODY 82 dtype([('bm', '<f8'), ('dl', '<f8'), ('pv', [('p', '<f8', (3,)), ('v', '<f8', (3,))])], align=True) 83 >>> erfa.DAYSEC 84 86400.0 85 86It is also possible to use the ufuncs directly, though then one has to 87deal with the warning and error states explicitly. For instance, compare:: 88 89 >>> erfa.jd2cal(-600000., [0, 1, 2, 3]) 90 Traceback (most recent call last): 91 ... 92 ErfaError: ERFA function "jd2cal" yielded 4 of "unacceptable date (Note 1)" 93 >>> erfa.ufunc.jd2cal(-600000., [0, 1, 2, 3]) 94 (array([-1, -1, -1, -1], dtype=int32), 95 ..., 96 array([-1, -1, -1, -1], dtype=int32)) 97 98 99License 100------- 101 102PyERFA is licensed under a 3-clause BSD style license - see the 103`LICENSE.rst <LICENSE.rst>`_ file. 104 105 106.. References 107.. _Python: https://www.python.org/ 108.. _ERFA: https://github.com/liberfa/erfa 109.. _Numpy: https://numpy.org/ 110.. _Astropy: https://www.astropy.org 111.. _Jinja2: https://palletsprojects.com/p/jinja/ 112.. |PyPI Status| image:: https://img.shields.io/pypi/v/pyerfa.svg 113 :target: https://pypi.python.org/pypi/pyerfa 114 :alt: PyPI Status 115.. |Zenodo| image:: https://zenodo.org/badge/261332899.svg 116 :target: https://zenodo.org/badge/latestdoi/261332899 117 :alt: DOI 10.5281/zenodo.3940699 118.. |Travis Status| image:: https://img.shields.io/travis/liberfa/pyerfa/master?logo=travis%20ci&logoColor=white&label=Travis%20CI 119 :target: https://travis-ci.org/liberfa/pyerfa 120 :alt: Travis CI Status 121.. |Documentation Status| image:: https://img.shields.io/readthedocs/pyerfa/latest.svg?logo=read%20the%20docs&logoColor=white&label=Docs&version=stable 122 :target: http://pyerfa.readthedocs.org/en/stable/?badge=stable 123 :alt: Documentation Status 124