kalbee

kalbee is a clean, modular Python implementation of Kalman Filters and related estimation algorithms. Designed for simplicity and performance, it provides a standard interface for state estimation in various applications.

Features

• 15 Filters: KF, EKF, UKF, SigmaPointUKF, Particle Filter, Ensemble KF, Information Filter, Alpha-Beta-Gamma, Adaptive KF, Square-Root KF, Vectorized KF, Fading Memory KF, H-Infinity, and Interacting Multiple Model (IMM)
• Sigma Points: Pluggable strategies — SimplexSigmaPoints, MerweScaledSigmaPoints, JulierSigmaPoints
• Motion Models: Ready-made constant-velocity, constant-acceleration, and coordinated-turn (F, Q) builders plus position measurement models
• Multi-Object Tracking: SORT-style MultiObjectTracker with Hungarian association, Mahalanobis/IoU gating, and track lifecycle management — built on top of any filter
• Innovation Gating: Chi-squared and Mahalanobis gating for outlier rejection
• Outlier Detection: Real-time Chi2OutlierDetector with adaptive thresholds
• Parameter Learning: Offline EM (em_kalman) that fits Q/R from data by maximum likelihood, complementing the online Adaptive KF
• Auto-Tuning: NIS-based automatic Q/R tuning (tune_kalman_filter, quick_tune)
• RTS Smoother: Rauch-Tung-Striebel backward smoother for post-processing
• Diagnostics: FilterDiagnostics for real-time monitoring, NIS/NEES consistency tests, innovation whiteness test
• Metrics: RMSE, NEES, NIS, Log-Likelihood for filter diagnostics
• Batch Processing: filter_sequence() with missing data handling
• State Persistence: save_state() / load_state() for JSON serialization
• Control Inputs: B matrix support in KF predict step
• Experiment Runner: Compare filters on synthetic signals with one line
• AutoFilter Factory: Switch between filters by name
• Numerical Stability: Joseph form covariance updates, Cholesky factor stabilization, and symmetry enforcement
• NumPy/SciPy Integration: Optimized for numerical computations

Installation

pip install kalbee

Or from source:

git clone https://github.com/MinLee0210/kalbee.git
cd kalbee
pip install -e .

Optional extras: pip install "kalbee[yolo]" (object-tracking examples), "kalbee[viz]" (plotting), or "kalbee[docs]" (documentation site).

Quick Start

1. Standard Kalman Filter

import numpy as np
from kalbee import KalmanFilter

state = np.zeros((2, 1))  # [position, velocity]
cov = np.eye(2)
F = np.array([[1, 1], [0, 1]])  # Constant velocity model
Q = np.eye(2) * 0.01
H = np.array([[1, 0]])
R = np.array([[0.1]])

kf = KalmanFilter(state, cov, F, Q, H, R)
kf.predict()
kf.update(np.array([[1.2]]))
print(f"Estimated State:\n{kf.x}")

2. Interacting Multiple Model (IMM) Filter

import numpy as np
from kalbee import KalmanFilter, InteractingMultipleModel

kf_cv = KalmanFilter(state_init, cov_init, F_cv, Q_cv, H, R)
kf_ca = KalmanFilter(state_init, cov_init, F_ca, Q_ca, H, R)

model_transition = np.array([[0.95, 0.05], [0.05, 0.95]])
model_probabilities = np.array([0.8, 0.2])

imm = InteractingMultipleModel([kf_cv, kf_ca], model_transition, model_probabilities)
imm.predict()
imm.update(measurement)

3. SigmaPointUKF with Pluggable Sigma Points

import numpy as np
from kalbee import SigmaPointUKF, MerweScaledSigmaPoints

state = np.zeros((2, 1))
cov = np.eye(2) * 10.0
Q = np.eye(2) * 0.01
R = np.array([[0.5]])

def f(x, dt):
    return np.array([[x[0, 0] + x[1, 0] * dt], [x[1, 0]]])

def h(x):
    return np.array([[x[0, 0]]])

sigma_pts = MerweScaledSigmaPoints(n=2, alpha=0.1, beta=2.0, kappa=0.0)
ukf = SigmaPointUKF(state, cov, Q, R, f, h, sigma_points=sigma_pts)

ukf.predict(dt=1.0)
ukf.update(np.array([[1.2]]))

4. Compare Filters with Experiments

from kalbee import run_experiment

report = run_experiment(
    signal="sine",
    filters=["kf", "ekf", "ukf", "pf"],
    noise_std=0.5,
)
print(report.summary())

5. AutoFilter Factory

from kalbee import AutoFilter

kf = AutoFilter.from_filter(state, cov, F, Q, H, R, mode="kf")
# Available modes: kf, ekf, ukf, abg, pf, enkf, if, akf, srkf, vkf, imms

6. Multi-Object Tracking

import numpy as np
from kalbee import KalmanFilter, MultiObjectTracker
from kalbee.models import constant_velocity, position_measurement_model

F, Q = constant_velocity(dt=1.0, process_var=0.1, n_dims=2)
H, R = position_measurement_model(order=1, n_dims=2, measurement_var=0.25)

def new_track(z):
    x0 = np.array([[z[0]], [0.0], [z[1]], [0.0]])
    return KalmanFilter(x0, np.eye(4) * 10.0, F, Q, H, R)

tracker = MultiObjectTracker(new_track, n_init=3, max_age=5)

for detections in detection_stream:
    confirmed = tracker.update(detections)
    for t in confirmed:
        print(t.id, t.state[0, 0], t.state[2, 0])

See examples/multi_object_tracking.py for a full runnable demo.

7. Learn Noise Covariances from Data (EM)

from kalbee import em_kalman
from kalbee.models import constant_velocity, position_measurement_model

F, _ = constant_velocity(dt=1.0, n_dims=1)
H, _ = position_measurement_model(order=1, n_dims=1)

result = em_kalman(measurements, F, H, n_iter=50)
print("Learned Q:\n", result.Q)
print("Learned R:\n", result.R)

8. Auto-Tuning

from kalbee import tune_kalman_filter, quick_tune

# Iterative NIS-based tuning
result = tune_kalman_filter(measurements, F, H, n_iter=50)
print(f"Q:\n{result.Q}\nR:\n{result.R}")

# Quick single-pass tuning
Q, R = quick_tune(measurements, F, H)

9. Real-Time Diagnostics

from kalbee import KalmanFilter, FilterDiagnostics

kf = KalmanFilter(state, cov, F, Q, H, R)
diag = FilterDiagnostics(m=1, n=2)

for z in measurements:
    kf.predict()
    kf.update(z)
    snapshot = diag.collect(kf, ground_truth=true_state)

print(diag.summary())

Documentation

Full documentation with theory, code examples, and experiments for each filter:

pip install mkdocs-material
mkdocs serve

• Getting Started
• Filters: KF · EKF · UKF · SigmaPointUKF · PF · EnKF · IF · ABG · AKF · Fading Memory KF · H-Infinity · SRKF · Vectorized KF · IMM
• Features: Gating · Outlier Detection · Auto-Tuning · Diagnostics · Consistency Tests · RTS Smoother · Metrics · Experiments · Maneuvering Target Tracking · YOLO Object Tracking
• Architecture

Testing

uv run pytest tests/                                  # run the suite
uv run pytest tests/ --cov=kalbee --cov-report=term   # with coverage

License

This project is licensed under the Apache License 2.0.