Hypercube Hopfield 1984

This package is the Python surface for HypercubeHopfield1984 (import hypercube_hopfield1984). Full API reference: docs/Python_SDK.md. C++ integration guide: docs/CPP_SDK.md. Project home: github.com/dliptak001/HypercubeHopfield1984.

HypercubeHopfield1984 is Hopfield's graded associative memory, the model of J. J. Hopfield's 1984 paper, "Neurons with graded response have collective computational properties like those of two-state neurons" (Proc. Natl. Acad. Sci. USA 81, 3088–3092), built on a Boolean hypercube. Every vertex holds a floating-point state and every edge a floating-point weight, both in [−1, 1]. The caller shows the network a pattern. In training mode the network adjusts its weights so the pattern becomes a low point of its energy. In latch mode the pattern plays two roles at once: it is the starting state of the cube, and it also stays applied to every vertex for the whole settle as a steady push, Hopfield's input current. The weights pull the cube toward what they have stored while the pattern keeps pulling it back toward itself, and the network returns the state where those two pulls balance.

That balance is the point of this network. Because the pattern never stops pulling, the output is never a stored pattern looked up from a fragment; it is the input, pulled part of the way toward what the memory has seen. It is a shaper, not a recall. A stored pattern comes back nearly as it went in. A damaged one comes back repaired toward its stored form. An unknown one comes back moved toward the nearest thing the memory knows, by an amount that says how familiar it is. If you want a clean retrieval from a cue, use a modern Hopfield network; if you want a signal bent by experience and passed on, use this one.

There is one class, Hopfield, and it stays a float network throughout: nothing is ever rounded to ±1. It stands beside HypercubeHopfield, the modern (dense, softmax-over-patterns) Hopfield network in the same family, which does the retrieval this one does not.

HypercubeAI ecosystem

HypercubeCascade  ·  HypercubeCNN  ·  HypercubeESN  ·  HypercubeEtalon  ·  HypercubeHopfield  ·  HypercubeHopfield1984  ·  HypercubeLCN  ·  HypercubeWorldModel  ·  HypercubeWTF

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

HypercubeHopfield1984 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: connectivity is implicit in the vertex indices, and the neighborhood is programmable. Two vertices are joined when their indices differ in exactly distance bits, so stepping to a neighbor is one XOR with a distance-bit mask. The dimension and that one number fix the whole graph, from the hypercube at distance 1 to the middle shell at dim/2.
• Perfect homogeneity: every vertex has the same degree and the same local world, so the dynamics mean the same thing everywhere.
• Cheap navigation: each neighbor is a few bit operations on the vertex index, not a pointer chase through a stored edge list.

Each product in the family is a different architecture on that same foundation.

The network

A vertex is an integer from 0 to 2ᵈⁱᵐ − 1. Its neighbors are the vertices whose index differs from it in exactly distance bits, so at distance 1 the graph is the hypercube itself and at larger distances every vertex has C(dim, distance) neighbors. Each edge carries one weight, read from both ends.

A settle rewrites each vertex to tanh(gain · hᵥ), where the local field hᵥ is the weighted sum of its neighbors' states plus the input current, the input gain times the pattern's value at that vertex. The vertices are rewritten one popcount class at a time, in place, so every rewrite is a descent on Hopfield's energy and the settle stops at a stationary point of it. Training adds η · eᵥ · eᵤ to every edge and clamps it to [−1, 1]. The full description, with the energy, the sweep, and the measured operating points, is in docs/hopfield.md.

Installation

Preferred: install a pre-built wheel from PyPI (no compiler).

pip install hypercube-hopfield1984

import hypercube_hopfield1984 as hh
print(hh.__version__)

Package name on PyPI: hypercube-hopfield1984. Import name: hypercube_hopfield1984. Main type: hh.Hopfield.

Wheels target Python 3.10 through 3.14 on common Windows, Linux, and macOS machines. Runtime dependency: NumPy only.

From source (full repository)

To compile the extension yourself, clone this entire repository (not a minimal source-only download of the python/ folder alone; the C++ core lives next to python/). You need Python 3.10+, a C++23 compiler, and CMake ≥ 3.20.

git clone https://github.com/dliptak001/HypercubeHopfield1984.git
cd HypercubeHopfield1984/python
pip install .

On Windows with CLion's MinGW, put that compiler's bin folder (and Ninja) on your PATH, then:

pip install . --no-build-isolation --force-reinstall --no-deps

(Exact CLion paths change with the version.)

Quick start

You bring each pattern as an array of 2ᵏ floats, k ≤ dim. How you get there (pad an image, reshape a spectrum, invent a layout) is up to you. A shorter pattern repeats onto every copy of the low-k cube.

import numpy as np
import hypercube_hopfield1984 as hh

net = hh.Hopfield(dim=10, gain=0.03, sweep_budget=64, rest_tolerance=0.01,
                  eta=0.003, input_gain=20.0, distance=5)
N = net.N                                   # 1024

rng = np.random.default_rng(0)
patterns = rng.uniform(-1, 1, (50, N)).astype(np.float32)
for _ in range(50):
    for p in patterns:
        net.train(p)                        # deepen each pattern's well

latch = net.latch(patterns[0])              # (N,) float32: the settled cube
print(net.sweep_count, net.at_rest)
print(net)

net.save("memory.pkl")
loaded = hh.Hopfield.load("memory.pkl")

The operating point above (dim 10, distance 5, gain 0.03, input gain 20, η 0.003) is the measured one: a stored pattern comes back with cosine 0.987 to itself and a pattern with a quarter of its sites randomized is repaired from cosine 0.75 to 0.85. The rows for dim 11 and 12 are one rule, gain = 7.56 / degree and input gain = degree / 12.6.

Features

• One class: hypercube_hopfield1984.Hopfield is the whole product surface
• train / latch / energy: exposed one-to-one with the C++ API
• dim 1 through 31: N = 2ᵈⁱᵐ vertices; distance picks the degree, the capacity lever
• Graded throughout: states and weights are floats in [−1, 1]; nothing is rounded to ±1
• Short exposures tile: a 2ᵏ pattern repeats onto every copy of the low-k cube
• Latch record: sweep_count and at_rest say how the last settle ended
• Weights as NumPy: net.weights (settable), row-major N × degree
• Save / load: save / load (pickle: config + weights)
• NumPy float32: arrays converted for you; prefer contiguous float32
• GIL released during latch, train, energy, and a weights load

Examples

For a first try, paste the Quick start after pip install hypercube-hopfield1984. That is self-contained.

The demo script on GitHub under python/examples/ is there to open or download; it is not added to your machine by pip.

# from a clone of HypercubeHopfield1984, after: pip install hypercube-hopfield1984
python python/examples/shaper.py

Documentation

Ecosystem

• HypercubeCascade: both frozen stages in series + thin readout.
• HypercubeCNN: cube-native conv stack with shared kernels.
• HypercubeESN: echo-state / reservoir computing on streams.
• HypercubeEtalon: frozen etalon transit + thin readout.
• HypercubeHopfield: the modern Hopfield network; clean retrieval from a cue.
• HypercubeHopfield1984: Hopfield's 1984 graded memory; a shaper, not a recall.
• HypercubeLCN: the locally connected net, every weight trained.
• HypercubeWorldModel: frozen WTF encoder + trained LCN predictor and decoder.
• HypercubeWTF: frozen reservoir orbit + thin readout.

License

Apache 2.0.

Definitions