opengnc.kalman_filters package

Submodules

opengnc.kalman_filters.akf module

Adaptive Kalman Filter (AKF) with online covariance estimation (Myers-Tapley).

class opengnc.kalman_filters.akf.AKF(dim_x: int, dim_z: int, window_size: int = 20)

Bases: KF

Adaptive Kalman Filter (AKF) using Myers-Tapley online covariance estimation.

Estimates process noise covariance (Q) and measurement noise covariance (R) online using the innovation sequence within a moving window.

Parameters:

• dim_x (int) – Dimension of the state vector.

• dim_z (int) – Dimension of the measurement vector.

• window_size (int, optional) – Moving window size (N) for covariance estimation. Default is 20.

predict(u: ndarray | None = None, f_mat: ndarray | None = None, q_mat: ndarray | None = None, b_mat: ndarray | None = None) → None

Predict step (stores history for adaptation).

Parameters:

• u (np.ndarray, optional) – Control input vector.

• f_mat (np.ndarray, optional) – State transition matrix.

• q_mat (np.ndarray, optional) – Process noise covariance.

• b_mat (np.ndarray, optional) – Control input matrix.

update(z: ndarray, h_mat: ndarray | None = None, r_mat: ndarray | None = None) → None

Update step with online R and Q adaptation.

Parameters:

• z (np.ndarray) – Measurement vector.

• h_mat (np.ndarray, optional) – Measurement matrix.

• r_mat (np.ndarray, optional) – Measurement noise covariance.

opengnc.kalman_filters.attitude_fusion module

Sensor-agnostic attitude fusion wrapper built on MEKF or UKF_Attitude.

class opengnc.kalman_filters.attitude_fusion.AttitudeSensorFusion(backend: str = 'mekf', **filter_kwargs: Any)

Bases: object

Decouple attitude filters from specific sensor combinations.

property bias: ndarray

predict(measurement: SensorMeasurement, dt: float | None = None) → None

Propagate the attitude state from an angular-rate sensor packet.

property quaternion: ndarray

update_from_measurement(measurement: SensorMeasurement) → None

update_from_measurements(measurements: list[SensorMeasurement]) → None

opengnc.kalman_filters.ckf module

Cubature Kalman Filter (CKF) using spherical-radial rule for non-linear estimation.

class opengnc.kalman_filters.ckf.CKF(dim_x: int, dim_z: int)

Bases: object

Cubature Kalman Filter (CKF) using the spherical-radial rule.

Offers superior numerical stability and accuracy for high-dimensional non-linear systems compared to the UKF. Uses exactly $2n$ cubature points with equal weights.

Parameters:

• dim_x (int) – Dimension of the state vector $x$.

• dim_z (int) – Dimension of the measurement vector $z$.

predict(dt: float, fx_func: Callable, q_mat: ndarray | None = None, **kwargs: Any) → None

Cubature predict step.

Parameters:

• dt (float) – Propagation time step (s).

• fx_func (Callable) – Non-linear transition function $f(x, dt, dots) to x_{new}$.

• q_mat (np.ndarray, optional) – Process noise covariance. Defaults to self.Q.

• **kwargs (Any) – Additional parameters for $f$.

update(z: ndarray, hx_func: Callable, r_mat: ndarray | None = None, **kwargs: Any) → None

Cubature update step.

Parameters:

• z (np.ndarray) – Measurement vector.

• hx_func (Callable) – Non-linear measurement model $h(x, dots) to z_{pred}$.

• r_mat (np.ndarray, optional) – Measurement noise covariance. Defaults to self.R.

• **kwargs (Any) – Additional parameters for $h$.

opengnc.kalman_filters.ekf module

Extended Kalman Filter (EKF) for non-linear systems using Jacobians.

class opengnc.kalman_filters.ekf.EKF(dim_x: int, dim_z: int)

Bases: object

Extended Kalman Filter (EKF) for non-linear systems.

Linearizes the non-linear state transition and measurement models around the current estimate using first-order Taylor expansion (Jacobians).

