SolutionOD#

class SolutionOD(filter_obj: FilterOD, output_settings: OutputSettings | None = None)#

Bases: object

Stores and manages the results of an orbit determination process.

Encapsulates all outputs from a filter including state deviations, covariances, residuals, and optional debugging quantities. Storage is controlled by OutputSettings.

Parameters:
filter_objFilterOD

The filter object that produced this solution.

output_settingsOutputSettings, optional

Configuration controlling what quantities are stored.

Attributes:
filterFilterOD

The filter object used for orbit determination.

output_settingsOutputSettings

Output configuration.

timestampsnp.ndarray

Epoch timestamps for the solution.

deviation_estnp.ndarray, optional

Estimated state deviation wrt the last iteration’s reference trajectory [n_epochs x n_states].

deviation_cumulativenp.ndarray, optional

Cumulative state deviation wrt the first (initial) reference trajectory, accumulated across all iterations up to and including this one [n_epochs x n_states]. Equal to deviation_est for single-iteration runs.

state_estnp.ndarray, optional

Absolute state estimate at each measurement epoch [n_epochs x n_states].

deviation_smoothnp.ndarray, optional

Smoothed state deviation history [n_epochs x n_states].

covariance_estlist of np.ndarray, optional

Estimated covariance matrices at each epoch.

covariance_smoothlist of np.ndarray, optional

Smoothed covariance matrices (from RTS smoother).

covariance_considerlist of np.ndarray, optional

Consider parameter covariance matrices.

prefitslist, optional

Pre-fit measurement residuals.

postfitslist, optional

Post-fit measurement residuals.

postfits_smootherlist, optional

Post-fit residuals for smoothed solution.

uq_metricsdict, optional

Uncertainty quantification metrics (mean, std, skewness, kurtosis, etc.).

debugdict, optional

Debug quantities (Kalman gains, innovation covariances, NIS).

Methods

UQ_compute([particle_states, confidence_levels])

Compute and store weighted uncertainty metrics for particle filters.

create_JSON(filepath[, fmt])

Export solution results to a JSON or pickle file.

deserialize(filepath[, filter_obj])

Deserialize SolutionOD object from binary file.

estimated_trajectory(epochs[, use_smoothed])

Computes the estimated trajectory (position, velocity, parameters) at filter measurement epochs.

global_std_devs()

Standard deviations of the combined global parameter estimate.

map_state_deviation_to_epoch([...])

Map corrections to their nominal initial epochs using STM ratios.

print_stats([verbose])

Print statistical summary of the OD solution.

propagate_covariance(epochs[, use_smoothed, ...])

Map covariance to arbitrary epochs using the trajectory STMs.

propagate_state(epochs[, use_smoothed, ...])

Map deviations with STMs and add them to the nominal state once.

propagate_state_covariance(epochs[, ...])

Map state and covariance using the same data cutoff and smoothing.

save([filepath, fmt])

Save all filter iterations to a single JSON or pickle file.

serialize(filepath[, protocol])

Serialize SolutionOD object to binary format using pickle.

state_covariance_to_elements([epochs, body, ...])

Express the estimate and its covariance in Keplerian elements.

See also

scarabaeus.FilterOD

Base filter class that produces this solution.

scarabaeus.OutputSettings

Controls which quantities are stored.

Notes

Storage of each quantity is controlled by the flags in the associated OutputSettings instance. Quantities not selected are left as None and not computed during the filter run.

save() and create_JSON() write self-describing files: the metadata labels every state index (owner, SPICE ID, frame, units) and records the a priori state and covariance, the convergence test and the provenance; the solution blocks add the estimate at the initial epoch. Covariances are written either in full or as diagonals, never both.

Choosing a mapped solution. State and covariance mapping use the same data-cutoff convention. For an existing solution and target EpochArray called epochs:

# Filtered: each target uses measurements through that target time.
filtered = solution.propagate_state_covariance(
    epochs, use_smoothed=False, lookback_s=0.0)

