Getting Started #

Installation #

pip install libephemeris

The PyPI wheel includes a bundled LEB2 base-tier core (~10.6 MB, 14 bodies, 1850-2150). With the default medium tier, LEB2 files are auto-downloaded on first use (~119 MB). Bodies not covered by LEB2 are resolved via Horizons API or Skyfield.

For full offline coverage, download a complete precision tier (DE kernel + planet centers + minor-body SPKs):

libephemeris download medium       # 1550-2650, ~200 MB total — recommended
libephemeris download base         # 1850-2150, lightweight
libephemeris download extended     # -13200 to +17191, full range

Optional Extras #

pip install libephemeris[nbody]   # REBOUND/ASSIST n-body integration for TNOs
pip install libephemeris[stars]   # Star catalog building (astropy)
pip install libephemeris[all]     # Everything

Requirements: Python 3.12+ | skyfield >= 1.54 | pyerfa >= 2.0

Ephemeris Tiers #

DE440 and DE441 have identical precision – DE441 is the extended-range version.

import libephemeris as swe

# Select by tier
swe.set_precision_tier("extended")

# Or by file directly
swe.set_ephemeris_file("de441.bsp")

# Or via environment variable
# export LIBEPHEMERIS_PRECISION=extended
# export LIBEPHEMERIS_EPHEMERIS=de441.bsp

First Calculation #

import libephemeris as swe
from libephemeris.constants import SE_SUN, SE_MOON, SE_MARS, SEFLG_SPEED

jd = swe.julday(2024, 3, 26, 12.0)

# Planet positions with velocity
sun, _ = swe.calc_ut(jd, SE_SUN, SEFLG_SPEED)
moon, _ = swe.calc_ut(jd, SE_MOON, SEFLG_SPEED)
mars, _ = swe.calc_ut(jd, SE_MARS, SEFLG_SPEED)

# Returns: (longitude, latitude, distance, speed_lon, speed_lat, speed_dist)
print(f"Sun:  {sun[0]:.4f} deg, speed {sun[3]:.4f} deg/day")
print(f"Moon: {moon[0]:.4f} deg, speed {moon[3]:.4f} deg/day")
print(f"Mars: {mars[0]:.4f} deg, speed {mars[3]:.4f} deg/day")

House Cusps #

jd = swe.julday(2024, 11, 5, 18.0)

# Placidus houses for Rome (41.9N, 12.5E)
cusps, ascmc = swe.houses(jd, 41.9028, 12.4964, b"P")

print(f"ASC: {ascmc[0]:.4f}")
print(f"MC:  {ascmc[1]:.4f}")
for i, cusp in enumerate(cusps, 1):
    print(f"House {i:2d}: {cusp:.4f}")

Thread Safety #

The global API uses mutable global state (compatible with PySwissEph). For concurrent calculations, use EphemerisContext:

from libephemeris import EphemerisContext, SE_SUN

ctx = EphemerisContext()
ctx.set_topo(12.5, 41.9, 0)
pos, _ = ctx.calc_ut(2451545.0, SE_SUN, 0)

Each context has independent state (sidereal mode, topographic position, LEB reader).

Minor Bodies #

For asteroids and TNOs, JPL SPK kernels provide high precision. Auto-download is supported:

swe.set_auto_spk_download(True)
pos, _ = swe.calc_ut(2460000.0, swe.SE_CHIRON, 0)

Fallback chain: SPK kernel → auto-download → strict precision check → REBOUND/ASSIST → Keplerian propagation.

With strict precision mode (enabled by default), SPKRequiredError is raised for mapped bodies when no SPK is available rather than silently falling back to low-precision Keplerian. Use set_strict_precision(False) to allow the full fallback chain.

See Optional Modules and Calculation Backends for details on the fallback chain, ASSIST n-body integration, and known limitations (e.g., Bennu).