Metadata-Version: 2.5
Name: jax-hybridmodels
Version: 0.3.0
Summary: Hybrid ODE and neural models in JAX
Project-URL: Homepage, https://github.com/DanielePessina/jax-hybridmodels
Project-URL: Documentation, https://danielepessina.github.io/jax-hybridmodels/
Project-URL: Repository, https://github.com/DanielePessina/jax-hybridmodels
Project-URL: Issues, https://github.com/DanielePessina/jax-hybridmodels/issues
Author-email: Daniele Pessina <daniele.pessina18@imperial.ac.uk>
License-Expression: BSD-3-Clause
License-File: LICENSE
Keywords: diffrax,equinox,hybrid models,jax,neural ODE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
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 :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: diffrax>=0.7.0
Requires-Dist: equinox>=0.13.7
Requires-Dist: evosax>=0.2.0
Requires-Dist: flax<0.12.9,>=0.12.1
Requires-Dist: jax<0.11,>=0.10.0
Requires-Dist: jaxkan>=0.3.7
Requires-Dist: jaxlib<0.11,>=0.10.0
Requires-Dist: jaxtyping>=0.3.0
Requires-Dist: numpy>=2.3
Requires-Dist: optax>=0.2.6
Requires-Dist: optimistix>=0.1.0
Requires-Dist: rich>=13.0
Requires-Dist: scipy>=1.16
Provides-Extra: bayes
Requires-Dist: arviz-base>=1.3; (python_version >= '3.12') and extra == 'bayes'
Requires-Dist: blackjax>=1.7.1; extra == 'bayes'
Provides-Extra: examples
Requires-Dist: matplotlib>=3.10.9; extra == 'examples'
Requires-Dist: openpyxl>=3.1.5; extra == 'examples'
Requires-Dist: pandas>=2.2.3; extra == 'examples'
Requires-Dist: python-libsbml>=5.20.4; extra == 'examples'
Requires-Dist: rlax>=0.1.9; extra == 'examples'
Requires-Dist: sympy>=1.14; extra == 'examples'
Provides-Extra: pandas
Requires-Dist: pandas>=2.2.3; extra == 'pandas'
Description-Content-Type: text/markdown

# jaxhybridmodels

A JAX/Equinox library for fitting user-written ODE models whose parameters or
rate laws are learned from data. Learned quantities stay inside declared
physical bounds, experiments may be sampled at irregular times, and training
uses Optax or Evosax.

## Documentation

<https://danielepessina.github.io/jax-hybridmodels/>. Start with
[Getting started](https://danielepessina.github.io/jax-hybridmodels/guide/getting-started),
pick a modelling pattern from the [Examples](https://danielepessina.github.io/jax-hybridmodels/examples/),
and look up exact signatures in the [API reference](https://danielepessina.github.io/jax-hybridmodels/api/).

| Need | Start here |
| --- | --- |
| Understand the model contract | [Model interface](https://danielepessina.github.io/jax-hybridmodels/guide/model-interface) |
| Build irregular data | [Data and buckets](https://danielepessina.github.io/jax-hybridmodels/guide/data) |
| Choose predictors and bounds | [Predictors and bounds](https://danielepessina.github.io/jax-hybridmodels/guide/predictors) |
| Train or freeze parameters | [Training](https://danielepessina.github.io/jax-hybridmodels/guide/training) |
| Extend the library | [Custom predictors](https://danielepessina.github.io/jax-hybridmodels/guide/custom-predictors) |

## First run

The examples are plain scripts. From a checkout:

```bash
uv sync --extra examples
uv run python examples/pendulum/train_harmonic.py
```

It fits the frequency of a harmonic oscillator to noisy position data with
`HybridModel.fit`, then predicts the data and simulates a new initial
condition. The Getting started page walks through a one-oscillator version
of the same code.

## Installation

### From PyPI

```bash
uv add jax-hybridmodels
```

The distribution is `jax-hybridmodels`; the import is `jaxhybridmodels`. Add
`jax-hybridmodels[pandas]` for `PredictionResult.to_dataframe`.

### Development

```bash
uv sync --extra examples
```

This installs the package in editable mode plus the examples' extra
dependencies. Plain `uv sync` installs the library alone.

## Contributing

Run the verification checks before pushing:

```bash
uv run ruff check .                            # lint
uv run ruff format --check .                   # formatting
uv run ty check src tests examples scripts     # typecheck (needs --extra examples)
uv run pytest -q                               # test suite, about three minutes
uv run pytest -q -m slow                       # slow example tests
npm --prefix docs run docs:check               # API sync + site build
```

The first three also run as pre-commit hooks. Install them once with
`uvx pre-commit install`.

See [`docs/README.md`](./docs/README.md) for local preview, API generation,
and Pages deployment details.

## License

BSD-3-Clause. See [LICENSE](./LICENSE).
