Optional Modules and Calculation Backends #

LibEphemeris works out of the box for planets and luminaries using Skyfield with NASA JPL DE440/441 ephemerides. For minor bodies (asteroids, TNOs, centaurs), multiple calculation backends are available with different precision levels. This guide explains what each optional module provides, when to install it, and how the library selects the best available backend at runtime.

Table of Contents #

• Calculation Backends
• Minor Body Fallback Chain
• Optional Extras
• Data Requirements
• Known Limitations
• Choosing the Right Setup

---

Calculation Backends #

Planets (Sun through Pluto), the Moon, and lunar nodes are served by the active calculation mode (auto, skyfield, leb, or horizons). No optional modules are needed for these bodies.

Minor bodies use a fallback chain of backends, each with different precision and requirements:

For planets, the LEB (LibEphemeris Binary) and Horizons API backends are also available. See Getting Started for ephemeris tier selection and the LEB guide for binary ephemeris details.

---

Minor Body Fallback Chain #

When you call calc_ut() for a minor body, the library tries each backend in order and uses the first one that succeeds:

1. SPK kernel (local file)
     |
     v  not found?
2. Auto-download SPK from JPL Horizons (if enabled)
     |
     v  download failed or body blocked?
3. Strict precision check
     |  If strict_precision=True and body has a downloadable SPK:
     |  raise SPKRequiredError (prevents silent precision loss)
     |
     v  body not strictly required, or strict_precision=False?
4. ASSIST n-body integration (if installed + data available)
     |
     v  not installed?
5. Keplerian propagation (always available, lowest precision)

Enabling auto-download #

import libephemeris as swe

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

SPK files are cached in ~/.libephemeris/spk/ and reused on subsequent calls.

Strict precision mode #

Strict precision (enabled by default) prevents the library from silently falling back to low-precision Keplerian calculations for bodies that have downloadable SPK kernels. When an SPK is missing for such a body, the library raises SPKRequiredError with instructions on how to obtain it.

Bodies for which JPL Horizons does not provide SPK generation (see Known Limitations) are exempt from this check and fall through to ASSIST or Keplerian.

swe.set_strict_precision(False)   # Allow Keplerian fallback for all bodies
swe.set_strict_precision(True)    # Require SPK where available (default)

---

Optional Extras #

nbody – REBOUND/ASSIST n-body integration #

pip install libephemeris[nbody]

Installs REBOUND (N-body integrator) and ASSIST (JPL-quality small body extension). Together they propagate asteroid orbits accounting for:

• Gravitational perturbations from Sun, Moon, and all 8 planets
• 16 massive asteroid perturbers (Ceres, Vesta, Pallas, etc.)
• Earth/Sun gravitational harmonics (J2, J3, J4)
• General relativistic corrections

When you need it: When you require sub-arcsecond precision for asteroids or TNOs and don’t want to manage individual SPK files. Also useful for bodies like Bennu where JPL does not provide auto-downloadable SPK kernels (see Known Limitations).

Data files (~714 MB total, downloaded separately):

libephemeris download assist

See REBOUND Integration for technical details and precision benchmarks.

stars – Star catalog #

pip install libephemeris[stars]

Installs Astropy for building and querying star catalogs. Required for fixed star calculations beyond the built-in named stars.

all – Everything #

pip install libephemeris[all]

Installs all optional runtime dependencies (nbody + stars).

dev – Development tools #

pip install libephemeris[dev]

For contributors only. Includes testing tools (pytest, pyswisseph for cross-validation), code quality (ruff, mypy), SPK generation (spiceypy), and manual building (ebooklib). Not needed for using the library.

---

Data Requirements #

Different setups require different data downloads:

---

Known Limitations #

Bodies without auto-downloadable SPK #

Most of the 37 minor bodies in the SPK map can be automatically downloaded from JPL Horizons. However, some bodies are blocked by JPL:

For Bennu, the library skips the auto-download attempt and the strict precision check, allowing the fallback chain to proceed to ASSIST or Keplerian. If you need sub-arcsecond Bennu positions, install the nbody extra and download ASSIST data.

A mission-specific NAIF kernel (bennu_refdrmc_v1.bsp from OSIRIS-REx, covering 2015-2023) exists and can be registered manually:

import libephemeris as swe

swe.register_spk_body(
    "/path/to/bennu_refdrmc_v1.bsp",
    ipl=swe.SE_BENNU,
    naif_id=2101955,
)
pos, _ = swe.calc_ut(2458849.5, swe.SE_BENNU, 0)  # 2020-01-01

Keplerian precision varies by body class #

These errors grow with distance from the orbital elements epoch. For applications requiring better than arcminute precision, use SPK kernels or ASSIST.

---

Choosing the Right Setup #

Astrology (natal charts, transits): Planets are always high-precision. For the major asteroids (Chiron, Ceres, Pallas, Juno, Vesta), enable auto-download or download SPKs once:

libephemeris download medium

import libephemeris as swe
swe.set_auto_spk_download(True)

Research / high-precision asteroid work: Install the n-body extra for sub-arcsecond precision on all minor bodies:

pip install libephemeris[nbody]
libephemeris download medium
libephemeris download assist

Offline / production deployment: Download everything upfront:

libephemeris download all

Or for fastest calculations, use the precomputed LEB binary ephemeris:

libephemeris download leb2-medium

import libephemeris as swe
from pathlib import Path

swe.set_leb_file(str(Path("~/.libephemeris/leb/medium_core.leb2").expanduser()))