Metadata-Version: 2.4
Name: pyrecest
Version: 2.4.0
Summary: Framework for recursive Bayesian estimation in Python.
License: MIT
License-File: LICENSE
Keywords: bayesian-filtering,recursive-estimation,tracking,multi-target-tracking,manifolds,directional-statistics
Author: Florian Pfaff
Author-email: pfaff@ias.uni-stuttgart.de
Requires-Python: >=3.11,<3.15
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Provides-Extra: all-support
Provides-Extra: healpy-support
Provides-Extra: jax-support
Provides-Extra: pytorch-support
Requires-Dist: autograd (>=1.7,<2.0) ; extra == "jax-support" or extra == "all-support"
Requires-Dist: beartype (>=0.18,<0.23)
Requires-Dist: healpy (>=1.17,<2.0) ; extra == "healpy-support" or extra == "all-support"
Requires-Dist: jax (>=0.4.30,<0.11) ; extra == "jax-support" or extra == "all-support"
Requires-Dist: jaxlib (>=0.4.30,<0.11) ; extra == "jax-support" or extra == "all-support"
Requires-Dist: matplotlib (>=3.8,<4.0)
Requires-Dist: mpmath (>=1.3,<1.4)
Requires-Dist: numpy (>=2.0,<2.5)
Requires-Dist: pyshtools (>=4.12,<5.0)
Requires-Dist: scipy (>=1.14,<1.18)
Requires-Dist: shapely (>=2.0,<3.0)
Requires-Dist: torch (>=2.4,<3.0) ; extra == "pytorch-support" or extra == "all-support"
Project-URL: Documentation, https://florianpfaff.github.io/PyRecEst/
Project-URL: Homepage, https://github.com/FlorianPfaff/PyRecEst
Project-URL: Issues, https://github.com/FlorianPfaff/PyRecEst/issues
Project-URL: Repository, https://github.com/FlorianPfaff/PyRecEst
Description-Content-Type: text/markdown

# PyRecEst

[![Tests](https://github.com/FlorianPfaff/PyRecEst/actions/workflows/tests.yml/badge.svg)](https://github.com/FlorianPfaff/PyRecEst/actions/workflows/tests.yml)
[![PyPI version](https://img.shields.io/pypi/v/pyrecest.svg)](https://pypi.org/project/pyrecest/)
[![Python versions](https://img.shields.io/pypi/pyversions/pyrecest.svg)](https://pypi.org/project/pyrecest/)
[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://florianpfaff.github.io/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:

```bash
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:

```bash
python -m pip install pyrecest
```

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

```bash
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:

```bash
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.

```python
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:

```bash
python examples/basic/kalman_filter.py
```

## Documentation

The `docs/` directory contains the first project documentation pages:

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

Build the documentation site locally with:

```bash
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:

```bash
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.
- `examples/basic/scgp_measurement_reliability.py` demonstrates
  reliability-weighted measurements for the full SCGP extended-object tracker.
- `tests/` contains additional usage examples for distributions, filters,
  smoothers, evaluation, sampling, metrics, and tracking utilities.

To run the test suite from a development environment:

```bash
python -m pytest
```

## Citation

If you use **PyRecEst** in your research, please cite:

<table>
  <tr>
    <th>BibTeX</th>
    <th>BibLaTeX</th>
  </tr>
  <tr>
    <td>
      <pre><code class="language-bibtex">@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}
}</code></pre>
    </td>
    <td>
      <pre><code class="language-biblatex">@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}
}</code></pre>
    </td>
  </tr>
</table>

## 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](https://github.com/libDirectional). The
backend implementations are based on those of
[geomstats](https://github.com/geomstats/geomstats).

## License
`PyRecEst` is licensed under the MIT License.

