Skip to content

Smoother Configurations

Smoother is configured using explicit *SmootherConfig classes.

Use smoother configs instead of filter configs when entering a Smoother handler. The classes inherit the familiar filtering options, plus smoother recording fields such as record_smoothed_states_mean, record_smoothed_states_cov_diag, record_smoothed_particles, and record_smoothed_log_weights.

Common Choices

from dynestyx.inference.smoother_configs import (
    ContinuousTimeKFSmootherConfig,
    KFSmootherConfig,
    PFSmootherConfig,
)

kf = KFSmootherConfig(filter_source="cd_dynamax")
pf = PFSmootherConfig(filter_source="cuthbert", n_particles=1_000)
ct_kf = ContinuousTimeKFSmootherConfig()

PFSmootherConfig exposes particle-smoother options: pf_backward_sampling_method, pf_mcmc_n_steps, and pf_n_smoother_particles. ContinuousTimeKFSmootherConfig exposes cdlgssm_smoother_type for the CD-Dynamax continuous-discrete linear Gaussian smoother variant.

Smoother configuration dataclasses. Shared by dispatchers and integration backends.

BaseSmootherConfig dataclass

Bases: ABC

Shared base class for all smoother configs.

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

Concrete smoother configs inherit from their corresponding filter configs, so backend selection, filter tuning, continuous-time solver options, and filter recording fields follow the same conventions as dynestyx.inference.filter_configs.

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

Attributes:

Name Type Description
record_smoothed_states_mean bool | None

Save the posterior smoothing mean \(\mathbb{E}[x_t \mid y_{1:T}]\) at each time step.
record_smoothed_states_cov bool | None

Save the full smoothing covariance at each time step. Can be large; prefer record_smoothed_states_cov_diag for high-dimensional states.
record_smoothed_states_cov_diag bool | None

Save only the marginal smoothing variances at each time step.
record_smoothed_particles bool | None

Save smoothed particles for particle smoothers.
record_smoothed_log_weights bool | None

Save smoothed particle log weights for particle smoothers.
record_smoothed_states_chol_cov bool | None

Save the Cholesky factor of the smoothing covariance when exposed by the backend.
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.

ContinuousTimeEKFSmootherConfig dataclass

Bases: ContinuousTimeEKFConfig, BaseSmootherConfig

Continuous-discrete Extended Kalman Smoother (CD-EKS).

Gaussian smoother for mildly nonlinear continuous-time dynamics with discrete observations. Requires differentiable dynamics; JAX autodiff is used to construct the local linearizations.

This smoother is currently implemented through the cd_dynamax backend. See ContinuousTimeEKFConfig for linearisation and solver options.

Does not support missing observations (data cannot have NaNs).

Attributes:

Name Type Description
filter_source FilterSource

Backend. Defaults to "cd_dynamax".
Algorithm Reference

The CD-EKS combines a continuous-discrete EKF filtering pass with a backward smoothing pass through the locally linear Gaussian approximations. It is the continuous-discrete analogue of EKFSmootherConfig.

The inherited filter_state_order and filter_emission_order options control the Taylor approximation used during the continuous-time filtering and smoothing computation.

References:

  • For continuous-discrete smoothing equations, see: Särkkä, S. (2006). Recursive Bayesian Inference on Stochastic Differential Equations.
  • For a modern textbook reference, see Chapter 10.9 of: Särkkä, S., & Solin, A. (2019). Applied Stochastic Differential Equations. Cambridge University Press. Available Online.
  • For general Gaussian smoothing background, see: Särkkä, S., & Svensson, L. (2023). Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. Available Online.

ContinuousTimeKFSmootherConfig dataclass

Bases: ContinuousTimeKFConfig, BaseSmootherConfig

Continuous-discrete Kalman Smoother (CD-KS).

The exact Bayesian smoother for continuous-time linear-Gaussian models with discrete observations. Use this when your model was built with LTI_continuous.

This smoother is currently implemented through the cd_dynamax backend. Inherited differential-equation solver options control the continuous-time filtering pass, and inherited record_smoothed_* fields control trace recording.

