empyrean.propagate

propagate(orbits, epochs, config=None, *, force_model=None, uncertainty_method=None, num_threads=None, events=None, tagged_covariance=False)[source]

Propagate orbits to target epochs.

Parameters:

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

  • epochs (Epochs | ndarray | Sequence[float]) – Target epochs. An Epochs table (converted to TDB internally), or a 1-D array of MJD TDB values.

  • config (PropagationConfig | None) – Full propagation configuration. Construct with PropagationConfig(force_model=..., uncertainty_method=...) etc. If omitted, one is built from the sugar kwargs below (or defaults).

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

  • uncertainty_method (UncertaintyMethod | SigmaPoint | MonteCarlo | str | None) – Quick override for config.uncertainty_method. Accepts either an enum / string (default parameters) or a parameterized dataclass (SigmaPoint(n_sigma=2.0) etc.). Ignored if config is given.

  • num_threads (int | None) – Threads for multi-orbit propagation. None (default) = sequential; 0 = use all available cores; n > 0 = use exactly n cores. Each orbit is integrated on a single thread; parallelism is across orbits, not within a single trajectory.

  • events (EventConfig | None) – Event-detection toggles + body filter + dense-output cadence. Override individual flags here without rebuilding a full PropagationConfig. See EventConfig.

  • tagged_covariance (bool) – When True, also read back the provenance-tagged, resolved-kind covariance at every output epoch (the honest covariance that distinguishes a second-order close-approach ellipsoid from the bare linear Φ Σ₀ Φᵀ mapping on the states). The result’s tagged_covariance table is populated and tagged_covariance_series() becomes usable. Off by default — the readback recomputes the resolved kind per orbit, so it isn’t free.

Return type:

PropagationResult

Returns:

PropagationResult – Propagated states, detected events, and per-orbit state sensitivity chains.

Examples

Defaults (Standard force model, FirstOrder uncertainty):

>>> result = empyrean.propagate(orbits, times)

With a config object:

>>> cfg = PropagationConfig(
...     force_model=ForceModelTier.FULL,
...     uncertainty_method=SigmaPoint(n_sigma=2.0),
...     num_threads=8,
... )
>>> result = empyrean.propagate(orbits, times, cfg)

With inline kwargs (sugar):

>>> result = empyrean.propagate(orbits, times, force_model="full")