QESN-MABe V2

April 25, 2026 · View on GitHub

Quantum-inspired Echo State Network on a 2D lattice — classical, NOT a quantum computer simulation.

QESN is a classical energy-diffusion reservoir that uses complex-valued amplitudes and a Schrödinger-inspired diffusion update. It runs on ordinary CPUs/GPUs — no quantum hardware is involved.

Earlier versions of this repo described the model as "genuine quantum mechanical evolution" or said it "runs the Schrödinger equation". That framing is retracted. The update rule is a symmetric, complex-valued Laplacian stencil with optional multiplicative decay. It is inspired by the form of the Schrödinger equation, not a rigorous simulation of it.

What this is

A 2D lattice of complex amplitudes.
A diffusion update (5-point stencil with periodic boundaries) applied for N steps.
A small Python reference implementation (src/qesn/) + a C++20 core (src/, include/).
A CLI (qesn-mabe) for synthetic simulations.
Pure-Python synthetic unit tests under tests/.

What this is NOT

Not a quantum computer simulation.
Not a variational quantum circuit.
Not running on quantum hardware.
Not a physically rigorous Schrödinger solver.
Not shipping the MABe 2022 dataset, weights, or a benchmark reproduction script.

Install

Python package (recommended)

pip install qesn-mabe

With optional extras:

pip install "qesn-mabe[arrow]"   # adds pyarrow for Parquet I/O
pip install "qesn-mabe[dev]"     # pytest + build + twine

From source:

git clone https://github.com/Agnuxo1/QESN_MABe_V2_REPO
cd QESN_MABe_V2_REPO
pip install -e ".[dev]"
pytest

C++ core (optional)

The C++ core is optional and only needed if you want to explore the original training binary.

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release

Options:

Option	Default	Effect
`QESN_WITH_CUDA`	`OFF`	Enable CUDA GPU acceleration (requires `nvcc`).
`QESN_WITH_ARROW`	`OFF`	Link Apache Arrow + Parquet.
`QESN_WITH_OPENMP`	`ON`	Enable OpenMP parallelism if available.

If Eigen3 is not found via find_package, CMake falls back to FetchContent from the upstream Eigen repo — no manual path setup required.

CLI usage

qesn-mabe info
qesn-mabe status
qesn-mabe simulate --lattice-size 64 --steps 100 --output run.json

The simulate subcommand runs a synthetic diffusion simulation (random energy injections on a fresh lattice) and writes metrics as JSON. It does not load the MABe dataset and does not produce classification labels.

Library usage

from qesn import Lattice, diffuse

lat = Lattice(width=64, height=64, coupling=0.20, decay=1.0)
lat.inject(32, 32, amount=1.0)
diffuse(lat, steps=100)
print(lat.energy(), lat.energy_map().shape)

Benchmarks

Historical README versions compared QESN against ResNet-50 + LSTM, Transformer, GCN, SlowFast, etc. with F1 numbers such as QESN F1 ≈ 0.48. Those numbers are unverified and not reproducible from this repo alone.

Full details: BENCHMARK_DISCLAIMER.md.

No benchmark numbers are claimed by this release.

Tests

Synthetic only — no dataset needed.

pytest

The suite covers the diffusion update (energy conservation, translation symmetry, validation of parameters), config round-trips, and the CLI.

License

Apache-2.0 — see LICENSE.

Author

Francisco Angulo de Lafuente — agnuxo1@gmail.com

Part of the @Agnuxo1 v1.0.0 open-source catalog (April 2026).

AgentBoot constellation — agents and research loops

AgentBoot — Conversational AI agent for bare-metal hardware detection and OS install.
autoresearch-nano — nanoGPT-based autonomous ML research loop.
The Living Agent — 16x16 Chess-Grid autonomous research agent.
benchclaw-integrations — Agent-framework adapters for the BenchClaw API.

CHIMERA / neuromorphic constellation — GPU-native scientific computing

NeuroCHIMERA — GPU-native neuromorphic framework on OpenGL compute shaders.
Holographic-Reservoir — Reservoir computing with simulated ASIC backend.
ASIC-RAG-CHIMERA — GPU simulation of a SHA-256 hash engine wired into a RAG pipeline.
ARC2-CHIMERA — Research PoC: OpenGL primitives for symbolic reasoning.
Quantum-GPS — Quantum-inspired GPU navigator (classical Eikonal solver).