Metadata-Version: 2.4
Name: modax-solvers
Version: 0.0.7
Summary: GPU-accelerated ODE solvers for massive ensembles of low-dimensional trajectories
Author-email: Lawrence Berry <lawrenceberry@outlook.com>
License-Expression: MIT
Project-URL: Documentation, https://lawrenceberry.github.io/modax/
Project-URL: Source, https://github.com/lawrenceberry/modax
Project-URL: Issues, https://github.com/lawrenceberry/modax/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jax>=0.6.2
Requires-Dist: numba>=0.61
Requires-Dist: numba-cuda-mlir[cu13]>=0.5.1; python_version >= "3.11"
Requires-Dist: numba-cuda-mlir[cu12]>=0.5.1; python_version < "3.11"
Requires-Dist: numba-enzyme-cuda>=0.3.0
Requires-Dist: networkx>=3.4
Requires-Dist: numpy>=2.2.6
Requires-Dist: cvxopt>=1.3
Requires-Dist: scipy>=1.15.3
Provides-Extra: sparse
Provides-Extra: cuda12
Requires-Dist: jax[cuda12]>=0.6.2; extra == "cuda12"
Provides-Extra: cuda13
Requires-Dist: jax[cuda13]>=0.9.1; python_version >= "3.11" and extra == "cuda13"
Dynamic: license-file

<p align="center">
  <img alt="modax logo" src="docs/assets/modax.svg" width="480">
</p>

<h1 align="center">modax</h1>

<!--
The coverage badge reads a gist that the `tests` workflow rewrites on every
push to main; the id below is the repository variable COVERAGE_GIST_ID.
These badges sit above the `overview` snippet marker, so the documentation
site does not repeat them.
-->
<p align="center">
  <a href="https://github.com/lawrenceberry/modax/actions/workflows/tests.yml"><img alt="tests" src="https://github.com/lawrenceberry/modax/actions/workflows/tests.yml/badge.svg?branch=main"></a>
  <a href="https://github.com/lawrenceberry/modax/actions/workflows/tests.yml"><img alt="coverage" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2Flawrenceberry%2Fb451e14a9620fabb0d49c345f13b5414%2Fraw%2Fmodax-coverage.json"></a>
  <a href="https://github.com/lawrenceberry/modax/actions/workflows/lint.yml"><img alt="lint" src="https://github.com/lawrenceberry/modax/actions/workflows/lint.yml/badge.svg?branch=main"></a>
  <a href="https://pypi.org/project/modax-solvers/"><img alt="PyPI" src="https://img.shields.io/pypi/v/modax-solvers"></a>
  <a href="https://pypi.org/project/modax-solvers/"><img alt="Downloads" src="https://img.shields.io/pypi/dm/modax-solvers"></a>
  <a href="https://pypi.org/project/modax-solvers/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/modax-solvers"></a>
  <a href="https://docs.jax.dev/"><img alt="JAX" src="https://img.shields.io/badge/JAX-compatible-3f51b5"></a>
  <a href="https://arxiv.org/abs/2609.35661"><img alt="arXiv" src="https://img.shields.io/badge/arXiv-2609.35661-b31b1b.svg"></a>
  <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
</p>

<p align="center">
  <a href="#installation">Installation</a> •
  <a href="#quickstart">Quickstart</a> •
  <a href="https://lawrenceberry.github.io/modax/">Documentation</a> •
  <a href="https://arxiv.org/abs/2609.35661">Paper</a> •
  <a href="#citation">Citation</a>
</p>

<!-- --8<-- [start:overview] -->

`modax` is a library of GPU-accelerated ODE solvers optimised for solving **massive ensembles** (1k-100k) of low-dimensional (<200D) ODE trajectories, built on JAX and Numba-CUDA-MLIR. Applications include: Bayesian parameter estimation, uncertainty quantification and the integration of physically uncoupled systems.

Every solver is compiled as a **custom CUDA kernel** using Numba-CUDA-MLIR. Each ODE trajectory is solved within its own CUDA thread and results are exposed to JAX as an XLA FFI custom call. Calls to `modax` therefore behave as ordinary JAX primitives. They are `jit`-traceable, auto-differentiable and a `vmap` over a single solve lowers to one native ensemble launch.

