Skip to content

README.md

Latest commit

 

History

History
143 lines (104 loc) · 5.05 KB

README.md

File metadata and controls

143 lines (104 loc) · 5.05 KB
Raw

kooplearn logo

Docs CI codecov PyPI version Python versions License

kooplearn is a Python library to learn evolution operators — also known as Koopman or Transfer operators — from data. kooplearn models can:

  1. Predict the evolution of states and observables.
  2. Estimate the eigenvalues and eigenfunctions of the learned evolution operators.
  3. Compute the Dynamic Mode Decomposition of states and observables.
  4. Learn neural-network representations $x_t \mapsto \varphi(x_t)$ for evolution operators.

Why Choosing kooplearn?

  1. It is easy to use and strictly adheres to the scikit-learn API.

  2. Kernel estimators are state-of-the-art:

  3. Includes representation-learning losses (implemented both in Pytorch and JAX) to train neural-network Koopman embeddings.

  4. Offers a collection of datasets for benchmarking evolution-operator learning algorithms.

Installation

To install the core version of kooplearn:

pip

pip install kooplearn

uv

uv add kooplearn

To enable neural-network representations using kooplearn.torch or kooplearn.jax:

pip

# Torch
pip install "kooplearn[torch]"
# JAX
pip install "kooplearn[jax]"

uv

# Torch
uv add "kooplearn[torch]"
# JAX
uv add "kooplearn[jax]"

From source

For development, clone the repository and install the package with all optional extras and dependency groups:

git clone https://github.com/Machine-Learning-Dynamical-Systems/kooplearn.git
cd kooplearn
uv sync --all-extras --all-groups

With pip>=25.1, the equivalent editable install is:

python -m pip install -U pip
python -m pip install -e ".[torch,jax]" --group dev --group docs --group examples

Testing

Run the default test suite from the repository root with:

uv run pytest

After installing with pip, use:

python -m pytest

Contributing

We welcome contributions from the community. See CONTRIBUTING.md for development setup, testing, issue reports, and pull request guidance.

License

This project is licensed under the MIT License.

Main contributors

kooplearn is an joint effort between teams at the Italian Institute of Technology in Genoa and the École polytechnique in Paris. The main contributors to the project are (in alphabetical order):

  • Vladimir Kostic
  • Karim Lounici
  • Giacomo Meanti
  • Erfan Mirzaei
  • Pietro Novelli
  • Daniel Ordoñez-Apraez
  • Grégoire Pacreau
  • Massimiliano Pontil
  • Giacomo Turri

The mantainer of this repo is Pietro Novelli.

Citing kooplearn

@article{kooplearn,
title={kooplearn: A scikit-learn compatible library of algorithms for evolution operator learning},
author={Turri, Giacomo and Pacreau, Grégoire and Meanti, Giacomo and Devergne, Timothée and Ordoñez-Apraez, Daniel and Mirzaei, Erfan and Belucci, Bruno and Lounici, Karim and Kostic, Vladimir R. and Pontil, Massimiliano and Novelli, Pietro},
doi={10.21105/joss.10342},
url={https://doi.org/10.21105/joss.10342},
year={2026},
publisher={The Open Journal},
volume={11},
number={122},
pages={10342},
journal={Journal of Open Source Software},
}

We hope you find kooplearn useful for your dynamical systems analysis. If you encounter any issues or have suggestions for improvements, please don't hesitate to raise an issue. Happy coding!