pyerfa

library2.0.1.5pypypi✓ verified 26d ago

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.

data

pip install pyerfa

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PYERFA

pyerfa

datapythonv2.0.1.5

Install

3.7s avg

Import

276ms

Disk

93MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.1.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.268s · 92.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.7s · import 0.284s · 89MB

93MB installed

● package 93MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

erfa

✓ import erfa

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

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]}")

Debug

Known issues

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

affects: >=2.0.0

breakingNumPy 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.

affects: All versions built against NumPy 1.x when used with NumPy 2.0, and vice-versa. Specifically affects `pyerfa < 2.0.1.3` when used with NumPy 2.0.

gotchaOlder 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.

affects: All versions, particularly `pyerfa >= 2.0.0.3` with `numpy < 1.17`.

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

affects: >=2.0.1

gotchaA 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.

affects: <2.0.1

Errors

Common errors & fixes

RuntimeError: module compiled against API version 0xe but this version of numpy is 0xd

PyERFA was compiled against a different NumPy C API version than the one currently installed in your environment, leading to binary incompatibility. This often happens after NumPy is upgraded or downgraded without reinstalling packages that depend on its C API.

fix

Reinstall pyerfa to ensure it's compiled against your current NumPy version: `pip uninstall pyerfa numpy && pip install numpy pyerfa` or `conda uninstall pyerfa numpy && conda install numpy pyerfa`. If using a specific NumPy version, ensure it's compatible or recompile pyerfa against it.

ModuleNotFoundError: No module named 'erfa'

The `pyerfa` package, which is imported as `erfa`, is not installed in your Python environment or is not accessible in the Python path.

fix

Install the pyerfa package using pip: `pip install pyerfa` or using conda: `conda install -c conda-forge pyerfa`.

ImportError: erfa version X or later must be installed to use Astropy. erfa is not installed.

Astropy, which depends on pyerfa, cannot detect a compatible version of pyerfa, even if pyerfa might appear to be installed. This can occur due to environment issues, conflicting installations, or an outdated pyerfa version that Astropy no longer supports.

fix

Ensure both astropy and pyerfa are updated and compatible by reinstalling them: `pip install --upgrade astropy pyerfa` or `conda update astropy pyerfa`. In some cases, a full reinstallation of the environment might be necessary if conflicts persist. If `pyerfa` was a dependency from a port (e.g., MacPorts), ensure the `py-pyerfa` port is correctly installed.

Upgrade

Version history

2.0.1.5latest on PyPI · released Nov 11, 2024

Audit

Dependencies

numpyrequiredAll C routines are wrapped as NumPy universal functions, and PyERFA has frequent updates related to NumPy compatibility.

setuptools-scmoptionalUsed for version management and building the package.

liberfaoptionalThe underlying C library for which PyERFA provides bindings. It is bundled, but can be optionally used as a system library by setting the PYERFA_USE_SYSTEM_LIBERFA environment variable.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/liberfa/pyerfa ↗

packagehttps://pypi.org/project/pyerfa/ ↗

homepagehttps://pyerfa.readthedocs.io ↗