LKF#
- class LKF(propagator: Propagator | MissionSequence, measurements: MeasurementSpec, settings: FilterSettings, traj_name: str | None = None, traj_dir: str | None = None, overwrite_traj: bool = True, verbose: bool = True)#
Bases:
FilterODLinearized 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 keeps the covariance positive definite under rounding better than \((I - K_k H_k)\bar{P}_k\). The result is symmetrized after each update: rounding leaves the product slightly asymmetric, and the next gain amplifies the asymmetry when the data are much more precise than \(\bar{P}_k\) (Doppler).
Consider parameters
When consider parameters \(c\) are present, the filter runs a consider analysis, the same estimator as
SRIF,SRIFBandLSB([1], Ch. 6). The estimate is conditioned on \(c = \bar{c}\), so the gain uses \(\bar{P}_{xx}\), the covariance with the considered states known:\[ \begin{align}\begin{aligned}S_k = H_{x,k}\,\bar{P}_{xx,k}\,H_{x,k}^T + R_k, \quad K_k = \bar{P}_{xx,k}\,H_{x,k}^T S_k^{-1}\\\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\end{aligned}\end{align} \]The sensitivity \(S_x\) carries the error in \(c\) into the estimate:
\[\bar{S}_{x,k} = (\Phi_{x}\,\hat{S}_{x,k-1} + \Psi)\,\Phi_{c}^{-1}, \quad \hat{S}_{x,k} = (I - K_k H_{x,k})\,\bar{S}_{x,k} - K_k H_{c,k}\]and the consider covariance is
\[\hat{P}_{c,k} = \hat{P}_{xx,k} + \hat{S}_{x,k}\,P_{cc}\,\hat{S}_{x,k}^T, \quad \hat{P}_{xc,k} = \hat{S}_{x,k}\,P_{cc}\]At the first epoch and at sequence nodes, \(S_x = P_{xc} P_{cc}^{-1}\) and \(P_{xx} = P_c - S_x P_{xc}^T\), so an a-priori correlation between \(x\) and \(c\) is kept. Process noise enters \(P_{xx}\) only. The state deviation \(\hat{x}_k\) is not updated for consider parameters.
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:
- propagatorPropagator or MissionSequence
Propagator defining the reference trajectory and STMs. A
MissionSequencecan be used for multi-leg trajectories with maneuver events.- measurementsMeasurementSpec
Measurement specification object.
- settingsFilterSettings
Filter configuration including initial covariance and optional process noise model.
- traj_namestr, optional
Name for the trajectory BSP file. Auto-generated if
None.- traj_dirstr, optional
Directory for the trajectory BSP file.
- overwrite_trajbool, optional
If
True, overwrite any existing trajectory file.- verbosebool, optional
If
False, silence the printout of the propagation run at construction. Defaults toTrue.
- Attributes:
innovation_covariancesInnovation covariance \(S_k = H_k \bar{P}_k H_k^T + R_k\) at each measurement update.
innovationsPre-update innovation \(\nu_k = y_k - H_k \bar{x}_k\) at each measurement update, paired with
innovation_covariances.kalman_gainsKalman gain \(K_k\) at each measurement update.
See also
scarabaeus.SRIFSquare-root information form of the same algorithm, with superior numerical conditioning for ill-posed problems.
scarabaeus.FilterODBase class providing trajectory and measurement handling.
scarabaeus.SolutionODContainer for the estimated state history and covariance.
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 the data are much more precise than the a-priori (\(H\bar{P}H^T/R \gtrsim 10^8\), typical for Doppler), the covariance form can use up most of the float64 digits, and the LKF covariances may then differ from the SRIF ones by a few percent. When process noise is not needed, the batch estimatorsLSBandSRIFBare simpler alternatives.References
[1]Tapley, B. D., Schutz, B. E., & Born, G. H. (2004). Statistical Orbit Determination. Elsevier Academic Press. ISBN 978-0-12-683630-1.
- property innovation_covariances: list#
Innovation covariance \(S_k = H_k \bar{P}_k H_k^T + R_k\) at each measurement update. With consider parameters it also holds their contribution \(H_y P_{cc} H_y^T\), \(H_y = H_x S_x + H_c\). Populated when
settings.output.save_innovation_covariancesorsettings.output.save_nis_statisticsisTrue.
- property innovations: list#
Pre-update innovation \(\nu_k = y_k - H_k \bar{x}_k\) at each measurement update, paired with
innovation_covariances. Populated whensettings.output.save_nis_statisticsisTrue(not in covariance analysis).