# Rolling prediction: each target uses measurements through 14 days earlier.
prediction_14d = solution.propagate_state_covariance(
    epochs, use_smoothed=False, lookback_s=14 * 86400.0)

# Reconstruction: every target uses the final filter update.
reconstructed = solution.propagate_state_covariance(
    epochs, use_smoothed=False, use_all_data=True)

Each result is a list of (StateArray, covariance) pairs in requested epoch order. For covariance-only analyses, use propagate_covariance() with the same cutoff keywords; such analyses do not store state deviations. Covariance rows follow the nominal state component order, and entry (i, j) has the product of component i and j units.

For a selected update at epoch \(r\), mapping to \(t\) uses

\[\begin{split}A(t,r) &= \Phi(t,t_0)\Phi(r,t_0)^{-1}, \\ \hat x(t) &= x_{\mathrm{nom}}(t) + A(t,r)\delta x(r), \\ P(t) &= A(t,r)P(r)A(t,r)^T.\end{split}\]

These are linearized mappings around the fitted nominal reference. They add no measurements or process noise. Reconstruction maps the final covariance; it is not a stochastic backward smoother. When coverage is insufficient or STM interpolation is rejected, mapping reintegrates the nominal reference on copies of the propagator. The correction is added once.

The default lookback_s=None retains the older API convention: a continuous arc maps its final update inside/after the measurement arc and its first update before it. Specify lookback_s=0.0, use_smoothed=False for a causal filtered product. An explicit cutoff before the first update uses the prior; the prior covariance must be available. Simultaneous updates retain their order, and the last one at a cutoff is selected.

Consider-augmented covariance is included by default when considered parameters are present. A smoothed augmented history is unavailable, so those queries need use_smoothed=False. A paired query requires both smoothed histories or neither, preventing mixed state and covariance products.

Sequences use local leg STMs, with shared nodes assigned to the later leg. Positive lookback and all-data reconstruction across sequence events currently raise NotImplementedError because they require event transition maps.

Reading and saving results. estimated_trajectory() reads each measurement epoch’s own update and requires an epoch match within one microsecond. Use propagate_state() for arbitrary epochs. Sequence parameter results are grouped by leg and contain only the requested rows for each leg, in request order. map_state_deviation_to_epoch() maps corrections to nominal initial epochs and returns one vector per sequence leg in either sequence mapping mode.

UQ_compute() uses normalized particle weights consistently for the mean, population covariance, intervals and effective sample size. Its covariance diagonal equals the squared reported standard deviations; this is not an unbiased sample covariance with an N-1 correction.

serialize() preserves the update timeline, component frame/units, residual epochs, sequence layout and multi-arc global results alongside stored arrays. deserialize() can inspect and export those results without the original filter. Trajectory queries and propagation require reattaching the matching fitted filter, since the pickle does not embed its propagator or SPICE kernels.

References

[1]

Tapley, B. D., Schutz, B. E., & Born, G. H. (2004). Statistical Orbit Determination. Elsevier Academic Press. ISBN 978-0-12-683630-1.

classmethod deserialize(filepath: str | Path, filter_obj: FilterOD | None = None) → SolutionOD#

Deserialize SolutionOD object from binary file.

Parameters:
filepathstr or Path

Path to pickle file.

filter_objFilterOD, optional

Matching fitted filter, needed for trajectory queries and STM mappings. If None, create a metadata-only placeholder for inspecting stored results and exporting them again.

Returns:
SolutionOD

Deserialized solution object.

Raises:
FileNotFoundError

If file does not exist.

Notes

Files written before timeline, residual-epoch and frame/unit metadata were saved remain readable: absent metadata defaults to None and the measurement timestamps serve as the fallback timeline. Missing sequence event metadata cannot be reconstructed without the original filter. Loading does not initialize or rerun the supplied filter. Only load pickle files from trusted sources.

