Simultaneous Kalman Filters

Common errors

• ValueError: operands could not be broadcast together with shapes (X,Y) (Z,W) (and similar numpy shape errors)

  cause Input data (observations, state transition matrices, noise covariance matrices) does not conform to the expected dimensions for vectorized processing. simdkalman typically expects `(n_series, n_timesteps, n_features)` for observations or `(n_series, n_features, n_features)` for covariance matrices.
  fix Carefully check the shape of all input arrays against the documentation requirements. Use `np.newaxis` or `reshape` to ensure your data has the correct number of dimensions, especially for `n_features` if your data is 1D.

• AttributeError: 'KalmanFilter' object has no attribute 'compute'

  cause Attempting to use the `compute` method on `KalmanFilter` from a specific version (1.0.0) that had a bug affecting this method. Or, using an API that was changed/removed in older versions.
  fix Update `simdkalman` to version 1.0.1 or newer, which fixed the `compute` method. Always refer to the latest documentation for current API usage.

• RuntimeError: The observation_model must be set.

  cause The `observation_model` parameter, which defines how hidden states map to observations, was not provided during `KalmanFilter` initialization.
  fix Ensure `KalmanFilter` is initialized with a valid `observation_model` (e.g., `np.array([[1]])` for a simple case, or a callable for a more complex model) alongside `state_transition`, `process_noise`, and `observation_noise`.

Warnings

• gotcha Versions prior to 1.0.2 contained a bug where shape checks for updates with varying or vectorized H-matrices were incorrect, potentially leading to wrong results without explicit errors for affected use cases.
  Fix: Update to simdkalman version 1.0.2 or newer to ensure correct handling of vectorized observation models. Review code that uses varying H-matrices.
• gotcha Versions prior to 1.0.4 might consume significantly more memory, especially when processing very large datasets or many parallel time series, due to less optimized internal data structures.
  Fix: Upgrade to simdkalman 1.0.4 or higher to benefit from memory usage reductions. If using older versions and encountering OOM errors, consider processing data in smaller batches if feasible.
• gotcha simdkalman is designed for vectorized (simultaneous) Kalman filter operations on multiple time series. While it can be used for a single series, it might be less performant or efficient than single-series-optimized Kalman filter implementations or simpler statistical methods for very small datasets.
  Fix: Ensure you are leveraging the library's vectorized capabilities by passing data for multiple series. For single series or very small datasets, consider if a different library or approach might be more suitable.

Install

• pip install simdkalman Install latest version

Imports

• KalmanFilter
  wrong:

  from simdkalman.KalmanFilter import KalmanFilter

  correct:

  import simdkalman
  kalman_filter = simdkalman.KalmanFilter(...)

  KalmanFilter is part of the top-level simdkalman module, not a submodule.

Quickstart

This quickstart demonstrates how to create a `KalmanFilter` instance and use it to smooth a batch of time series data. It generates synthetic 1D random walk data for multiple series, then applies a simple Kalman filter model. Crucially, input observations are reshaped to the expected `(n_series, n_timesteps, n_features)` format.

import numpy as np
import simdkalman

# Generate some synthetic data for 3 series, 50 time steps each
n_series = 3
n_timesteps = 50
rand = np.random.RandomState(0)
true_states = np.cumsum(rand.normal(0, 0.1, size=(n_series, n_timesteps)), axis=1)
observations = true_states + rand.normal(0, 1, size=(n_series, n_timesteps))

# Initialize a Kalman Filter
# Simple 1-D random walk model:
#   state_transition = [[1]] (state at t is state at t-1)
#   process_noise = [[0.1]] (noise in state transition)
#   observation_model = [[1]] (observation is directly the state)
#   observation_noise = [[1.0]] (noise in observation)
kf = simdkalman.KalmanFilter(
    state_transition = np.array([[1]]), # 1D state, previous state is current state
    process_noise = np.diag([0.1]), # Variance of 0.1 for state evolution
    observation_model = np.array([[1]]), # Observation is the state itself
    observation_noise = np.diag([1.0]) # Observation noise variance of 1.0
)

# Smooth the observations
# `observations` needs to be 3D: (n_series, n_timesteps, n_features)
# Here n_features is 1 for 1D data.
smoothed_states = kf.smooth(observations[:, :, np.newaxis]).states.mean

print(f"Smoothed states shape: {smoothed_states.shape}")
# Expected: (n_series, n_timesteps, 1)

# You can also predict new values
predicted_states = kf.predict(observations[:, :, np.newaxis], n_test=10).states.mean
print(f"Predicted states shape: {predicted_states.shape}")