Does not support missing observations (data cannot have NaNs).

Attributes:

Name Type Description
cdlgssm_smoother_type CDKFSmootherType

CD-Dynamax smoother variant. "cd_smoother_1" is the default; "cd_smoother_2" exposes the backend's alternate continuous-discrete RTS implementation.
filter_source FilterSource

Backend. Defaults to "cd_dynamax".
Algorithm Reference

Continuous-discrete Kalman smoothing runs a continuous-time Kalman filtering pass between observations, applies discrete Kalman updates at observation times, and then integrates the corresponding backward smoothing equations through the filtered trajectory.

The result is the continuous-discrete analogue of the RTS smoother: each state is conditioned on all observations \(y_{1:T}\), not just the observations available up to that time.

References:

  • For continuous-discrete smoothing equations, see: Särkkä, S. (2006). Recursive Bayesian Inference on Stochastic Differential Equations.
  • 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.
  • For general Gaussian smoothing background, see: Särkkä, S., & Svensson, L. (2023). Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. Available Online.

EKFSmootherConfig dataclass

Bases: EKFConfig, BaseSmootherConfig

Extended Kalman Smoother (EKS) for discrete-time models.

The Gaussian smoother corresponding to EKFConfig. Use this for differentiable nonlinear dynamics when local linearization is a reasonable approximation to the filtering and smoothing distributions.

This is exact (but wasteful) for linear-Gaussian models. For those models, prefer KFSmootherConfig.

Does not support missing observations (data cannot have NaNs).

Attributes:

Name Type Description
filter_source FilterSource

Backend. Defaults to "cuthbert".
Algorithm Reference

The EKS applies the RTS backward recursion to the linear-Gaussian approximations produced by an EKF filtering pass. The transition matrix in the smoothing gain is the Jacobian of the transition function at the filtered mean:

\[ G_t = P_{t|t} F_t^\top P_{t+1|t}^{-1}. \]

Smoothed means and covariances are then computed with the same backward recursion as KFSmootherConfig.

References:

  • For a classical textbook treatment, see: Jazwinski, A. H. (1970). Stochastic Processes and Filtering Theory. Academic Press.
  • For a modern textbook reference, see: Särkkä, S., & Svensson, L. (2023). Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. Available Online.

KFSmootherConfig dataclass

Bases: KFConfig, BaseSmootherConfig

Rauch-Tung-Striebel Kalman Smoother (RTS) for discrete-time models.

The exact Bayesian smoother for discrete-time linear-Gaussian state-space models. Use this when your model was built with LTI_discrete or with LinearGaussianStateEvolution + LinearGaussianObservation.

The smoother computes \(p(x_t \mid y_{1:T})\), while KFConfig computes \(p(x_t \mid y_{1:t})\). Use the inherited record_smoothed_* fields to save smoothed means, covariances, or covariance diagonals in the NumPyro trace.

Supports missing observations via NaNs when filter_source="cuthbert". Does not support missing observations (data cannot have NaNs) when filter_source="cd_dynamax".

Time-varying linear-Gaussian models (callable (t_now, t_next) / (t,) parameters on LinearGaussianStateEvolution / LinearGaussianObservation) are supported only with filter_source="cuthbert"; filter_source="cd_dynamax" raises TypeError for callable parameters.

Attributes:

Name Type Description
filter_source FilterSource

Backend. Defaults to "cd_dynamax".
associative bool | None

Whether to enable cuthbert's associative parallel-in-time scan. This is only supported when filter_source="cuthbert". Defaults to None, which selects an associative scan if filter_source="cuthbert", and a sequential scan otherwise.
Algorithm Reference

After a forward Kalman filtering pass, the RTS smoother runs a backward recursion over the filtered and one-step-ahead predicted Gaussian states. For a linear transition matrix \(A_t\), the smoothing gain is

\[ G_t = P_{t|t} A_t^\top P_{t+1|t}^{-1}. \]

The smoothed mean and covariance are then

\[ m_{t|T} = m_{t|t} + G_t (m_{t+1|T} - m_{t+1|t}), \]

and