UQ_compute(particle_states: ndarray | None = None, confidence_levels: List[float] | None = None) → Dict#

Compute and store weighted uncertainty metrics for particle filters.

Computes mean, std, covariances, high-order statistical moments (skewness, kurtosis), weighted percentiles, and effective sample size from particle distributions.

Parameters:
particle_statesnp.ndarray, optional

Finite states with nonempty shape (n_particles, n_states, n_epochs). If None, read filter.particles. Values use each state component’s native units.

confidence_levelslist of float, optional

Central interval probabilities strictly between 0 and 1. Defaults to [0.68, 0.95, 0.997]. Bounds use weighted empirical quantiles.

Returns:
dict

Mean, standard deviation, skewness and excess kurtosis arrays of shape (n_epochs, n_states); a list of (n_states, n_states) population covariances; percentiles[level] arrays of shape (n_epochs, n_states, 2), lower bound first; and an effective_sample_size array of shape (n_epochs,). Mean, standard deviation and bounds use component units; covariance uses their pairwise products. The same dictionary is saved as uq_metrics.

Raises:
ValueError

If particle data is missing/nonfinite or its shape is invalid; weights are invalid or have zero mass; or levels are outside (0,1).

Notes

filter.weights may have shape (n_particles,) for static weights or (n_particles, n_epochs) for time-dependent weights. Missing weights imply a uniform distribution. Weights must be finite and nonnegative; they are normalized separately at each epoch without changing the filter. Covariance uses the weighted population moment (no N-1 sample correction), so its diagonal agrees with the squared returned standard deviations. Effective sample size is 1 / sum(w**2) using normalized w. Zero-variance components have zero skewness and excess kurtosis.

create_JSON(filepath: str | Path, fmt: str = None) → None#

Export solution results to a JSON or pickle file.

Parameters:
filepathstr or Path

Path to the output file.

fmt{“json”, “pickle”}, optional

On-disk format. When None (default) it is inferred from the file extension (.pkl gives pickle, otherwise JSON); when given explicitly, the file extension is normalised to match.

Notes

Holds the same fields as the final block of save(), with the metadata of save() plus n_epochs at the top level, but no iteration history.

estimated_trajectory(epochs: EpochArray, use_smoothed: bool = True)#

Computes the estimated trajectory (position, velocity, parameters) at filter measurement epochs.

This method is only valid at the epochs where the filter processed measurements (i.e. the epochs stored in solution.timestamps). Passing any other epoch raises a ValueError — use propagate_state() for arbitrary epochs, including epochs outside the measurement arc.

Parameters:
epochsEpochArray

The measurement epochs at which to evaluate the estimated trajectory. Every epoch must match an entry in solution.timestamps to within one microsecond. Queries snap to the matched stored epoch.

use_smoothedbool, optional

If True and a smoothed solution is available, use the smoothed deviations; otherwise use the filtered deviations. Defaults to True.

Returns:
estimated_posnumpy.ndarray, shape (n, 3)

Estimated position at each epoch [km].

estimated_velnumpy.ndarray, shape (n, 3)

Estimated velocity at each epoch [km/s].

estimated_paramsnumpy.ndarray or list or None

Estimated parameters at each requested epoch, or None if absent. For sequences, a list per leg containing only the requested rows for that leg, in request order (empty for unrequested legs).

Raises:
ValueError

If any requested epoch does not correspond to a filter measurement epoch. Use propagate_state() for arbitrary epochs.

global_std_devs() → ndarray#

Standard deviations of the combined global parameter estimate.

Only meaningful when this solution was produced by MultiFilterOD.fit(), which populates multi_arc_global with the combined covariance P_G.

Raises:
ValueError

If multi_arc_global has not been set (single-arc solution).

map_state_deviation_to_epoch(map_back_sequence: bool = False, use_smoothed: bool = True)#

Map corrections to their nominal initial epochs using STM ratios.

Parameters:
map_back_sequencebool, optional

