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.
Project links
| 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
- v0.3.0 introduced multi-ISA wheels and
Py_LIMITED_API(abi3): a singlecp312-abi3-<plat>wheel runs on CPython 3.12, 3.13, 3.14, ... See Build. - The Python API is stable across the
0.3.xline. The C++ headers are versioned by directory and followSameMajorVersioncompatibility.