API reference

Pipeline entry points

empyrean.propagate	Propagate orbits to target epochs.
empyrean.generate_ephemeris	Generate predicted ephemeris (RA/Dec) for orbits at observer locations.
empyrean.determine	Run the full orbit determination pipeline (IOD + DC).
empyrean.evaluate	Evaluate residuals for an orbit against observations.
empyrean.refine	Refine an orbit with new observations using a Bayesian prior.
empyrean.transform_coordinates	Transform coordinates to a different representation, frame, or origin.
empyrean.get_states	Query Cartesian states of a body from the SPK ephemeris.
empyrean.get_observer_states	Compute observer Cartesian states in ICRF relative to SSB.
empyrean.compute_impact_probabilities	Run impact-probability detection over a propagation window with one full propagation per supplied UncertaintyMethod.
empyrean.compute_b_planes	Run B-plane breakdown extraction over a propagation window with one full propagation per supplied UncertaintyMethod.

I/O helpers

empyrean.query_sbdb	Query JPL SBDB for orbital elements with covariance.
empyrean.query_horizons	Query JPL Horizons for observer-table ephemerides.
empyrean.query_observations	Fetch ADES observation records from the MPC for one or more designations.
empyrean.read_ades	Read ADES PSV observations into optical + radar tables.
empyrean.initialize	Initialize empyrean with SPICE kernel data.
empyrean.download_data	Download all required SPICE kernel files.
empyrean.default_data_dir	Return the OS-appropriate XDG data directory empyrean uses by default.

Coordinates & orbits

empyrean.CartesianCoordinates	Cartesian state vectors.
empyrean.KeplerianCoordinates	Keplerian orbital elements.
empyrean.CometaryCoordinates	Cometary orbital elements.
empyrean.SphericalCoordinates	Spherical coordinates (topocentric / observer-centric).
empyrean.CartesianCovariance	Covariance matrix for Cartesian state [x, y, z, vx, vy, vz].
empyrean.KeplerianCovariance	Covariance matrix for Keplerian elements [a, e, i, raan, ap, ma].
empyrean.CometaryCovariance	Covariance matrix for cometary elements [q, e, i, raan, ap, tp].
empyrean.SphericalCovariance	Covariance matrix for spherical coords [rho, lon, lat, vrho, vlon, vlat].
empyrean.CartesianOrbits	Orbits in Cartesian coordinates.
empyrean.KeplerianOrbits	Orbits in Keplerian elements.
empyrean.CometaryOrbits	Orbits in cometary elements.
empyrean.SphericalOrbits	Orbits in spherical coordinates.
empyrean.NonGravParams	Non-gravitational acceleration parameters.
empyrean.PhotometricParams	Photometric parameters for apparent magnitude computation.
empyrean.Epochs	Epochs as Modified Julian Dates with an explicit time scale.
empyrean.TimeScale	Time scale for epoch values.
empyrean.Frame	Reference frame for coordinate states.
empyrean.Origin	Origin (center body) for a coordinate state.

Observers

empyrean.Observers

Precomputed observer states as Cartesian coordinates.

Propagation

empyrean.PropagationConfig	Configuration for orbit propagation.
empyrean.PropagationResult	Result of orbit propagation.
empyrean.DiagnosticsConfig	Per-trajectory diagnostic outputs (sensitivity, nonlinearity, Lyapunov, keyhole, bifurcation).
empyrean.AdvancedIntegratorConfig	Integrator-tuning knobs.
empyrean.IntegratorChoice	Integrator backend selector.
empyrean.OriginSwitchingConfig	Trajectory splitting at body acceleration-dominance boundaries (Amato/Baù/Bombardelli 2017 §6).
empyrean.ForceModelTier	Force model tier for propagation.
empyrean.UncertaintyMethod	Uncertainty propagation method — shortcut identifiers for the zero-arg / default-params cases.
empyrean.SigmaPoint	Sigma-point (unscented) transform.
empyrean.MonteCarlo	Monte Carlo sampling.
empyrean.EventConfig	Configuration for event detection during propagation.
empyrean.Events	All events detected during propagation, grouped by type.
empyrean.EventSummary	One-row-per-event summary across all event types.
empyrean.CloseApproachStarts	Close approach zone entry events.
empyrean.CloseApproachEnds	Close approach zone exit events.
empyrean.Periapses	Periapsis (closest approach) events within a CA zone.
empyrean.Impacts	Nominal impact events (body surface intersection).
empyrean.PossibleImpacts	Probabilistic impact assessments from covariance analysis.
empyrean.AtmosphericEntries	Atmospheric entry events (Karman line inbound crossing).
empyrean.AtmosphericExits	Atmospheric exit events.
empyrean.CaptureStarts	Temporary gravitational capture start events.
empyrean.CaptureEnds	Temporary gravitational capture end (escape) events.
empyrean.ShadowEntries	Shadow zone entry events (Sun occluded by a body).
empyrean.ShadowExits	Shadow zone exit events (Sun no longer occluded).