For sequences, False (default) maps each leg’s own correction to its start. True starts with the final leg’s correction and maps backward through earlier legs using the filter’s definition-node maps. Both modes return a list in forward leg order. Ignored for continuous arcs.

use_smoothedbool, optional

Use the first smoothed epoch in each selected arc/leg if a nonempty smoothed history is stored. Otherwise use its last filtered epoch. Defaults to True. The last update wins at simultaneous epochs.

Returns:
ndarray or list of ndarray

Correction at the nominal initial epoch for a continuous arc, or one correction per sequence leg start. Each vector uses its model’s component order, units and frames, with storage padding removed. If no deviation history exists, return a zero vector sized from filter.n (falling back to filter.n_states or 6 for minimal filter objects).

Raises:
ValueError

If the timeline is invalid, the trajectory is unavailable, or a sequence leg contains no deviation rows.

numpy.linalg.LinAlgError

If a reference STM is singular.

See also

propagate_state

Map and combine corrections with nominal states.

Notes

A correction at stored epoch r is mapped to initial epoch s as

\[\delta x(s) = \Phi(s,t_0)\Phi(r,t_0)^{-1}\delta x(r).\]

The first measurement may follow the initial epoch, and the stored initial STM need not be identity. Both are handled explicitly. Shared sequence nodes belong to the later leg. Mapping through nodes uses the filter’s existing definition transformations; it does not run a smoother or add new observations. States a later leg drops (e.g. the parameters of a burn followed by a coast) are recovered from the forward solution at the node when the filter stored one (LKF, SRIF, SRIFB, LSB), see FilterOD._map_back_across_node().

print_stats(verbose: bool = True) → None#

Print statistical summary of the OD solution.

Parameters:
verbosebool, optional

Print detailed statistics. Defaults to True.

propagate_covariance(epochs: EpochArray, use_smoothed: bool = True, *, lookback_s: float | None = None, use_all_data: bool = False, include_consider: bool = True, apriori_covariance: ndarray | None = None, apriori_epoch: float | None = None) → List[ndarray]#

Map covariance to arbitrary epochs using the trajectory STMs.

With lookback_s=0 the forward product uses the last update at or before each epoch; a positive lookback moves that data cutoff earlier. Reconstruction explicitly selects the final update with use_all_data. In both cases \(P(t)=\Phi(t,t_k)P(t_k)\Phi(t,t_k)^T\) with the full STM, including considered parameters and their cross-covariances. No process noise or measurement updates are added during this mapping.

Stored STMs are used throughout their coverage, including before the first measurement and after the last one. For a continuous arc, missing or insufficiently accurate STMs are integrated on a copy of the propagator along the same nominal reference; this never changes the selected covariance or the filter’s propagator.

Parameters:
epochsEpochArray

Epochs where you want the propagated covariance.

use_smoothedbool, optional

If True and a smoothed solution is available, uses the smoothed covariance history (covariance_smooth) instead of the forward-filter history (covariance_est). Defaults to True. Set False for a causal filtered product or rolling forecast.

lookback_sfloat or None, optional

Nonnegative interval between the plotted epoch and its data cutoff. Zero uses measurements through t; 14*86400 uses measurements only through t - 14 days. A cutoff cannot use a smoothed history, and a positive lookback cannot be combined with use_all_data=True. Currently supported for continuous arcs. With None (the default), preserve the original mapping convention: continuous arcs use the final covariance inside/after the measurement arc and the first covariance before it; sequences use the last timeline update. This default is not a causal filtered product.

use_all_databool, optional

Map the final covariance to every requested epoch (deterministic reconstruction). Defaults to False. Currently requires a continuous arc; this is not a stochastic backward smoother.

include_considerbool, optional

Include the consider-augmented covariance when the filter has considered parameters (on a sequence, on the legs that consider any; the others have no augmented one). Defaults to True. No smoothed augmented history exists, and the filtered one is only stored with save_consider_covariance_history; in either case the estimated-only covariance is mapped and a RuntimeWarning is issued.

