Core Types

Fundamental data structures used throughout dynaris. These are the building blocks that filters, smoothers, and the DLM class operate on.

StateSpaceModel

The central model representation. Holds the four system matrices (F, G, V, W) following West and Harrison (1997) notation. Returned by all component functions and composed via +.

class dynaris.core.state_space.StateSpaceModel(observation_matrix, system_matrix, obs_cov, evolution_cov, input_matrix=None)[source]

Bases: object

Linear-Gaussian Dynamic Linear Model.

Following West & Harrison (1997) notation:

System equation: theta_t = G @ theta_{t-1} + omega_t, omega_t ~ N(0, W) Observation eq: Y_t = F’ @ theta_t + nu_t, nu_t ~ N(0, V)

Parameters:

  • observation_matrix (Array)

  • system_matrix (Array)

  • obs_cov (Array)

  • evolution_cov (Array)

  • input_matrix (Array | None)

observation_matrix

F, shape (obs_dim, state_dim).

Type:

Array

system_matrix

G, shape (state_dim, state_dim).

Type:

Array

obs_cov

V, shape (obs_dim, obs_dim).

Type:

Array

evolution_cov

W, shape (state_dim, state_dim).

Type:

Array

input_matrix

B, shape (state_dim, input_dim) or None.

Type:

Array | None

property state_dim: int

Dimension of the state (parameter) vector.

property obs_dim: int

Dimension of the observation vector.

property F: jax.Array

Observation/regression matrix (F in W&H).

property G: jax.Array

System/evolution matrix (G in W&H).

property V: jax.Array

Observational variance/covariance (V in W&H).

property W: jax.Array

Evolution covariance (W in W&H).

property B: Array | None

Alias for input_matrix.

initial_state(mean=None, cov=None)[source]

Create a default initial GaussianState for this model.

Parameters:

  • mean (Array | None) – Initial state mean (m_0). Defaults to zeros.

  • cov (Array | None) – Initial state covariance (C_0). Defaults to 1e6 * I (diffuse prior).

Returns:

GaussianState with the specified or default initial conditions.

Return type:

GaussianState

tree_flatten()[source]

Flatten into JAX pytree leaves and auxiliary data.

Return type:

tuple[list[jax.Array], dict[str, bool]]

classmethod tree_unflatten(aux_data, children)[source]

Reconstruct from JAX pytree leaves.

Parameters:
Return type:

StateSpaceModel

GaussianState

Represents a Gaussian belief about the state: a mean vector and covariance matrix. Used internally by the Kalman filter and smoother at each time step.

class dynaris.core.types.GaussianState(mean, cov)[source]

Bases: object

A Gaussian belief state: mean vector and covariance matrix.

Parameters:
mean

State mean vector, shape (state_dim,).

Type:

jax.Array

cov

State covariance matrix, shape (state_dim, state_dim).

Type:

jax.Array

property dim: int

State dimension, inferred from mean vector.

tree_flatten()[source]

Flatten into JAX pytree leaves.

Return type:

tuple[tuple[jax.Array, jax.Array], None]

classmethod tree_unflatten(aux_data, children)[source]

Reconstruct from JAX pytree leaves.

Parameters:
Return type:

GaussianState

FilterResult

Container returned by the Kalman filter. Holds filtered state means, covariances, log-likelihood, and forecast errors for all time steps.

class dynaris.core.results.FilterResult(filtered_states, filtered_covariances, predicted_states, predicted_covariances, log_likelihood, observations)[source]

Bases: NamedTuple

Output of a forward filtering pass.

All array fields have a leading time dimension T (number of observations).

Parameters:
filtered_states

Filtered state means, shape (T, state_dim).

Type:

jax.Array

filtered_covariances

Filtered state covariances, shape (T, state_dim, state_dim).

Type:

jax.Array

predicted_states

One-step-ahead predicted means, shape (T, state_dim).

Type:

jax.Array

predicted_covariances

One-step-ahead predicted covariances, shape (T, state_dim, state_dim).

Type:

jax.Array

log_likelihood

