Skip to content

Getting Started

Installation

pip install kalbee

uv pip install kalbee

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

Core Concepts

All filters in kalbee share a common interface through BaseFilter:

Step Method What it does
1. Init __init__() Set initial state \(x\), covariance \(P\), and model matrices
2. Predict predict(dt) Propagate state forward: \(\hat{x}_{k\|k-1} = f(x_{k-1})\)
3. Update update(z) Correct state with measurement: \(\hat{x}_k = \hat{x}_{k\|k-1} + K(z - h(\hat{x}))\)

Your First Filter

import numpy as np
from kalbee import KalmanFilter

# State: [position, velocity], measuring position only
state = np.zeros((2, 1))
covariance = np.eye(2)

# Constant-velocity model (dt=1)
F = np.array([[1, 1], [0, 1]])  # Transition
Q = np.eye(2) * 0.01            # Process noise
H = np.array([[1, 0]])           # Measurement matrix
R = np.array([[0.1]])            # Measurement noise

kf = KalmanFilter(state, covariance, F, Q, H, R)

# Predict & update loop
measurements = [1.2, 2.1, 2.8, 4.1, 5.0]
for z in measurements:
    kf.predict()
    kf.update(np.array([[z]]))
    print(f"Position: {kf.x[0,0]:.2f}, Velocity: {kf.x[1,0]:.2f}")

Quick Experiment

Compare multiple filters with one line:

from kalbee import run_experiment

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

Using AutoFilter

Switch between filters without changing code structure:

from kalbee import AutoFilter

# Create any filter by name
kf = AutoFilter.from_filter(state, cov, F, Q, H, R, mode="kf")
ekf = AutoFilter.from_filter(state, cov, Q, R, mode="ekf")
ukf = AutoFilter.from_filter(state, cov, Q, R, f, h, mode="ukf")

Available modes: kf, ekf, ukf, abg, pf, enkf, if, akf

What's Next?

Explore each filter in detail: