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, Frame, 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, Frame::ICRF, Origin::SSB)?;
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_coordinates_single(&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`
Rank candidate follow-up observations	`Context::evaluate_plan`
Convert between coordinate types	`Context::transform_coordinates` (batch) / `Context::transform_coordinates_single`
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 propagate::AdvancedIntegratorConfig;
pub use propagate::CovarianceKind;
pub use propagate::CovarianceQuality;
pub use propagate::DiagnosticsConfig;
pub use propagate::EphemerisOverlapPolicy;
pub use propagate::Event;
pub use propagate::EventConfig;
pub use propagate::ForceModelTier;
pub use propagate::IntegratorChoice;
pub use propagate::OriginSwitchingConfig;
pub use propagate::PropagatedState;
pub use propagate::PropagationConfig;
pub use propagate::PropagationResult;
pub use propagate::TaggedCovariance;
pub use propagate::TargetFunctional;
pub use propagate::UncertaintyMethod;
pub use time::Epoch;
pub use time::TimeScale;
pub use time::iso_to_mjd;
pub use time::mjd_to_iso;

Modules§

propagate: Orbit propagation and event detection.
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.
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.
CovarianceMetrics: Summary metrics for a state covariance — the prior, the posterior, or a candidate’s running total.
DataDirOptions: Options for Context::from_data_dir_with.
DebiasingConfig: Catalog-bias-correction configuration.
DetermineEntry: One object’s slot in a batch determine: its identifier and either the delivered fit or the typed failure.
DetermineFailure: One object’s failure inside a batch determine.
DetermineResult: Result of a differential-correction orbit determination.
DetermineResults: The result of a batch Context::determine — one DetermineEntry per ADES object in the observations, ordered by object_id.
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 propagation traced the STM — see ObservationSensitivity for what makes it trace).
Error: Error returned from an empyrean FFI call.
EvaluateResult: Result of evaluating a candidate orbit against observations (no fit).
FitSummaryRow: One row of the fit summary: what orbit determination did with one object.
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.
JointCovariance: A fitted or propagated joint’s cross terms, as the library hands them back.
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).
Observations: Owned set of ADES observations returned by Context::read_ades.
ObservatoryConfig: Per-site astrometric assumptions and observability filters.
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.
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.
PlanCandidate: What one candidate observation would buy.
PlanEphemerisPoint: One predicted sky position from the plan’s optical ephemeris.
PlanResult: The result of evaluating an observation plan.
PlannedObservation: One candidate observation: when it would be taken and what it would measure.
PlanningConfig: Configuration for Context::evaluate_plan.
RadarObservation: A single radar observation — full ADES radar schema.
RadarPlanSpec: The radar measurement a candidate would make: the link (transmit and receive dishes), the waveform, and how the effective SNR is sourced.
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: What a fit does with each parameter axis (mirrors the engine’s SolveFor).
SolvedCovariance: Full tagged solved-parameter covariance from a wide OD fit.
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.
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.
TargetRadarProperties: Target physical properties the radar link budget needs to predict an SNR. Every field is optional; None means “not known”.
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.
WideCross: Cross-covariance terms beyond the state+Marsden \(9 \times 9\): state↔DT, state↔AMRAT, state↔\(\Delta v\), and every mixed parameter pair.

Enums§

BuiltSystemGuardError: Which guard axis a BuiltSystem call tripped.
CandidateKind: What a candidate turned out to be, with the fields only that kind reports.
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.
DataTier: Force-model tier whose kernel set a data-directory constructor acquires and loads.
DebiasingResolution: Healpix resolution of a debiasing table.
DetermineFailureKind: Why one object’s fit failed inside a batch Context::determine.
Frame: Reference frame.
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.
ParamColumn: Which solved parameter a cross term refers to.
ParamDisposition: What a fit did with one parameter axis.
PhaseFunction: Phase-function model for HG-family photometry.
PhotometryModel: Photometric model for the post-OD phase-function fit.
PlannedObservationKind: The measurement a PlannedObservation would make.
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.
RadarMode: Which radar observable(s) a candidate would measure.
RadarResidualKind: Which radar observable a RadarResidual refers to.
RadarStation: A radar dish the planner can schedule against.
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.
SolverStop: Which criterion ended the solve that produced a fit’s published state.
SteeringLaw: Steering law — how the thrust direction is computed from the spacecraft state relative to the arc’s central_body.
TrustGateEvent: The intervening event named by a CovarianceTrust::EncounterIntervenes verdict.
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 placed ahead of the preset’s rules (sigma resolution is first-match-wins, so they override the preset for their stations).

Constants§

MAX_THRUST_SEGMENTS: The largest number of thrust Δv correction segments one fit can declare, and the length of SolveFor::thrust.
SENSITIVITY_ROW_DEC: Row of the declination partials, in degrees per input unit.
SENSITIVITY_ROW_RA: Row of the right-ascension partials, in degrees per input unit.
SENSITIVITY_ROW_RANGE: Row of the range (topocentric distance) partials, in AU per input unit.
SENSITIVITY_ROW_VDEC: Row of the Dec-rate partials, in deg/day per input unit.
SENSITIVITY_ROW_VRA: Row of the RA-rate partials, in deg/day per input unit. The rate is dRA/dt, not scaled by cos(Dec).
SENSITIVITY_ROW_VRANGE: Row of the range-rate partials, in AU/day per input unit.

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.
offline_floor_is_active: Whether the EMPYREAN_OFFLINE floor is in force for this process.
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_fit_summary_csv: Write the per-object fit summary to CSV.
write_fit_summary_json: Write the per-object fit summary to JSON.
write_fit_summary_parquet: Write the per-object fit summary 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§

Constants§

Functions§

Type Aliases§

Crate empyrean