SolutionOD#
- class SolutionOD(filter_obj: FilterOD, output_settings: OutputSettings | None = None)#
Bases:
objectStores 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:
filterFilterODThe 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_estfor single-iteration runs.state_estnp.ndarray, optionalAbsolute 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.
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.FilterODBase filter class that produces this solution.
scarabaeus.OutputSettingsControls which quantities are stored.
Notes
Storage of each quantity is controlled by the flags in the associated
OutputSettingsinstance. Quantities not selected are left asNoneand not computed during the filter run.save()andcreate_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
solutionand targetEpochArraycalledepochs:# 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, usepropagate_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 componentiandjunits.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=Noneretains the older API convention: a continuous arc maps its final update inside/after the measurement arc and its first update before it. Specifylookback_s=0.0, use_smoothed=Falsefor 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
NotImplementedErrorbecause 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. Usepropagate_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 aneffective_sample_sizearray of shape (n_epochs,). Mean, standard deviation and bounds use component units; covariance uses their pairwise products. The same dictionary is saved asuq_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.weightsmay 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 (.pklgives pickle, otherwise JSON); when given explicitly, the file extension is normalised to match.
Notes
Holds the same fields as the
finalblock ofsave(), with the metadata ofsave()plusn_epochsat 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 aValueError— usepropagate_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.timestampsto 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
Noneif 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 populatesmulti_arc_globalwith the combined covarianceP_G.- Raises:
- ValueError
If
multi_arc_globalhas 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 tofilter.n_statesor 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_stateMap 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=0the 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 withuse_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.
See also
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_covarianceCovariance mapping with the same reference policy.
propagate_state_covarianceReturn matched state/covariance pairs.
estimated_trajectoryRead 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 (.pklgives pickle, otherwise JSON); when given explicitly, the file extension is normalised to match.
Notes
metadatadescribes the state (frame,units,state_components,state_labels), the a priori state and covariance (apriori), the last convergence test (convergence),provenanceandcovariance_storage. Each block holds the fields of_solution_to_dict().Iteration blocks store covariance diagonals.
finalstores full covariances whenoutput_settings.save_full_covarianceis set and diagonals otherwise, never both. Eachiter_<k>block adds that pass’sconvergencetest and itsepoch_solution(the deviation from the a priori state at the initial epoch).finaladds the fullepoch_solutionof_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 frompropagate_state_covariance(), which keeps the two consistent with each other and withuse_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 byMEAN_ELEMENT_NAMES, in km and radians.- covarianceslist of numpy.ndarray
One
(6, 6)element covariance per epoch.
- Raises:
- ElementConversionError
If
bodyis ambiguous or absent from the state vector, or the gravitational parameter cannot be resolved.
See also
scarabaeus.OrbitalElements.covariance_to_elementsThe transformation applied here.
SolutionOD.propagate_state_covarianceSupplies 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
argpandRAANweakly 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.
- exception DebugHistoryError#
Bases:
ValueErrorRaised when filter debug histories that pair up per measurement update differ in length.
- exception ElementConversionError#
Bases:
ValueErrorRaised when the estimate cannot be expressed in orbital elements — the body is not in the state vector, or its gravitational parameter is not available.