`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_obj (FilterOD) – The filter object that produced this solution.
output_settings (OutputSettings, optional) – Configuration controlling what quantities are stored.

filter#

Reference to the filter object.

Type:: FilterOD

output_settings#

Output configuration.

Type:: OutputSettings

timestamps#

Epoch timestamps for the solution.

Type:: np.ndarray

deviation_est#

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

Type:: np.ndarray, optional

deviation_cumulative#

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

Type:: np.ndarray, optional

state_est#

Absolute state estimate (reference + deviation_est) at each measurement epoch [n_epochs x n_states]. Layout: [pos_x, pos_y, pos_z, vel_x, vel_y, vel_z, param_0, …]. Computed lazily on first access (SPICE queries).

Type:: np.ndarray, optional

deviation_smooth#

Smoothed state deviation history [n_epochs x n_states].

Type:: np.ndarray, optional

covariance_est#

Estimated covariance matrices at each epoch.

Type:: list of np.ndarray, optional

covariance_smooth#

Smoothed covariance matrices (from RTS smoother).

Type:: list of np.ndarray, optional

covariance_consider#

Consider parameter covariance matrices.

Type:: list of np.ndarray, optional

prefits#

Pre-fit measurement residuals.

Type:: list, optional

postfits#

Post-fit measurement residuals.

Type:: list, optional

postfits_smoother#

Post-fit residuals for smoothed solution.

Type:: list, optional

uq_metrics#

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

Type:: dict, optional

debug#

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

Type:: dict, optional

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.

See also

scarabaeus.FilterOD: Base filter class that produces this solution.
scarabaeus.OutputSettings: Controls which quantities are stored.

References

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

Attributes:

filter: The filter object used for orbit determination.
is_covariance_analysis: Whether this is a covariance analysis.
n_epochs: Number of epochs in the solution.
n_states: Number of states in the state vector.
state_est: Absolute state estimate at each measurement epoch [n_epochs x n_states].

Methods

`UQ_compute`([particle_states, confidence_levels])	Compute UQ metrics for particle-based 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`([...])	Maps the state deviation to the initial epoch using the state transition matrix.
`print_stats`([verbose])	Print statistical summary of the OD solution.
`propagate_covariance`(epochs[, use_smoothed])	Propagate the estimated covariance to arbitrary epochs using trajectory STMs.
`propagate_state`(epochs[, use_smoothed])	Propagate the estimated state to arbitrary epochs using trajectory STMs.
`propagate_state_covariance`(epochs[, ...])	Propagate both the estimated state and covariance to arbitrary epochs.
`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.

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

Deserialize SolutionOD object from binary file.

Parameters:

filepath (str or Path) – Path to pickle file.
filter_obj (FilterOD, optional) – Filter object to associate with solution. If None, creates placeholder.

Returns:

Deserialized solution object.

Return type:

SolutionOD

Raises:

FileNotFoundError – If file does not exist.

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

Compute UQ metrics for particle-based filters.

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

Parameters:

particle_states (np.ndarray, optional) – Particle states [n_particles x n_states x n_epochs]. If None, attempts to extract from filter.
confidence_levels (list of float, optional) – Confidence levels for uncertainty bounds.

Returns:

UQ metrics including mean, std, covariances, skewness, kurtosis, percentiles, and effective sample size.

Return type:

dict

Raises:

ValueError – If particle data is unavailable.

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

Export solution results to a JSON or pickle file.

Parameters:

filepath (str 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 → pickle, otherwise JSON); when given explicitly, the file extension is normalised to match.

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:

epochs (EpochArray) – The measurement epochs at which to evaluate the estimated trajectory. Every epoch must match an entry in solution.timestamps to within 1 s.
use_smoothed (bool, optional) – If True and a smoothed solution is available, use the smoothed deviations; otherwise use the filtered deviations. Defaults to True.

Returns:

estimated_pos (numpy.ndarray, shape (n, 3)) – Estimated position at each epoch [km].
estimated_vel (numpy.ndarray, shape (n, 3)) – Estimated velocity at each epoch [km/s].
estimated_params (numpy.ndarray or list or None) – Estimated parameters at each epoch, or None if no parameters exist.

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)#

Maps the state deviation to the initial epoch using the state transition matrix.

If smoothed solution is available, simply returns the first smoothed deviation (which is already at the initial epoch). Otherwise, maps the filtered deviation backward through the STMs.

Parameters:

map_back_sequence (bool, optional) – If True, maps deviations back through the entire sequence; otherwise, maps only the last leg. Only used when smoothed solution is not available. Defaults to True.
use_smoothed (bool, optional) – If True and smoothed solution is available, uses the first smoothed deviation. Otherwise maps filtered deviations backward. Defaults to True.

Returns:

mapped – The mapped state deviation(s) at the initial epoch. For sequences, returns a list with one deviation per leg if not mapping back. Otherwise returns a single deviation vector.

Return type:

numpy.ndarray or list of numpy.ndarray

print_stats(verbose: bool = True) → None#

Print statistical summary of the OD solution.

Parameters:: verbose (bool, optional) – Print detailed statistics. Defaults to True.

propagate_covariance(epochs: EpochArray, use_smoothed: bool = True) → List[ndarray]#

Propagate the estimated covariance to arbitrary epochs using trajectory STMs.

For epochs inside the measurement arc, uses stored trajectory STMs. For epochs outside the arc, re-propagates from the nearest arc boundary.

Parameters:

epochs (EpochArray) – Epochs where you want the propagated covariance.
use_smoothed (bool, 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.

propagate_state(epochs: EpochArray, use_smoothed: bool = True) → List[StateArray]#

Propagate the estimated state to arbitrary epochs using trajectory STMs.

For epochs inside the measurement arc, uses stored trajectory STMs. For epochs outside the arc, re-propagates from the nearest arc boundary.

Parameters:: epochs (EpochArray) – Epochs where you want the estimated state.
Returns:: One StateArray per requested epoch.
Return type:: list of StateArray

propagate_state_covariance(epochs: EpochArray, use_smoothed: bool = True) → List[tuple]#

Propagate both the estimated state and covariance to arbitrary epochs.

Parameters:

epochs (EpochArray) – Epochs where you want the estimated state and covariance.
use_smoothed (bool, optional) – If True and a smoothed solution is available, uses smoothed deviations. Defaults to True.

Returns:

One tuple per requested epoch: (StateArray, P(t)).

Return type:

list of (StateArray, np.ndarray)

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:

filepath (str 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 → pickle, otherwise JSON); when given explicitly, the file extension is normalised to match.

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

Serialize SolutionOD object to binary format using pickle.

Parameters:

filepath (str or Path) – Path to output pickle file.
protocol (int, optional) – Pickle protocol version. Defaults to highest available.

Notes

The filter object reference is NOT serialized to avoid circular dependencies and large file sizes. Only solution data is preserved.

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.