Metadata-Version: 2.4
Name: dynestyx
Version: 0.0.5
Summary: NumPyro integration for dynamical systems
Author: Basis
License-Expression: Apache-2.0
License-File: LICENSE.md
Keywords: bayesian modeling,dynamical systems,jax,machine learning,statistics
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.12
Requires-Dist: arviz<1.0.0,>=0.18.0
Requires-Dist: blackjax>=1.3
Requires-Dist: cd-dynamax
Requires-Dist: cuthbert>=0.0.9
Requires-Dist: cuthbertlib>=0.0.9
Requires-Dist: effectful
Requires-Dist: equinox>=0.13.2
Requires-Dist: ipywidgets>=8.1.8
Requires-Dist: jax>=0.6.2
Requires-Dist: jaxlib>=0.6.2
Requires-Dist: jupyter>=1.1.1
Requires-Dist: matplotlib>=3.10.7
Requires-Dist: mkdocstrings[python]>=1.0.1
Requires-Dist: numpyro>=0.19.0
Requires-Dist: pytest>=9.0.1
Requires-Dist: pytkdocs-tweaks>=0.0.8
Requires-Dist: tfp-nightly>=0.26.0dev20250530
Description-Content-Type: text/markdown

![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/BasisResearch/dynestyx/test.yml) ![GitHub License](https://img.shields.io/github/license/BasisResearch/dynestyx)

# Welcome to Dynestyx

![dynestyx logo](docs/logo/dynestyx.gif)

`dynestyx` is a library designed for Bayesian modeling and inference of dynamical systems. It is an extension of [NumPyro](https://num.pyro.ai/en/stable/), and incorporates a wide variety of state-of-the-art inference methods for state space models.

To get started, you can [read the documentation](https://basisresearch.github.io/dynestyx) (version menu: **stable** = latest release, **latest** = `main`) or go straight to the [quickstart](https://basisresearch.github.io/dynestyx/tutorials/quickstart/). See [Versioned documentation](docs/versioning.md) for details.

## Goals of `dynestyx`

The goal of `dynestyx` is to decouple model code and inference code for dynamical systems, a common theme in *probabilistic programming languages* like [NumPyro](https://num.pyro.ai/en/stable/). The benefits of this are two-fold: modellers get an interface that is simple to use, with access to advanced inference methods for free. Methods researchers simultaneously get a platform where their methodologies can be immediately used, with a natural testbed of problems to evaluate performance on.

### Relation to Existing Libraries

While many probabilistic programming languages now exist (e.g., [Pyro](https://pyro.ai/), [NumPyro](https://num.pyro.ai/en/stable/), and [Stan](https://mc-stan.org/)), these solutions do not offer support of structured inference methods specifically designed for the dynamical systems setting, leading to subpar inference and ad-hoc code that may be difficult to write for practitioners. In `dynestyx`, we treat dynamical systems as first-class objects, with direct interfacing to methods like pseudo-marginal MCMC and stochastic variational inference for parameter inference.

Simultaneously, many strong solutions exist for inference in dynamical systems; modern examples include [dynamax](https://github.com/probml/dynamax) for discrete-time dynamical systems, [cd-dynamax](https://github.com/hd-UQ/cd_dynamax) for continuous-time dynamical systems, and [PFJax](https://pfjax.readthedocs.io/en/latest/) for nonlinear and non-Gaussian discrete-time dynamical systems. While featureful, one drawback of this suite of methods is a varied set of APIs, with model code that is tightly coupled with the resulting inference method. In `dynestyx`, we offer a large variety of different inference methods under the same roof in a unified, abstract API. Iterating and selecting the appropriate inference methods is thus a significantly simpler process. Using tools from PPLs, we are also able to introspectively analyze a given model, and select appropriate inference methods which take advantage of model structure (e.g., linearity or Gaussianity).

## Installation

For installation, we recommend [`uv`](https://docs.astral.sh/uv/):
```bash
uv venv
source .venv/bin/activate
uv pip install git+https://github.com/BasisResearch/dynestyx.git
```

But `pip` works as well:
```bash
pip install git+https://github.com/BasisResearch/dynestyx.git
```

## Quickstart

We provide a more mathematical introduction in the [Introduction](docs/math_intro.md) section. For a hands-on tutorial with code examples, check out the [Quickstart Tutorial](docs/tutorials/quickstart.ipynb).

## Contributing

Contributions are welcome. See [Contributing Guidelines](CONTRIBUTING.md) for development setup, testing expectations, and the pull request workflow.