Filter Configurations¶

The single Filter() handler is directed to the appropriate filtering algorithm via the provided FilterConfig. We provide a summary below, as well as an exhaustive list of classes.

Available filter configurations¶

Config class	Time domain	When it fits best
`KFConfig`	Discrete	Linear-Gaussian dynamics and linear-Gaussian observations (exact & optimal).
`EKFConfig`	Discrete	Nonlinear, differentiable Gaussian dynamics, nonlinear but differentiable Gaussian observations (approximate). (default).
`UKFConfig`	Discrete	Nonlinear, differentiable Gaussian dynamics, nonlinear but differentiable Gaussian observations (approximate). Generally more accurate, but slower than `EKFConfig`.
`EnKFConfig`	Discrete	High-dimensional or expensive models with lower-dimensional structure and Gaussian observations (approximate).
`PFConfig`	Discrete	Applicable for arbitrary state-space models, but quite expensive and noisy estimates (asymptotically exact in the limit of infinite particles, approximate in practice).
`HMMConfig`	Discrete (HMM)	Finite discrete latent state space (exact & optimal).
`ContinuousTimeKFConfig`	Continuous-discrete	Linear-Gaussian SDE + linear-Gaussian observations (exact and optimal).
`ContinuousTimeEKFConfig`	Continuous-discrete	Mildly nonlinear SDE with differentiable drift and difussion terms; Gaussian observations (approximate).
`ContinuousTimeUKFConfig`	Continuous-discrete	Nonlinear SDE; derivative-free; Gaussian observations (approximate). Generally more accurate, but slower than `ContinuousTimeEKFConfig`.
`ContinuousTimeEnKFConfig`	Continuous-discrete	High-dimensional or expensive models with lower-dimensional structure and Gaussian observations (approximate). Performs reasonably as a default. (default)
`ContinuousTimeDPFConfig`	Continuous-discrete	Applicable for arbitrary state-space models, but quite expensive and noisy estimates (asymptotically exact in the limit of infinite particles, approximate in practice).

Discrete Time Configuration Classes¶

Filter configuration dataclasses. Shared by dispatchers and integration backends.

`BaseFilterConfig` `dataclass` ¶

Shared configuration options inherited by all filter configs.

You do not instantiate this class directly; use one of the concrete subclasses (e.g. KFConfig, PFConfig).

The record_* fields let you save intermediate filtering outputs into the NumPyro trace as numpyro.deterministic sites, making them accessible after inference (e.g. for plotting filtered trajectories). None defers to the backend's default for that quantity.

Attributes:

Name	Type	Description
`record_filtered_states_mean`	`bool \| None`	Save the posterior mean \(\mathbb{E}[x_t \mid y_{1:t}]\) at each time step.
`record_filtered_states_cov`	`bool \| None`	Save the full posterior covariance at each step. Can be large — prefer `record_filtered_states_cov_diag` for high-dimensional states.
`record_filtered_states_cov_diag`	`bool \| None`	Save only the marginal variances (diagonal of the covariance) at each step.
`record_filtered_states_chol_cov`	`bool \| None`	Save the Cholesky factor of the posterior covariance (Gaussian filters only).
`record_filtered_particles`	`bool \| None`	Save the full particle array at each step (particle-based filters only).
`record_filtered_log_weights`	`bool \| None`	Save the log importance weights at each step (particle-based filters only).
`record_max_elems`	`int`	Hard cap on total scalar elements saved across all `record_*` sites. Prevents accidentally filling device memory for long sequences or large state spaces. Defaults to `100_000`.
`cov_rescaling`	`float \| None`	Multiply all predicted covariances by this factor before the update. Values slightly above `1.0` implement covariance inflation, which can improve robustness when the model is misspecified. `None` disables rescaling.
`crn_seed`	`Array \| None`	Fix the PRNG key for stochastic filters (EnKF, PF). Useful when differentiating through the filter: a fixed key makes the randomness a deterministic function of model parameters. `None` draws a fresh key each call.
`warn`	`bool`	Whether or not to suppress warnings from filtering backends. Defaults to `True`.
`filter_source`	`FilterSource \| None`	Internal backend library. Set by each subclass; rarely needs to be changed manually.
`extra_filter_kwargs`	`dict`	Extra keyword arguments passed directly to the backend. Useful for advanced backend-specific options.

`KFConfig` `dataclass` ¶

Bases: BaseFilterConfig

Kalman Filter (KF) for discrete-time linear-Gaussian models.