Parameters:

• dim_x (int) – Dimension of the state vector $x$.

• dim_z (int) – Dimension of the measurement vector $z$.

predict(fx_func: Callable[[...], ndarray], f_jac_func: Callable[[...], ndarray], dt: float, u: ndarray | None = None, q_mat: ndarray | None = None, **kwargs: Any) → None

Non-linear state prediction.

Equations: - State Predict: $mathbf{hat{x}}_{k|k-1} = f(mathbf{hat{x}}_{k-1|k-1}, Delta t, mathbf{u})$ - Covariance Predict: $mathbf{P}_{k|k-1} = mathbf{F} mathbf{P}_{k-1|k-1} mathbf{F}^T + mathbf{Q}$ where $mathbf{F}$ is the state transition Jacobian.

Parameters:

• fx_func (Callable) – Transition function.

• f_jac_func (Callable) – Jacobian of fx_func.

• dt (float) – Propagation step (s).

• u (np.ndarray | None, optional) – Control input.

• q_mat (np.ndarray | None, optional) – Process noise.

• **kwargs (Any) – Additional parameters.

update(z: ndarray, hx_func: Callable[[...], ndarray], h_jac_func: Callable[[...], ndarray], r_mat: ndarray | None = None, **kwargs: Any) → None

Non-linear measurement update.

Equations: - Innovation: $mathbf{y} = mathbf{z} - h(mathbf{hat{x}}_{k|k-1})$ - Gain: $mathbf{K} = mathbf{P}_{k|k-1} mathbf{H}^T (mathbf{H} mathbf{P}_{k|k-1} mathbf{H}^T + mathbf{R})^{-1}$ - Update: $mathbf{hat{x}}_{k|k} = mathbf{hat{x}}_{k|k-1} + mathbf{K} mathbf{y}$ - Joseph Form Covariance: $mathbf{P}_{k|k} = (mathbf{I} - mathbf{K} mathbf{H}) mathbf{P}_{k|k-1} (mathbf{I} - mathbf{K} mathbf{H})^T + mathbf{K} mathbf{R} mathbf{K}^T$

Parameters:

• z (np.ndarray) – Measurement vector.

• hx_func (Callable) – Measurement model.

• h_jac_func (Callable) – Jacobian of hx_func.

• r_mat (np.ndarray | None, optional) – Measurement noise.

• **kwargs (Any) – Additional parameters.

opengnc.kalman_filters.enkf module

Ensemble Kalman Filter (EnKF) using Monte Carlo samples for covariance representation.

class opengnc.kalman_filters.enkf.EnKF(dim_x: int, dim_z: int, ensemble_size: int = 50)

Bases: object

Ensemble Kalman Filter.

Uses an ensemble of states to represent the error covariance matrix.

property P: ndarray

Return the ensemble covariance matrix.

initialize_ensemble(x_mean: ndarray, p_cov: ndarray) → None

Initialize the ensemble from a multivariate normal distribution.

predict(dt: float, fx_func: Callable, q_mat: ndarray | None = None, **kwargs: Any) → None

Propagate each ensemble member forward in time.

update(z: ndarray, hx_func: Callable, r_mat: ndarray | None = None, **kwargs: Any) → None

Update the ensemble using a measurement.

property x: ndarray

Return the ensemble mean state.

opengnc.kalman_filters.fixed_interval_smoother module

Fixed-Interval Smoother (Fraser-Potter / Two-Filter) for linear systems.

opengnc.kalman_filters.fixed_interval_smoother.fixed_interval_smoother(x_forward: list[ndarray], p_forward: list[ndarray], f_mats: list[ndarray], q_mats: list[ndarray], z_meas: list[ndarray], h_mats: list[ndarray], r_mats: list[ndarray]) → tuple[ndarray, ndarray]

Fixed-Interval Smoother (Two-Filter / Fraser-Potter approach).

Combines a forward-running Kalman filter with a backward-running information filter to produce the optimal estimate at every point in a fixed interval.

