Crate empyrean

Expand description

§empyrean

High-precision Solar System dynamics — trajectory propagation, ephemeris generation, orbit determination, and event analysis (close approaches, occultations, eclipses, sphere-of-influence crossings) for real Solar System bodies.

Safe Rust wrapper over empyrean-sys. Use this crate to propagate orbits, generate ephemerides, and determine orbits from observations without writing unsafe code.

§Standard workflow

Pull an orbit from JPL SBDB, propagate it forward, generate ephemerides at an observatory, and inspect detected events:

use empyrean::{Context, EphemerisConfig, Origin, PropagationConfig};

let ctx = Context::from_data_dir(None)?;

// 1. Pull Apophis from SBDB (CometaryCoordinates with covariance).
let batch = empyrean::query_sbdb(&["99942"], None)?;

// 2. Propagate 10 years past the SBDB epoch.
let cfg = PropagationConfig::default();
let t0 = batch.orbits[0].state.epoch.mjd_tdb()?;
let epochs = vec![empyrean::Epoch::from_mjd_tdb(t0 + 10.0 * 365.25)];
let result = ctx.propagate(&batch.orbits, &epochs, &cfg)?;
println!("{} states, {} events", result.states.len(), result.events.len());

// 3. Predict on-sky positions at Mauna Kea (MPC code 568).
let observers = ctx.get_observers(&["568"], &epochs)?;
let eph_cfg = EphemerisConfig::default();
let eph = ctx.generate_ephemeris(&batch.orbits, &observers, &eph_cfg)?;

For close-approach analysis (impact probability, B-plane geometry), see Context::compute_impact_probabilities and Context::compute_b_planes. For OD from astrometric observations, see Context::determine and the Session type for interactive masking workflows.

§Coordinate transform

use empyrean::{Context, CoordinateState, Frame, Origin, Representation};

let ctx = Context::from_data_dir(None)?;
let input = CoordinateState::cometary(
    empyrean::Epoch::from_mjd_tdb(60200.0),
    [0.7461, 0.1914, 3.339, 204.446, 126.687, 60159.0],
    Frame::EclipticJ2000,
    Origin::SUN,
);
let cart = ctx.transform(&input, Representation::Cartesian, Frame::ICRF, Origin::SUN)?;
println!("x = {:.6} AU", cart.elements[0]);

§Quick reference

You want…	API
Propagate orbits to target epochs	`Context::propagate`
Predict observations at observatories	`Context::generate_ephemeris`
Fit an orbit to observations	`Context::determine`
Re-fit with a Bayesian prior	`Context::refine`
Residuals only — no fit	`Context::evaluate`
Stateful, mask-and-refit OD	`Session`
Impact probability	`Context::compute_impact_probabilities`
B-plane geometry	`Context::compute_b_planes`
Convert between coordinate types	`Context::transform`
Body / observer states	`Context::get_states` / `Context::get_observers`
Pull an orbit from JPL SBDB	`query_sbdb`
Pull predicted ephemeris from Horizons	`query_horizons`
Pull SSB state vectors from Horizons	`query_horizons_vectors`
Pull observations from MPC	`query_observations`
Pull radar astrometry from JPL	`query_radar`
Read ADES PSV observations	`Context::read_ades`
Default data directory	`default_data_dir`

§Conventions

Distances in AU; velocities in AU/day; angles in degrees at the API boundary (radians internally).
Epochs are MJD on the TDB scale unless otherwise stated. See time::Epoch for time-scale-aware values and time::iso_to_mjd / time::mjd_to_iso for ISO 8601 interop.
Default integrator is IntegratorChoice::GR15 (median Horizons error ≈ 35 m). Switch to IntegratorChoice::DOP853 via AdvancedIntegratorConfig::integrator for ~1.4× speed at the cost of ~10× position error.
Default frame for propagation output is Frame::EclipticJ2000 (the integration frame); set PropagationConfig::frame to Frame::ICRF for ICRF output.

Re-exports§

pub use time::Epoch;
pub use time::TimeScale;
pub use time::iso_to_mjd;
pub use time::mjd_to_iso;

Modules§

time: Time scale conversions: ISO 8601 ↔ MJD in UTC or TDB.

Structs§