apriori_covariancendarray, optional

Prior for cutoffs before the first update. Defaults to the filter’s initial covariance. A missing prior raises instead of using a posterior containing future measurements.

apriori_epochfloat, optional

TDB epoch of the prior. Defaults to the filter’s initial state epoch.

Returns:
list of ndarray

Covariances in requested epoch order, including repeated epochs. Each matrix follows the full nominal state order and frames; element (i,j) has the product of component i and j units. Sequence legs may have different matrix sizes. Empty input returns [].

Raises:
ValueError

If histories or trajectory are unavailable; timeline lengths, epochs, cutoffs or dimensions are invalid; an explicit cutoff uses smoothing; or the required prior/consider covariance is missing.

NotImplementedError

For positive lookback or all-data reconstruction across sequence events, which require event transition maps.

numpy.linalg.LinAlgError

If a reference STM is singular.

Notes

For a selected covariance P(r), define A = Phi(t,t0) Phi(r,t0)^(-1). The mapped covariance is P(t) = A P(r) A.T, explicitly symmetrized to remove floating-point asymmetry. Mapping adds no process noise and performs no new measurement update. All-data reconstruction is a deterministic mapping of the final covariance, not a stochastic backward smoother. All STMs in a ratio use the same nominal reference.

Examples

For an existing solution and target EpochArray epochs:

filtered = solution.propagate_covariance(
    epochs, use_smoothed=False, lookback_s=0.0)
prediction_14d = solution.propagate_covariance(
    epochs, use_smoothed=False, lookback_s=14 * 86400.0)
reconstructed = solution.propagate_covariance(
    epochs, use_smoothed=False, use_all_data=True)
propagate_state(epochs: EpochArray, use_smoothed: bool = True, *, lookback_s: float | None = None, use_all_data: bool = False, apriori_deviation=None, apriori_epoch: float | None = None) → List[StateArray]#

Map deviations with STMs and add them to the nominal state once.

Parameters:
epochsEpochArray

Target epochs, converted to TDB seconds internally. None or an empty array returns an empty list. Input order and duplicates are retained.

use_smoothedbool, optional

Use a nonempty smoothed deviation history when available; otherwise use filtered deviations. Defaults to True.

lookback_sfloat or None, optional

Nonnegative data-cutoff interval in seconds. Zero selects the last update at or before t; positive values select the last update at or before t-lookback_s. None preserves the legacy convention: continuous arcs use the final update inside/after the measurement arc and the first update before it; sequences use the last timeline update. The default is not a causal filtered estimate.

use_all_databool, optional

Reconstruct every target from the final update. Defaults to False. Cannot be combined with positive lookback. Continuous arcs only.

apriori_deviationarray_like, optional

Prior correction for an explicit cutoff before the first update, in full nominal component order and units. Defaults to the filter’s initial deviation, then its settings, then a zero vector.

apriori_epochfloat, optional

TDB epoch of the prior correction. Defaults to the nominal initial state epoch. Ignored when all references are stored updates.

Returns:
list of StateArray

One corrected state per target. Component units, frames, owners and ordering follow the nominal model. Sequence leg sizes may differ.

Raises:
ValueError

If a history or trajectory is absent; histories, epochs, cutoffs or dimensions are invalid; an explicit cutoff selects smoothed data; or reference and target belong to different sequence legs.

NotImplementedError

For positive lookback or all-data reconstruction on sequences; these operations require event transition maps.

numpy.linalg.LinAlgError

If the reference STM is singular.

See also

propagate_covariance

Covariance mapping with the same reference policy.

propagate_state_covariance

Return matched state/covariance pairs.

estimated_trajectory

Read each measurement epoch’s own filter update.

Notes

For a selected correction at r and STMs sharing nominal origin t0,

\[\hat x(t) = x_{\mathrm{nom}}(t) + \Phi(t,t_0)\Phi(r,t_0)^{-1}\delta x_r.\]

