pyswisseph-rs

Python bindings for the swisseph-rs crate — a pure-Rust reimplementation of the Swiss Ephemeris.

Why this package? Every method on Ephemeris releases the GIL, so a single shared instance can drive a ThreadPoolExecutor at full core utilization with zero coordination. No global state, no swe_close(), no mutex — just pass the same object to every thread.

pip install pyswisseph-rs     # or: uv add pyswisseph-rs

Quickstart (zero files, Moshier ephemeris)

The built-in Moshier analytical ephemeris covers all planets for any date without ephemeris files. Accuracy is ~1 arc-second for modern dates.

from swisseph_rs import Body, CalcFlags, Ephemeris, EphemerisConfig

eph = Ephemeris(EphemerisConfig())   # Moshier by default, no files needed
result = eph.calc_ut(2451545.0, Body.SUN, CalcFlags.SPEED)

lon, lat, dist, lon_speed, lat_speed, dist_speed = result.data
print(f"Sun longitude at J2000: {lon:.6f}°")

Using Swiss Ephemeris data files

For sub-arc-second precision, point EphemerisConfig at a directory containing the Swiss Ephemeris data files:

from swisseph_rs import Ephemeris, EphemerisConfig, EphemerisSource

eph = Ephemeris(EphemerisConfig(
    ephemeris_source=EphemerisSource.SWISS,
    ephe_path="/path/to/ephe",
))

Data files (sepl*.se1, semo*.se1, seas*.se1, etc.) are available from Astrodienst. Download the files covering your date range and place them in the directory you point ephe_path to.

For JPL ephemerides, set ephemeris_source=EphemerisSource.JPL and optionally jpl_filename="de441.eph".

Threading

pyswisseph-rs is designed for concurrent workloads. Every Ephemeris method releases the GIL around the Rust computation, so multiple Python threads run in true parallel on separate cores.

import concurrent.futures
from swisseph_rs import Body, CalcFlags, Ephemeris, EphemerisConfig

eph = Ephemeris(EphemerisConfig())
bodies = [Body.SUN, Body.MOON, Body.MERCURY, Body.VENUS, Body.MARS,
          Body.JUPITER, Body.SATURN]

def calc_year(year_offset):
    """Calculate daily positions for one year."""
    jd_start = 2451545.0 + year_offset * 365.25
    results = []
    for day in range(365):
        for body in bodies:
            r = eph.calc_ut(jd_start + day, body, CalcFlags.SPEED)
            results.append(r.data[0])  # longitude
    return results

# Same Ephemeris instance shared across all threads — no copies, no locks
with concurrent.futures.ThreadPoolExecutor(max_workers=4) as pool:
    futures = [pool.submit(calc_year, y) for y in range(20)]
    all_results = [f.result() for f in futures]

This consistently achieves near-linear speedup (e.g. ~3.5x on 4 cores). Results are bit-identical to serial execution.

What about multiprocessing?

Ephemeris is not picklable. For process-based parallelism, construct a separate Ephemeris in each worker. But threading is usually the better choice here — there is no GIL contention, so threads give you the speedup without the IPC overhead.

Sidereal mode and topographic position

Configuration that the C library sets via global state (swe_set_sid_mode, swe_set_topo) is passed through EphemerisConfig instead:

from swisseph_rs import (
    Ephemeris, EphemerisConfig, SiderealMode, TopoPosition,
)

eph = Ephemeris(EphemerisConfig(
    sidereal_mode=SiderealMode.LAHIRI,
    topographic=TopoPosition(longitude=-74.006, latitude=40.7128, altitude=10.0),
))

The config is frozen after construction — no mutable global state, no ordering bugs between set_* calls.

Migrating from C pyswisseph

pyswisseph-rs wraps the same Swiss Ephemeris engine but replaces the C library's global-state API with an object-oriented, stateless design. The key differences:

1. No global state. swe_set_ephe_path, swe_set_sid_mode, swe_set_topo become fields on EphemerisConfig. swe_close is unnecessary.
2. Methods on Ephemeris. Functions like swe_calc become eph.calc().
3. Named types. Flags are CalcFlags.SPEED, bodies are Body.SUN, not raw integers.

Every method's docstring includes the corresponding swe_* name. Use help(eph.calc) or check the type stubs for the mapping.

Function mapping (top 25)

Module structure

Free functions live in submodules mirroring the Rust crate's module tree:

from swisseph_rs import date, math, houses, azalt, sidereal_time

Types and flags are re-exported at the top level:

from swisseph_rs import Body, CalcFlags, EphemerisConfig, Ephemeris

Design and transliteration discipline

pyswisseph-rs maintains a strict 1:1 correspondence with the underlying Rust crate's public API. Every Python class, enum, and function mirrors exactly one Rust symbol. This is a deliberate design choice documented in CONTEXT.md and the architecture decision records in docs/adr/:

• ADR 0001 — PyO3 on the lib crate, not the C FFI layer
• ADR 0002 — strict 1:1 transliteration from Rust to Python

License

This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See LICENSE for the full text.

The wheel statically links the swisseph-rs crate, which is a derivative work of the Swiss Ephemeris by Astrodienst AG, also licensed under AGPL-3.0-or-later.