Parameters:

• x_forward (list of np.ndarray) – Forward filtered states $x_{k|k}$. Length N.

• p_forward (list of np.ndarray) – Forward filtered covariances $P_{k|k}$. Length N.

• f_mats (list of np.ndarray) – State transition matrices $F_k$ (from $k$ to $k+1$). Length N-1.

• q_mats (list of np.ndarray) – Process noise covariances $Q_k$ (from $k$ to $k+1$). Length N-1.

• z_meas (list of np.ndarray) – Measurements $z_k$. Length N.

• h_mats (list of np.ndarray) – Measurement matrices $H_k$. Length N.

• r_mats (list of np.ndarray) – Measurement noise covariances $R_k$. Length N.

Returns:

• x_smooth (np.ndarray) – Smoothed states.

• p_smooth (np.ndarray) – Smoothed covariances.

opengnc.kalman_filters.imm module

Interacting Multiple Model (IMM) Filter for switching-mode systems.

class opengnc.kalman_filters.imm.IMM(filters: list[Any], transition_matrix: ndarray)

Bases: object

Interacting Multiple Model (IMM) Filter.

Estimates the state of a system that can switch between multiple discrete modes (models). Ideal for tracking maneuvering targets where dynamics switch between models like constant velocity and constant acceleration.

Parameters:

• filters (list) – List of filter objects (e.g., KF, EKF, UKF).

• transition_matrix (np.ndarray) – Model transition probability matrix (N x N), where $T_{ij} = P(M_j | M_i)$.

property mu: ndarray

Alias for mu_probs (backward compatibility).

predict(dt: float, **kwargs: Any) → None

Predict step (Mixing and model-specific prediction).

Parameters:

• dt (float) – Time step (s).

• **kwargs (Any) – Additional arguments passed to the sub-filters’ predict methods.

update(z: ndarray, **kwargs: Any) → None

Update step (Model-specific update and mode probability update).

Parameters:

• z (np.ndarray) – Measurement vector (dim_z,).

• **kwargs (Any) – Additional arguments passed to the sub-filters’ update methods.

opengnc.kalman_filters.kf module

Standard Linear Kalman Filter (KF) implementation.

class opengnc.kalman_filters.kf.KF(dim_x: int, dim_z: int)

Bases: object

Standard Discrete-Time Linear Kalman Filter (KF).

Suitable for linear estimation and navigation problems (e.g., constant velocity or constant acceleration models in Cartesian space).

Parameters:

• dim_x (int) – Dimension of the state vector $x$.

• dim_z (int) – Dimension of the measurement vector $z$.

predict(u: ndarray | None = None, f_mat: ndarray | None = None, q_mat: ndarray | None = None, b_mat: ndarray | None = None) → None

Predict the state and covariance one step forward.

Equations: $x_{k|k-1} = F x_{k-1|k-1} + B u_k$ $P_{k|k-1} = F P_{k-1|k-1} F^T + Q$

Parameters:

• u (np.ndarray, optional) – Control input vector (dim_u,).

• f_mat (np.ndarray, optional) – State transition matrix (dim_x, dim_x). Defaults to self.F.

• q_mat (np.ndarray, optional) – Process noise covariance (dim_x, dim_x). Defaults to self.Q.

• b_mat (np.ndarray, optional) – Control input matrix (dim_x, dim_u). Defaults to self.B.

update(z: ndarray, h_mat: ndarray | None = None, r_mat: ndarray | None = None) → None

Update state estimate using a new measurement.

Uses the Joseph robust form for covariance updates to maintain symmetry and positive-definiteness.

Parameters:

• z (np.ndarray) – Measurement vector (dim_z,).

• h_mat (np.ndarray, optional) – Measurement matrix (dim_z, dim_x). Defaults to self.H.

• r_mat (np.ndarray, optional) – Measurement noise covariance (dim_z, dim_z). Defaults to self.R.

opengnc.kalman_filters.mekf module