This is linearized mapping about the fitted reference. It performs no new filter update, adds no process noise, and is not a nonlinear integration of the corrected state. The correction is added once. Missing coverage or rejected STM interpolation triggers nominal reintegration on copies, preserving the selected reference update and the live filter. Shared sequence boundaries belong to the later leg.

Examples

For an existing solution and target EpochArray epochs:

filtered = solution.propagate_state(
    epochs, use_smoothed=False, lookback_s=0.0)
prediction_14d = solution.propagate_state(
    epochs, use_smoothed=False, lookback_s=14 * 86400.0)
reconstructed = solution.propagate_state(
    epochs, use_smoothed=False, use_all_data=True)
propagate_state_covariance(epochs: EpochArray, use_smoothed: bool = True, *, lookback_s: float | None = None, use_all_data: bool = False, include_consider: bool = True, apriori_deviation=None, apriori_covariance=None, apriori_epoch: float | None = None) → List[tuple]#

Map state and covariance using the same data cutoff and smoothing.

Parameters:
epochsEpochArray

Target epochs. None or an empty array returns an empty list.

use_smoothedbool, optional

Use both smoothed histories if available. Defaults to True. If neither is stored, use filtered histories. If only one is stored, raise instead of mixing smoothed and filtered solution products.

lookback_sfloat or None, optional

Data-cutoff interval in seconds, as in propagate_state(). None preserves legacy reference selection; zero uses data through t; positive values use data through t-lookback_s.

use_all_databool, optional

Reconstruct every target from the final update. Defaults to False; cannot be combined with positive lookback. Continuous arcs only.

include_considerbool, optional

Include consider-augmented covariance when the filter has considered parameters. Defaults to True. Falls back to the estimated-only covariance, with a RuntimeWarning, when no augmented history fits (always the case when smoothing).

apriori_deviationarray_like, optional

Prior correction in nominal component units for cutoffs before data. Defaults to the filter’s initial deviation or zero.

apriori_covariancearray_like, optional

Full prior covariance for cutoffs before data. Defaults to the filter’s initial covariance. Element (i,j) has the product of component i and j units, in the same order as the nominal state.

apriori_epochfloat, optional

Shared TDB epoch of the prior deviation and covariance. Defaults to the nominal initial state epoch.

Returns:
list of tuple of (StateArray, ndarray)

One pair per target in request order, retaining duplicates. Each covariance has shape (state.size, state.size) and uses its state’s component ordering, frames and units.

Raises:
ValueError

If only one smoothed history is stored, output counts/dimensions differ, or either mapper rejects the input/history.

NotImplementedError

For cutoffs/reconstruction requiring sequence event transition maps.

numpy.linalg.LinAlgError

If an STM needed by either mapper is singular.

Notes

Both quantities are mapped about the fitted reference. Mapping adds no process noise; reconstruction is not a stochastic backward smoother. See the individual mappers for prior selection and integration fallback.

Examples

Return causal state/covariance pairs without later measurements:

pairs = solution.propagate_state_covariance(
    epochs, use_smoothed=False, lookback_s=0.0)
for state, covariance in pairs:
    sigma = np.sqrt(np.diag(covariance))
save(filepath: str | Path = None, fmt: str = None) → None#

Save all filter iterations to a single JSON or pickle file.

If filepath is None, uses output_settings.output_dir / output_settings.solution_json_filename + the format extension.

Each iteration is a key ‘iter_1’, ‘iter_2’, etc. The current (final) solution is also stored under ‘final’.

Parameters:
filepathstr or Path, optional

Destination file. When None, derived from the output settings.

fmt{“json”, “pickle”}, optional

On-disk format. When None (default) it is inferred from the file extension (.pkl gives pickle, otherwise JSON); when given explicitly, the file extension is normalised to match.

Notes

metadata describes the state (frame, units, state_components, state_labels), the a priori state and covariance (apriori), the last convergence test (convergence), provenance and covariance_storage. Each block holds the fields of _solution_to_dict().

