Metadata-Version: 2.4
Name: hypercube-hopfield
Version: 1.0.2
Summary: Python bindings for HypercubeHopfield: modern Hopfield associative memory on hypercube graphs
License-Expression: Apache-2.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Project-URL: Homepage, https://github.com/dliptak001/HypercubeHopfield
Project-URL: Repository, https://github.com/dliptak001/HypercubeHopfield
Project-URL: Documentation, https://github.com/dliptak001/HypercubeHopfield/blob/main/docs/Python_SDK.md
Requires-Python: >=3.10
Requires-Dist: numpy>=1.21
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Description-Content-Type: text/markdown

# HypercubeHopfield

**HypercubeHopfield** — modern Hopfield associative memory on a Boolean
hypercube. Neurons sit on the vertices of a dim-dimensional cube
(`N = 2^dim`). Patterns are stored **explicitly** and retrieved by
**softmax attention** over a sparse neighborhood — not collapsed into a
Hebbian weight matrix, and not full all-to-all modern-Hopfield attention
either.

**A topology you don't store.** Connectivity is the mask table of the
Hamming ball — one XOR per neighbor, no adjacency list, at any size.
Each vertex attends only inside that ball; cost scales with connections,
not with the full cube.

---

<p align="center">
  <strong>HypercubeAI ecosystem</strong><br/>
  <sub>One geometry. Topology-native intelligence.</sub>
</p>

<p align="center">
  <a href="https://github.com/dliptak001/HypercubeESN"><strong>HypercubeESN</strong></a>
  &nbsp;·&nbsp;
  <a href="https://github.com/dliptak001/HypercubeCNN"><strong>HypercubeCNN</strong></a>
  &nbsp;·&nbsp;
  <a href="https://github.com/dliptak001/HypercubeHopfield"><strong>HypercubeHopfield</strong></a>
  &nbsp;·&nbsp;
  <a href="https://github.com/dliptak001/HypercubeWTF"><strong>HypercubeWTF</strong></a>
</p>

HypercubeHopfield is an experiment in the **HypercubeAI** project — our quest
to map AI and ML strategies onto the hypercube as a computational substrate.

Why the hypercube? A few properties keep showing up — and they explain why a
frozen reservoir and a HypercubeCNN readout fit together so cleanly:

- **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:

| Product | Natural data | Role of the hypercube |
|---------|--------------|------------------------|
| **[HypercubeESN](https://github.com/dliptak001/HypercubeESN)** | Low-dim **streams** over time | Frozen **reservoir** stepped each sample; multi-slice state → HypercubeCNN readout |
| **[HypercubeCNN](https://github.com/dliptak001/HypercubeCNN)** | Static patterns on the cube | Trainable **spatial** conv/pool on the cube (no recurrent reservoir) |
| **[HypercubeHopfield](https://github.com/dliptak001/HypercubeHopfield)** | Patterns / attractors | Associative memory dynamics on the cube |
| **[HypercubeWTF](https://github.com/dliptak001/HypercubeWTF)** | Static high-dim fields (**no** intrinsic time) | Same **frozen hypercube reservoir** discipline as ESN, driven for a short orbit per sample, then HypercubeCNN on the **end state** |

---

## Installation

```bash
pip install hypercube-hopfield
```

Pre-built wheels for **Python 3.10–3.13** on Windows, Linux, and macOS.
NumPy is the only runtime dependency.

Build from source (C++23 + CMake): see the [Python SDK guide](https://github.com/dliptak001/HypercubeHopfield/blob/main/docs/Python_SDK.md).

## Quick Start

```python
import numpy as np
import hypercube_hopfield as hh

# 256 neurons (dim=8, N=2^8)
net = hh.HopfieldNetwork(dim=8, seed=42)

patterns = np.random.randn(10, net.num_vertices).astype(np.float32)
net.store_patterns(patterns)

cue = patterns[0] + np.random.randn(net.num_vertices).astype(np.float32) * 0.3
result = net.recall(cue)
print(f"Converged: {result.converged}, steps: {result.steps}")
# result.state is the cleaned recall; input cue is not modified
```

## Features

- **Explicit pattern storage** — modern Hopfield retrieval without a Hebbian weight matrix
- **Sparse Hamming-ball attention** — `reach` and `neighbor_fraction` control connectivity and cost
- **Two update modes** — Sync (default, deterministic) and Async (guaranteed energy descent)
- **Pickle / `save` / `load`** — persist config and all stored patterns
- **NumPy integration** — automatic float32 conversion; `recall` does not mutate the cue

## Documentation

- [Python SDK Reference](https://github.com/dliptak001/HypercubeHopfield/blob/main/docs/Python_SDK.md) — full API, persistence, errors
- [Project README](https://github.com/dliptak001/HypercubeHopfield) — architecture framing, C++ quick start, build
- [HopfieldNetwork architecture](https://github.com/dliptak001/HypercubeHopfield/blob/main/docs/HopfieldNetwork.md) — connectivity, energy, parameters
