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.

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]"

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