3. LKF#

class LKF(propagator: Propagator, measurements: List[Dict], settings: FilterSettings, traj_name: str | None = None, traj_dir: str | None = None, overwrite_traj: bool = True)#

Bases: FilterOD

Implements a Linearized Kalman Filter (LKF) for spacecraft orbit determination.

Applies the Linearized Kalman Filter (LKF) method to estimate a spacecraft’s state using sequential measurements while propagating uncertainty through a dynamic model. The LKF is particularly useful when the state evolution and measurement models are nonlinear, but can be linearized using a State Transition Matrix (STM).

The filter follows a predict-update cycle, where:

The prediction step propagates the state and covariance forward in time.
The update step refines the state using measurement updates via the Kalman gain.

The LKF is recursive, meaning it updates the estimate as new measurements become available, making it computationally efficient compared to batch methods.

Parameters:

propagator (Propagator) – An instance of the Propagator class that provides the spacecraft trajectory and STM.
settings (FilterSettings) – An instance of the FilterSettings class containing filter configuration, including: * Initial state covariance matrix. * Process noise model and parameters.
measurements (list) –
A list of measurement observations, where each entry includes:
- Measurement time.
- Residuals between observed and predicted values.
- Measurement covariance matrix.
- Measurement Jacobian (sensitivity matrix).
- Additional metadata (e.g., instrument, measurement type).
traj_name (str, optional) – The name of the trajectory file to be created (default is None).
traj_dir (str, optional) – Directory to save the trajectory file (default is current working directory).
overwrite_traj (bool, optional) – If True, overwrite the existing trajectory file (default is True).

See also

scarabaeus.FilterOD: Base class for orbit determination filters.
scarabaeus.SolutionOD: Stores estimated state history and covariance evolution.
scarabaeus.CovarianceMatrix: Defines measurement noise covariance.
scarabaeus.StateNoiseCompensation: Represents process noise in the system dynamics.

Notes

The LKF assumes Gaussian noise models for both system dynamics and measurement errors.

Process noise can be included to account for unmodeled dynamics in state propagation.

The filter can operate across multiple trajectory legs, adjusting the state size at event epochs.

Unlike batch least-squares, the Kalman filter updates estimates sequentially, allowing real-time implementation.

References

Tapley, B. D., Schutz, B. E., & Born, G. H. (2004). Statistical orbit determination. Elsevier.

Methods

`compute`([meas_corr, printOutput, ...])	Performs the state estimation using the Linearized Kalman Filter.
`iterate`([traj_name, traj_dir, ...])	Perform iterative orbit determination with automatic convergence checking.
`map_covariance_definition_node`(...[, ...])	Adjusts the covariance matrix to match a new state vector definition.
`map_deviation_definition_node`(...[, ...])	Adjusts the deviation vector to align with a new state vector definition.
`map_stm_definition_node`(counter_events, old_STM)	Adjusts the State Transition Matrix (STM) to match a new state definition.
`observability_test`([print_obs, threshold, ...])	Performs an observability analysis on the system by computing the information matrix.
`reinitialize`([state_deviation, ...])	Reinitialize the filter for iterative estimation.
`smoother`([printOutput])	Rauch-Tung-Striebel backward smoother.
`split_partials_hx_hc`(H)	Split the partial derivatives matrix into estimated and consider parameters.
`split_stm_phi_psi`(STM)	Split the State Transition Matrix (STM) into Phi and Psi components.
`unwrap_residuals`(postfit_residuals, ...)	Organizes postfit residuals into a dictionary categorized by dataset.
`validate_sequence_batch`()	Validates consistency in state vector definitions across sequential estimation legs.

compute(meas_corr: list = None, printOutput: bool = True, underweighting_factor: float = 1.0) → SolutionOD#

Performs the state estimation using the Linearized Kalman Filter.

Iterates through the measurement epochs, performing prediction and update steps. The predicted state is corrected based on new measurements using the Kalman gain.

Parameters:

meas_corr (list, optional) – List of correction factors for measurement covariance. Defaults to None.
printOutput (bool, optional) – If True, prints the progress of the filter. Defaults to True.
underweighting_factor (float, optional) – A scaling factor to modify the measurement covariance (used for robustness). Defaults to 1.0.

Returns:

An object containing the estimated state deviation history and covariance evolution.

Return type:

SolutionOD

iterate(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}")

map_covariance_definition_node(counter_events: int, old_covariance: ndarray, flag_augment: bool = True) → ndarray#

