{"id":2685,"library":"pyerfa","title":"Pyerfa","description":"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.","status":"active","version":"2.0.1.5","language":"en","source_language":"en","source_url":"https://github.com/liberfa/pyerfa","tags":["astronomy","scientific-computing","physics","numpy","c-bindings"],"install":[{"cmd":"pip install pyerfa","lang":"bash","label":"Install Pyerfa"}],"dependencies":[{"reason":"All C routines are wrapped as NumPy universal functions, and PyERFA has frequent updates related to NumPy compatibility.","package":"numpy","optional":false},{"reason":"Used for version management and building the package.","package":"setuptools-scm","optional":true},{"reason":"The 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.","package":"liberfa","optional":true}],"imports":[{"note":"The package can be imported as 'erfa', which exposes all ERFA ufuncs, constants, and NumPy dtypes.","symbol":"erfa","correct":"import erfa"}],"quickstart":{"code":"import erfa\n\n# Convert Julian Date to Calendar Date\njulian_date = 2460000.0\ncalendar_result = erfa.jd2cal(julian_date, [0]) # The second argument is for fractional days, here 0 for simplicity\nprint(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]}\")\n\n# Example of a planet's heliocentric position and velocity\n# erfa.plan94(jd1, jd2, planet_id) where jd1+jd2 is Julian Date, planet_id (1=Mercury, ..., 9=Pluto)\nposition_velocity = erfa.plan94(julian_date, 0.0, 1) # Mercury\nprint(f\"Mercury's position (x, y, z): {position_velocity['p'][0]}\")\nprint(f\"Mercury's velocity (vx, vy, vz): {position_velocity['v'][0]}\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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`.","severity":"breaking","affected_versions":">=2.0.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.","message":"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.","severity":"breaking","affected_versions":"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."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, particularly `pyerfa >= 2.0.0.3` with `numpy < 1.17`."},{"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.","message":"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.","severity":"gotcha","affected_versions":">=2.0.1"},{"fix":"Upgrade to `pyerfa v2.0.1` or later to mitigate this issue and ensure stable behavior, particularly in optimized builds.","message":"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.","severity":"gotcha","affected_versions":"<2.0.1"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}