empyrean.generate_ephemeris

generate_ephemeris(orbits, observers, config=None, *, force_model=None, uncertainty_method=None, _builtsystem=None)[source]

Generate predicted ephemeris (RA/Dec) for orbits at observer locations.

Parameters:

  • orbits (CartesianOrbits | KeplerianOrbits | CometaryOrbits | SphericalOrbits) – Input orbits with optional covariance and non-gravitational parameters.

  • observers (Observers) – Observer states from get_observer_states().

  • config (EphemerisConfig | None) –

    Full configuration. Construct with EphemerisConfig(propagation=PropagationConfig(...), ...). If omitted, one is built from the sugar kwargs below (or defaults).

    config.propagation.ephemeris_overlap_policy and config.propagation.excluded_perturbers are both honored here, and one of them is required to generate an ephemeris for an SB441-N16 body (1 Ceres, 2 Pallas, 4 Vesta, …), which is otherwise both the target and one of its own perturbers; see EphemerisConfig.

    config.propagation.events and config.propagation.diagnostics do not apply to this call and raise a ValueError if modified.

  • force_model (ForceModelTier | str | None) – Quick override for config.propagation.force_model. Ignored if config is given.

  • uncertainty_method (UncertaintyMethod | SigmaPoint | MonteCarlo | GaussianMixture | Auto | str | None) – Optional quick override for config.propagation.uncertainty_method. Only the analytic methods are supported for ephemeris: FIRST_ORDER, SECOND_ORDER, AUTO, and GAUSSIAN_MIXTURE (SECOND_ORDER additionally populates observation Hessians on the resulting ObservationSensitivity; GAUSSIAN_MIXTURE is an adaptive-Gaussian-mixture method that is likewise analytic on this path). The sky-plane covariance is a first-order STM projection (J·Φ·Σ·Φᵀ·Jᵀ) that does not consume a sampled ensemble, so the sampling methods SIGMA_POINT and MONTE_CARLO are rejected with a ValueError rather than silently downgraded to first order. For a sampled state covariance use propagate() with SIGMA_POINT; for Monte-Carlo impact probability use compute_impact_probabilities(). Ignored if config is given.

  • _builtsystem (Any)

Return type:

EphemerisResult

Returns:

EphemerisResult – Wraps the Ephemeris table and, when the propagation traced the state-transition matrix, the observation-partials ObservationSensitivity container. The STM is traced when the input orbit carries a covariance, and — covariance or not — whenever config.propagation.compute_stm=True: that flag reaches the engine on this path, so partials can be requested for an orbit with no covariance at all. Rows are orbit-major and, within each orbit, follow the observer-input order (sensitivity rows too). Each observer carries its own epoch, so positional pairing against the input observers is safe within an orbit block.

Examples

Defaults (Standard force model, FirstOrder uncertainty):

>>> result = empyrean.generate_ephemeris(orbits, observers)

With a config object:

>>> cfg = EphemerisConfig(
...     propagation=PropagationConfig(
...         force_model=ForceModelTier.STANDARD,
...         uncertainty_method=UncertaintyMethod.SECOND_ORDER,
...     ),
...     compute_diagnostics=False,
... )
>>> result = empyrean.generate_ephemeris(orbits, observers, cfg)