<!-- --8<-- [end:overview] -->

The [documentation](https://lawrenceberry.github.io/modax/) covers the solver
API and explains how to use the library. The [paper](https://arxiv.org/abs/2609.35661) details the technical implementation, example applications and performance benchmarks against other GPU-accelerated ODE libraries in Julia and Python.

## Installation

<!-- --8<-- [start:install] -->

```bash
pip install "modax-solvers[cuda13]"   # or [cuda12]; Python 3.10 needs cuda12
```

There is no system library to install first: every dependency ships wheels,
the AMD ordering included. A GPU is needed to run a solve. The Enzyme-derived
Jacobians come from
[numba-enzyme-cuda](https://pypi.org/project/numba-enzyme-cuda/), the
CUDA-enabled fork of numba-enzyme, which carries its own LLVM 15 and Enzyme
binaries and provides the `numba_enzyme` import package, so upstream
`numba-enzyme` must not be installed alongside it. See
[wheels/README.md](https://github.com/lawrenceberry/modax/blob/main/wheels/README.md) for what is in the wheel and why.

Any GPU of compute capability 7.0 or later runs it. On Blackwell (10.0 and
up) the kernels and their Enzyme derivatives are compiled for `sm_90`, the
newest target whose LLVM dialect Enzyme's LLVM 15 toolchain reads, and linked
for the GPU itself; `NUMBA_ENZYME_CUDA_CC` overrides that target.

<!-- --8<-- [end:install] -->

## Quickstart

<!-- --8<-- [start:quickstart] -->

This example demonstrates a stiff decay chain A → B → C, solved for 1000 rate constants at once, with
a declared sparsity pattern (i.e. which inputs affect which outputs):

```python
import jax.numpy as jnp
import numpy as np
from modax.rodas5P import solve


def ode_fn(y, t, p):  # tuples of scalars in and out
    return -p[0] * y[0], p[0] * y[0] - p[1] * y[1], p[1] * y[1]


sparsity = np.array([[1, 0, 0], [1, 1, 0], [0, 1, 1]], dtype=bool)
params = jnp.stack([jnp.logspace(0, 4, 1000), jnp.ones(1000)], axis=1)
y0 = jnp.array([1.0, 0.0, 0.0])
t_span = jnp.linspace(0.0, 10.0, 11)

y = solve(ode_fn, y0, t_span, params, sparsity=sparsity)  # (1000, 11, 3)
```

<!-- --8<-- [end:quickstart] -->

## Development

<!-- --8<-- [start:development] -->

The repository uses [uv](https://docs.astral.sh/uv/):

```bash
git clone https://github.com/lawrenceberry/modax.git && cd modax
uv sync                 # CPU
uv sync --extra cuda13  # or --extra cuda12, for GPU

uv run pytest tests     # most tests skip themselves without a GPU
uv run ruff format && uv run ruff check --fix
uv run ty check
uv run pre-commit install   # runs the three checks above on every commit
```

The documentation builds in an environment of its own, since syncing the docs
group into the default one replaces the project's packages:

```bash
UV_PROJECT_ENVIRONMENT=.venv-docs uv sync --only-group docs --no-install-project
UV_PROJECT_ENVIRONMENT=.venv-docs uv run --no-sync mkdocs serve
```

<!-- --8<-- [end:development] -->

## Citation

<!-- --8<-- [start:citation] -->

If you use modax in your research, please cite the
[arXiv article](https://arxiv.org/abs/2609.35661):

```bibtex
@misc{berry2026acceleratingmassiveensemblesordinary,
      title={Accelerating massive ensembles of ordinary differential equations}, 
      author={Lawrence Berry and Will Handley and Oliver Hahn and Nils Schöneberg},
      year={2026},
      eprint={2609.35661},
      archivePrefix={arXiv},
      primaryClass={astro-ph.IM},
      url={https://arxiv.org/abs/2609.35661}, 
}
```

<!-- --8<-- [end:citation] -->

## License

<!-- --8<-- [start:license] -->

modax is released under the
[MIT License](https://github.com/lawrenceberry/modax/blob/main/LICENSE).

<!-- --8<-- [end:license] -->
