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

• 10 Filters: KF, EKF, UKF, Particle Filter, Ensemble KF, Information Filter, Alpha-Beta-Gamma, Adaptive KF, Square-Root KF (SRKF), and Vectorized KF (VKF)
• Estimators: Interacting Multiple Model (IMM) filter blending/switching estimator
• RTS Smoother: Rauch-Tung-Striebel backward smoother for post-processing
• Metrics: RMSE, NEES, NIS, Log-Likelihood for filter diagnostics
• 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

# Define CV and CA filters with shared state size (6D)
# CV model setup
kf_cv = KalmanFilter(state_init, cov_init, F_cv, Q_cv, H, R)
# CA model setup
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. Vectorized Kalman Filter (Batched Tracking)

import numpy as np
from kalbee import VectorizedKalmanFilter

batch_size = 1000
state = np.zeros((batch_size, 2, 1))
covariance = np.repeat(np.eye(2)[np.newaxis, :, :], batch_size, axis=0)

# Load batched models and predict
vkf = VectorizedKalmanFilter(state, covariance, F_batch, Q_batch, H_batch, R_batch)
vkf.predict()
vkf.update(batched_measurements)

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

Documentation

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

pip install mkdocs-material
mkdocs serve

• Getting Started
• Filters: KF · EKF · UKF · PF · EnKF · IF · ABG · AKF · SRKF · Vectorized KF · IMM
• Features: 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.