2. FilterOD#

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

Bases: object

Implements an orbit determination filter for spacecraft trajectory estimation.

Parameters:

propagator (Propagator) – The propagator object containing state vector and dynamics.
measurements (list of dict) – List of measurement descriptors.
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.

References

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

Methods

`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.
`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.

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

2. FilterOD#

This Page