HypercubeESN

Package version 2.0.2.

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 · HypercubeLCN

📄 Foundational paper: Boolean Hypercubes as a Neural Substrate (D. C. Liptak, 2026)

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.

Headline results

Primary validators — open-loop (NARMA, MC) and closed-loop free-run (Lorenz).

NARMA

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

Campaign write-up

Memory capacity (Jaeger MC)

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

MemoryCapacity

Lorenz (free-run)

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

Lorenz

Installation

pip install hypercube-esn

Pre-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.

Quick start

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}")

Examples

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.py

Onboarding demos only — easy synthetic signals, not storefront metrics. Frozen NARMA / MemoryCapacity / Lorenz numbers live in the C++ examples/ campaigns. Index: python/examples/README.md.

Features

Simple API — fit() runs warmup, collect, and batch train in one call
Hypercube dim 5–16 — N = 2^dim 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 ESN surface, 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)

Documentation

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

License

Apache-2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hypercube_esn-2.0.2.tar.gz (28.9 kB view details)

Uploaded Sep 4, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

hypercube_esn-2.0.2-cp314-cp314-win_amd64.whl (428.6 kB view details)

Uploaded Sep 4, 2026 CPython 3.14Windows x86-64

hypercube_esn-2.0.2-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (296.7 kB view details)

Uploaded Sep 4, 2026 CPython 3.14manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

hypercube_esn-2.0.2-cp314-cp314-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl (269.0 kB view details)

Uploaded Sep 4, 2026 CPython 3.14manylinux: glibc 2.26+ ARM64manylinux: glibc 2.28+ ARM64

hypercube_esn-2.0.2-cp314-cp314-macosx_13_0_x86_64.whl (258.2 kB view details)

Uploaded Sep 4, 2026 CPython 3.14macOS 13.0+ x86-64

hypercube_esn-2.0.2-cp314-cp314-macosx_13_0_arm64.whl (227.2 kB view details)

Uploaded Sep 4, 2026 CPython 3.14macOS 13.0+ ARM64

hypercube_esn-2.0.2-cp313-cp313-win_amd64.whl (414.9 kB view details)

Uploaded Sep 4, 2026 CPython 3.13Windows x86-64

hypercube_esn-2.0.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (296.5 kB view details)

Uploaded Sep 4, 2026 CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

hypercube_esn-2.0.2-cp313-cp313-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl (268.4 kB view details)

Uploaded Sep 4, 2026 CPython 3.13manylinux: glibc 2.26+ ARM64manylinux: glibc 2.28+ ARM64

hypercube_esn-2.0.2-cp313-cp313-macosx_13_0_x86_64.whl (258.1 kB view details)

Uploaded Sep 4, 2026 CPython 3.13macOS 13.0+ x86-64

hypercube_esn-2.0.2-cp313-cp313-macosx_13_0_arm64.whl (226.9 kB view details)

Uploaded Sep 4, 2026 CPython 3.13macOS 13.0+ ARM64

hypercube_esn-2.0.2-cp312-cp312-win_amd64.whl (415.0 kB view details)

Uploaded Sep 4, 2026 CPython 3.12Windows x86-64

hypercube_esn-2.0.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (296.4 kB view details)

Uploaded Sep 4, 2026 CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

hypercube_esn-2.0.2-cp312-cp312-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl (268.5 kB view details)

Uploaded Sep 4, 2026 CPython 3.12manylinux: glibc 2.26+ ARM64manylinux: glibc 2.28+ ARM64

hypercube_esn-2.0.2-cp312-cp312-macosx_13_0_x86_64.whl (258.0 kB view details)

Uploaded Sep 4, 2026 CPython 3.12macOS 13.0+ x86-64

hypercube_esn-2.0.2-cp312-cp312-macosx_13_0_arm64.whl (226.9 kB view details)

Uploaded Sep 4, 2026 CPython 3.12macOS 13.0+ ARM64

