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

• 8 Filters: KF, EKF, UKF, Particle, Ensemble, Information, Alpha-Beta-Gamma, Adaptive KF
• 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, 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 .

🛠️ 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. 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())

3. 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

📚 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
• Features: RTS Smoother · Metrics · Experiments
• Architecture

🧪 Testing

uv run pytest tests/   # 58 tests

📄 License

This project is licensed under the Apache License 2.0.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. Check TODO.md for ideas.