Py ERFA:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- PyERFA v2.0.1.1 »
- Quickstart

# Quickstart

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

The package can be obtained from PyPI or directly from the git repository:

    $ git clone --recursive https://github.com/liberfa/pyerfa/

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