Metadata-Version: 2.4
Name: hypercube-hopfield
Version: 1.0.0
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: Modern Hopfield Associative Memory

Pattern storage and recall on Boolean hypercube graphs, with exponential
capacity and softmax attention over sparse Hamming-ball neighborhoods.

## Installation

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

## Quick Start

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

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

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

# Recall from a noisy cue
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}")
```

## Features

- **Explicit pattern storage** with exponential capacity
- **Softmax attention** over sparse Hamming-ball neighborhoods
- **Two update modes**: Sync (deterministic, GPU-portable) and Async (guaranteed energy descent)
- **Pickle support** for saving/loading networks
- **NumPy integration** with automatic float32 conversion

## Documentation

See [Python SDK Reference](https://github.com/dliptak001/HypercubeHopfield/blob/main/docs/Python_SDK.md) for the full API.