Multiplicative Extended Kalman Filter (MEKF) for attitude estimation.

class opengnc.kalman_filters.mekf.MEKF(q_init: ndarray | None = None, beta_init: ndarray | None = None)

Bases: object

Packet-oriented multiplicative EKF for spacecraft attitude estimation.

VECTOR_QUANTITIES = {'magnetic_field', 'nadir_vector', 'sun_vector'}

predict(measurement: SensorMeasurement, dt: float | None = None, q_mat: ndarray | None = None) → None

Propagate state from an angular-rate measurement packet.

update(measurement: SensorMeasurement, r_mat: ndarray | None = None) → None

Apply a vector or quaternion correction from a measurement packet.

update_quaternion(measurement: SensorMeasurement, r_mat: ndarray | None = None) → None

Apply a direct attitude correction from a quaternion measurement packet.

opengnc.kalman_filters.pf module

Particle Filter (Sequential Importance Resampling) for non-Gaussian, nonlinear systems.

class opengnc.kalman_filters.pf.ParticleFilter(dim_x: int, dim_z: int, num_particles: int = 1000)

Bases: object

Bootstrap particle filter.

Represents the posterior distribution using weighted particles.

property P: ndarray

Return the weighted error covariance matrix.

initialize_particles(x_mean: ndarray, p_cov: ndarray) → None

Initialize particles from a multivariate Gaussian distribution.

neff() → float

Calculate the effective number of particles.

predict(dt: float, fx_func: Callable, q_mat: ndarray | None = None, **kwargs: Any) → None

Propagate each particle and inject process noise.

resample() → None

Resample particles using systematic resampling.

update(z: ndarray, hx_func: Callable, r_mat: ndarray | None = None, **kwargs: Any) → None

Reweight particles from the latest measurement and resample if needed.

property x: ndarray

Return the weighted mean state.

opengnc.kalman_filters.rts_smoother module

Rauch-Tung-Striebel (RTS) Smoother for linear systems.

opengnc.kalman_filters.rts_smoother.rts_smoother(x_filtered_list: list[ndarray], p_filtered_list: list[ndarray], f_mats: list[ndarray], q_mats: list[ndarray]) → tuple[ndarray, ndarray]

Rauch-Tung-Striebel (RTS) Smoother for linear systems.

Performs a backward pass over Kalman filter results to provide optimal minimum-variance estimates utilizing all future information (fixed-interval smoothing).

Parameters:

• x_filtered_list (list[np.ndarray]) – List of filtered state estimates $x_{k|k}$ (N steps).

• p_filtered_list (list[np.ndarray]) – List of filtered covariances $P_{k|k}$ (N steps).

• f_mats (list[np.ndarray]) – List of state transition matrices $F_k$ from $k$ to $k+1$. (N-1 steps).

• q_mats (list[np.ndarray]) – List of process noise covariances $Q_k$ from $k$ to $k+1$. (N-1 steps).

Returns:

(x_smoothed, p_smoothed) arrays. - x_smoothed: (N, dim_x) - p_smoothed: (N, dim_x, dim_x)

Return type:

tuple[np.ndarray, np.ndarray]

opengnc.kalman_filters.sr_ukf module

Square-root Unscented Kalman Filter (SR-UKF) algorithm.

class opengnc.kalman_filters.sr_ukf.SRUKF(dim_x: int, dim_z: int, alpha: float = 0.001, beta: float = 2.0, kappa: float = 0.0)

Bases: object

Square-root Unscented Kalman Filter.

Propagates the Cholesky factor of the covariance matrix for improved numerical stability relative to the standard UKF.

property P: ndarray

Return the full covariance matrix P = S S^T.

predict(dt: float, fx_func: Callable, qs_mat: ndarray | None = None, **kwargs: Any) → None

Perform the SR-UKF predict step.

update(z: ndarray, hx_func: Callable, rs_mat: ndarray | None = None, **kwargs: Any) → None

Perform the SR-UKF update step.

opengnc.kalman_filters.ukf module