hypercube_esn-2.0.2-cp311-cp311-win_amd64.whl (412.8 kB view details)

Uploaded Sep 4, 2026 CPython 3.11Windows x86-64

hypercube_esn-2.0.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (295.0 kB view details)

Uploaded Sep 4, 2026 CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

hypercube_esn-2.0.2-cp311-cp311-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl (267.6 kB view details)

Uploaded Sep 4, 2026 CPython 3.11manylinux: glibc 2.26+ ARM64manylinux: glibc 2.28+ ARM64

hypercube_esn-2.0.2-cp311-cp311-macosx_13_0_x86_64.whl (255.1 kB view details)

Uploaded Sep 4, 2026 CPython 3.11macOS 13.0+ x86-64

hypercube_esn-2.0.2-cp311-cp311-macosx_13_0_arm64.whl (225.1 kB view details)

Uploaded Sep 4, 2026 CPython 3.11macOS 13.0+ ARM64

hypercube_esn-2.0.2-cp310-cp310-win_amd64.whl (411.4 kB view details)

Uploaded Sep 4, 2026 CPython 3.10Windows x86-64

hypercube_esn-2.0.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (293.7 kB view details)

Uploaded Sep 4, 2026 CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

hypercube_esn-2.0.2-cp310-cp310-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl (267.0 kB view details)

Uploaded Sep 4, 2026 CPython 3.10manylinux: glibc 2.26+ ARM64manylinux: glibc 2.28+ ARM64

hypercube_esn-2.0.2-cp310-cp310-macosx_13_0_x86_64.whl (253.7 kB view details)

Uploaded Sep 4, 2026 CPython 3.10macOS 13.0+ x86-64

hypercube_esn-2.0.2-cp310-cp310-macosx_13_0_arm64.whl (223.8 kB view details)

Uploaded Sep 4, 2026 CPython 3.10macOS 13.0+ ARM64

File details

Details for the file hypercube_esn-2.0.2.tar.gz.

File metadata

Download URL: hypercube_esn-2.0.2.tar.gz
Upload date: Sep 4, 2026
Size: 28.9 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hypercube_esn-2.0.2.tar.gz
Algorithm	Hash digest
SHA256	`0e8bc44646e05eb77823f2d024dfb0c164268e3028d85d8c6581cbb2a919f78f`
MD5	`aeaf59b74a53464b088b7cc5f437efa6`
BLAKE2b-256	`1ad8bf03e4d6630304dd20dce1d9999f559e89fff035d178493905417c297ec3`

Algorithm	Hash digest
SHA256	`5907014eacb221bb7755d2e566fa192277599ae918f54234bd82b94eb787fb7c`
MD5	`d354274326da1aae98eae22a145a622c`
BLAKE2b-256	`e877750ad8c1a457c236871803533d485f54dd2018516b350bbe82f283154716`

Algorithm	Hash digest
SHA256	`2b997523fe92dfc4eb26c8dc74666501003122e28d4f905a7c26d317b80967eb`
MD5	`42d0b9e275f7f71821c4a7b77809a2e0`
BLAKE2b-256	`7f8df5e0bd847d96fe439587b889e3e3c4df90b3e5a3531a39427c4462e580e4`

Algorithm	Hash digest
SHA256	`68ade76249b4eccc16dcf8b71385aadda87ce83ef32bf4c169f173c80f79f00c`
MD5	`f80021fb12398a610659493680f02a6c`
BLAKE2b-256	`8bb1253523fd9143f65fb88cbfdbcab6e5521ba7e6f878518b53cfaf788c321a`

Algorithm	Hash digest
SHA256	`700f4ef22279f4694b79cadb3f5814eee86ebe98dc1dd7838bcdf016bc147506`
MD5	`8c2ed85f1bfb6eb620045de1da0996c1`
BLAKE2b-256	`c57706e729d5f5a15689d35164df585b9c15075934d6da0b6dd4cb9909d4ce90`

