resvoir-ml

Instrument-grade reservoir-computing forecasters. Deterministic. Tiny. Fast.

pip install resvoir-ml

import numpy as np
from resvoir_ml import NVAR

series = np.sin(np.linspace(0, 20, 500))
model = NVAR().fit(series)
preds = model.predict(horizon=50)

That's the whole surface. No model zoo, no hyperparameter wizard, no pretraining. Eighty-four parameters on Lorenz-63. Trains in 0.1 seconds. Forecasts 1,500 steps in under 50 ms.

Why

Reservoir computing — specifically NVAR (Gauthier et al. 2021) — wins a specific wedge of the forecasting landscape that bigger methods can't reach:

• Temporal, nonlinear, sometimes chaotic dynamics
• Small-to-medium training data (200 to 20,000 samples)
• Latency-critical or parameter-critical inference

See the benchmark for the evidence: NVAR wins 19 of 21 cells against LightGBM, Transformer, TimesFM zero-shot, and a classical ARIMA baseline across Lorenz-63, Mackey-Glass, and Lorenz-96.

API

from resvoir_ml import NVAR

# Accepts numpy arrays, pandas Series, and pandas DataFrames.
# 1D or 2D. Channels in columns.
model = NVAR(k=2, s=1, p=2, ridge=2.5e-6).fit(training_series)

# Default: continues from the end of the training series.
preds = model.predict(horizon=100)

# Or supply your own warm-start history.
preds = model.predict(horizon=100, history=latest_window)

# Persistence.
model.save("forecaster.rvr")
from resvoir_ml import Forecaster
loaded = Forecaster.load("forecaster.rvr")

How this relates to existing RC libraries

reservoir-computing by Bianchi is an ESN-focused library with a strong classification and clustering emphasis. It is an excellent academic reference.

resvoir-ml is different in three ways:

• NVAR as the primary model, not ESN. NVAR has no random matrices — it is fully deterministic, has fewer parameters, and typically outperforms ESN on low-dimensional chaos.
• Forecasting-first API. Classification is not the primary use case.
• Companion products. This library is the open core of the Resvoir project, which also ships a hosted streaming API and an edge-compile target (NVAR → C header for MCU deployment).

Roadmap

• 0.1 (now) — NVAR, save / load, numpy + pandas inputs
• 0.2 — ESN with input standardization and residual readout
• 0.3 — resvoir_ml.forecast() top-level convenience that auto-picks a config from signal shape
• 0.4 — resvoir_ml.metrics module (valid prediction horizon, NRMSE per step)

License

MIT. See LICENSE.

Citation

If you use this library in research, please cite the benchmark:

Belden, Z. Resvoir Chaos Benchmark: Reservoir Computing vs Deep and Foundation Models. 2026. https://github.com/beldez01/Resvoir

And the underlying NVAR paper:

Gauthier, D. J., Bollt, E., Griffith, A., & Barbosa, W. A. S. (2021). Next generation reservoir computing. Nature Communications, 12, 5564.