Metadata-Version: 2.4
Name: resvoir-ml
Version: 0.1.0
Summary: Instrument-grade reservoir-computing forecasters. Deterministic, tiny, fast.
Project-URL: Homepage, https://github.com/beldez01/Resvoir
Project-URL: Documentation, https://github.com/beldez01/Resvoir#readme
Project-URL: Repository, https://github.com/beldez01/Resvoir
Project-URL: Issues, https://github.com/beldez01/Resvoir/issues
Project-URL: Benchmark, https://github.com/beldez01/Resvoir/tree/main/benchmarks
Author: Zachary Belden
License: MIT
License-File: LICENSE
Keywords: chaos,dynamical-systems,echo-state-network,forecasting,nvar,reservoir-computing,time-series
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: numpy>=1.26
Provides-Extra: dev
Requires-Dist: pandas>=2.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: pandas
Requires-Dist: pandas>=2.0; extra == 'pandas'
Description-Content-Type: text/markdown

# resvoir-ml

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

```bash
pip install resvoir-ml
```

```python
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](https://github.com/beldez01/Resvoir/tree/main/benchmarks) 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

```python
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`](https://pypi.org/project/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.
