Quickstart

A complete propagation in a dozen lines:

import numpy as np
import empyrean

empyrean.initialize()                              # one-time, loads kernels

orbits = empyrean.query_sbdb(["99942"])            # CometaryOrbits — Apophis
result = empyrean.propagate(
    orbits,
    np.array([60500.0, 61500.0, 62500.0]),         # MJD TDB; spans 2024-07, 2027-04, 2030-01
)

print(f"{len(result.states)} states, "
      f"{len(result.events.summary)} events, "
      f"{len(result.sensitivity)} STMs")

Output structure

PropagationResult bundles three things:

result.states        # CartesianOrbits (one row per epoch × orbit)
result.events        # Events (14 typed sub-tables, one per event kind)
result.sensitivity   # StateSensitivities | None — STMs / STTs per epoch

All three are quivr tables — columnar, PyArrow-backed, parquet-friendly.

Output frame and origin default to EclipticJ2000, heliocentric (Sun-centered), MJD TDB epochs. To get ICRF or SSB-centered output, set frame or transform via transform_coordinates().

Inline configuration

Use the keyword shortcuts when you don’t need a full config object:

result = empyrean.propagate(
    orbits, epochs,
    force_model="basic",                # skip the 16 asteroid perturbers
    uncertainty_method="second_order",  # populate STTs
    num_threads=8,
)

For the full surface, build a PropagationConfig.

Quick reference

You want…	Function
Propagate orbits to target epochs	empyrean.propagate()
Predict observations at observatories	empyrean.generate_ephemeris()
Fit an orbit to observations	empyrean.determine()
Re-fit with a Bayesian prior	empyrean.refine()
Residuals only — no fit	empyrean.evaluate()
Stateful, mask-and-refit OD	empyrean.Session
Impact probability	empyrean.compute_impact_probabilities()
B-plane geometry	empyrean.compute_b_planes()
Convert between coordinate types	empyrean.transform_coordinates()
Body states	empyrean.get_states()
Observatory states	empyrean.get_observer_states()
Pull an orbit from JPL SBDB	empyrean.query_sbdb()
Pull predicted ephemeris from Horizons	empyrean.query_horizons()
Pull observations from MPC	empyrean.query_observations()
Read ADES PSV observations	empyrean.read_ades()
Look up the default data directory	empyrean.default_data_dir()