`LKF`#

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

Bases: FilterOD

Linearized Kalman Filter (LKF) for spacecraft orbit determination.

The LKF is a sequential estimator that operates on a fixed reference trajectory computed once before filtering begins. At each measurement epoch \(t_k\) the filter estimates the deviation from that reference, \(\hat{x}_k\), rather than the full state. This is the key distinction from the Extended Kalman Filter (EKF): the EKF re-linearizes around the updated state after every measurement, effectively re-propagating a new reference at each step.

Why the LKF is preferred over the EKF in astrodynamics

For deep-space and interplanetary missions, tracking passes are typically short and separated by long coast arcs of hours to days. In this sparse- measurement regime the EKF is prone to divergence: the re-linearization point drifts with each update, and the STM computed from the updated state can become inconsistent with the actual nonlinear dynamics over the long coast arcs, destabilizing the covariance propagation. The LKF avoids this by keeping a single, dynamically consistent reference trajectory throughout the entire pass. Iterated re-runs of the filter (outer iterations) progressively reduce the linearization error without sacrificing numerical stability.

Algorithm

Let \(\hat{x}_k\) be the estimated state deviation at epoch \(t_k\) and \(\hat{P}_k\) be the associated covariance.

Time update — propagate from \(t_{k-1}\) to \(t_k\) using the one-step STM \(\Phi_{k,k-1} = \Phi_k \Phi_{k-1}^{-1}\):

\[ \begin{align}\begin{aligned}\bar{x}_k = \Phi_{k,k-1}\,\hat{x}_{k-1}\\\bar{P}_k = \Phi_{k,k-1}\,\hat{P}_{k-1}\,\Phi_{k,k-1}^T + Q_k\end{aligned}\end{align} \]

where \(Q_k\) is the discrete process noise covariance (zero when no SNC/DMC model is active).

Measurement update — given the prefit residual \(y_k = z_k - h(\bar{x}^*_k)\), the measurement Jacobian \(H_k\), and the measurement noise covariance \(R_k\):

\[ \begin{align}\begin{aligned}K_k = \bar{P}_k H_k^T \bigl(H_k \bar{P}_k H_k^T + R_k\bigr)^{-1}\\\hat{x}_k = \bar{x}_k + K_k\,(y_k - H_k\,\bar{x}_k)\\\hat{P}_k = (I - K_k H_k)\,\bar{P}_k\,(I - K_k H_k)^T + K_k R_k K_k^T\end{aligned}\end{align} \]

The last line uses the Joseph-stabilized form, which preserves symmetry and positive definiteness of the covariance regardless of numerical rounding.

Schmidt consider parameters

When consider parameters \(c\) are present, the innovation covariance is inflated by their uncertainty before computing the Kalman gain:

\[ \begin{align}\begin{aligned}S_k = H_{x,k}\,\bar{P}_{xx,k}\,H_{x,k}^T + H_{c,k}\,P_{cc}\,H_{c,k}^T + R_k\\K_k = \bar{P}_{xx,k}\,H_{x,k}^T S_k^{-1}\end{aligned}\end{align} \]

The posterior covariance carries an additional consider contribution:

\[\hat{P}_{xx,k} = (I - K_k H_{x,k})\,\bar{P}_{xx,k}\, (I - K_k H_{x,k})^T + K_k R_k K_k^T + K_k H_{c,k}\,P_{cc}\,H_{c,k}^T K_k^T\]

The state deviation \(\hat{x}_k\) is not updated for consider parameters; only the covariance is inflated.

Smoother (Rauch–Tung–Striebel)

After the forward pass the LKF supports an optional Rauch–Tung–Striebel (RTS) backward smoother. Starting from the last epoch \(K\) and working backwards to \(k = 1\):

\[ \begin{align}\begin{aligned}G_k = \hat{P}_k\,\Phi_{k+1,k}^T\,\bar{P}_{k+1}^{-1}\\\hat{x}_k^s = \hat{x}_k + G_k\,(\hat{x}_{k+1}^s - \bar{x}_{k+1})\\\hat{P}_k^s = \hat{P}_k + G_k\,(\hat{P}_{k+1}^s - \bar{P}_{k+1})\,G_k^T\end{aligned}\end{align} \]

where \(G_k\) is the smoother gain, and the superscript \(s\) denotes smoothed quantities. The smoother uses all measurements — past and future — to refine the estimate at each epoch, reducing uncertainty particularly over coast arcs between tracking passes.

Parameters:

propagator (Propagator or MissionSequence) – Propagator defining the reference trajectory and STMs. A MissionSequence can be used for multi-leg trajectories with maneuver events.
measurements (MeasurementSpec) – Measurement specification object.
settings (FilterSettings) – Filter configuration including initial covariance and optional process noise model.
traj_name (str, optional) – Name for the trajectory BSP file. Auto-generated if None.
traj_dir (str, optional) – Directory for the trajectory BSP file.
overwrite_traj (bool, optional) – If True, overwrite any existing trajectory file.

Notes

For dense tracking or when superior numerical conditioning is required, prefer SRIF, which delivers the same solution with roughly double the effective floating-point precision. When process noise is not needed, the batch estimators LSB and SRIFB are simpler alternatives.

See also

scarabaeus.SRIF: Square-root information form of the same algorithm, with superior numerical conditioning for ill-posed problems.
scarabaeus.FilterOD: Base class providing trajectory and measurement handling.
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).
covariance_consider_history: Consider-augmented covariance at each measurement epoch (when consider parameters are active).
covariance_history: Posterior covariance at each measurement epoch.
flag_sequence: True for multi-leg (mission-sequence) trajectories.
has_consider: True if consider parameters are present in the state vector.
innovation_covariances: Innovation covariance \(S_k = H_k \bar{P}_k H_k^T + R_k\) at each epoch.
kalman_gains: Kalman gain \(K_k\) at each measurement epoch.
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.
postfit_residuals: Post-update measurement residuals, keyed by epoch.
prefit_residuals: Pre-update measurement residuals, keyed by epoch.
propagator: Propagator or ScenarioSetup used to build the reference trajectory.
settings: Filter configuration (covariance, process noise, output options).
state_deviation_history: State deviation at each measurement epoch.
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.

property innovation_covariances: list#: Innovation covariance \(S_k = H_k \bar{P}_k H_k^T + R_k\) at each epoch. Populated when settings.output.save_innovation_covariances is True.

property kalman_gains: list#: Kalman gain \(K_k\) at each measurement epoch. Populated when settings.output.save_kalman_gains is True.

LKF#

`LKF`#