Total log-likelihood scalar, shape ().

Type:

jax.Array

observations

The input observations, shape (T, obs_dim).

Type:

jax.Array

filtered_states: jax.Array

Alias for field number 0

filtered_covariances: jax.Array

Alias for field number 1

predicted_states: jax.Array

Alias for field number 2

predicted_covariances: jax.Array

Alias for field number 3

log_likelihood: jax.Array

Alias for field number 4

observations: jax.Array

Alias for field number 5

SmootherResult

Container returned by the RTS smoother. Holds smoothed state means and covariances for all time steps.

class dynaris.core.results.SmootherResult(smoothed_states, smoothed_covariances, filtered_states, filtered_covariances, predicted_states, predicted_covariances, log_likelihood, observations)[source]

Bases: NamedTuple

Output of a backward smoothing pass.

Extends filter output with smoothed estimates.

Parameters:
smoothed_states

Smoothed state means, shape (T, state_dim).

Type:

jax.Array

smoothed_covariances

Smoothed state covariances, shape (T, state_dim, state_dim).

Type:

jax.Array

filtered_states

Filtered state means, shape (T, state_dim).

Type:

jax.Array

filtered_covariances

Filtered state covariances, shape (T, state_dim, state_dim).

Type:

jax.Array

predicted_states

One-step-ahead predicted means, shape (T, state_dim).

Type:

jax.Array

predicted_covariances

One-step-ahead predicted covariances, shape (T, state_dim, state_dim).

Type:

jax.Array

log_likelihood

Total log-likelihood scalar, shape ().

Type:

jax.Array

observations

The input observations, shape (T, obs_dim).

Type:

jax.Array

smoothed_states: jax.Array

Alias for field number 0

smoothed_covariances: jax.Array

Alias for field number 1

filtered_states: jax.Array

Alias for field number 2

filtered_covariances: jax.Array

Alias for field number 3

predicted_states: jax.Array

Alias for field number 4

predicted_covariances: jax.Array

Alias for field number 5

log_likelihood: jax.Array

Alias for field number 6

observations: jax.Array

Alias for field number 7

Protocols

Interfaces that filter and smoother implementations must satisfy. Useful for type checking and extending dynaris with custom algorithms.

class dynaris.core.protocols.FilterProtocol(*args, **kwargs)[source]

Interface that all filtering algorithms must implement.

predict(state, model, u=None)[source]

Predict the next state (time update / prior).

Parameters:

  • state (GaussianState) – Current filtered state belief.

  • model (StateSpaceModel) – The state-space model defining dynamics.

  • u (Array | None) – Optional control input vector, shape (input_dim,).

Returns:

Predicted (prior) GaussianState for the next time step.

Return type:

GaussianState

update(predicted, observation, model)[source]

Incorporate an observation (measurement update / posterior).

Parameters:

  • predicted (GaussianState) – Predicted state from the predict step.

  • observation (jax.Array) – Observation vector, shape (obs_dim,).

  • model (StateSpaceModel) – The state-space model defining the observation equation.

Returns:

Filtered (posterior) GaussianState.

Return type:

GaussianState

scan(model, observations, initial_state=None, inputs=None)[source]

Run the full forward filtering pass over a sequence.

Parameters:

  • model (StateSpaceModel) – The state-space model.

  • observations (Array) – Observation sequence, shape (T, obs_dim).

  • initial_state (GaussianState | None) – Initial state belief. If None, uses model defaults.

  • inputs (Array | None) – Optional control inputs, shape (T, input_dim).

Returns:

FilterResult containing all filtered and predicted states.

Return type:

FilterResult

class dynaris.core.protocols.SmootherProtocol(*args, **kwargs)[source]

Interface for backward smoothing algorithms.

smooth(model, filter_result)[source]

Run backward smoothing given forward filter results.

Parameters:

  • model (StateSpaceModel) – The state-space model.

  • filter_result (FilterResult) – Output from a forward filtering pass.

Returns:

SmootherResult with smoothed state estimates.

Return type:

SmootherResult