The exact Bayesian filter for linear-Gaussian state-space models; requires a model built with LTI_discrete or using LinearGaussianStateEvolution + LinearGaussianObservation. For nonlinear Gaussian models, use EKFConfig, UKFConfig, or EnKFConfig instead.

Attributes:

Name	Type	Description
`filter_source`	`FilterSource`	Backend. Defaults to `"cd_dynamax"`.

Algorithm Reference

When the dynamics and observation process of a dynamical system are both linear-Gaussian, the recursive updates can be computed in closed form.

This proceeds via a "prediction" step, where the mean and covariance are propagated forward in time, and an "update" step, where the mean and covariance are updated with the observation.

The prediction step is given by:

\[ \hat x_{t|t-1} = A \hat x_{t-1|t-1} + b, \quad P_{t|t-1} = A P_{t-1|t-1} A^\top + Q \]

The update step is given by:

\[ \hat x_{t|t} = \hat x_{t|t-1} + K_t (y_t - H \hat x_{t|t-1}), \quad P_{t|t} = (I - K_t H) P_{t|t-1} \]

where \(K_t\) is the Kalman gain.

The Kalman gain is given by:

\[ K_t = P_{t|t-1} H^\top (H P_{t|t-1} H^\top + R)^{-1} \]

where \(H\) is the Jacobian of \(h\) at \(\hat x_{t|t-1}\).

There are variants to the particular algorithm; the cuthbert implementation is the so-called "square root" form. This provides a more numerically stable implementation of the Kalman filter.

References:

For the classsical reference, see: Kalman, R. E. (1960). A New Approach to Linear Filtering and Prediction Problems. Journal of Basic Engineering, 82(1), 35-45.
For a more modern textbook reference, see Chapter 6 of: Särkkä, S., & Svensson, L. (2023). Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. Available Online.
For more details on the cuthbert implementation, see the cuthbert documentation.

`EKFConfig` `dataclass` ¶

Bases: BaseFilterConfig

Extended Kalman Filter (EKF) for discrete-time models.

The EKF linearizes nonlinear dynamics at the current mean estimate via a first-order Taylor expansion. It is fast and simple, but may not work well for strongly nonlinear models. The Taylor series expansion is automatically performed via Jax autodiff.

This is exact (but wasteful) for linear-Gaussian models.

This is the default discrete-time filter when no filter_config is passed to Filter.

Attributes:

Name	Type	Description
`filter_emission_order`	`FilterEmissionOrder`	Linearisation order for the observation function. `"first"` (default) is the standard Jacobian-based EKF. `"second"` reduces bias for strongly curved observation maps at the cost of Hessian computation. `"zeroth"` skips observation linearisation.
`filter_source`	`FilterSource`	Backend. Defaults to `"cuthbert"`.

Algorithm Reference

The EKF propagates a Gaussian approximation \(\mathcal{N}(\hat x_{t|t}, P_{t|t})\) through Jacobian linearizations of \(f\) and \(h\):

\[ \hat x_{t|t-1} = f(\hat x_{t-1|t-1}), \quad P_{t|t-1} = F_t P_{t-1|t-1} F_t^ op + Q_t \]

where \(F_t\) is the Jacobian of \(f\) at \(\hat x_{t|t-1}\), and proceeds via the typical Kalman update.

References:

The cuthbert implementation of the EKF is based on the taylor_kf module therein. See the cuthbert documentation for more information.
For a more modern textbook reference, see Chapter 7 of: Särkkä, S., & Svensson, L. (2023). Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. Available Online.

`UKFConfig` `dataclass` ¶

Bases: BaseFilterConfig

Unscented Kalman Filter (UKF) for discrete-time models.

A derivative-free Gaussian filter that handles stronger nonlinearities than the EKF by propagating a small, deterministic set of sigma points through the dynamics. No Jacobians are computed. Slightly more expensive than the EKF but often more accurate on curved manifolds.

The default parameters (alpha, beta, kappa) work well for most problems; they rarely need to be changed.

Attributes:

Name	Type	Description
`alpha`	`float`	Spread of sigma points around the current mean. Smaller → tighter cluster; larger → sigma points reach further. Defaults to \(\sqrt{3}\).
`beta`	`int`	Encodes prior knowledge about the distribution shape. `2` is optimal for Gaussians. Defaults to `2`.
`kappa`	`int`	Secondary scaling parameter. Defaults to `1`.
`filter_source`	`FilterSource`	Backend. Defaults to `"cd_dynamax"`.

Algorithm Reference

For a state of dimension \(n\), \(2n+1\) sigma points are placed as:

\[ \mathcal{X}_0 = \hat x, \quad \mathcal{X}_i = \hat x \pm \sqrt{(n + \lambda) P}_i, \quad \lambda = \alpha^2 (n + \kappa) - n \]

Each sigma point is propagated through \(f\) and \(h\); the outputs are recombined with weights depending on \(\alpha, \beta, \kappa\) to recover the predicted mean and covariance.

References: - For the original paper, see: Julier, S. J., & Uhlmann, J. K. (1997). New extension of the Kalman filter to nonlinear systems. SPIE Proceedings, 3068. - For a more modern textbook reference, see Section 8.8 of: Särkkä, S., & Svensson, L. (2023). Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. Available Online.

`PFConfig` `dataclass` ¶

Bases: BaseFilterConfig

Bootstrap Particle Filter (PF) for discrete-time models.

The most flexible filter: works with any model, including non-Gaussian observations and highly nonlinear dynamics. The main cost is that accuracy scales with the number of particles, so large state dimensions can become expensive.

The primary tuning knob is n_particles. Estimates will generally get better and less noisy with more particles, but introduces a linear computational cost. ess_threshold_ratio controls the frequency of resampling; sampling more frequently can help avoid particle degeneracy, but also increases variance.

Attributes:

Name	Type	Description
`n_particles`	`int`	Number of particles. More particles give a lower- variance log-likelihood estimate at linear compute cost. Defaults to `1_000`.
`resampling_method`	`PFResamplingConfig`	Controls the resampling algorithm and gradient behaviour. See `PFResamplingConfig`. Defaults to systematic resampling with stop-gradient.
`ess_threshold_ratio`	`float`	Resampling fires when the effective sample size drops below `ess_threshold_ratio * n_particles`. `1.0` → always resample; `0.0` → never. Defaults to `0.7`.
`filter_source`	`FilterSource`	Backend. Defaults to `"cuthbert"`, which is currently the only available implementation.

Algorithm Reference

At each step, particles are propagated through the transition and reweighted by the observation likelihood. The resulting empirical distribution is asymptotically exact to the true filtering distribution as the number of particles goes to infinity. The marginal log-likelihood without a resampling step is estimated as:

\[ \log p(y_{1:T}) \approx \sum_{t=1}^T \log \frac{1}{N} \sum_{i=1}^N \tilde{w}_t^{(i)} \]

where \(\tilde{w}_t^{(i)}\) is the are unnormalized weights of each particle.

There are several different resampling algorithms available, which result in different approximations of the score function \(\nabla_\theta \log p(y_{1:T} | \theta)\). For more information on these options, see PFResamplingConfig.

References:

For a classical reference to particle filters, see: Doucet, A., De Freitas, N., & Gordon, N. (2001). An Introduction to Sequential Monte Carlo Methods. In Sequential Monte Carlo Methods in Practice (pp. 3-14). New York, NY: Springer New York.
For a more modern textbook, see Chapter 11.4 of: Särkkä, S., & Svensson, L. (2023). Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. Available Online.
For a more recent review of differentiable particle filters, see: Brady, J. J., Cox, B., Li, Y., & Elvira, V. (2025). PyDPF: A Python Package for Differentiable Particle Filtering. arXiv:2510.25693.

`EnKFConfig` `dataclass` ¶

Bases: BaseFilterConfig

Ensemble Kalman Filter (EnKF) for discrete-time models.

A good general-purpose filter for nonlinear models. Works with any differentiable or non-differentiable dynamics and scales well to moderate state dimensions. Cheaper per-step than the particle filter, but assumes observations are approximately Gaussian given the ensemble.

The primary tuning knob is n_particles, with more particles providing more accurate results at the cost of higher compute. If the ensemble collapses over long trajectories, increase inflation_delta slightly (e.g. 0.05–0.2).

Attributes:

Name	Type	Description
`n_particles`	`int`	Number of ensemble members. More members give a better covariance estimate at higher compute cost. Defaults to `30`.
`crn_seed`	`Array \| None`	Fixed PRNG key for the ensemble. Defaults to `jr.PRNGKey(0)`, i.e., common random numbers are used. This can reduce variance in gradient-based learning, but introduces further bias.
`perturb_measurements`	`bool \| None`	Add noise to observations before the ensemble update (stochastic EnKF). Set `False` for the square-root variant. `None` defers to the backend default.
`inflation_delta`	`float \| None`	Scale ensemble anomalies by \(\sqrt{1 + \delta}\) before the update to prevent collapse. `None` disables inflation.
`filter_source`	`FilterSource`	Backend. Defaults to `"cd_dynamax"`.

Algorithm Reference

The ensemble Kalman filter comprises ensemble members \(x_t^{(i)}, i = 1, \ldots, N_{\text{particles}}\). There are many implementation tricks in the EnKF; we describe the basic version here.

For each time step \(t\), the ensemble is propagated forward by the transition model:

\[ \hat{x}_t^{(i)} = f(x_t^{(i)}, u_t, t_t) + \epsilon_t^{(i)}, \]

where \(u_t\) is the control input at time \(t\) and \(t_t\) is the time of the transition, and \(\epsilon_t^{(i)} \sim \mathcal{N}(0, Q)\) is the process noise.

Each ensemble member is then updated using observations:

\[ x_t^{(i)} = \hat{x}_t^{(i)} + \hat{K}_t^{(i)} \left(y_t - h(x_t^{(i)}, u_t, t_t)\right), \]

where \(\hat{K}_t^{(i)}\) is the Kalman gain for the \(i\)-th ensemble member, computed as

\[ \hat{K}_t^{(i)} = \hat{P}_t^{(i)} H^\top (H \hat{P}_t^{(i)} H^\top + R)^{-1}, \]

where \(\hat{P}_t^{(i)}\) is the empirical covariance of the particles, and \(R\) is the covariance of the observation model.

The resulting estimator is known to be biased for non-linear observations, but is often rather robust in practice to moderate nonlinearities. It is particualrly effective for high-dimensional inverse problems, where other particle methods like particle filters often struggle.

References:

- The implementation details are due to: Sanz-Alonso, D., Stuart, A. M., & Taeb, A. (2018).
    Inverse problems and data assimilation. [arXiv:1810.06191](https://arxiv.org/abs/1810.06191).
- For a classical reference to the ensemble Kalman filter, see: Evensen, G. (2003).
    The ensemble Kalman filter: Theoretical formulation and practical implementation. Ocean Dynamics, 53(4), 343-367.
- The solution using automatic differentiation for nonlinear dynamics is due to: Chen, Y., Sanz-Alonso, D., & Willett, R. (2022).
    Autodifferentiable ensemble Kalman filters. SIAM Journal on Mathematics of Data Science, 4(2), 801-833.
    [Available Online](https://epubs.siam.org/doi/abs/10.1137/21M1434477).

Continuous Time Configuration Classes¶

Filter configuration dataclasses. Shared by dispatchers and integration backends.

`ContinuousTimeConfig` `dataclass` ¶

Solver options shared by all continuous-discrete filter configs.

Between observation times, the filter propagates a distribution (or ensemble/particles) forward in continuous time by solving an ODE/SDE numerically. These options control that solver.

Attributes:

Name	Type	Description
`filter_state_order`	`FilterStateOrder`	Accuracy of the continuous-time propagation between observations. `"first"` (default) propagates both mean and covariance (sufficient for most problems). `"zeroth"` propagates only the mean (faster, less accurate). `"second"` adds a higher-order correction for strongly nonlinear drifts.
`diffeqsolve_max_steps`	`int`	Maximum ODE solver steps between any two consecutive observations. Increase if the solver hits this limit (stiff dynamics or very long inter-observation gaps). Defaults to `1_000`.
`diffeqsolve_dt0`	`float`	Initial step-size hint for the solver. Adaptive solvers adjust this automatically; fixed-step solvers use it as the constant step. Defaults to `0.01`.
`diffeqsolve_kwargs`	`dict`	Additional kwargs forwarded to `diffrax.diffeqsolve` (e.g. `solver`, `stepsize_controller`, `adjoint`). Defaults to `{}`.

`ContinuousTimeKFConfig` `dataclass` ¶

Bases: BaseFilterConfig, ContinuousTimeConfig

Continuous-discrete Kalman Filter (CD-KF).

The exact Bayesian filter for continuous-time linear-Gaussian models. Use this when your model was built with LTI_continuous. For nonlinear SDEs, use ContinuousTimeEKFConfig, ContinuousTimeUKFConfig, or ContinuousTimeEnKFConfig.

Inherits solver options from ContinuousTimeConfig and recording options from BaseFilterConfig.

Attributes:

Name	Type	Description
`filter_source`	`FilterSource`	Backend. Defaults to `"cd_dynamax"`.

Algorithm Reference

Between observations the mean and covariance evolve via the Kalman–Bucy ODEs:

\[ \dot{\hat x} = A \hat x + B u, \quad \dot P = A P + P A^\top + L Q L^\top \]

At each observation the standard Kalman update is applied.

References:

For a modern textbook reference, see Chapter 10.6 of: Särkkä, S., & Solin, A. (2019). Applied Stochastic Differential Equations. Cambridge University Press. Available Online.

`ContinuousTimeEKFConfig` `dataclass` ¶

Bases: EKFConfig, ContinuousTimeConfig

Continuous-discrete Extended Kalman Filter (CD-EKF).

Fast Gaussian filter for mildly nonlinear SDEs. Requires differentiable dynamics (JAX autodiff is used). The moment equations for the Gaussian approximation are solved between observations and a Kalman update is applied at each observation.

See EKFConfig for linearisation options and ContinuousTimeConfig for solver options.

Attributes:

Name	Type	Description
`filter_source`	`FilterSource`	Backend. Defaults to `"cd_dynamax"`.

Algorithm Reference

References:

For a modern textbook reference, see Chapter 10.7 of: Särkkä, S., & Solin, A. (2019). Applied Stochastic Differential Equations. Cambridge University Press. Available Online.

`ContinuousTimeKFConfig` `dataclass` ¶

Bases: BaseFilterConfig, ContinuousTimeConfig

Continuous-discrete Kalman Filter (CD-KF).

The exact Bayesian filter for continuous-time linear-Gaussian models. Use this when your model was built with LTI_continuous. For nonlinear SDEs, use ContinuousTimeEKFConfig, ContinuousTimeUKFConfig, or ContinuousTimeEnKFConfig.

Inherits solver options from ContinuousTimeConfig and recording options from BaseFilterConfig.

Attributes:

Name	Type	Description
`filter_source`	`FilterSource`	Backend. Defaults to `"cd_dynamax"`.

Algorithm Reference

Between observations the mean and covariance evolve via the Kalman–Bucy ODEs:

\[ \dot{\hat x} = A \hat x + B u, \quad \dot P = A P + P A^\top + L Q L^\top \]

At each observation the standard Kalman update is applied.

References:

For a modern textbook reference, see Chapter 10.6 of: Särkkä, S., & Solin, A. (2019). Applied Stochastic Differential Equations. Cambridge University Press. Available Online.

`ContinuousTimeEnKFConfig` `dataclass` ¶

Bases: EnKFConfig, ContinuousTimeConfig

Continuous-discrete Ensemble Kalman Filter (CD-EnKF).

The default filter for continuous-time models. Each ensemble member is propagated forward by solving the SDE between observations; the ensemble Kalman update is applied at observation times. Works with any SDE model without requiring gradients.

See EnKFConfig for particle/ensemble tuning options and ContinuousTimeConfig for solver options.

Attributes:

Name	Type	Description
`filter_source`	`FilterSource`	Backend. Defaults to `"cd_dynamax"`.

Algorithm Reference

References:

The implementation details are due to: Sanz-Alonso, D., Stuart, A. M., & Taeb, A. (2018). Inverse problems and data assimilation. arXiv:1810.06191.
For a classical reference to the ensemble Kalman filter, see: Evensen, G. (2003). The ensemble Kalman filter: Theoretical formulation and practical implementation. Ocean Dynamics, 53(4), 343-367.
The solution using automatic differentiation for nonlinear dynamics is due to: Chen, Y., Sanz-Alonso, D., & Willett, R. (2022). Autodifferentiable ensemble Kalman filters. SIAM Journal on Mathematics of Data Science, 4(2), 801-833. Available Online.

Filter Configurations¶

Available filter configurations¶

Discrete Time Configuration Classes¶

BaseFilterConfig dataclass ¶

KFConfig dataclass ¶

EKFConfig dataclass ¶

UKFConfig dataclass ¶

PFConfig dataclass ¶

EnKFConfig dataclass ¶

Continuous Time Configuration Classes¶

ContinuousTimeConfig dataclass ¶

ContinuousTimeKFConfig dataclass ¶

ContinuousTimeEKFConfig dataclass ¶

ContinuousTimeKFConfig dataclass ¶

ContinuousTimeEnKFConfig dataclass ¶

`BaseFilterConfig` `dataclass` ¶

`KFConfig` `dataclass` ¶

`EKFConfig` `dataclass` ¶

`UKFConfig` `dataclass` ¶

`PFConfig` `dataclass` ¶

`EnKFConfig` `dataclass` ¶

`ContinuousTimeConfig` `dataclass` ¶

`ContinuousTimeKFConfig` `dataclass` ¶

`ContinuousTimeEKFConfig` `dataclass` ¶

`ContinuousTimeKFConfig` `dataclass` ¶

`ContinuousTimeEnKFConfig` `dataclass` ¶