Metadata-Version: 2.4
Name: holographic-reservoir
Version: 1.0.0
Summary: Holographic Reservoir Computing Framework — pure-Python simulation with optional ASIC hardware backend.
Author-email: Francisco Angulo de Lafuente <agnuxo1@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Agnuxo1/Holographic-Reservoir
Project-URL: Source, https://github.com/Agnuxo1/Holographic-Reservoir
Project-URL: Issues, https://github.com/Agnuxo1/Holographic-Reservoir/issues
Keywords: reservoir-computing,neuromorphic,echo-state-network,holographic,asic,simulation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Provides-Extra: hardware
Requires-Dist: requests>=2.28; extra == "hardware"
Requires-Dist: scipy>=1.10; extra == "hardware"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# Holographic Reservoir Computing Framework (Simulation + Optional ASIC Hardware)

[![PyPI](https://img.shields.io/pypi/v/holographic-reservoir.svg)](https://pypi.org/project/holographic-reservoir/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)

A pure-Python reservoir computing framework built on a bipartite expander
graph (the "Veselov layer") with a pluggable hardware backend. The default
backend is a deterministic SHA-256 based **simulation** — no network, no
ASIC, no external services. Optional AxeOS ASIC hardware is supported but
strictly opt-in.

## Install

```bash
pip install holographic-reservoir
```

Optional hardware extras:

```bash
pip install "holographic-reservoir[hardware]"
```

## Quickstart (three commands, no hardware)

```bash
holographic-reservoir info
holographic-reservoir demo
holographic-reservoir benchmark --size 200 --n 1500
```

Programmatic use:

```python
from holographic_reservoir import HolographicReservoirModel, mackey_glass

series = mackey_glass(n=1501, rng_seed=0)
u, y = series[:-1].reshape(-1, 1), series[1:]

model = HolographicReservoirModel(size=200, random_seed=0)
model.fit(u[:1000], y[:1000], washout=100)
mse = ((model.predict(u[1000:]) - y[1000:]) ** 2).mean()
print(f"MSE = {mse:.3e}")
```

## Honest scope

- **Hardware backend is optional.** The default is a pure-Python
  simulation using deterministic SHA-256 entropy; it runs anywhere Python
  3.10+ runs and needs only NumPy. The AxeOS backend is activated only
  when you pass `--hardware axeos --endpoint IP:PORT` and connects to a
  real miner only in that case.
- **The paper in `docs/papers/` is a research preprint, NOT a
  peer-reviewed IEEE publication.** Treat it as an author preprint /
  technical report. No peer-review status should be inferred from its
  formatting.
- **Research artefacts** (legacy experiment scripts, HTML drafts,
  hardware telemetry reports) are preserved in `archive/` and
  `experiments/` for transparency and are not part of the v1.0 API.

## Architecture

```
holographic_reservoir/
├── backends.py   # HardwareBackend, SimulatedASICBackend, AxeOSBackend
├── model.py      # HolographicReservoirModel + Mackey-Glass generator
├── cli.py        # demo / benchmark / info subcommands
└── core/         # Legacy VeselovLayer expander graph (backcompat shim)
```

## CLI

| Command | Purpose |
|---|---|
| `holographic-reservoir info` | Show version and backend availability. |
| `holographic-reservoir demo` | Offline Mackey-Glass demo, prints MSE. |
| `holographic-reservoir benchmark` | Mackey-Glass MSE benchmark. |

Flags (all subcommands): `--hardware {simulation,axeos}`,
`--endpoint IP:PORT`, `--seed`, `--size`, `--n`.

## Author and credits

Copyright 2026 **Francisco Angulo de Lafuente** (`agnuxo1@gmail.com`).
Released under the Apache License 2.0.

Contains legacy research code from the CHIMERA / HRC experiments by the
same author. Co-authors and collaborators credited in individual research
artefacts under `docs/papers/` retain their attribution.

## License

Apache-2.0. See [`LICENSE`](LICENSE).
