Revise the README

README.md

@@ -1,93 +1,90 @@
 # probdiffeq
 
-[![Actions status](https://github.com/pnkraemer/probdiffeq/workflows/ci/badge.svg)](https://github.com/pnkraemer/probdiffeq/actions)
-[![image](https://img.shields.io/pypi/v/probdiffeq.svg)](https://pypi.python.org/pypi/probdiffeq)
-[![image](https://img.shields.io/pypi/l/probdiffeq.svg)](https://pypi.python.org/pypi/probdiffeq)
-[![image](https://img.shields.io/pypi/pyversions/probdiffeq.svg)](https://pypi.python.org/pypi/probdiffeq)
+[![CI](https://github.com/pnkraemer/probdiffeq/workflows/ci/badge.svg)](https://github.com/pnkraemer/probdiffeq/actions)
+[![PyPI version](https://img.shields.io/pypi/v/probdiffeq.svg)](https://pypi.python.org/pypi/probdiffeq)
+[![License](https://img.shields.io/pypi/l/probdiffeq.svg)](https://pypi.python.org/pypi/probdiffeq)
+[![Python versions](https://img.shields.io/pypi/pyversions/probdiffeq.svg)](https://pypi.python.org/pypi/probdiffeq)
 
-## Probabilistic solvers for differential equations in JAX
+## Probabilistic ODE solvers in JAX
 
-ProbDiffEq implements adaptive probabilistic numerical solvers for initial value problems.
+**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**.
 
-It inherits automatic differentiation, vectorisation, and GPU capability from JAX.
+## Features
 
-**Features include:**
-
-* ⚡ Calibration and step-size adaptation
-* ⚡ Stable implementation of filtering, smoothing, and other estimation strategies
-* ⚡ Custom information operators, dense output, and posterior sampling
-* ⚡ State-space model factorisations
-* ⚡ Physics-enhanced regression
-* ⚡ Taylor-series estimation with and without Jets
-* ⚡ 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/).
-
-
-**Tutorials:**
-
-* **AN EASY EXAMPLE:** [LINK](https://pnkraemer.github.io/probdiffeq/examples_quickstart/easy_example/)
-* **EXAMPLES:** [LINK](https://pnkraemer.github.io/probdiffeq/examples_solver_config/posterior_uncertainties/)
-* **CHOOSING A SOLVER:** [LINK](https://pnkraemer.github.io/probdiffeq/getting_started/choosing_a_solver/)
-* **API DOCUMENTATION:** [LINK](https://pnkraemer.github.io/probdiffeq/api_docs/ivpsolve/)
-* **ISSUE TRACKER:** [LINK](https://github.com/pnkraemer/probdiffeq/issues)
-* **BENCHMARKS:** [LINK](https://pnkraemer.github.io/probdiffeq/benchmarks/lotkavolterra/plot/)
+- ⚡ Calibration and step-size adaptation  
+- ⚡ Stable implementations of filtering, smoothing, and other estimation strategies  
+- ⚡ Custom information operators, dense output, and posterior sampling  
+- ⚡ State-space model factorisations  
+- ⚡ Parameter estimation
+- ⚡ Taylor-series estimation with and without Jets  
+- ⚡ Seamless interoperability with [Optax](https://optax.readthedocs.io/en/latest/index.html), [BlackJAX](https://blackjax-devs.github.io/blackjax/), and other JAX-based libraries  
+- ⚡ Numerous tutorials (basic and advanced) -- see the [documentation](https://pnkraemer.github.io/probdiffeq/)  
 
+---
 
 ## Installation
 
-Get the most recent stable version from PyPi:
+Install the latest release from PyPI:
 
-```
+```bash
 pip install probdiffeq
 ```
-This installation assumes that [JAX](https://jax.readthedocs.io/en/latest/) is already available.
 
-To install ProbDiffEq with `jax[cpu]`, run
-```commandline
+> This assumes [JAX](https://jax.readthedocs.io/en/latest/) is already installed.  
+
+To install with JAX (CPU backend):  
+
+```bash
 pip install probdiffeq[cpu]
 ```
 
+⚠️ **Note:** This is an active research project. Expect rough edges and breaking API changes.
+
+---
+
+## Benchmarks
 
-**WARNING:**
-_**This is a research project. Expect rough edges and sudden API changes.**_
+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/).
 
-**VERSIONING:**
-As long as Probdiffeq is in its initial development phase (version 0.MINOR.PATCH), version numbers are increased as follows:
+Run benchmarks locally:
 
-* Bugfixes and new features increase the PATCH version. 
-* Breaking changes increase the MINOR version.
+```bash
+pip install .[example,test]
+make benchmarks-run
+```
 
-See also: [semantic versioning](https://semver.org/).
 
+---
 
-## What's next?
+## Contributing
 
-Start with the quickstart, continue with the `Solvers & Solutions` examples and only then move to the `Parameter estimation` examples and the API documentation.
+Contributions are very welcome!  
+- Browse open issues (look for “good first issue”).  
+- Check the developer documentation.  
+- Open an issue for feature requests or ideas.  
 
-The examples show how to interact with the API and explain some valuable facts about probabilistic numerical solvers.
-They may be more instructive than the API docs.
+---
 
-The advanced examples show applications of probabilistic numerical solvers, often in conjunction with external libraries.
-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).
+## Citing
 
-## Citing this repository
-If you find Probdiffeq helpful for your research, please consider citing:
+If you use **Probdiffeq** in your research, please cite:
 
 ```bibtex
 @phdthesis{kramer2024implementing,
   title={Implementing probabilistic numerical solvers for differential equations},
-  author={Kr{\"a}mer, Peter Nicholas},
+  author={Kr{"a}mer, Peter Nicholas},
   year={2024},
-  school={Universit{\"a}t T{\"u}bingen}
+  school={Universit{"a}t T{"u}bingen}
 }
 ```
-This thesis contains detailed information about the maths and algorithms behind what is implemented here.
-A PDF is available [at this link](https://tobias-lib.ub.uni-tuebingen.de/xmlui/handle/10900/152754).
+The [PDF](https://tobias-lib.ub.uni-tuebingen.de/xmlui/handle/10900/152754) explains the mathematics and algorithms behind this library.  
+
+For the *solve-and-save-at* functionality, cite:
 
-If you use the solve-and-save-at functionality, please cite
 ```bibtex
 @InProceedings{kramer2024adaptive,
   title     = {Adaptive Probabilistic ODE Solvers Without Adaptive Memory Requirements},
-  author    = {Kr\"{a}mer, Nicholas},
+  author    = {Kr"{a}mer, Nicholas},
   booktitle = {Proceedings of the First International Conference on Probabilistic Numerics},
   pages     = {12--24},
   year      = {2025},
@@ -98,55 +95,36 @@ If you use the solve-and-save-at functionality, please cite
   url       = {https://proceedings.mlr.press/v271/kramer25a.html}
 }
 ```
-This article introduced the algorithm we use.
-The implementation is slightly different to what we would do for non-probabilistic solvers; see the paper.
-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).
+Link to the paper: [PDF](https://arxiv.org/abs/2410.10530).
 
+Link to the experiments: 
+[Code for experiments](https://github.com/pnkraemer/code-adaptive-prob-ode-solvers).  
 
-_Probdiffeq's algorithms have been developed over many years and in multiple research papers.
-Linking concrete citation information for specific algorithms is a work in progress.
-Feel free to reach out if you need help determining which works to cite!_
+📌 Algorithms in Probdiffeq are based on multiple research papers. If you’re unsure which to cite, feel free to reach out.  
 
-## Contributing
-Contributions are welcome!
-Check the existing issues for a "good first issue" and consult the developer documentation.
+---
 
-If you have a feature that you would like to see implemented, create an issue!
+## Versioning
 
-## Benchmarks
+Probdiffeq follows **0.MINOR.PATCH** until its first stable release:  
+- **PATCH** → bugfixes & new features  
+- **MINOR** → breaking changes  
 
-ProbDiffEq curates a range of benchmarks that includes various library-internal configurations
-but also other packages like [SciPy](https://scipy.org/), [JAX](https://jax.readthedocs.io/en/latest/), or [Diffrax](https://docs.kidger.site/diffrax/). 
-To run the benchmark locally, install all dependencies via
-```commandline
-pip install .[example,test]
-```
-and then either open Jupyter and go to `docs/benchmarks`
-or execute all benchmarks via
-```commandline
-make benchmarks-run
-```
-Be patient; it might take a while. 
-Afterwards, open Jupyter to look at the result or build the documentation via
-```
-mkdocs serve
-```
-What do you find?
+See [semantic versioning](https://semver.org/).
+
+---
 
-## Similar projects
+## Related projects
 
-* [Tornadox](https://github.com/pnkraemer/tornadox)
-* [ProbNumDiffEq.jl](https://nathanaelbosch.github.io/ProbNumDiffEq.jl/stable/)
-* [ProbNum](https://probnum.readthedocs.io/en/latest/)
-* [Diffrax](https://docs.kidger.site/diffrax/)
+- [Tornadox](https://github.com/pnkraemer/tornadox)  
+- [ProbNumDiffEq.jl](https://nathanaelbosch.github.io/ProbNumDiffEq.jl/stable/)  
+- [ProbNum](https://probnum.readthedocs.io/en/latest/)  
 
-Here's how to transition from those packages: [link](https://pnkraemer.github.io/probdiffeq/quickstart/transitioning_from_other_packages/).
+The docs include guidance on migrating from these packages. Missing something? Open an issue or pull request!
 
-Is anything missing from this list? Please open an issue or make a pull request.
+---
 
 ## You might also like
 
-* [diffeqzoo](https://diffeqzoo.readthedocs.io/en/latest/): 
-  A library, for example, implementations of differential equations in NumPy and JAX
-* [probfindiff](https://probfindiff.readthedocs.io/en/latest/): 
-  Probabilistic numerical finite differences in JAX.
+- [diffeqzoo](https://diffeqzoo.readthedocs.io/en/latest/) — reference implementations of differential equations in NumPy and JAX  
+- [probfindiff](https://probfindiff.readthedocs.io/en/latest/) — probabilistic finite-difference methods in JAX  

mkdocs.yml

@@ -73,7 +73,7 @@ extra:
       name: pnkraemer
   generator: false
 nav:
-  - Probabilistic solvers for differential equations in JAX: index.md
+  - index.md
   - An easy example: examples_quickstart/quickstart.ipynb
   - Migration guide: migration_guide.md
   - Choosing a solver: choosing_a_solver.md