Algorithm	Hash digest
SHA256	`34d3a234542401ad28467d4a70347c0a3028e2e38731759edaaa4e2b1c6f9de3`
MD5	`292401583c39d29d72dfa9b57a95e679`
BLAKE2b-256	`3ed234610a9785d471760bbade35d1d1a2a5aa89a3fd043e43fbe963fe41e24c`

Algorithm	Hash digest
SHA256	`35043b453fe1f92a0bb7fffcb04ce70a8310d7edf0a0e1da2238061206ce0955`
MD5	`f9c4374153c77853e62215857dedcd93`
BLAKE2b-256	`9054bd2de9fdb9dac2c059dd06aea21b8918e7a30afe0de04709767d01435eaf`

Algorithm	Hash digest
SHA256	`834f081c8f64ea2a943807411b8a072eedaed0fa1a8ad21d44e5ee6b1cbbf4dc`
MD5	`946d4bffad6701123ac4b0e63484bae9`
BLAKE2b-256	`e8251fa8b2bcd4631f756b305291a17d8ff42eb167c5517ef8d292e88167d163`

Algorithm	Hash digest
SHA256	`27ab46f74533fd8b0a7826e42b9b7fc21051f763d6e4a2740a8b2cd2f818f9f9`
MD5	`0e129372605ca5229fb80e06f0818d37`
BLAKE2b-256	`6581f16ed79b49dbdaf6b65c5800938e55d97a711e264fea001b64216faa261c`

Algorithm	Hash digest
SHA256	`85bce106d1d7875b1f7970e1de976a1fda7d942dfa40fc7a18bb57c9b43c9168`
MD5	`e74e18a611d0468a440619182b7f2d0f`
BLAKE2b-256	`367badc6c35600e208f5f1633d02fdc957ee9df34a2d857636aaeb6365947835`

Algorithm	Hash digest
SHA256	`876e687ca30a383c7ee8c6e01e2fba42c728e75ac8b21b5bc26a57d226a24752`
MD5	`77b6fb9db200768077710ea2e1f756a3`
BLAKE2b-256	`88035b2d1bf68660a3ca811260dcf55d8c7adbe39130a7f58d9cf5b11a602eac`

Algorithm	Hash digest
SHA256	`499955c9e20cc9ba463f6ac116f6b4544ee01551ccb95a8f8290211f8a98f647`
MD5	`c46076e475de443b410f3c2340e2735a`
BLAKE2b-256	`2de3aaaa478d9c2fccefa8afe6e4b1ba79b3dfa2dfc2f186f80afc22fc98999e`

Algorithm	Hash digest
SHA256	`fd86252e0062b486a2524f6d9caa0c434ab9ade4323c693e11caae5c7a8f9894`
MD5	`82288df8dc069fed5ecc210c37a096ed`
BLAKE2b-256	`df3d168766a0df97733161c834e850bed60674a1913ca348c0b97252b5d1b5c7`

Algorithm	Hash digest
SHA256	`47143cc856bfa9739be70c8a3c2621bb5e958602a0e8e4a6ed537aecdd49df3f`
MD5	`4c8b22b0932041208f81c2405d448036`
BLAKE2b-256	`79f5f90f285e69ba5c728b2810b452108a2572181ebcded4065539c6658aa743`

Algorithm	Hash digest
SHA256	`70896649305ddb663c5c82cd1402068a3c52f73e115eb7f4cbabff3c69f1884a`
MD5	`f5738064d02238a0243a9a0b764b2399`
BLAKE2b-256	`a27c4ceaf773f661257054664e0eff7b0fec1dfa98ec95cf82a0d62219d9fb7e`

Algorithm	Hash digest
SHA256	`71c449e25cf2d37081d124f09db0892a14435aff04bbc1d4e044cdc72900ff09`
MD5	`d356a5b8881ab6896cbf5d6a8520aeda`
BLAKE2b-256	`95ed19ae31d555c884cba38164726567999ef348215da12991f60aeea67dab2a`