Unscented Kalman Filter (UKF) with support for states on manifolds.

class opengnc.kalman_filters.ukf.UKF(dim_x: int, dim_z: int, dim_p: int | None = None, alpha: float = 0.001, beta: float = 2.0, kappa: float = 0.0, subtract_x: Callable[[...], ndarray] | None = None, add_x: Callable[[...], ndarray] | None = None, mean_x: Callable[[...], ndarray] | None = None)

Bases: object

Generalized Unscented Kalman Filter (UKF).

generate_sigma_points(x: ndarray, p_cov: ndarray) → ndarray

predict(dt: float, fx_func: Callable[[...], ndarray], q_mat: ndarray | None = None, **kwargs: Any) → None

update(z: ndarray, hx_func: Callable, r_mat: ndarray | None = None, **kwargs: Any) → None

class opengnc.kalman_filters.ukf.UKF_Attitude(q_init: ndarray | None = None, bias_init: ndarray | None = None, dim_z: int = 3, **kwargs: Any)

Bases: UKF

Packet-oriented UKF specialized for spacecraft attitude estimation.

VECTOR_QUANTITIES = {'magnetic_field', 'nadir_vector', 'sun_vector'}

predict(measurement: SensorMeasurement, dt: float | None = None, q_mat: ndarray | None = None) → None

Propagate the attitude state from an angular-rate measurement packet.

update(measurement: SensorMeasurement, r_mat: ndarray | None = None) → None

Apply a vector or quaternion correction from a measurement packet.

Module contents

class opengnc.kalman_filters.AKF(dim_x: int, dim_z: int, window_size: int = 20)

Bases: KF

Adaptive Kalman Filter (AKF) using Myers-Tapley online covariance estimation.

Estimates process noise covariance (Q) and measurement noise covariance (R) online using the innovation sequence within a moving window.

Parameters:

• dim_x (int) – Dimension of the state vector.

• dim_z (int) – Dimension of the measurement vector.

• window_size (int, optional) – Moving window size (N) for covariance estimation. Default is 20.

predict(u: ndarray | None = None, f_mat: ndarray | None = None, q_mat: ndarray | None = None, b_mat: ndarray | None = None) → None

Predict step (stores history for adaptation).

Parameters:

• u (np.ndarray, optional) – Control input vector.

• f_mat (np.ndarray, optional) – State transition matrix.

• q_mat (np.ndarray, optional) – Process noise covariance.

• b_mat (np.ndarray, optional) – Control input matrix.

update(z: ndarray, h_mat: ndarray | None = None, r_mat: ndarray | None = None) → None

Update step with online R and Q adaptation.

Parameters:

• z (np.ndarray) – Measurement vector.

• h_mat (np.ndarray, optional) – Measurement matrix.

• r_mat (np.ndarray, optional) – Measurement noise covariance.

class opengnc.kalman_filters.AttitudeSensorFusion(backend: str = 'mekf', **filter_kwargs: Any)

Bases: object

Decouple attitude filters from specific sensor combinations.

property bias: ndarray

predict(measurement: SensorMeasurement, dt: float | None = None) → None

Propagate the attitude state from an angular-rate sensor packet.

property quaternion: ndarray

update_from_measurement(measurement: SensorMeasurement) → None

update_from_measurements(measurements: list[SensorMeasurement]) → None

class opengnc.kalman_filters.CKF(dim_x: int, dim_z: int)

Bases: object

Cubature Kalman Filter (CKF) using the spherical-radial rule.

Offers superior numerical stability and accuracy for high-dimensional non-linear systems compared to the UKF. Uses exactly $2n$ cubature points with equal weights.

Parameters:

• dim_x (int) – Dimension of the state vector $x$.

• dim_z (int) – Dimension of the measurement vector $z$.

predict(dt: float, fx_func: Callable, q_mat: ndarray | None = None, **kwargs: Any) → None

Cubature predict step.

Parameters:

• dt (float) – Propagation time step (s).