\[ P_{t|T} = P_{t|t} + G_t (P_{t+1|T} - P_{t+1|t}) G_t^\top. \]

References:

  • For the original smoother, see: Rauch, H. E., Tung, F., & Striebel, C. T. (1965). Maximum likelihood estimates of linear dynamic systems. AIAA Journal, 3(8), 1445-1450.
  • For a modern textbook reference, see: Särkkä, S., & Svensson, L. (2023). Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. Available Online.

PFSmootherConfig dataclass

Bases: PFConfig, BaseSmootherConfig

Particle smoother for discrete-time models.

Use this for nonlinear or non-Gaussian discrete-time models. Particle smoothing is more flexible than Gaussian smoothing, but accuracy scales with the number of particles and backward-sampled smoother trajectories.

This smoother is currently supported with filter_source="cuthbert" only.

Does not support missing observations (data cannot have NaNs).

Attributes:

Name Type Description
n_particles int

Number of particles in the forward particle filter. More particles give a lower-variance log-likelihood and smoothing approximation at linear compute cost. Defaults to 1_000.
pf_backward_sampling_method PFBackwardSamplingMethod

Backward simulation method. "tracing" is the default, "exact" performs exact backward sampling where available, and "mcmc" uses an MCMC backward kernel.
pf_mcmc_n_steps int

Number of MCMC steps used when pf_backward_sampling_method="mcmc".
pf_n_smoother_particles int | None

Number of backward-sampled smoother particles. None inherits n_particles from PFConfig.
filter_source FilterSource

Backend. Defaults to "cuthbert", which is currently the only available implementation.
Algorithm Reference

Particle smoothers augment a forward particle filter with a backward pass that reconstructs trajectories from the particle approximation to the filtering distributions.

In backward simulation, a sampled state \(x_{t+1}^{(j)}\) chooses an ancestor at time \(t\) with probabilities proportional to

\[ w_t^{(i)} p(x_{t+1}^{(j)} \mid x_t^{(i)}). \]

The "tracing" method follows stored particle ancestors. The "exact" and "mcmc" methods use backward kernels that can better approximate the full smoothing distribution at higher compute cost.

References:

  • For backward simulation particle smoothing, see: Godsill, S. J., Doucet, A., & West, M. (2004). Monte Carlo smoothing for nonlinear time series. Journal of the American Statistical Association, 99(465), 156-168.
  • For a general SMC/particle filtering reference, 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 modern textbook reference, see: Särkkä, S., & Svensson, L. (2023). Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. Available Online.

UKFSmootherConfig dataclass

Bases: UKFConfig, BaseSmootherConfig

Unscented Kalman Smoother (UKS) for discrete-time models.

A derivative-free Gaussian smoother that handles nonlinearities by propagating deterministic sigma points rather than Jacobians. Use this when sigma-point propagation is a better local approximation than EKF linearization.

This smoother is currently supported with filter_source="cd_dynamax" only. Cuthbert UKF smoothing is not implemented.

Does not support missing observations (data cannot have NaNs).

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

The UKS uses a forward UKF pass followed by an RTS-style backward pass. Instead of using a Jacobian in the smoothing gain, it estimates the lag-one cross-covariance \(P_{t,t+1|t}\) by propagating sigma points:

\[ G_t = P_{t,t+1|t} P_{t+1|t}^{-1}. \]

The smoothed mean and covariance then follow the same correction form as the Kalman and extended Kalman smoothers.

References:

  • For the original unscented Kalman filter paper, see: Julier, S. J., & Uhlmann, J. K. (1997). New extension of the Kalman filter to nonlinear systems. SPIE Proceedings, 3068.
  • For the unscented RTS smoother, see: Särkkä, S. (2008). Unscented Rauch-Tung-Striebel smoother. IEEE Transactions on Automatic Control, 53(3), 845-849.
  • For a modern textbook reference, see: Särkkä, S., & Svensson, L. (2023). Bayesian Filtering and Smoothing (Vol. 17). Cambridge University Press. Available Online.

_config_to_smoother_record_kwargs(config: BaseSmootherConfig) -> dict

Build smoother record kwargs dict from config.