Ephemeris

empyrean.Ephemeris	Predicted astrometric ephemeris for observed objects.
empyrean.EphemerisConfig	Configuration for empyrean.generate_ephemeris().
empyrean.EphemerisResult	Result of empyrean.generate_ephemeris().

Impact probability and B-plane

empyrean.ImpactProbabilities	Probabilistic impact assessments tagged by uncertainty method.
empyrean.BPlanes	B-plane geometry breakdowns tagged by uncertainty method.

Math primitives

empyrean.eigenvector_max_6x6	Dominant eigenvalue / eigenvector of a 6 × 6 symmetric matrix.
empyrean.split_gaussian	Split a 6D Gaussian into k weighted components along the dominant eigenvector of the covariance.
empyrean.MixtureComponent	One weighted component of a 6D Gaussian mixture.

Sensitivity

empyrean.StateSensitivities	Per-(orbit, epoch) state-transition matrices and tensors.
empyrean.ObservationSensitivities	Per-(orbit, observer, epoch) observation Jacobians and Hessians.

Orbit determination

empyrean.ADESObservations	ADES optical observations — full schema.
empyrean.ODConfig	Unified orbit-determination configuration.
empyrean.DetermineResult	Result of orbit determination — returned by both determine() (full IOD + DC pipeline) and refine() (Bayesian-prior fit against an existing orbit + covariance).
empyrean.EvaluateResult	Result of orbit evaluation (residuals only, no fitting).
empyrean.ObservationResults	Per-observation OD results — full upstream surface.
empyrean.ResidualSummary	Aggregate residual statistics over a set of observations.
empyrean.AcceptabilityReport	Structured fit-quality verdict — mirrors scott::od::AcceptabilityReport.
empyrean.StationBiases	Per-station fitted nuisance biases.
empyrean.OutputEpoch	Output epoch for the fitted orbit.
empyrean.OutputEpochMode	How OutputEpoch selects the fitted-orbit epoch.
empyrean.Session	Stateful orbit-determination handle.
empyrean.SessionDiff	Pairwise diagnostic between two fits in the same session.

OD configuration

empyrean.WeightingConfig	Observation weighting pipeline.
empyrean.WeightingLayer	One element of the weighting pipeline.
empyrean.WeightingLayerKind	Discriminator for WeightingLayer variants.
empyrean.WeightingPreset	Preset selector for WeightingConfig.
empyrean.SigmaPolicy	How a weighting layer's σ combines with the per-observation reported σ.
empyrean.DebiasingConfig	Catalog-bias-correction configuration.
empyrean.DebiasingResolution	Healpix resolution of a debiasing table.
empyrean.StationRaDecConfig	Per-station RA/Dec bias-fit configuration.
empyrean.RejectionConfig	Outlier-rejection configuration.
empyrean.RejectionKind	Outlier-rejection strategy selector.
empyrean.SolveForParams	Parameters to solve for in differential correction.
empyrean.IODConfig	IOD ranging tuning.
empyrean.AutoEscalationPolicy	Trigger thresholds for SolveForParams.AUTO escalation.
empyrean.AcceptabilityThresholds	Thresholds for the post-DC fit-acceptability sub-checks.
empyrean.CovarianceRepresentation	Coordinate basis the OD output covariance is reported in.