Iteration blocks store covariance diagonals. final stores full covariances when output_settings.save_full_covariance is set and diagonals otherwise, never both. Each iter_<k> block adds that pass’s convergence test and its epoch_solution (the deviation from the a priori state at the initial epoch). final adds the full epoch_solution of _epoch_solution(), or None if it cannot be formed.

serialize(filepath: str | Path, protocol: int = 5) → None#

Serialize SolutionOD object to binary format using pickle.

Parameters:
filepathstr or Path

Path to output pickle file.

protocolint, optional

Pickle protocol version. Defaults to highest available.

Notes

The filter object reference is NOT serialized to avoid circular dependencies and large file sizes. Stored solution arrays, any already-computed absolute-state cache, residual epochs, full update timeline, frame/units, state components, sequence layout, run metadata (a priori, convergence, provenance), the epoch solution and multi-arc global results are preserved. Serializing does not force the lazy absolute-state cache to be evaluated. Reattach the matching fitted filter on deserialization to use trajectory or STM methods; propagators and SPICE kernels are not embedded.

state_covariance_to_elements(epochs: EpochArray | None = None, body=None, grav_param=None, use_smoothed: bool = True) → Tuple[ndarray, ndarray, List[ndarray]]#

Express the estimate and its covariance in Keplerian elements.

Pairs the estimated state and covariance with covariance_to_elements(), so the result is the same solution read in (a, e, i, RAAN, argp, M) instead of Cartesian components. The state and covariance are taken from propagate_state_covariance(), which keeps the two consistent with each other and with use_smoothed.

Parameters:
epochsEpochArray, optional

Epochs to report. Defaults to the solution’s measurement epochs, which for a long arc means one state and covariance propagation per measurement — pass a coarser set if that is more than you need.

bodyBody or int, optional

Which object in the state vector to convert, as the body itself or its SPICE ID. Only needed when more than one body carries a position, as in a spacecraft-plus-asteroid estimate.

grav_paramfloat, ArrayWUnits or CelestialBody, optional

Gravitational parameter of the attracting body. Defaults to that of the state’s own origin.

use_smoothedbool, optional

Passed through to propagate_state_covariance(). Defaults to True.

Returns:
timesnumpy.ndarray

Epochs, seconds past J2000 TDB, one per row of elements.

elementsnumpy.ndarray

(n_epochs, 6) mean elements, ordered by MEAN_ELEMENT_NAMES, in km and radians.

covarianceslist of numpy.ndarray

One (6, 6) element covariance per epoch.

Raises:
ElementConversionError

If body is ambiguous or absent from the state vector, or the gravitational parameter cannot be resolved.

See also

scarabaeus.OrbitalElements.covariance_to_elements

The transformation applied here.

SolutionOD.propagate_state_covariance

Supplies the state and covariance.

Notes

The mapping is linearised about the estimate, so it holds while the Cartesian uncertainty is small against the curvature of the element map. A near-circular or near-equatorial orbit leaves argp and RAAN weakly defined, and their variances inflate accordingly — that is the geometry showing through, not a defect in the transform.

The elements are only Keplerian in an inertial frame centred on the attracting body; reading them off a state expressed otherwise gives numbers without the usual meaning.

References

[1]

Montenbruck, O., & Gill, E. (2000). Satellite Orbits: Models, Methods and Applications. Springer. ISBN 978-3-540-67280-7.

property is_covariance_analysis: bool#

Whether this is a covariance analysis.

property n_epochs: int#

Number of epochs in the solution.

property n_states: int#

Number of states in the state vector (the full union for a sequence).

exception DebugHistoryError#

Bases: ValueError

Raised when filter debug histories that pair up per measurement update differ in length.

exception ElementConversionError#

Bases: ValueError

Raised when the estimate cannot be expressed in orbital elements — the body is not in the state vector, or its gravitational parameter is not available.