kalman-py

Fast, exact and numerically robust Kalman filters for Python

Quick Start · Highlights · Benchmarks · Architecture · Roadmap · Development · Documentation

kalman-py is a typed Kalman filtering library with linear, extended and unscented filters, RTS smoothers, maximum-likelihood noise learning and consistency diagnostics. It runs on NumPy out of the box, and on an optional JAX backend that compiles the whole time loop with jax.lax.scan. On linear-Gaussian problems it produces the same estimates as FilterPy and pykalman (within 1e-11), so it can replace them without changing your results.

📌 Project status

	Linear KF, EKF and UKF with RTS smoothers, each on the NumPy and JAX backends, step-by-step or batch. Joseph-form and square-root covariance updates.
	Q/R learning by EM or gradient-based maximum likelihood, and NIS/NEES consistency checks with plotting helpers.
	Reproducible comparison with FilterPy and pykalman on five frozen scenarios (S1–S5), shared with the C, C++ and Rust implementations.
	GitHub Actions on every push and pull request: Python 3.10–3.14 on Linux, macOS and Windows, with and without JAX, the minimum supported dependency versions, the docs, and a comparison report against FilterPy and pykalman.
	Documentation site (MkDocs Material) with guides, an API reference and a migration guide from FilterPy, plus three tutorial notebooks: target tracking, multi-rate sensor fusion and learning the noise, published at joslo2345.github.io/kalman-py.
	Release automation is ready: a GitHub release builds, checks and tests the package, then publishes it to PyPI with trusted publishing. The first release (0.1.0) is pending the PyPI-side setup. See the changelog.

✨ Highlights

🚀 Quick Start

kalman-py isn't on PyPI yet. Install it from a clone, with the optional extras you need:

pip install -e ".[jax,plot]"   # or just -e . for NumPy only

Linear filter and smoother

import numpy as np
from kalman_py import KalmanFilter

dt = 0.1
F = np.array([[1.0, dt], [0.0, 1.0]])  # constant velocity: state (position, velocity)
H = np.array([[1.0, 0.0]])  # measure position
Q = 0.5 * np.array([[dt**3 / 3, dt**2 / 2], [dt**2 / 2, dt]])
R = np.array([[0.25]])
kf = KalmanFilter(F, H, Q, R, x0=[0.0, 1.0], P0=np.eye(2))

rng = np.random.default_rng(0)
zs = (np.arange(1, 201) * dt + 0.5 * rng.standard_normal(200))[:, None]

# Real-time: one measurement at a time
kf.predict()
kf.update(zs[0])

# Batch: the whole sequence at once (backend="jax" compiles it), then smooth
result = kf.filter(zs)
smoothed = kf.smooth(result)
print(result.means[-1], float(result.log_likelihood))

(x0, P0) is the prior before the first prediction, as in FilterPy. Pass square_root=True for the square-root form.

Extended and unscented filters

import jax
import jax.numpy as jnp
from kalman_py import ExtendedKalmanFilter, UnscentedKalmanFilter

jax.config.update("jax_enable_x64", True)


def f(x, dt):  # 2-D constant velocity: state (px, py, vx, vy)
    return jnp.array([x[0] + dt * x[2], x[1] + dt * x[3], x[2], x[3]])


def h(x):  # range and bearing from a sensor at the origin
    return jnp.array([jnp.hypot(x[0], x[1]), jnp.arctan2(x[1], x[0])])


def wrap_bearing(z, z_pred):  # bearing residuals in [-pi, pi)
    d = jnp.asarray(z) - jnp.asarray(z_pred)
    return d.at[1].set((d[1] + jnp.pi) % (2 * jnp.pi) - jnp.pi)


truth = np.column_stack([np.linspace(-200, -150, 100), np.linspace(60, -20, 100)])
truth = np.hstack([truth, np.tile([0.5, -0.8], (100, 1))])
radar = np.asarray(jax.vmap(h)(truth)) + rng.normal(0, [0.5, 0.01], (100, 2))

model = dict(Q=0.01 * np.eye(4), R=np.diag([0.25, 1e-4]), x0=truth[0], P0=np.eye(4))
ekf = ExtendedKalmanFilter(f, h, **model, residual_z=wrap_bearing)  # Jacobians by autodiff
ukf = UnscentedKalmanFilter(f, h, **model, residual_z=wrap_bearing, square_root=True)

