PyRecEst

Recursive Bayesian Estimation for Python.

PyRecEst is a Python library for recursive Bayesian estimation on Euclidean spaces and manifolds. It uses a NumPy backend by default and can also run with PyTorch or JAX backends.

Features

PyRecEst provides tools for:

• distributions and densities on Euclidean spaces and manifolds;
• recursive Bayesian estimators, filters, and trackers;
• multi-target tracking (MTT) and extended object tracking (EOT);
• evaluation of filters and trackers; and
• sampling distributions and generating grids.

Which API Should I Start With?

Task	Start with
Linear Euclidean Gaussian filtering	KalmanFilter and examples/basic/kalman_filter.py
Reusable transition and measurement models	examples/basic/kalman_filter_with_models.py
Nonlinear filtering	examples/basic/ukf_with_models.py or particle-filter examples
Multi-target tracking with clutter or missed detections	examples/basic/multi_target_tracking.py
Circular, spherical, or manifold-valued states	circular, hypertoroidal, and hyperspherical distribution modules
Backend-portable code	pyrecest.backend imports plus focused tests under each backend

For more detail, see docs/choosing-an-api.md and docs/backend-compatibility.md.

Command Line And Reproducible Scenarios

After installation, use the lightweight CLI to inspect an environment or run a reproducible scenario:

pyrecest info
pyrecest backends --format markdown
pyrecest run-scenario scenarios/linear_gaussian_cv_1d/config.toml

The same scenario runner is available from a source checkout via scripts/run_scenario.py. Scenario definitions live in scenarios/ and include TOML configuration plus JSON golden outputs.

The pyrecest.diagnostics module defines common diagnostics containers for innovation statistics, particle-filter health, and association decisions.

Installation

PyRecEst requires Python 3.11 or newer and earlier than Python 3.15.

Install the package from PyPI:

python -m pip install pyrecest

Optional backend and domain-specific dependencies can be installed with extras:

python -m pip install "pyrecest[pytorch_support]"
python -m pip install "pyrecest[jax_support]"
python -m pip install "pyrecest[healpy_support]"
python -m pip install "pyrecest[all_support]"

Pip normalizes extra names, so the equivalent hyphenated spellings such as pyrecest[pytorch-support], pyrecest[jax-support], pyrecest[healpy-support], and pyrecest[all-support] may also appear in package-index metadata.

For development from a source checkout, use Poetry or the provided conda environment:

poetry install --with dev --all-extras
# or
conda env create -f environment.yml

Quickstart

The following example runs a one-dimensional constant-velocity Kalman filter. It uses the backend abstraction exposed by pyrecest.backend, so the same code can run on supported numerical backends.

from pyrecest.backend import array, diag
from pyrecest.filters import KalmanFilter


dt = 1.0
system_matrix = array([[1.0, dt], [0.0, 1.0]])
measurement_matrix = array([[1.0, 0.0]])
system_noise_cov = diag(array([0.05, 0.01]))
measurement_noise_cov = array([[0.25]])
measurements = [0.9, 2.0, 3.1, 3.9, 5.2]

kalman_filter = KalmanFilter((array([0.0, 1.0]), diag(array([1.0, 1.0]))))

for measurement in measurements:
    kalman_filter.predict_linear(system_matrix, system_noise_cov)
    kalman_filter.update_linear(
        array([measurement]), measurement_matrix, measurement_noise_cov
    )
    print(kalman_filter.get_point_estimate())

Run the complete script with:

python examples/basic/kalman_filter.py

Documentation

The docs/ directory contains the first project documentation pages:

• Getting started covers installation, development setup, backend selection, and running examples.
• API overview maps the main packages and points to the most common public entry points.
• Backend compatibility explains the NumPy, PyTorch, and JAX support model and known limitations.
• Choosing an API maps task families to recommended filters, distributions, trackers, and examples.
• Distribution taxonomy summarizes the main representation families by domain and use case.
• Error handling documents the shared exception types and user-facing diagnostics policy.
• API reference contains generated package reference pages built with MkDocs and mkdocstrings.
• Task tutorials show common distribution, filtering, tracking, and evaluation workflows.
• Shapes and conventions documents common vector, matrix, measurement-set, batch, and manifold-coordinate shapes.
• Examples lists the executable examples and what each one demonstrates.

Build the documentation site locally with:

poetry install --with docs --without dev
poetry run mkdocs build --strict

Backends

PyRecEst imports pyrecest.backend dynamically. The default backend is NumPy. Set PYRECEST_BACKEND before Python imports pyrecest to select another backend:

PYRECEST_BACKEND=pytorch python examples/basic/kalman_filter.py
PYRECEST_BACKEND=jax python examples/basic/kalman_filter.py

Install the matching optional extra before using a non-default backend.

Examples and tests

• examples/basic/kalman_filter.py contains a small executable Kalman filter example.
• tests/ contains additional usage examples for distributions, filters, smoothers, evaluation, sampling, metrics, and tracking utilities.

To run the test suite from a development environment:

python -m pytest

Citation

If you use PyRecEst in your research, please cite:

BibTeX	BibLaTeX
@misc{pfaff_pyrecest_2023, author = {Florian Pfaff}, title = {PyRecEst: Recursive Bayesian Estimation for Python}, year = {2023}, howpublished = {\url{https://github.com/FlorianPfaff/PyRecEst}}, note = {MIT License} }	@software{pfaff_pyrecest_2023_software, author = {Florian Pfaff}, title = {PyRecEst: Recursive Bayesian Estimation for Python}, year = {2023}, url = {https://github.com/FlorianPfaff/PyRecEst}, license = {MIT}, keywords = {Bayesian filtering; manifolds; tracking; Python; NumPy; PyTorch; JAX} }

Credits

• Florian Pfaff (pfaff@ias.uni-stuttgart.de)

PyRecEst borrows its structure from libDirectional and follows its code closely for many classes. libDirectional, a project to which Florian Pfaff contributed extensively, is available on GitHub. The backend implementations are based on those of geomstats.

License

PyRecEst is licensed under the MIT License.