Pyerfa

2.0.1.5 · active · verified Fri Apr 10

PyERFA provides Python bindings for the ERFA library (Essential Routines for Fundamental Astronomy), a C library based on the IAU SOFA library. It wraps ERFA's C routines as NumPy universal functions, allowing them to be called with scalar or array inputs. The library is actively maintained, with frequent patch releases addressing compatibility, especially with NumPy versions. The current version is 2.0.1.5.

Warnings

breaking PyERFA 2.0.0 introduced a significant breaking change: it cannot run with previous versions of the `liberfa` C library due to an update to `liberfa v2.0.0`. Ensure that the `pyerfa` and `liberfa` versions are compatible, especially if attempting to use a system-installed `liberfa`.
Fix: Upgrade `pyerfa` to its latest version, which bundles a compatible `liberfa`. If using a system `liberfa` (via `PYERFA_USE_SYSTEM_LIBERFA=1`), ensure it is `liberfa v2.0.0` or later for `pyerfa >= 2.0.0`.
breaking NumPy 2.0 introduces Application Binary Interface (ABI) breaking changes. This means `pyerfa` binaries built against NumPy 1.x will not work with NumPy 2.0, potentially causing `ImportError` due to binary incompatibility. PyERFA has released specific versions (`2.0.1.3`, `2.0.1.4`) to provide wheels compatible with both NumPy 1.x and 2.0.
Fix: Always use the latest `pyerfa` version (>=2.0.1.3) with pre-built wheels that support the specific NumPy version in your environment. If building from source, ensure you build against your target NumPy version. Consider creating isolated environments to manage dependencies.
gotcha Older NumPy versions might not be compatible with recent `pyerfa` releases. For instance, `pyerfa 2.0.0.3` explicitly ensured compatibility with `numpy >= 1.17`. Using `pyerfa` with very old NumPy versions can lead to build or runtime errors.
Fix: Ensure your NumPy installation meets the minimum requirements of your `pyerfa` version. It is generally recommended to use a recent, well-supported version of NumPy.
gotcha Since `v2.0.1`, PyERFA transitioned to using only the Python limited API. While this generally improves forward compatibility, it might affect very specialized integrations that rely on specific Python-C API details not exposed by the limited API.
Fix: Most users will not be affected. If you are developing extensions or advanced integrations with `pyerfa` at the C level, be aware of the limited API constraints.
gotcha A dangling pointer issue was fixed in `pyerfa v2.0.1` that could lead to unexpected behavior, especially when compiling projects that use `pyerfa` with the `-O3` optimization flag.
Fix: Upgrade to `pyerfa v2.0.1` or later to mitigate this issue and ensure stable behavior, particularly in optimized builds.

Install

pip install pyerfa Install Pyerfa

Imports

erfa
```
import erfa
```
The package can be imported as 'erfa', which exposes all ERFA ufuncs, constants, and NumPy dtypes.

Quickstart

This quickstart demonstrates how to import `erfa` and use two common functions: `jd2cal` for Julian Date to calendar conversion and `plan94` to get a planet's heliocentric position and velocity.

import erfa

# Convert Julian Date to Calendar Date
julian_date = 2460000.0
calendar_result = erfa.jd2cal(julian_date, [0]) # The second argument is for fractional days, here 0 for simplicity
print(f"Julian Date {julian_date} corresponds to year={calendar_result.iy[0]}, month={calendar_result.im[0]}, day={calendar_result.id[0]}, fraction={calendar_result.fd[0]}")

# Example of a planet's heliocentric position and velocity
# erfa.plan94(jd1, jd2, planet_id) where jd1+jd2 is Julian Date, planet_id (1=Mercury, ..., 9=Pluto)
position_velocity = erfa.plan94(julian_date, 0.0, 1) # Mercury
print(f"Mercury's position (x, y, z): {position_velocity['p'][0]}")
print(f"Mercury's velocity (vx, vy, vz): {position_velocity['v'][0]}")

view raw JSON →