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)[source]

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[source]

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[source]

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.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)[source]

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[source]

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[source]

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)[source]

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[source]

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[source]

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)[source]

Bases: object

Ensemble Kalman Filter (EnKF).

Uses an ensemble of states to represent the error covariance matrix. Highly efficient for high-dimensional systems (e.g., weather/climate models) where the full covariance matrix is too large to compute.

Parameters:

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

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

  • ensemble_size (int, optional) – Number of ensemble members (N). Default is 50.

property P: ndarray

Ensemble covariance matrix.

initialize_ensemble(x_mean: ndarray, p_cov: ndarray) → None[source]

Initialize the ensemble using a multivariate normal distribution.

Parameters:

  • x_mean (np.ndarray) – Mean initial state (dim_x,).

  • p_cov (np.ndarray) – Initial state error covariance (dim_x, dim_x).

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

Predict step (Propagates each ensemble member).

Parameters:

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

  • fx_func (Callable) – Nonlinear state transition function $f(x, dt, **kwargs) to x_{new}$.

  • q_mat (np.ndarray, optional) – Process noise covariance (dim_x, dim_x). If None, uses self.Q.

  • **kwargs (Any) – Additional arguments passed to transition function.

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

Update step (Ensemble transformation).

Parameters:

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

  • hx_func (Callable) – Nonlinear measurement function $h(x, **kwargs) to z_{pred}$.

  • r_mat (np.ndarray, optional) – Measurement noise covariance (dim_z, dim_z). If None, uses self.R.

  • **kwargs (Any) – Additional arguments passed to measurement function.

property x: ndarray

Ensemble mean state vector.

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][source]

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)[source]

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[source]

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[source]

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)[source]

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[source]

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[source]

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)[source]

Bases: object

Multiplicative Extended Kalman Filter (MEKF) for Attitude Estimation.

Maintains a global quaternion for orientation and an additive 3-component error vector in the tangent space for bias and local attitude corrections.

Parameters:

  • q_init (np.ndarray, optional) – Initial quaternion $[q_x, q_y, q_z, q_w]$. Defaults to identity $[0,0,0,1]$.

  • beta_init (np.ndarray, optional) – Initial gyro bias $[b_x, b_y, b_z]$ (rad/s). Defaults to zeros.

predict(omega_meas: ndarray, dt: float, q_mat: ndarray | None = None) → None[source]

Predict the reference state and propagate error covariance.

Parameters:

  • omega_meas (np.ndarray) – Measured angular velocity in body frame (rad/s).

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

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

update(z_body: ndarray, z_ref: ndarray, r_mat: ndarray | None = None) → None[source]

Perform a vector measurement update.

Linearizes the observation of a reference vector (e.g., Sun, Earth) and applies a multiplicative correction to the quaternion.

Parameters:

  • z_body (np.ndarray) – Measured vector in spacecraft body frame (normalized).

  • z_ref (np.ndarray) – Reference vector in inertial frame (normalized).

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

opengnc.kalman_filters.pf module

Particle Filter (Sequential Importance Resampling) for non-Gaussian/non-linear systems.

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

Bases: object

Bootstrap Particle Filter (Sequential Importance Resampling).

Estimated non-Gaussian distributions and handles highly non-linear dynamics by propagating a set of discrete particles (samples).

Parameters:

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

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

  • num_particles (int, optional) – Number of particles (N). Default is 1000.

property P: ndarray

Weighted error covariance matrix.

initialize_particles(x_mean: ndarray, p_cov: ndarray) → None[source]

Initialize particles from a multivariate Gaussian distribution.

Parameters:

  • x_mean (np.ndarray) – Mean initial state (dim_x,).

  • p_cov (np.ndarray) – Initial covariance (dim_x, dim_x).

neff() → float[source]

Calculate effective number of particles.

Returns:

Effective sample size.

Return type:

float

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

Predict step (Proposal distribution).

