Skip to main content

A simple and flexible code for Reservoir Computing architectures like Echo State Networks.

Project description

Simple and flexible library for Reservoir Computing architectures like Echo State Networks (ESN).

PyPI version HAL PyPI - Python Version
Downloads Documentation Status Testing codecov


Google Colab iconTutorials: Open in Colab

Open book iconDocumentation: https://reservoirpy.readthedocs.io/


[!TIP] 🎉 Exciting News! We just launched a new beta tool based on a Large Language Model! 🚀 You can chat with ReservoirChat and ask anything about Reservoir Computing and ReservoirPy! 🤖💡 Don’t miss out, it’s available for a limited time! ⏳

https://chat.reservoirpy.inria.fr


Feature overview:

Moreover, graphical tools are included to easily explore hyperparameters with the help of the hyperopt library. Tutorial on Google Colab

Quick try ⚡

Installation

pip install reservoirpy

An example on chaotic timeseries prediction (Mackey-Glass)

For a general introduction to reservoir computing and ReservoirPy features, take a look at the tutorials

from reservoirpy.datasets import mackey_glass, to_forecasting
from reservoirpy.nodes import Reservoir, Ridge
from reservoirpy.observables import rmse, rsquare

### Step 1: Load the dataset

X = mackey_glass(n_timesteps=2000)  # (2000, 1)-shaped array
# create y by shifting X, and train/test split
x_train, x_test, y_train, y_test = to_forecasting(X, test_size=0.2)

### Step 2: Create an Echo State Network

# 100 neurons reservoir, spectral radius = 1.25, leak rate = 0.3
reservoir = Reservoir(units=100, sr=1.25, lr=0.3)
# feed-forward layer of neurons, trained with L2-regularization
readout = Ridge(ridge=1e-5)
# connect the two nodes
esn = reservoir >> readout

### Step 3: Fit, run and evaluate the ESN

esn.fit(x_train, y_train, warmup=100)
predictions = esn.run(x_test)

print(f"RMSE: {rmse(y_test, predictions)}; R^2 score: {rsquare(y_test, predictions)}")
# RMSE: 0.0020282; R^2 score: 0.99992

More examples and tutorials 🎓

Tutorials

Examples

For advanced users, we also showcase partial reproduction of papers on reservoir computing to demonstrate some features of the library.

Papers and projects using ReservoirPy

If you want your paper to appear here, please contact us (see contact link below).

  • ( HAL | PDF | Code ) Leger et al. (2024) Evolving Reservoirs for Meta Reinforcement Learning. EvoAPPS 2024
  • ( arXiv | PDF ) Chaix-Eichel et al. (2022) From implicit learning to explicit representations. arXiv preprint arXiv:2204.02484.
  • ( HTML | HAL | PDF ) Trouvain & Hinaut (2021) Canary Song Decoder: Transduction and Implicit Segmentation with ESNs and LTSMs. ICANN 2021
  • ( HTML ) Pagliarini et al. (2021) Canary Vocal Sensorimotor Model with RNN Decoder and Low-dimensional GAN Generator. ICDL 2021.
  • ( HAL | PDF ) Pagliarini et al. (2021) What does the Canary Say? Low-Dimensional GAN Applied to Birdsong. HAL preprint.
  • ( HTML | HAL | PDF ) Hinaut & Trouvain (2021) Which Hype for My New Task? Hints and Random Search for Echo State Networks Hyperparameters. ICANN 2021

Awesome Reservoir Computing

We also provide a curated list of tutorials, papers, projects and tools for Reservoir Computing (not necessarily related to ReservoirPy) here!:

https://github.com/reservoirpy/awesome-reservoir-computing

Contact

If you have a question regarding the library, please open an issue.

If you have more general question or feedback you can contact us by email to xavier dot hinaut the-famous-home-symbol inria dot fr.

Citing ReservoirPy

Trouvain, N., Pedrelli, L., Dinh, T. T., Hinaut, X. (2020) ReservoirPy: an efficient and user-friendly library to design echo state networks. In International Conference on Artificial Neural Networks (pp. 494-505). Springer, Cham. ( HTML | HAL | PDF )

If you're using ReservoirPy in your work, please cite our package using the following bibtex entry:

@incollection{Trouvain2020,
  doi = {10.1007/978-3-030-61616-8_40},
  url = {https://doi.org/10.1007/978-3-030-61616-8_40},
  year = {2020},
  publisher = {Springer International Publishing},
  pages = {494--505},
  author = {Nathan Trouvain and Luca Pedrelli and Thanh Trung Dinh and Xavier Hinaut},
  title = {{ReservoirPy}: An Efficient and User-Friendly Library to Design Echo State Networks},
  booktitle = {Artificial Neural Networks and Machine Learning {\textendash} {ICANN} 2020}
}

Acknowledgement


This package is developed and supported by Inria at Bordeaux, France in Mnemosyne group. Inria is a French Research Institute in Digital Sciences (Computer Science, Mathematics, Robotics, ...).

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

reservoirpy-0.3.13.post1.tar.gz (169.9 kB view details)

Uploaded Source

Built Distribution

reservoirpy-0.3.13.post1-py3-none-any.whl (209.8 kB view details)

Uploaded Python 3

File details

Details for the file reservoirpy-0.3.13.post1.tar.gz.

File metadata

  • Download URL: reservoirpy-0.3.13.post1.tar.gz
  • Upload date:
  • Size: 169.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.11.5

File hashes

Hashes for reservoirpy-0.3.13.post1.tar.gz
Algorithm Hash digest
SHA256 2a71fd26a169f6e1aa152adeb4712d0449da4903a41861c99084c4ad3efd4235
MD5 b75a6ce6679ca0e848958b345feb706e
BLAKE2b-256 430ffbdeddb8f5050912edd8b360394dd22f2048b75006696346b8fb0ed7a447

See more details on using hashes here.

File details

Details for the file reservoirpy-0.3.13.post1-py3-none-any.whl.

File metadata

File hashes

Hashes for reservoirpy-0.3.13.post1-py3-none-any.whl
Algorithm Hash digest
SHA256 4d469f229d8eb6812eb1ca47b4b64d195a28fa0c7d068e6564023311d876e996
MD5 d63083e23bd2beb40ca6531da6a80dc1
BLAKE2b-256 df58764c5367274978a3a638b58e4a5c9bb7a2c155931d4ec2c6f7e3ba63817e

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page