`FilterOD`#

class FilterOD(propagator: Propagator | MissionSequence, measurements: MeasurementSpec, settings: FilterSettings, traj_name: str | None = None, traj_dir: str | None = None, overwrite_traj: bool = True)#

Bases: object

Parent class for orbit determination filters used for spacecraft state and parameter estimation from tracking measurements.

The framework supports single- and multi-object estimation problems through flexible dynamical and measurement model definitions. The class propagates a reference solution, constructs the linearized measurement sensitivity matrix, and estimates corrections to the reference trajectory, dynamical states, and model parameters.

Supported estimation problems include spacecraft translational dynamics, stochastic and deterministic parameters, multi-arc or mission-sequence configurations, and coupled dynamical systems.

Maximum-a-posteriori estimate

Every filter in this framework estimates the deviation \(\Delta x_0\) from the reference trajectory \(x^*(t)\) that minimises the weighted least-squares cost:

\[J(\Delta x_0) = \Delta x_0^T P_0^{-1} \Delta x_0 + \sum_k \Bigl[y_k - H_k \Phi_{k,0}\,\Delta x_0\Bigr]^T R_k^{-1} \Bigl[y_k - H_k \Phi_{k,0}\,\Delta x_0\Bigr]\]

where \(y_k = z_k - h(x^*(t_k))\) is the prefit residual and \(P_0^{-1}\) is the a-priori information matrix. Under Gaussian assumptions the minimiser is the maximum-a-posteriori (MAP) estimate \(\hat{x}_0 = x^*(t_0) + \widehat{\Delta x}_0\).

Iteration

Because the measurement model is linearised around \(x^*\), the single-pass estimate is only first-order accurate. The fit() method re-runs the filter iteratively: after each pass the reference is re-propagated from \(x^*(t_0) + \widehat{\Delta x}_0\) and the filter is re-applied on the updated reference. At convergence the accumulated deviation satisfies \(\widehat{\Delta x}_0 \approx 0\), meaning the current reference is the MAP estimate and the covariance is the true posterior covariance linearised around the solution.

Schmidt consider parameters

Parameters that affect measurements but are poorly constrained and should not be estimated can be declared as consider parameters (FilterSettings). Their uncertainty is propagated through the filter and inflates the covariance of the estimated state (Schmidt, 1966), but their values are never updated by measurements. This prevents over-confidence when unmodelled force parameters are present.

Parameters:

propagator (Propagator or MissionSequence) – Propagator or mission sequence object that defines the reference trajectory and state transition matrices (STMs) for orbit determination.
measurements (MeasurementSpec) – Measurement specification object.
settings (FilterSettings) – Filter configuration settings.
traj_name (str, optional) – Name for the trajectory BSP file.
traj_dir (str, optional) – Directory to write trajectory.
overwrite_traj (bool) – If True, overwrite existing trajectory file.

Notes

This class is not instantiated directly; use a concrete subclass (LKF, SRIF, LSB, or SRIFB). Call fit() to run the filter and retrieve results via SolutionOD.

See also

scarabaeus.LKF: Linearized Kalman Filter (sequential, covariance form).
scarabaeus.SRIF: Square Root Information Filter (sequential, square-root form).
scarabaeus.LSB: Batch Least-Squares estimator.
scarabaeus.SRIFB: Batch Square Root Information Filter.
scarabaeus.SolutionOD: Container for the estimated state history and covariance.

References

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

Attributes:

DMC_flag: True when Dynamic Model Compensation (DMC) process noise is active.
SNC_flag: True when State Noise Compensation (SNC) process noise is active.
apriori_covariance_est: Apriori covariance restricted to the estimated parameter subspace.
covariance_analysis: True when running in covariance-analysis mode (no measurement updates).
flag_sequence: True for multi-leg (mission-sequence) trajectories.
has_consider: True if consider parameters are present in the state vector.
measurement_data: Container for all measurement datasets, residuals, and editing flags.
measurements: Measurement specification object passed at construction time.
n: Dimension of the estimated state vector.
propagator: Propagator or ScenarioSetup used to build the reference trajectory.
settings: Filter configuration (covariance, process noise, output options).
trajectory: Propagated reference trajectory stored in a SPICE BSP kernel with a companion JSON file for STMs and estimated parameters.

Methods

`fit`([traj_name, traj_dir, overwrite_traj, ...])	Perform iterative orbit determination with automatic convergence checking.
`observability_test`([print_obs, threshold, ...])	Compute the observability and information matrices for the current filter setup.

fit(traj_name: str | None = None, traj_dir: str | None = None, overwrite_traj: bool = True, max_iterations: int = 10, convergence_threshold: float = 1e-06, verbose: bool = True, if_sequential_smooth: bool = False)#

Perform iterative orbit determination with automatic convergence checking.

Runs the filter iteratively, applying state corrections from each solution to the next iteration until convergence or maximum iterations is reached.