Parameters:

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

  • fx_func (Callable) – State transition function $f(x, dt, **kwargs) to x_{new}$.

  • q_mat (np.ndarray, optional) – Process noise covariance (dim_x, dim_x). If None, uses self.Q.

  • **kwargs (Any) – Additional arguments passed to transition function.

resample() → None[source]

Resample particles using Systematic Resampling.

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

Update step (Weighting and Resampling).

Parameters:

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

  • hx_func (Callable) – Measurement function $h(x, **kwargs) to z_{pred}$.

  • r_mat (np.ndarray, optional) – Measurement noise covariance (dim_z, dim_z). If None, uses self.R.

  • **kwargs (Any) – Additional arguments passed to measurement function.

property x: ndarray

Weighted mean state vector.

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][source]

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)[source]

Bases: object

Square-Root Unscented Kalman Filter (SR-UKF).

Provides better numerical stability and efficiency than standard UKF by propagating the Cholesky factor (S) of the covariance matrix, where $P = S S^T$.

Parameters:

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

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

  • alpha (float, optional) – Primary scaling parameter. Default is 1e-3.

  • beta (float, optional) – Secondary scaling parameter (optimal for Gaussians = 2). Default is 2.0.

  • kappa (float, optional) – Tertiary scaling parameter. Default is 0.0.

property P: ndarray

Full error covariance matrix P = S S^T.

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

Predict step.

Parameters:

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

  • fx_func (Callable) – State transition function $f(x, dt, **kwargs) to x_{new}$.

  • qs_mat (np.ndarray, optional) – Square-root process noise covariance (S_Q). If None, uses self.Qs.

  • **kwargs (Any) – Additional arguments passed to transition function.

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

Update step.

Parameters:

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

  • hx_func (Callable) – Measurement function $h(x, **kwargs) to z_{pred}$.

  • rs_mat (np.ndarray, optional) – Square-root measurement noise covariance (S_R). If None, uses self.Rs.

  • **kwargs (Any) – Additional arguments passed to measurement function.

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)[source]

Bases: object

Generalized Unscented Kalman Filter (UKF).

Propagates state and covariance through non-linear functions using the Unscented Transform (UT) with support for manifolds (e.g., $S^3$ for quaternions).

Parameters:

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

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

  • dim_p (int, optional) – Dimension of the covariance $P$ in tangent space. Defaults to dim_x.

  • alpha (float, optional) – UT tuning parameter $(10^{-4}, 1)$. Controls spread of sigma points.

  • beta (float, optional) – UT parameter incorporating prior knowledge of distribution. Default 2.0.

  • kappa (float, optional) – UT secondary scaling parameter. Usually 0 or $3-L$.

  • subtract_x (Callable, optional) – Tangent space difference $(x_1, x_2) to dx$.

  • add_x (Callable, optional) – Manifold state update $(x, dx) to x_{new}$.

  • mean_x (Callable, optional) – Weighted manifold mean $(sigmas, weights) to x_{mean}$.

generate_sigma_points(x: ndarray, p_cov: ndarray) → ndarray[source]

Generates sigma points around $x$ using covariance $P$ in tangent space.

Parameters:

  • x (np.ndarray) – Current state estimate.

  • p_cov (np.ndarray) – Current estimation error covariance (tangent space).

Returns:

Sigma points array (num_sigmas, dim_x).

Return type:

np.ndarray

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

Unscented transform prediction step.

Parameters:

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

  • fx_func (Callable) – Non-linear transition function.

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

  • **kwargs (Any) – Additional parameters.

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

Unscented 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.ukf.UKF_Attitude(q_init: ndarray | None = None, bias_init: ndarray | None = None, dim_z: int = 3, **kwargs: Any)[source]

Bases: UKF

Specialized UKF for Attitude Estimation. State: [q0, q1, q2, q3, bias_x, bias_y, bias_z] (7 dim) Covariance/Error: 6 dim (tangent space)

Module contents