archimedes.observers.KalmanFilterBase

class archimedes.observers.KalmanFilterBase(dyn: ~typing.Callable, obs: ~typing.Callable, Q: ~numpy.ndarray, R: ~numpy.ndarray, missing: ~typing.Callable[[~numpy.ndarray], bool] = <function _default_missing>)

Abstract base class for Kalman filter implementations.

This class defines the common interface for Kalman filters used in system identification and state estimation.

All Kalman filter implementations follow the discrete-time state-space model:

x[k+1] = f(t[k], x[k], *args) + w[k]    (dynamics)
y[k]   = h(t[k], x[k], *args) + v[k]    (observations)

where w[k] ~ N(0, Q) is process noise and v[k] ~ N(0, R) is measurement noise.

Parameters:

  • dyn (callable) – Dynamics function with signature f(t, x, *args) that returns the predicted state at the next time step. Must be compatible with automatic differentiation for gradient-based filters.

  • obs (callable) – Observation function with signature h(t, x, *args) that maps state to expected measurements. Must be compatible with automatic differentiation for gradient-based filters.

  • Q (array_like) – Process noise covariance matrix of shape (nx, nx) where nx is the state dimension. Must be positive semi-definite.

  • R (array_like) – Measurement noise covariance matrix of shape (ny, ny) where ny is the measurement dimension. Must be positive definite.

  • missing (callable, optional) – Function to check if a value is missing (default: always returns False). The function should accept a single argument and return a boolean indicating whether the measurement is considered missing or corrupted. The “correct” step will be skipped if the measurement is missing, and the filter step will return zero innovation with pure prediction for state and covariance.

Variables:

  • nx (int) – State dimension, derived from the shape of Q.

  • ny (int) – Measurement dimension, derived from the shape of R.

Notes

This class is decorated with @struct, making it compatible with function transformations and enabling efficient automatic differentiation through the filter operations. The filter parameters can be modified using standard tree operations.

Subclasses must implement the abstract step method that performs one complete filtering step (prediction + update). The implementation details depend on the specific filtering algorithm (EKF, UKF, etc.).

The args parameter in function signatures allows passing additional arguments to both dynamics and observation functions, enabling time-varying parameters or external inputs.

Examples

>>> # Subclasses implement the filtering algorithm
>>> class CustomFilter(KalmanFilterBase):
...     def step(self, t, x, y, P, args=None):
...         # Implementation-specific filtering logic
...         return x_new, P_new, innovation
>>>
>>> # Define system dynamics and observations
>>> def f(t, x):
...     return np.array([x[0] + 0.1*x[1], 0.9*x[1]], like=x)
>>>
>>> def h(t, x):
...     return np.array([x[0]], like=x)
>>>
>>> # Create filter instance
>>> Q = np.eye(2) * 0.01  # Process noise
>>> R = np.array([[0.1]]) # Measurement noise
>>> kf = CustomFilter(dyn=f, obs=h, Q=Q, R=R)
>>>
>>> # Filter properties
>>> print(f"State dimension: {kf.nx}")
>>> print(f"Measurement dimension: {kf.ny}")

See also

ExtendedKalmanFilter

Extended Kalman Filter implementation

UnscentedKalmanFilter

Unscented Kalman Filter implementation

Methods

missing()

replace(**updates)

Returns a new object replacing the specified fields with new values.

step(t, x, y, P[, args])

Perform one step of the filter, combining prediction and update steps.

Attributes

nx

State dimension derived from process noise covariance matrix.

ny

Measurement dimension derived from measurement noise covariance matrix.

dyn

obs

Q

R

__init__(dyn: ~typing.Callable, obs: ~typing.Callable, Q: ~numpy.ndarray, R: ~numpy.ndarray, missing: ~typing.Callable[[~numpy.ndarray], bool] = <function _default_missing>) → None
replace(**updates) → T

Returns a new object replacing the specified fields with new values.

abstractmethod step(t, x, y, P, args=None)

Perform one step of the filter, combining prediction and update steps.

This abstract method must be implemented by subclasses to define the specific filtering algorithm. It should perform both the prediction step (using the dynamics model) and the update step (incorporating the measurement).

Parameters:

  • t (float) – Current time step.

  • x (array_like) – State vector of shape (nx,).

  • y (array_like) – Measurement vector of shape (ny,).

  • P (array_like) – State covariance matrix of shape (nx, nx).

  • args (tuple, optional) – Additional arguments to pass to the dynamics and observation functions. Default is None.

Returns:

  • x_new (ndarray) – Updated state estimate of shape (nx,).

  • P_new (ndarray) – Updated state covariance matrix of shape (nx, nx).

  • innovation (ndarray) – Measurement residual (innovation) of shape (ny,), computed as the difference between the actual measurement and the predicted measurement from the current state estimate.

Notes

The innovation sequence should have zero mean and known covariance (the innovation covariance) if the filter is performing optimally. This can be used for filter consistency checking and parameter tuning.

property nx

State dimension derived from process noise covariance matrix.

property ny

Measurement dimension derived from measurement noise covariance matrix.