Metadata-Version: 2.4
Name: aqua-blue
Version: 0.1.5
Summary: Lightweight and basic reservoir computing library
Project-URL: Homepage, https://github.com/Chicago-Club-Management-Company/aqua-blue
License-Expression: MIT
License-File: LICENSE
Keywords: computing,forecasting,learning,machine,prediction,reservoir,series,time
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: numpy~=2.0.2
Provides-Extra: dev
Requires-Dist: hatchling~=1.27.0; extra == 'dev'
Requires-Dist: mypy~=1.13.0; extra == 'dev'
Requires-Dist: pdoc3~=0.11.5; extra == 'dev'
Requires-Dist: pytest~=8.0.2; extra == 'dev'
Requires-Dist: ruff~=0.9.4; extra == 'dev'
Provides-Extra: examples
Requires-Dist: matplotlib~=3.9.4; extra == 'examples'
Requires-Dist: scipy~=1.13.1; extra == 'examples'
Description-Content-Type: text/markdown

# aqua-blue
Lightweight and basic reservoir computing library

[![Custom shields.io](https://img.shields.io/badge/docs-brightgreen?logo=github&logoColor=green&label=gh-pages)](https://chicago-club-management-company.github.io/aqua-blue/)


[![PyPI version shields.io](https://img.shields.io/pypi/v/aqua-blue.svg)](https://pypi.python.org/pypi/aqua-blue/)
[![PyPI pyversions shields.io](https://img.shields.io/pypi/pyversions/aqua-blue.svg)](https://pypi.python.org/pypi/aqua-blue/)

## 🌊 What is aqua-blue?

`aqua-blue` is a lightweight `python` library for reservoir computing (specifically [echo state networks](https://en.wikipedia.org/wiki/Echo_state_network)) depending only on `numpy`. `aqua-blue`'s namesake comes from:

- A blue ocean of data, aka a reservoir 💧
- A very fancy cat named Blue 🐾

## 📥 Installation

`aqua-blue` is on PyPI, and can therefore be installed with `pip`:

```bash
pip install aqua-blue
```

## 📝 Quickstart

```py
import numpy as np
import aqua_blue

# generate arbitrary two-dimensional time series
# y_1(t) = cos(t), y_2(t) = sin(t)
# resulting dependent variable has shape (number of timesteps, 2)
t = np.linspace(0, 4.0 * np.pi, 10_000)
y = np.vstack((2.0 * np.cos(t) + 1, 5.0 * np.sin(t) - 1)).T

# create time series object to feed into echo state network
time_series = aqua_blue.time_series.TimeSeries(dependent_variable=y, times=t)

# normalize
normalizer = aqua_blue.utilities.Normalizer()
time_series = normalizer.normalize(time_series)

# make model and train
model = aqua_blue.models.Model(
    reservoir=aqua_blue.reservoirs.DynamicalReservoir(
        reservoir_dimensionality=100,
        input_dimensionality=2
    ),
    readout=aqua_blue.readouts.LinearReadout()
)
model.train(time_series)

# predict and denormalize
prediction = model.predict(horizon=1_000)
prediction = normalizer.denormalize(prediction)
```

## 📃 License

`aqua-blue` is released under the MIT License.

---

![Blue](https://raw.githubusercontent.com/Chicago-Club-Management-Company/aqua-blue/refs/heads/main/assets/blue.jpg)

*Blue, the cat behind `aqua-blue`.*