• fx_func (Callable) – Non-linear transition function $f(x, dt, dots) to x_{new}$.

• q_mat (np.ndarray, optional) – Process noise covariance. Defaults to self.Q.

• **kwargs (Any) – Additional parameters for $f$.

update(z: ndarray, hx_func: Callable, r_mat: ndarray | None = None, **kwargs: Any) → None

Cubature update step.

Parameters:

• z (np.ndarray) – Measurement vector.

• hx_func (Callable) – Non-linear measurement model $h(x, dots) to z_{pred}$.

• r_mat (np.ndarray, optional) – Measurement noise covariance. Defaults to self.R.

• **kwargs (Any) – Additional parameters for $h$.

class opengnc.kalman_filters.EKF(dim_x: int, dim_z: int)

Bases: object

Extended Kalman Filter (EKF) for non-linear systems.

Linearizes the non-linear state transition and measurement models around the current estimate using first-order Taylor expansion (Jacobians).

Parameters:

• dim_x (int) – Dimension of the state vector $x$.

• dim_z (int) – Dimension of the measurement vector $z$.

predict(fx_func: Callable[[...], ndarray], f_jac_func: Callable[[...], ndarray], dt: float, u: ndarray | None = None, q_mat: ndarray | None = None, **kwargs: Any) → None

Non-linear state prediction.

Equations: - State Predict: $mathbf{hat{x}}_{k|k-1} = f(mathbf{hat{x}}_{k-1|k-1}, Delta t, mathbf{u})$ - Covariance Predict: $mathbf{P}_{k|k-1} = mathbf{F} mathbf{P}_{k-1|k-1} mathbf{F}^T + mathbf{Q}$ where $mathbf{F}$ is the state transition Jacobian.

Parameters:

• fx_func (Callable) – Transition function.

• f_jac_func (Callable) – Jacobian of fx_func.

• dt (float) – Propagation step (s).

• u (np.ndarray | None, optional) – Control input.

• q_mat (np.ndarray | None, optional) – Process noise.

• **kwargs (Any) – Additional parameters.

update(z: ndarray, hx_func: Callable[[...], ndarray], h_jac_func: Callable[[...], ndarray], r_mat: ndarray | None = None, **kwargs: Any) → None

Non-linear measurement update.

Equations: - Innovation: $mathbf{y} = mathbf{z} - h(mathbf{hat{x}}_{k|k-1})$ - Gain: $mathbf{K} = mathbf{P}_{k|k-1} mathbf{H}^T (mathbf{H} mathbf{P}_{k|k-1} mathbf{H}^T + mathbf{R})^{-1}$ - Update: $mathbf{hat{x}}_{k|k} = mathbf{hat{x}}_{k|k-1} + mathbf{K} mathbf{y}$ - Joseph Form Covariance: $mathbf{P}_{k|k} = (mathbf{I} - mathbf{K} mathbf{H}) mathbf{P}_{k|k-1} (mathbf{I} - mathbf{K} mathbf{H})^T + mathbf{K} mathbf{R} mathbf{K}^T$

Parameters:

• z (np.ndarray) – Measurement vector.

• hx_func (Callable) – Measurement model.

• h_jac_func (Callable) – Jacobian of hx_func.

• r_mat (np.ndarray | None, optional) – Measurement noise.

• **kwargs (Any) – Additional parameters.

class opengnc.kalman_filters.EnKF(dim_x: int, dim_z: int, ensemble_size: int = 50)

Bases: object

Ensemble Kalman Filter.

Uses an ensemble of states to represent the error covariance matrix.

property P: ndarray

Return the ensemble covariance matrix.

initialize_ensemble(x_mean: ndarray, p_cov: ndarray) → None

Initialize the ensemble from a multivariate normal distribution.

predict(dt: float, fx_func: Callable, q_mat: ndarray | None = None, **kwargs: Any) → None

Propagate each ensemble member forward in time.

update(z: ndarray, hx_func: Callable, r_mat: ndarray | None = None, **kwargs: Any) → None

