You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## Probabilistic solvers for differential equations in JAX
8
+
## Probabilistic ODE solvers in JAX
9
9
10
-
ProbDiffEq implements adaptive probabilistic numerical solvers for initial value problems.
10
+
**Probdiffeq** implements adaptive probabilistic numerical solvers for ordinary differential equations (ODEs). It builds on [JAX](https://jax.readthedocs.io/en/latest/), thus inheriting **automatic differentiation**, **vectorisation**, and **GPU acceleration**.
11
11
12
-
It inherits automatic differentiation, vectorisation, and GPU capability from JAX.
12
+
## Features
13
13
14
-
**Features include:**
15
-
16
-
* ⚡ Calibration and step-size adaptation
17
-
* ⚡ Stable implementation of filtering, smoothing, and other estimation strategies
18
-
* ⚡ Custom information operators, dense output, and posterior sampling
19
-
* ⚡ State-space model factorisations
20
-
* ⚡ Physics-enhanced regression
21
-
* ⚡ Taylor-series estimation with and without Jets
22
-
* ⚡ Compatibility with other JAX-based libraries such as [Optax](https://optax.readthedocs.io/en/latest/index.html) or [BlackJAX](https://blackjax-devs.github.io/blackjax/).
- ⚡ Stable implementations of filtering, smoothing, and other estimation strategies
16
+
- ⚡ Custom information operators, dense output, and posterior sampling
17
+
- ⚡ State-space model factorisations
18
+
- ⚡ Parameter estimation
19
+
- ⚡ Taylor-series estimation with and without Jets
20
+
- ⚡ Seamless interoperability with [Optax](https://optax.readthedocs.io/en/latest/index.html), [BlackJAX](https://blackjax-devs.github.io/blackjax/), and other JAX-based libraries
21
+
- ⚡ Numerous tutorials (basic and advanced) -- see the [documentation](https://pnkraemer.github.io/probdiffeq/)
33
22
23
+
---
34
24
35
25
## Installation
36
26
37
-
Get the most recent stable version from PyPi:
27
+
Install the latest release from PyPI:
38
28
39
-
```
29
+
```bash
40
30
pip install probdiffeq
41
31
```
42
-
This installation assumes that [JAX](https://jax.readthedocs.io/en/latest/) is already available.
43
32
44
-
To install ProbDiffEq with `jax[cpu]`, run
45
-
```commandline
33
+
> This assumes [JAX](https://jax.readthedocs.io/en/latest/) is already installed.
34
+
35
+
To install with JAX (CPU backend):
36
+
37
+
```bash
46
38
pip install probdiffeq[cpu]
47
39
```
48
40
41
+
⚠️ **Note:** This is an active research project. Expect rough edges and breaking API changes.
42
+
43
+
---
44
+
45
+
## Benchmarks
49
46
50
-
**WARNING:**
51
-
_**This is a research project. Expect rough edges and sudden API changes.**_
47
+
We maintain benchmarks comparing **Probdiffeq** against other solvers and libraries, including [SciPy](https://scipy.org/), [JAX](https://jax.readthedocs.io/en/latest/), and [Diffrax](https://docs.kidger.site/diffrax/).
52
48
53
-
**VERSIONING:**
54
-
As long as Probdiffeq is in its initial development phase (version 0.MINOR.PATCH), version numbers are increased as follows:
49
+
Run benchmarks locally:
55
50
56
-
* Bugfixes and new features increase the PATCH version.
57
-
* Breaking changes increase the MINOR version.
51
+
```bash
52
+
pip install .[example,test]
53
+
make benchmarks-run
54
+
```
58
55
59
-
See also: [semantic versioning](https://semver.org/).
60
56
57
+
---
61
58
62
-
## What's next?
59
+
## Contributing
63
60
64
-
Start with the quickstart, continue with the `Solvers & Solutions` examples and only then move to the `Parameter estimation` examples and the API documentation.
61
+
Contributions are very welcome!
62
+
- Browse open issues (look for “good first issue”).
63
+
- Check the developer documentation.
64
+
- Open an issue for feature requests or ideas.
65
65
66
-
The examples show how to interact with the API and explain some valuable facts about probabilistic numerical solvers.
67
-
They may be more instructive than the API docs.
66
+
---
68
67
69
-
The advanced examples show applications of probabilistic numerical solvers, often in conjunction with external libraries.
70
-
For example, [this notebook](https://pnkraemer.github.io/probdiffeq/advanced_examples/physics_enhanced_regression_1/) shows how to combine ProbDiffEq with [Optax](https://optax.readthedocs.io/en/latest/index.html), and [this notebook](https://pnkraemer.github.io/probdiffeq/advanced_examples/physics_enhanced_regression_2/) does the same with [BlackJAX](https://optax.readthedocs.io/en/latest/index.html).
68
+
## Citing
71
69
72
-
## Citing this repository
73
-
If you find Probdiffeq helpful for your research, please consider citing:
70
+
If you use **Probdiffeq** in your research, please cite:
74
71
75
72
```bibtex
76
73
@phdthesis{kramer2024implementing,
77
74
title={Implementing probabilistic numerical solvers for differential equations},
78
-
author={Kr{\"a}mer, Peter Nicholas},
75
+
author={Kr{"a}mer, Peter Nicholas},
79
76
year={2024},
80
-
school={Universit{\"a}t T{\"u}bingen}
77
+
school={Universit{"a}t T{"u}bingen}
81
78
}
82
79
```
83
-
This thesis contains detailed information about the maths and algorithms behind what is implemented here.
84
-
A PDF is available [at this link](https://tobias-lib.ub.uni-tuebingen.de/xmlui/handle/10900/152754).
80
+
The [PDF](https://tobias-lib.ub.uni-tuebingen.de/xmlui/handle/10900/152754) explains the mathematics and algorithms behind this library.
81
+
82
+
For the *solve-and-save-at* functionality, cite:
85
83
86
-
If you use the solve-and-save-at functionality, please cite
87
84
```bibtex
88
85
@InProceedings{kramer2024adaptive,
89
86
title = {Adaptive Probabilistic ODE Solvers Without Adaptive Memory Requirements},
90
-
author = {Kr\"{a}mer, Nicholas},
87
+
author = {Kr"{a}mer, Nicholas},
91
88
booktitle = {Proceedings of the First International Conference on Probabilistic Numerics},
92
89
pages = {12--24},
93
90
year = {2025},
@@ -98,55 +95,36 @@ If you use the solve-and-save-at functionality, please cite
The implementation is slightly different to what we would do for non-probabilistic solvers; see the paper.
103
-
A PDF is available [here](https://arxiv.org/abs/2410.10530) and the paper's experiments are [here](https://github.com/pnkraemer/code-adaptive-prob-ode-solvers).
98
+
Link to the paper: [PDF](https://arxiv.org/abs/2410.10530).
104
99
100
+
Link to the experiments:
101
+
[Code for experiments](https://github.com/pnkraemer/code-adaptive-prob-ode-solvers).
105
102
106
-
_Probdiffeq's algorithms have been developed over many years and in multiple research papers.
107
-
Linking concrete citation information for specific algorithms is a work in progress.
108
-
Feel free to reach out if you need help determining which works to cite!_
103
+
📌 Algorithms in Probdiffeq are based on multiple research papers. If you’re unsure which to cite, feel free to reach out.
109
104
110
-
## Contributing
111
-
Contributions are welcome!
112
-
Check the existing issues for a "good first issue" and consult the developer documentation.
105
+
---
113
106
114
-
If you have a feature that you would like to see implemented, create an issue!
107
+
## Versioning
115
108
116
-
## Benchmarks
109
+
Probdiffeq follows **0.MINOR.PATCH** until its first stable release:
110
+
-**PATCH** → bugfixes & new features
111
+
-**MINOR** → breaking changes
117
112
118
-
ProbDiffEq curates a range of benchmarks that includes various library-internal configurations
119
-
but also other packages like [SciPy](https://scipy.org/), [JAX](https://jax.readthedocs.io/en/latest/), or [Diffrax](https://docs.kidger.site/diffrax/).
120
-
To run the benchmark locally, install all dependencies via
121
-
```commandline
122
-
pip install .[example,test]
123
-
```
124
-
and then either open Jupyter and go to `docs/benchmarks`
125
-
or execute all benchmarks via
126
-
```commandline
127
-
make benchmarks-run
128
-
```
129
-
Be patient; it might take a while.
130
-
Afterwards, open Jupyter to look at the result or build the documentation via
0 commit comments