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) over every object in observations.
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 a chosen frame and origin.
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_horizons_vectors	Query JPL Horizons for a Cartesian state vector at a single epoch.
empyrean.query_observations	Fetch ADES observation records from the MPC for one or more designations.
empyrean.query_radar	Fetch radar (delay / Doppler) astrometry from JPL 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	Provision a usable data directory with the required SPICE kernels.
empyrean.default_data_dir	Return the OS-appropriate XDG data directory empyrean uses by default.
empyrean.versions	Return per-crate versions of the empyrean stack.
empyrean.version_string	Return the multi-line version report for the empyrean stack.

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	Marsden-Sekanina non-gravitational acceleration parameters.
empyrean.PhotometricParams	Photometric parameters for apparent magnitude computation.
empyrean.SRPParams	Solar-radiation-pressure force slot.
empyrean.WideCross	Row-aligned cross-covariance terms beyond the state+Marsden 9x9.
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.

Continuous thrust

empyrean.ThrustParams	Thrust parameters for one orbit: thrust arcs plus optional $\Delta v$ targeting corrections.
empyrean.ThrustArc	A single continuous-thrust arc with smooth on/off switching and optional mass depletion.
empyrean.SteeringLaw	Represent a PEP 604 union type
empyrean.ConstantRTN	Constant RTN steering angles relative to the arc's central body.
empyrean.VelocityTangent	Thrust aligned with the velocity vector relative to the central body: $\hat{d} = \hat{v}_\text{body}$.
empyrean.InertialFixed	Fixed direction in the inertial frame (normalized internally).

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.EphemerisOverlapPolicy	What to do when the propagated state coincides with an SB441-N16 perturber's own SPK ephemeris — the self-perturbation case, where a body is both the thing being propagated and one of the forces acting on it.
empyrean.ForceModelTier	Force model tier for propagation.
empyrean.UncertaintyMethod	Uncertainty propagation method — shortcut identifiers for the zero-arg / default-params cases.
empyrean.Auto	Adaptive per-close-approach uncertainty-method selection.
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).
empyrean.CovarianceRegimeChanges	Covariance-regime transitions from UncertaintyMethod.AUTO.

Tagged covariance

The per-epoch covariance readback, carrying the joint’s off-diagonal blocks alongside the 6×6 state block.

empyrean.TaggedCovariance	Provenance-tagged covariance at a single (orbit, epoch).
empyrean.TaggedCovariances	Per-(orbit, epoch) provenance-tagged covariance readback.
empyrean.CovarianceKind	How a covariance was derived at an output epoch.
empyrean.CovarianceQuality	Definiteness of a tagged covariance matrix.
empyrean.TargetFunctional	The functional a tagged covariance's second moment describes.
empyrean.GaussianMixture	Adaptive Gaussian mixture (AGM).

System handles

empyrean.build_system	Assemble a reusable BuiltSystem force-model handle.
empyrean.od_system	Assemble a BuiltSystem keyed for the orbit-determination entry points.
empyrean.BuiltSystem	A reusable pre-built force-model handle.
empyrean.SystemDescription	A reproducibility summary of a BuiltSystem's frozen force model plus the kernel-identity manifest it captured.
empyrean.KernelRecord	One entry of the kernel-identity manifest a handle captured at construction.
empyrean.KernelKind	Category of a loaded data file in a handle's kernel manifest.
empyrean.KernelProvenance	Where a kernel in a handle's manifest came from.

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.

Observation planning

empyrean.evaluate_plan	Rank candidate follow-up observations by how much each would tighten an orbit.
empyrean.PlanResult	The result of evaluating an observation plan.
empyrean.PlanMetrics	Covariance summary metrics bracketing the campaign — two rows.
empyrean.PlanCandidates	Per-candidate information gain — one row per planned observation.
empyrean.PlanEphemeris	Predicted sky position at each optical candidate's epoch.

Planning configuration

empyrean.PlanningConfig	Configuration for empyrean.evaluate_plan().
empyrean.ObservatoryConfig	Per-site astrometric assumptions and observability filters.
empyrean.STAGE_PRIOR	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
empyrean.STAGE_POSTERIOR	str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
empyrean.PlannedObservation	One candidate observation: when it would be taken and what it would measure.
empyrean.PlannedObservationKind	What a PlannedObservation would measure.
empyrean.RadarMode	Which radar observable(s) a candidate would measure.
empyrean.RadarStation	A radar dish the planner can schedule against.

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.
empyrean.SENSITIVITY_ROW_RANGE	int([x]) -> integer int(x, base=10) -> integer
empyrean.SENSITIVITY_ROW_RA	int([x]) -> integer int(x, base=10) -> integer
empyrean.SENSITIVITY_ROW_DEC	int([x]) -> integer int(x, base=10) -> integer
empyrean.SENSITIVITY_ROW_VRANGE	int([x]) -> integer int(x, base=10) -> integer
empyrean.SENSITIVITY_ROW_VRA	int([x]) -> integer int(x, base=10) -> integer
empyrean.SENSITIVITY_ROW_VDEC	int([x]) -> integer int(x, base=10) -> integer

Orbit determination

empyrean.ADESObservations	ADES optical observations — full schema.
empyrean.ADESRadarObservations	ADES radar 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.DetermineResults	The result of a batch orbit determination — every object the observations grouped into, delivered or not.
empyrean.DetermineFailure	Why one object in a batch produced no orbit.
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.FitSummary	One row per input object of a batch orbit determination — delivered or not.
empyrean.BandStat	Per-band photometric fit statistics.
empyrean.AcceptabilityReport	Structured fit-quality verdict — mirrors scott::od::AcceptabilityReport.
empyrean.GateRecord	One model-ladder gate decision from the photometric fit.
empyrean.SolvedCovariance	Full tagged solved-parameter covariance from a wide OD fit.
empyrean.StallDelivery	The numbers behind a fit delivered by the stable-stall acceptance — one whose final solve latched no convergence criterion but was stationary to a small fraction of its own formal σ, with χ² clearing the fit-quality bars.
empyrean.CovarianceTrust	Event-aware trust verdict on the delivered covariance, evaluated over its validity window on the converged orbit.
empyrean.TrustGateEvent	The intervening event named by an encounter_intervenes covariance-trust verdict.
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.

Post-OD photometry

empyrean.PhotometryConfig	Post-OD photometric-fit configuration.
empyrean.PhotometryModel	Photometric model for the post-OD phase-function fit.
empyrean.PhotometryResult	Post-OD photometric solution — an H/G fit over the arc's magnitudes, run after the orbit is solved.

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.SolveFor	What the fit does with each parameter axis.
empyrean.ParamDisposition	A parameter axis's treatment in a fit.
empyrean.IODConfig	IOD ranging tuning.
empyrean.OriginPolicy	Origin-policy selector for the OD pipeline.
empyrean.OriginPolicyMode	How OriginPolicy selects the central body for IOD + DC.
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.