Update the ensemble using a measurement.

property x: ndarray

Return the ensemble mean state.

class opengnc.kalman_filters.IMM(filters: list[Any], transition_matrix: ndarray)

Bases: object

Interacting Multiple Model (IMM) Filter.

Estimates the state of a system that can switch between multiple discrete modes (models). Ideal for tracking maneuvering targets where dynamics switch between models like constant velocity and constant acceleration.

Parameters:

• filters (list) – List of filter objects (e.g., KF, EKF, UKF).

• transition_matrix (np.ndarray) – Model transition probability matrix (N x N), where $T_{ij} = P(M_j | M_i)$.

property mu: ndarray

Alias for mu_probs (backward compatibility).

predict(dt: float, **kwargs: Any) → None

Predict step (Mixing and model-specific prediction).

Parameters:

• dt (float) – Time step (s).

• **kwargs (Any) – Additional arguments passed to the sub-filters’ predict methods.

update(z: ndarray, **kwargs: Any) → None

Update step (Model-specific update and mode probability update).

Parameters:

• z (np.ndarray) – Measurement vector (dim_z,).

• **kwargs (Any) – Additional arguments passed to the sub-filters’ update methods.

class opengnc.kalman_filters.KF(dim_x: int, dim_z: int)

Bases: object

Standard Discrete-Time Linear Kalman Filter (KF).

Suitable for linear estimation and navigation problems (e.g., constant velocity or constant acceleration models in Cartesian space).

Parameters:

• dim_x (int) – Dimension of the state vector $x$.

• dim_z (int) – Dimension of the measurement vector $z$.

predict(u: ndarray | None = None, f_mat: ndarray | None = None, q_mat: ndarray | None = None, b_mat: ndarray | None = None) → None

Predict the state and covariance one step forward.

Equations: $x_{k|k-1} = F x_{k-1|k-1} + B u_k$ $P_{k|k-1} = F P_{k-1|k-1} F^T + Q$

Parameters:

• u (np.ndarray, optional) – Control input vector (dim_u,).

• f_mat (np.ndarray, optional) – State transition matrix (dim_x, dim_x). Defaults to self.F.

• q_mat (np.ndarray, optional) – Process noise covariance (dim_x, dim_x). Defaults to self.Q.

• b_mat (np.ndarray, optional) – Control input matrix (dim_x, dim_u). Defaults to self.B.

update(z: ndarray, h_mat: ndarray | None = None, r_mat: ndarray | None = None) → None

Update state estimate using a new measurement.

Uses the Joseph robust form for covariance updates to maintain symmetry and positive-definiteness.

Parameters:

• z (np.ndarray) – Measurement vector (dim_z,).

• h_mat (np.ndarray, optional) – Measurement matrix (dim_z, dim_x). Defaults to self.H.

• r_mat (np.ndarray, optional) – Measurement noise covariance (dim_z, dim_z). Defaults to self.R.

class opengnc.kalman_filters.MEKF(q_init: ndarray | None = None, beta_init: ndarray | None = None)

Bases: object

Packet-oriented multiplicative EKF for spacecraft attitude estimation.

VECTOR_QUANTITIES = {'magnetic_field', 'nadir_vector', 'sun_vector'}

predict(measurement: SensorMeasurement, dt: float | None = None, q_mat: ndarray | None = None) → None

Propagate state from an angular-rate measurement packet.

update(measurement: SensorMeasurement, r_mat: ndarray | None = None) → None

Apply a vector or quaternion correction from a measurement packet.

update_quaternion(measurement: SensorMeasurement, r_mat: ndarray | None = None) → None

Apply a direct attitude correction from a quaternion measurement packet.

class opengnc.kalman_filters.ParticleFilter(dim_x: int, dim_z: int, num_particles: int = 1000)

Bases: object

Bootstrap particle filter.

Represents the posterior distribution using weighted particles.

property P: ndarray

Return the weighted error covariance matrix.