ekf_result = ekf.filter(radar, dt=1.0, backend="jax")
ukf_result = ukf.filter(radar, dt=1.0, backend="jax")
ukf_smoothed = ukf.smooth(ukf_result)

The target crosses the negative x-axis, where bearings wrap from +π to −π; residual_z is all either filter needs to handle it.

Learn Q and R from data

from kalman_py.learning import fit_noise

fit = fit_noise(F, H, zs, x0=[0.0, 1.0], P0=np.eye(2))  # gradient-based when JAX is installed
print(fit.R, fit.log_likelihood, fit.converged)

Check consistency and plot

from kalman_py.diagnostics import consistency_check
from kalman_py.plotting import plot_estimates

check = consistency_check(result.nis, dof=1)
print(f"{check.fraction_inside:.0%} of steps inside the 95% NIS bounds")

axes = plot_estimates(smoothed, labels=["position", "velocity"])

📊 Benchmarks

Measured against FilterPy (per-step mode) and pykalman (batch mode) on the shared scenarios in tests/vectors/, with the same inputs, seeds and precision for every library. Estimates match in every linear case, so the comparison is about speed, stability and features.

In per-step mode both libraries make the same number of small NumPy calls; kalman-py's extra cost is the symmetrization that keeps every covariance exactly symmetric.

Float32 stability (S4)

Reproduce everything:

ENV="$(git rev-parse --short HEAD),<cpu>,<os>,python-$(python -c 'import platform; print(platform.python_version())'),$(date +%F)"
uv run python benchmarks/run.py "$ENV"          # S1, S2, S5: speed, accuracy, memory
uv run python benchmarks/accuracy.py "$ENV"     # S3 accuracy, S4 stability
uv run python scripts/make_table.py results/results.csv kalman-py --readme README.md
uv run python scripts/plot_benchmarks.py        # the charts above

🏗️ Architecture

flowchart LR
    subgraph API["Filter classes"]
        KF["KalmanFilter"]
        EKF["ExtendedKalmanFilter"]
        UKF["UnscentedKalmanFilter"]
    end
    subgraph Backends
        NP["numpy_backend<br/>step + batch loops"]
        JX["jax_backend<br/>jit + lax.scan"]
    end
    KF & EKF & UKF -- "backend='numpy'" --> NP
    KF & EKF & UKF -- "backend='jax'" --> JX
    NP & JX --> RES["FilterResult<br/>means · covs · priors · NIS · log-likelihood"]
    RES --> SM["RTS smoother"]
    RES --> DIAG["diagnostics<br/>NIS / NEES / χ²"]
    RES --> PLOT["plotting"]
    JX --> LEARN["learning.fit_noise<br/>EM · BFGS"]
    NP --> LEARN

🗺️ Roadmap

🛠️ Development

uv sync --all-extras          # add --group docs for the documentation tools
uv run pytest                 # fast tests
uv run pytest -m ""           # everything, including slow comparison tests
uv run ruff check && uv run ruff format --check && uv run mypy src tests

uv sync --all-extras --group docs
uv run --no-sync mkdocs serve     # documentation at http://127.0.0.1:8000

CI (.github/workflows/ci.yml) runs lint and types, the tests on Python 3.10–3.14 × Linux/macOS/Windows (with JAX, and without it on 3.10 and 3.14), and a comparison job. That job runs every pass condition including the slow tests, benchmarks against FilterPy and pykalman, and compares speed with the latest main run. Timing regressions over 10% are reported as warnings, because shared runners vary by 10–20%; set REGRESSION_MODE to --fail to turn them into errors.

• 🐞 Found a bug? Open an issue with a minimal reproduction.
• 🧪 Changing numerics? The equivalence tests against FilterPy and pykalman and the stability property tests must keep passing; benchmark scenarios in tests/vectors/ are frozen.
• 📐 Conventions: filters predict before the first update; covariances stay exactly symmetric; float32 inputs stay float32 end to end.
• 📚 Docs and tutorials: code in the README and in docs/ is executed by the tests, and the notebooks in examples/ are re-run in CI, so keep them runnable.

🙏 Acknowledgements

kalman-py is measured against, and owes a great deal to, FilterPy and pykalman, and is built on NumPy and JAX.

📄 License

Released under the MIT License.