Algorithm	Hash digest
SHA256	`01088ace149419ba0cee43de1e752ea3923765955fabd9280ba10a51af9ecde7`
MD5	`91a9e664fd5c292eb96b00c362a08627`
BLAKE2b-256	`db458ae86956de99474b05f24a92b0659d0c9e19cdde5b2ddcb9f37ee865b1d7`

Algorithm	Hash digest
SHA256	`ca414e48faa427a848358ffc841d3993a2ac0cd865292fb94a78f2a80d39a22c`
MD5	`43dab494a97ef3418509257f215fb997`
BLAKE2b-256	`2950d32eff698de203098658709037d3358611d52b7fd9dba8dc406a31609faf`

Algorithm	Hash digest
SHA256	`1da1a27ed5e666fbbfbd5c7707a04acc0bae54d18ce5c9c3ecc07979a0647ced`
MD5	`51e1ccf0345f1d3e9f10f99aa08d0029`
BLAKE2b-256	`76355323af4a1c6d9fcd4426cc0b36cd277cbef7bce432d55d8fbff93f01432f`

Algorithm	Hash digest
SHA256	`dda9f7b79366b9a4400407170df3bfd008c0888c512c6314ccdd9ed84689885b`
MD5	`e3db6cfd4424447eb2d2d1226e8384eb`
BLAKE2b-256	`1dc3652e0fbfdc0d5ab5db77db8e2bb880265bde838efef87cc2d2c748825ed0`

Algorithm	Hash digest
SHA256	`3103b3ff98ade22a033ac4c8cd8d35e7cbbef69fd2669316574e9627c31f3b21`
MD5	`1e35ce37c87b6e5c6d934d6d6c18b030`
BLAKE2b-256	`df83d807e249298ff640fee0134a71c937aa2dd502a8f8633235b9acfd139660`

hypercube-esn 2.0.2

HypercubeESN

Headline results

NARMA

Memory capacity (Jaeger MC)

Lorenz (free-run)

Installation

Quick start

Examples

Features

Documentation

License

Project links

Key dates

1 maintainer

GitHub Statistics

License expression

Requires

Provides Extra

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

Algorithm	Hash digest
SHA256	`270dc87700de82e2052002ea8147fa7168a8e83a59091550c42f039fff52b98e`
MD5	`bf03d7a5048af03fb7294048479dbab7`
BLAKE2b-256	`aeb0e954942f0e62cd29aca0899ebb7785da8de895a51f3b83b7138567eeab7b`

Algorithm	Hash digest
SHA256	`8391fafa463d0e42c59a8e06ada1de1448236fab9b49f0f5fe7850b466013cd1`
MD5	`1b98bd564e7544a2f8060caf817669a6`
BLAKE2b-256	`0e918aa31a0c8a5ed8f62aa53930b338ca32acd9ca9467365aedcc8ec8681e6e`

Algorithm	Hash digest
SHA256	`abf8c10b23aee24ccc5b9243ccd68aab6a9180e10e38065d9160668557db1ba4`
MD5	`3e6482894eef2526ae7c64e66f0d3a8a`
BLAKE2b-256	`ceb04a37a79cbe4ab5bed813cb45ab07699f9668590fd3008fe746f0f5a778f4`

Algorithm	Hash digest
SHA256	`ecfead39dc86f5aabaf45a1f37d9f62ef4e10d3482e27db1c88acd929740e134`
MD5	`aa6a5c31880fbbf7ded4452918a47cd7`
BLAKE2b-256	`93034a1b8f88f3a26377f288f4f52f07dcd36f7c88d607c87fdb4ad226721a34`

Algorithm	Hash digest
SHA256	`c479c5902074cd1a0d64d3ac1e5c18762bf0d19e50132c5a255d2bebd35c936a`
MD5	`ba17aae8199b967ed833b8021f557a0a`
BLAKE2b-256	`9251fc58215a4ff658b9f1ee7c92e3ca7848c0d8aa56cf85a14b10d4e948c305`