Package version 2.0.1.
Python bindings for HypercubeESN — reservoir computing on a Boolean hypercube. Neurons sit on the vertices, each carrying a short delay line of its own past, wired to single-bit-flip neighbors by XOR.
Three properties follow:
- A topology you don't store. Connectivity is implicit in the vertex indices — no adjacency list.
- Hidden multi-scale structure. Full neighbor connectivity with random weights turns the cube into nested clusters — local, regional, and global at once — that nobody designed in.
- Memory you can address. Each vertex carries a delay line of its own recent past, so the reservoir remembers specific lags by construction, not echoes.
The reservoir state is a signal on that graph, not an anonymous vector. What reads it is HypercubeCNN — convolutions on the same vertices and XOR neighborhoods, not a ridge fit on a flat state and not an image CNN on a fabricated 2D grid. The pairing is topology-native: the readout consumes the reservoir with zero distortion, and the learned kernels exploit the locality that generated the dynamics. The data never leaves the hypercube it was born on.
2.0 readout upgrade. Each HCNN conv site now has an explicit self/center weight alongside its dim Hamming-1 neighbors. The change significantly improves readout quality across the board (for all tasks and dims).
HypercubeAI ecosystem
HypercubeESN · HypercubeCNN · HypercubeHopfield · HypercubeWTF · HypercubeEtalon · HypercubeCascade
HypercubeESN is an experiment in the HypercubeAI project — our quest to systematically re-implement classical neural architectures on a Boolean hypercube topology instead of Euclidean grids or random graphs. The central thesis is “topology-native intelligence”: the hypercube’s algebraic structure (vertex-transitive symmetry, Hamming geometry, bitwise addressing) can serve as a first-class computational substrate.
- A topology you don’t store — the graph is specified: connectivity is implicit in the vertex indices; with a seed and a few config scalars the whole reservoir reconstructs mathematically.
- Perfect homogeneity — every vertex has the same degree and the same local world, so local dynamics mean the same thing everywhere — no structural favorites baked in by a random graph.
- Cheap navigation — each neighbor is a few bit operations on the vertex index, not a pointer chase through a stored edge list, so walks stay arithmetic and cache-friendly.
- Topology-native pairing — the readout consumes the reservoir’s output with zero geometric distortion, and the learned kernels exploit the same locality that generated the dynamics. The data never leaves the hypercube it was born on.
Each product in the family is a different architecture on that same foundation.
Primary validators — open-loop (NARMA, MC) and closed-loop free-run (Lorenz).
tanh-wrapped orders 30 / 50 / 70; Same operating point (same dim, sr, memory depth, reservoir seed, ...) for all three orders.
| Order | Best-5 mean test NRMSE |
|---|---|
| 30 | 0.0441 |
| 50 | 0.0751 |
| 70 | 0.1251 |
Linear short-term memory (ridge on reservoir state — not HCNN). Tunable via dim, memory depth, and spectral radius.
| dim | N | Peak TotalMC |
|---|---|---|
| 5 | 32 | ~30 |
| 8 | 256 | ~250 |
| 10 | 1024 | ~820 |
| 12 | 4096 | ~1380 |
Closed-loop free-run on Lorenz-63: input-bank self-feedback (predicted
[x, y, z, x*z] re-injected as the next drive). dim 10, M = 2; VPT
threshold θ = 0.25. Best orbit VPT in Lyapunov times for three trained
seeds:
| ESN seed | Best VPT (LT) |
|---|---|
| 3079493423467196890 | 14.13 |
| 696634088797950509 | 13.00 |
| 7934791766227647176 | 10.67 |
pip install hypercube-esnPre-built wheels for Python 3.10–3.14 on Windows (x64), Linux (x86_64, aarch64), and macOS (x86_64, arm64). No compiler required for wheels.
import numpy as np
import hypercube_esn as he
signal = np.sin(np.linspace(0, 20 * np.pi, 2000)).astype(np.float32)
esn = he.ESN(dim=7, seed=73895) # explicit seed (defaults match C++ ReservoirConfig)
esn.fit(signal, warmup=200)
print(f"R² = {esn.r2():.6f}")
print(f"NRMSE = {esn.nrmse():.6f}")Runnable Python hosts (public API only — no CMake / no C++ example binaries).
Scripts live in the git tree under
python/examples/;
they are not installed by the PyPI wheel.
| Script | |
|---|---|
| basic_prediction.py | Next-step sine prediction (fit → R² / NRMSE) |
| classification.py | Binary sign classification (accuracy) |
# clone HypercubeESN, then from the repo root:
pip install hypercube-esn
python python/examples/basic_prediction.py
python python/examples/classification.pyOnboarding demos only — easy synthetic signals, not storefront metrics. Frozen
NARMA / MemoryCapacity / Lorenz numbers live in the C++
examples/
campaigns. Index:
python/examples/README.md.
- Simple API —
fit()runs warmup, collect, and batch train in one call - Hypercube dim 5–16 — N = 2dim neurons (32…65,536); delay-line depth M
- HCNN readout (self tap) — conv on the hypercube with K = dim + 1 (neighbors + center); 2.0 upgrade vs neighbor-only kernels; not ridge alone
- Multi-slice readout — optional B ages packed into the readout (
readout_slices) - Multi-input — channels map to contiguous vertex blocks
- Closed-loop drive — external feedback channels +
reservoir_step - Regression & classification — same
ESNsurface, task-selected head - Streaming — online
train_step/train_step_batch - Persistence — pickle,
save/load, optional HCNW export - Wheels — Python 3.10–3.14 on Windows, Linux, macOS (no local C++ toolchain)
| Doc | |
|---|---|
| Python SDK | API reference (fit, streaming, config, pickle) |
| Python examples | Runnable hosts (git tree; not in the wheel) |
| NARMA campaign | Open-loop validator (N30 / N50 / N70) |
| Project README | Architecture and C++ side |
| C++ SDK | Native library |
Repository: github.com/dliptak001/HypercubeESN
Apache-2.0