AcceptabilityReport: Acceptability sub-checks reported on a DetermineResult.
AcceptabilityThresholds: Thresholds for the post-DC fit-acceptability sub-checks.
AdvancedIntegratorConfig: Integrator-tuning knobs.
AutoEscalationPolicy: Tuning for SolveForParams::Auto automatic escalation.
BPlane: One B-plane breakdown for a single close approach.
BandStat: Per-band photometric fit statistics.
BuiltSystem: A reusable pre-built force-model handle.
Context: Handle to loaded SPICE kernels, gravitational parameters, and ephemeris state required for every propagation, ephemeris, or OD call.
CoordinateState: Coordinate state: epoch + six-element state vector + optional covariance.
DebiasingConfig: Catalog-bias-correction configuration.
DetermineResult: Result of a differential-correction orbit determination.
DiagnosticsConfig: Per-trajectory diagnostic outputs.
EphemerisConfig: Ephemeris-generation configuration.
EphemerisEntry: One row of predicted astrometry.
EphemerisResult: Result of Context::generate_ephemeris: the per-(orbit, observer, epoch) ephemeris entries plus the observation-sensitivity rows (empty unless the uncertainty method traced the STM).
Error: Error returned from an empyrean FFI call.
EvaluateResult: Result of evaluating a candidate orbit against observations (no fit).
Event: A detected dynamical event from propagation.
EventConfig: Event-detection configuration. Controls which event kinds the integrator looks for during propagation, plus body filtering and dense-output cadence around close approaches.
GateRecord: One model-ladder gate decision from the photometric fit.
IODConfig: IOD ranging tuning.
ImpactProbability: One impact-probability record produced by a single UncertaintyMethod propagation.
KernelRecord: One entry of the kernel-identity manifest a handle captured at construction. Names the provenance of each loaded data file — never any tuning rationale.
MixtureComponent: A component of a Gaussian mixture produced by split_gaussian.
ODConfig: Orbit-determination configuration.
Observation: A single astrometric observation — full ADES schema.
ObservationResidual: Per-observation result from orbit determination or evaluation.
ObservationSensitivity: Observation-sensitivity row: the partial derivatives of the sky-plane observable w.r.t. the input state, for one (orbit, observer, epoch). Produced when the ephemeris uncertainty method traced the STM.
Observations: Owned set of ADES observations returned by Context::read_ades.
Observer: Observer state at one epoch.
Orbit: Orbit to propagate: coordinate state plus optional Marsden non-grav coefficients (A1, A2, A3), a configurable g(r) distance scaling, and optional photometric parameters.
OrbitBatch: A batch of orbits paired with their orbit / object identifiers.
OriginSwitchingConfig: Trajectory splitting at body Laplace SOIs (Amato/Baù/Bombardelli 2017 §6). Default enabled — chaotic Earth-encounter trajectories are re-centered on the dominant body during flybys, preserving sub-meter precision. Set enabled = false to opt out.
PhotometryConfig: Post-OD photometric-fit configuration (mirrors the engine’s photometry config). Attach via ODConfig::photometry. Sentinel rule: 0 / 0.0 on a tuning field requests the engine default.
PhotometryResult: Post-OD photometric solution — an H/G fit over the arc’s magnitudes, run after the orbit is solved (photometry has no astrometric partials, so it never touches the state). H carries honest σ via covariance.
PropagatedState: A propagated state at one epoch.
PropagationConfig: Top-level propagation configuration.
PropagationResult: Result of propagating one or more orbits.
RadarObservation: A single radar observation — full ADES radar schema.
RadarResidual: Radar residual block on an ObservationResidual row.
RejectionConfig: Outlier-rejection configuration. The active fields are determined by kind.
ResidualSummary: Summary statistics over a residual set. AT/CT RMS values are NaN when no sky-motion rates were available.
Session: Stateful orbit-determination handle.
SessionDiff: Pairwise diagnostic between two fits in the same session.
SolveFor: Per-axis wide solve-for selection (mirrors the engine’s SolveFor).
SolvedCovariance: Full tagged solved-parameter covariance from a wide OD fit.
State: A single body state.
StationBias: One per-station fitted nuisance bias.
StationRaDecConfig: Per-station RA/Dec bias-fit configuration.
SystemDescription: A reproducibility summary of a BuiltSystem’s frozen force model plus the kernel-identity manifest it captured from the context.
TaggedCovariance: Provenance-tagged, resolved-kind covariance readback at one (orbit, epoch) — the honest covariance, distinct from the bare linear PropagatedState::covariance.
ThrustArc: A single continuous-thrust arc with smooth on/off switching and optional mass depletion.
ThrustParams: Thrust parameters for an orbit: thrust arcs plus optional Δv targeting corrections.
Versions: Per-crate versions reported by the empyrean stack.
WeightingConfig: Observation weighting pipeline.

Enums§