Parameters:

traj_name (str, optional) – Base name for trajectory files. Iteration number will be appended. If None, auto-generates names. Defaults to None.
traj_dir (str, optional) – Directory for trajectory files. Defaults to None (current directory).
overwrite_traj (bool, optional) – Whether to overwrite existing trajectories. Defaults to True.
max_iterations (int, optional) – Maximum number of iterations. Defaults to 10.
convergence_threshold (float, optional) – RMS deviation threshold for convergence. Defaults to 1e-6.
verbose (bool, optional) – If True, prints iteration progress. Defaults to True.
if_sequential_smooth (bool, optional) – If True, applies sequential smoothing after filtering. Defaults to False.

Returns:

solution (SolutionOD) – Final filter solution from the last iteration.
iteration_count (int) – Number of iterations performed.
converged (bool) – Whether convergence was achieved.

Examples

>>> # Automatic iteration with convergence checking
>>> lkf = LKF(propagator, covariance, measurements)
>>> solution, n_iters, converged = lkf.iterate(
...     max_iterations=5,
...     convergence_threshold=1e-6
... )
>>> print(f"Converged in {n_iters} iterations: {converged}")

observability_test(print_obs=False, threshold=0.1, meas_corr=None)#

Compute the observability and information matrices for the current filter setup.

The observability matrix \(\mathcal{O}\) is formed by stacking the measurement sensitivity matrices mapped back to the reference epoch \(t_0\) via the State Transition Matrix (STM):

\[\begin{split}\mathcal{O} = \begin{bmatrix} H_1\,\Phi_{1,0} \\ H_2\,\Phi_{2,0} \\ \vdots \\ H_k\,\Phi_{k,0} \end{bmatrix}\end{split}\]

where \(H_k\) is the measurement Jacobian at epoch \(t_k\) and \(\Phi_{k,0}\) is the STM from \(t_0\) to \(t_k\). The system is observable if and only if \(\mathcal{O}\) has full column rank \(n\) (the state dimension).

The information matrix (Fisher information / weighted normal matrix) \(\Lambda\) accumulates the measurement information across all epochs:

\[\Lambda = \sum_{k} H_{k0}^T\, R_k^{-1}\, H_{k0}\]

where \(H_{k0} = H_k\,\Phi_{k,0}\) and \(R_k\) is the measurement noise covariance at epoch \(k\). The system is observable if and only if \(\Lambda\) is positive definite, i.e. all its eigenvalues exceed threshold.

Parameters:

print_obs (bool, optional) – If True, prints the state dimension, rank of \(\Lambda\), and whether it is strictly positive definite.
threshold (float, optional) – Minimum eigenvalue threshold used to assess positive definiteness of \(\Lambda\). Defaults to 1e-1.
meas_corr (list, optional) – Off-diagonal correlation coefficients for the per-epoch measurement noise covariance \(R_k\). Must be a flat list of \(n_m (n_m - 1) / 2\) values covering the upper triangular part of the correlation matrix in row-major order, where \(n_m\) is the number of simultaneous measurements at each epoch. When None, \(R_k\) is diagonal (measurements assumed uncorrelated).

Returns:

info_matrix, obs_matrix – A tuple with the following values corresponding to their respective indices:

[0] = info_matrixnumpy.ndarray of shape (n, n)
The information matrix \(\Lambda\).
[1] = obs_matrixnumpy.ndarray of shape (m, n)
The observability matrix \(\mathcal{O}\), where m is the total number of measurements across all epochs.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

property DMC_flag: bool#: True when Dynamic Model Compensation (DMC) process noise is active.

property SNC_flag: bool#: True when State Noise Compensation (SNC) process noise is active.

property apriori_covariance_est: ndarray#

Apriori covariance restricted to the estimated parameter subspace.

Returns the (n_est x n_est) block of the full initial covariance matrix corresponding to estimated (non-considered) state variables. When no consider parameters are present the full matrix is returned.

Returns:: Square apriori covariance of shape (n_est, n_est).
Return type:: np.ndarray

property covariance_analysis: bool#: True when running in covariance-analysis mode (no measurement updates).

property flag_sequence: bool#: True for multi-leg (mission-sequence) trajectories.

property has_consider: bool#: True if consider parameters are present in the state vector.

property measurement_data#: Container for all measurement datasets, residuals, and editing flags.

property measurements#: Measurement specification object passed at construction time.

property n: int#: Dimension of the estimated state vector.

property propagator#: Propagator or ScenarioSetup used to build the reference trajectory. Replaced by a ScenarioSetup when a MissionSequence is provided.

property settings#: Filter configuration (covariance, process noise, output options).

property trajectory#: Propagated reference trajectory stored in a SPICE BSP kernel with a companion JSON file for STMs and estimated parameters.

FilterOD#

`FilterOD`#