Project documentation

Fixed-size C++23 state estimation with a thin Python interface.

fast-kalman

Fixed-size C++23 Kalman filters with a nanobind Python binding. Same code underlies both APIs; the Python layer is a thin wrapper, not a reimplementation.

Resource Use it for
Project homepage Positioning, headline results, and a compact technical overview
GitHub repository Source, issues, examples, and reproducible benchmark harnesses
PyPI package Binary wheels and release metadata
Benchmark methods Full tables, commands, definitions, and caveats

What's in this documentation

Page Topic
Getting started Install, import, first filter
Dispatch Templated vs runtime-sized classes, ISA backends
Python API Full Python API reference
C++ API C++ API reference
Filter catalog The seven filter kinds and when to use each
Smoother RTS smoother and smooth_with_bands
Bank LinearKalmanFilterBank for fan-out workloads
Tuning Estimating filter parameters from data
Build CMake options, multi-ISA wheels, abi3
Benchmarks Numbers vs OpenCV cv::KalmanFilter

The changelog at the repo root tracks API and performance changes per release.

What this library is for

Small fixed-size state-space estimation. The library specializes hard for tiny matrices — 1×1 through 8×8 — and trades general-purpose flexibility for about two orders of magnitude of headroom against cv::KalmanFilter on the small shapes that dominate streaming finance, IMU sensor fusion, and per-pixel tracking. If your nx is in the hundreds, use Eigen.

API at a glance

import kalman
kf = kalman.LinearKalmanFilter(nx=2, nz=1)
kf.H = [1.0, 0.0]
result = kf.update_many(measurements, delta_t=dts, record_states=True)
trajectory = result["states"]   # shape (N, 2), zero-copy numpy view
#include <kalman/kalman.hpp>
kalman::LinearKalmanFilter<2, 1> kf;
kf.H = {{1.0, 0.0}};
for (double z : measurements) kf.update({z});

Versioning + ABI