initialize_particles(x_mean: ndarray, p_cov: ndarray) → None

Initialize particles from a multivariate Gaussian distribution.

neff() → float

Calculate the effective number of particles.

predict(dt: float, fx_func: Callable, q_mat: ndarray | None = None, **kwargs: Any) → None

Propagate each particle and inject process noise.

resample() → None

Resample particles using systematic resampling.

update(z: ndarray, hx_func: Callable, r_mat: ndarray | None = None, **kwargs: Any) → None

Reweight particles from the latest measurement and resample if needed.

property x: ndarray

Return the weighted mean state.

opengnc.kalman_filters.PythonMEKF

alias of MEKF

opengnc.kalman_filters.PythonUKF_Attitude

alias of UKF_Attitude

opengnc.kalman_filters.RTS_smoother(x_filtered_list: list[ndarray], p_filtered_list: list[ndarray], f_mats: list[ndarray], q_mats: list[ndarray]) → tuple[ndarray, ndarray]

Rauch-Tung-Striebel (RTS) Smoother for linear systems.

Performs a backward pass over Kalman filter results to provide optimal minimum-variance estimates utilizing all future information (fixed-interval smoothing).

Parameters:

• x_filtered_list (list[np.ndarray]) – List of filtered state estimates $x_{k|k}$ (N steps).

• p_filtered_list (list[np.ndarray]) – List of filtered covariances $P_{k|k}$ (N steps).

• f_mats (list[np.ndarray]) – List of state transition matrices $F_k$ from $k$ to $k+1$. (N-1 steps).

• q_mats (list[np.ndarray]) – List of process noise covariances $Q_k$ from $k$ to $k+1$. (N-1 steps).

Returns:

(x_smoothed, p_smoothed) arrays. - x_smoothed: (N, dim_x) - p_smoothed: (N, dim_x, dim_x)

Return type:

tuple[np.ndarray, np.ndarray]

class opengnc.kalman_filters.SRUKF(dim_x: int, dim_z: int, alpha: float = 0.001, beta: float = 2.0, kappa: float = 0.0)

Bases: object

Square-root Unscented Kalman Filter.

Propagates the Cholesky factor of the covariance matrix for improved numerical stability relative to the standard UKF.

property P: ndarray

Return the full covariance matrix P = S S^T.

predict(dt: float, fx_func: Callable, qs_mat: ndarray | None = None, **kwargs: Any) → None

Perform the SR-UKF predict step.

update(z: ndarray, hx_func: Callable, rs_mat: ndarray | None = None, **kwargs: Any) → None

Perform the SR-UKF update step.

class opengnc.kalman_filters.UKF(dim_x: int, dim_z: int, dim_p: int | None = None, alpha: float = 0.001, beta: float = 2.0, kappa: float = 0.0, subtract_x: Callable[[...], ndarray] | None = None, add_x: Callable[[...], ndarray] | None = None, mean_x: Callable[[...], ndarray] | None = None)

Bases: object

Generalized Unscented Kalman Filter (UKF).

generate_sigma_points(x: ndarray, p_cov: ndarray) → ndarray

predict(dt: float, fx_func: Callable[[...], ndarray], q_mat: ndarray | None = None, **kwargs: Any) → None

update(z: ndarray, hx_func: Callable, r_mat: ndarray | None = None, **kwargs: Any) → None

class opengnc.kalman_filters.UKF_Attitude(q_init: ndarray | None = None, bias_init: ndarray | None = None, dim_z: int = 3, **kwargs: Any)

Bases: UKF

Packet-oriented UKF specialized for spacecraft attitude estimation.

VECTOR_QUANTITIES = {'magnetic_field', 'nadir_vector', 'sun_vector'}

predict(measurement: SensorMeasurement, dt: float | None = None, q_mat: ndarray | None = None) → None

Propagate the attitude state from an angular-rate measurement packet.

update(measurement: SensorMeasurement, r_mat: ndarray | None = None) → None

Apply a vector or quaternion correction from a measurement packet.