BuiltSystemGuardError: Which identity-guard axis a BuiltSystem forward-model call tripped.
CovarianceKind: How a covariance was derived — the resolved kind at an output epoch.
CovarianceQuality: Definiteness of a covariance matrix.
CovarianceRepresentation: Coordinate basis tag for OD output covariance.
CovarianceTrust: Event-aware trust verdict on the delivered covariance, evaluated over its validity window on the converged orbit. Absence (DetermineResult::covariance_trust == None) means the call path ran no gate — absence of a verdict is not trust.
DebiasingResolution: Healpix resolution of a debiasing table.
ForceModelTier: Force model tier. Each tier adds physics on top of the previous.
Frame: Reference frame.
IntegratorChoice: Integrator backend selector.
KernelKind: Category of a loaded data file in a handle’s kernel manifest.
KernelProvenance: Where a kernel in a handle’s manifest came from.
Origin: Origin (center body) for a coordinate state.
OriginPolicy: Origin-policy selector for the OD pipeline.
OutputEpoch: Output epoch for the fitted orbit.
PhaseFunction: Phase-function model for HG-family photometry.
PhotometryModel: Photometric model for the post-OD phase-function fit.
RadarMeasurement: The delay-or-Doppler measurement carried by a RadarObservation (ADES RadarValue choice). All values are ADES-native — no unit conversion is applied anywhere in the safe wrapper.
RadarResidualKind: Which radar observable a RadarResidual refers to.
RejectionKind: Outlier-rejection strategy selector. The variant chosen determines which fields of RejectionConfig are read; ignored fields keep their defaults.
RejectionReason: Why an observation was kept or rejected. The NotEvaluated variant is the safe-Rust analogue of the C ABI’s “not evaluated” sentinel — used on the evaluate path where rejection is not run.
Representation: Orbital state representation.
SigmaPolicy: How a weighting layer’s sigma combines with a per-observation reported sigma.
SolveForParams: Solve-for parameter set used by differential correction.
SteeringLaw: Steering law — how the thrust direction is computed from the spacecraft state relative to the arc’s central_body.
TargetFunctional: The functional a covariance’s second moment describes.
TrustGateEvent: The intervening event named by a CovarianceTrust::EncounterIntervenes verdict.
UncertaintyMethod: Uncertainty propagation method.
WeightingLayer: One element of the weighting pipeline.
WeightingPreset: Preset selector for WeightingConfig. Picking a preset seeds the layer chain with curated layers; entries in WeightingConfig::additional_layers are appended in order.

Functions§

default_data_dir: Return the platform XDG-compliant default data directory.
download_data: Provision the complete Standard-tier kernel set into data_dir (or the platform default_data_dir when None) and return the resolved directory.
eigenvector_max_6x6: Compute the largest eigenvalue and corresponding eigenvector of a 6×6 symmetric matrix.
frame_to_int: Convert a Frame to its integer code (matches the C ABI).
int_to_frame: Convert an integer code to a Frame.
int_to_rep: Convert an integer code to a Representation.
query_horizons: Query JPL Horizons for predicted ephemeris records at a single observatory across a list of MJD TDB epochs.
query_horizons_vectors: Query JPL Horizons for a Cartesian state vector at a single epoch.
query_observations: Query the MPC observations API for ADES records of one or more designations.
query_radar: Query the JPL sb_radar API for delay/Doppler radar astrometry of one or more designations.
query_sbdb: Query the JPL Small-Body Database for one or more orbits by designation, name, or SPK ID.
read_orbits_csv: Read an orbits CSV file.
read_orbits_json: Read an orbits JSON file.
read_orbits_parquet: Read an orbits parquet file.
rep_to_int: Convert a Representation to its integer code (matches the C ABI).
split_gaussian: Split a Gaussian (mean, covariance) into a mixture of k smaller Gaussians along the eigenvector of maximum variance.
version_string: Multi-line version report — empyrean-core <ver>\nvilleneuve <ver>\n….
versions: Per-crate version strings for the empyrean stack.
write_ephemeris_csv: Write ephemeris entries to CSV.
write_ephemeris_json: Write ephemeris entries to JSON.
write_ephemeris_parquet: Write ephemeris entries to a parquet file.
write_events_csv: Write events to CSV.
write_events_json: Write events to JSON.
write_events_parquet: Write events to a parquet file.
write_orbits_csv: Write an orbit batch to CSV.
write_orbits_json: Write an orbit batch to JSON.
write_orbits_parquet: Write an orbit batch to a parquet file.
write_residuals_csv: Write OD residuals to CSV.
write_residuals_json: Write OD residuals to JSON.
write_residuals_parquet: Write OD residuals to a parquet file.

Type Aliases§

Result: Result type for empyrean FFI calls.

Crate empyrean

Crate empyrean Copy item path

§empyrean

§Standard workflow

§Coordinate transform

§Quick reference

§Conventions

Re-exports§

Modules§

Structs§

Enums§

Functions§

Type Aliases§

Crate empyrean