Package: reservoirpy
ReservoirPy (v0.3.11) 🌀🧠Simple and flexible code for Reservoir Computing architectures like Echo State Networks (ESN).fromreservoirpy.nodesimportReservoir,Ridge,Inputdata=Input(input_dim=1)reservoir=Reservoir(100,lr=0.3,sr=1.1)readout=Ridge(ridge=1e-6)esn=data>>reservoir>>readoutforecast=esn.fit(X,y).run(timeseries)ReservoirPy is a simple user-friendly library based on Python scientific modules.
It provides aflexible interface to implement efficient Reservoir Computing(RC)
architectures with a particular focus onEcho State Networks(ESN).
Advanced features of ReservoirPy allow to improve computation time efficiency
on a simple laptop compared to basic Python implementation, with datasets of
any size.Some of its features are:offline and online training,parallel implementation,sparse matrix computation, fast spectral initialization,advanced learning rules(e.g.Intrinsic Plasticity) etc. It also makes possible
toeasily create complex architectures with multiple reservoirs(e.g.deep reservoirs),
readouts, andcomplex feedback loops.
Moreover, graphical tools are included toeasily explore hyperparameterswith the help of thehyperoptlibrary.
Finally, it includes several tutorials exploring exotic architectures
and examples of scientific papers reproduction.This library works forPython 3.8and higher.Follow @reservoirpyupdates and new releases on Twitter.Official documentation 📖Seethe official ReservoirPy's documentationto learn more about the main features of ReservoirPy, its API and the installation process. Or you can access directly theUser Guide with tutorials.Quick example of how to code a deep reservoirInstallationpipinstallreservoirpy(See below for more advanced installation options)Quick try ⚡An example on Chaotic timeseries prediction (MackeyGlass)Step 1: Load the datasetReservoirPy comes with some handy data generator able to create synthetic timeseries
for well-known tasks such as Mackey-Glass timeseries forecasting.fromreservoirpy.datasetsimportmackey_glassX=mackey_glass(n_timesteps=2000)Step 2: Create an Echo State Network......or any kind of model you wish to use to solve your task. In this simple
use case, we will try out Echo State Networks (ESNs), one of the
most minimal architecture of Reservoir Computing machines.An ESN is made of
areservoir, a random recurrent network used to encode our
inputs in a high-dimensional (non-linear) space, and areadout, a simple
feed-forward layer of neurons in charge withreading-outthe desired output from
the activations of the reservoir.fromreservoirpy.nodesimportReservoir,Ridgereservoir=Reservoir(units=100,lr=0.3,sr=1.25)readout=Ridge(output_dim=1,ridge=1e-5)We here obtain a reservoir with 100 neurons, aspectral radiusof 1.25 and
aleak rateof 0.3 (you can learn more about these hyperparameters going through
the tutorialUnderstand and optimize hyperparameters).
Here, our readout layer is just a single unit, that we will receive connections from (all units of) the reservoir.
Note that only the readout layer connections are trained.
This is one of the cornerstone of all Reservoir Computing techniques. In our
case, we will train these connections using linear regression, with a regularization
coefficient of 10-5.Now, let's connect everything using the>>operator.esn=reservoir>>readoutThat's it! Next step: fit the readout weights to perform the task we want.
We will train the ESN to make one-step-ahead forecasts of our timeseries.Step 3: Fit and run the ESNWe train our ESN on the first 500 timesteps of the timeseries, with 100 steps used to warm up the reservoir states.esn.fit(X[:500],X[1:501],warmup=100)Our ESN is now trained and ready to use. Let's run it on the remainder of the timeseries:predictions=esn.run(X[501:-1])As a shortcut, both operations can be performed in just one line!predictions=esn.fit(X[:500],X[1:501]).run(X[501:-1])Let's now evaluate its performances.Step 4: Evaluate the ESNfromreservoirpy.observablesimportrmse,rsquareprint("RMSE:",rmse(X[502:],predictions),"R^2 score:",rsquare(X[502:],predictions))Run and analyse this simple file (in the "tutorials/Simple Examples with Mackey-Glass" folder) to see a complete example of timeseries prediction with ESNs:simple_example_MackeyGlass.py (using the ESN class)pythonsimple_example_MackeyGlass.pyIf you have some issues testing some examples, have a look at theextended packages requirements in ReadTheDocs.More installation optionsTo install it, use one of the following commands:pipinstallreservoirpyorpipinstallreservoirpy==0.3.11If you want to run the Python Notebooks of thetutorialsfolder, install the packages in requirements file (warning: this may downgrade the version of hyperopt installed):pipinstall-rtutorials/requirements.txtIf you want to use the previous version 0.2.4, you can install ReservoirPy using:pipinstallreservoirpy==0.2.4If you want to enable thehyperpackage and its hyperparameter optimization helpers usinghyperopt, use:pipinstallreservoirpy[hyper]More examples and tutorials 🎓Go to the tutorial folderfor tutorials in Jupyter Notebooks.Go to the examples folderfor examples and papers with codes, also in Jupyter Notebooks.Paper with tutorialsTutorial for ReservoirPy (v0.2) can be found in thisPaper (Trouvain et al. 2020).Explore Hyper-Parameters with HyperoptA quick tutorial on how to explore hyperparameters with ReservoirPy and Hyperopt can be found in thispaper (Trouvain et al. 2020).Take a look at ouradvices and our method to explore hyperparametersfor reservoirs in ourrecent paper: (Hinaut et al 2021)HTMLHALTutorial and Jupyter Notebook for hyper-parameter explorationMore info on hyperopt:Official websitePapers and projects using ReservoirPyIf you want your paper to appear here, please contact us (see contact link below).Chaix-Eichel et al. (2022) From implicit learning to explicit representations. arXiv preprint arXiv:2204.02484.arXivPDFTrouvain & Hinaut (2021) Canary Song Decoder: Transduction and Implicit Segmentation with ESNs and LTSMs. ICANN 2021HTMLHALPDFPagliarini et al. (2021) Canary Vocal Sensorimotor Model with RNN Decoder and Low-dimensional GAN Generator. ICDL 2021.HTMLPagliarini et al. (2021) What does the Canary Say? Low-Dimensional GAN Applied to Birdsong. HAL preprint.HALPDFWhich Hype for My New Task? Hints and Random Search for Echo State Networks Hyperparameters. ICANN 2021HTMLHALPDFContactIf you have a question regarding the library, please open an Issue. If you have more general question or feedback you cancontact us on twitteror by email to xavier dot hinaut the-famous-home-symbol inria dot fr.Citing ReservoirPyTrouvain, 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.HTMLHALPDFIf 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}
}This package is developed and supported by Inria at Bordeaux, France inMnemosynegroup.Inriais a French Research Institute in Digital Sciences (Computer Science, Mathematics, Robotics, ...).