Adjusts the covariance matrix to match a new state vector definition.

Parameters:

counter_events (int) – Index of the current sequence event for state transition.
old_covariance (numpy.ndarray) – Previous covariance matrix to be updated.
flag_augment (bool, optional) – If True, expands the covariance matrix; otherwise, reduces it. Defaults to True.

Returns:

updated_covar – Updated covariance matrix reflecting the new state definition.

Return type:

numpy.ndarray

map_deviation_definition_node(counter_events: int, old_deviation: ndarray, flag_augment: bool = True) → ndarray#

Adjusts the deviation vector to align with a new state vector definition.

Parameters:

counter_events (int) – Index of the current sequence event for state transition.
old_deviation (numpy.ndarray) – Previous state deviation vector.
flag_augment (bool, optional) – If True, expands the deviation vector; otherwise, reduces it. Defaults to True.

Returns:

updated_dev – Updated deviation vector reflecting the new state definition.

Return type:

numpy.ndarray

map_stm_definition_node(counter_events: int, old_STM: ndarray, flag_augment: bool = True) → ndarray#

Adjusts the State Transition Matrix (STM) to match a new state definition.

Parameters:

counter_events (int) – Index of the current sequence event for state transition.
old_STM (numpy.ndarray) – Previous STM to be updated.
flag_augment (bool, optional) – If True, expands the STM; otherwise, reduces it. Defaults to True.

Returns:

updated_stm – Updated State Transition Matrix reflecting the new state definition.

Return type:

numpy.ndarray

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

Performs an observability analysis on the system by computing the information matrix.

Checks whether the system’s observability matrix has full rank and determines the positive definiteness of the information matrix.

Parameters:

print_obs (bool, optional) – If True, prints details of the observability analysis.
threshold (float, optional) – Minimum eigenvalue threshold for checking positive definiteness.
meas_corr (list, optional) – Measurement covariance correction factors.

Returns:

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

[0] = info_matrixnumpy.ndarray
The computed information matrix.
[1] = obs_matrixnumpy.ndarray
The observability matrix constructed from measurement partials.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

reinitialize(state_deviation: ndarray | None = None, state_vector: StateArray | None = None, traj_name: str | None = None, traj_dir: str | None = None, overwrite_traj: bool = True) → None#

Reinitialize the filter for iterative estimation.

Updates the state vector by applying deviations from a previous filter iteration, re-propagates the trajectory, and rebuilds measurement datasets. This method enables iterative orbit determination where each iteration refines the reference trajectory using corrections from the previous filter solution.

Parameters:

state_deviation (np.ndarray, optional) – State deviation vector from previous filter iteration (e.g., from solution.map_state_deviation_to_epoch()). If provided, this deviation is added to the current state vector. Shape should be (n,) or (n, 1). Defaults to None.
state_vector (StateArray, optional) – New state vector to use. If None, uses the current propagator’s state vector. If state_deviation is provided, it will be applied to this state vector. Defaults to None.
traj_name (str, optional) – Name for the new trajectory BSP file. If None, auto-generates a name. Defaults to None.
traj_dir (str, optional) – Directory to write the new trajectory. If None, uses current directory. Defaults to None.
overwrite_traj (bool, optional) – If True, overwrites existing trajectory file with the same name. Defaults to True.

Returns:

Updates self.trajectory and self.measurement_data in place.

Return type:

None

Raises:

ValueError – If state_deviation is provided but state_vector cannot be determined.

Notes

This method modifies the FilterOD object in place by: 1. Applying state deviation to the state vector (if provided) 2. Re-propagating the trajectory with the updated state 3. Rebuilding measurement datasets 4. Re-initializing filter attributes (sequence, ground stations, etc.)

The body objects are NOT modified - the same spacecraft body is used across iterations for simplicity. Each iteration operates on the same SPICE ID.

Examples

>>> # Manual iteration control
>>> lkf = LKF(propagator, covariance, measurements)
>>>
>>> # Iteration 1
>>> solution_it1 = lkf.compute()
>>> deviation_it1 = solution_it1.map_state_deviation_to_epoch()
>>>
>>> # Iteration 2
>>> lkf.reinitialize(state_deviation=deviation_it1)
>>> solution_it2 = lkf.compute()
>>>
>>> # Iteration 3
>>> deviation_it2 = solution_it2.map_state_deviation_to_epoch()
>>> lkf.reinitialize(state_deviation=deviation_it2)
>>> solution_it3 = lkf.compute()

3. LKF#

This Page