Metadata-Version: 2.4
Name: hypercube-cnn
Version: 1.0.0
Summary: Python bindings for HypercubeCNN: CNN on Boolean hypercube topology
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/HypercubeCNN
Project-URL: Repository, https://github.com/dliptak001/HypercubeCNN
Project-URL: Documentation, https://github.com/dliptak001/HypercubeCNN/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

# HypercubeCNN

[![Build wheels](https://github.com/dliptak001/HypercubeCNN/actions/workflows/wheels.yml/badge.svg)](https://github.com/dliptak001/HypercubeCNN/actions/workflows/wheels.yml)

Python bindings for **HypercubeCNN** — a dependency-free convolutional neural
network whose feature map is a Boolean hypercube. Choose a dimension **DIM**; each channel then lives on
exactly `N = 2^DIM` vertices (for example DIM 6 → 64 sites, DIM 10 → 1024).
A local filter at a vertex reaches only that site and its nearest neighbors,
and every neighbor index is a single XOR on the binary address — no spatial
grid, no adjacency list, no stencil table to store. The activations stay
ordinary real-valued units (ReLU, tanh, …); only the *topology* is binary, so
capacity is power-of-two by construction and packing non-cube data is host work.

You stack local layers, train for classification or regression, and save weights
with a small architecture sidecar. Optional helpers map images onto length N;
data that already lives at `2^D` (reservoir or ESN state, fingerprints, product
features) can drive the network with no packing step.

Compared with a standard vision CNN, the shared-weight stack and end-to-end
training stay familiar — only the domain changes. A usual network slides a
window on a rectangle and pads the borders; here every site has the same
neighbors under the cube’s symmetry, with no image edge and no stencil table.
Pixels are not native: pack them onto the N sites first, then train on those
length-N inputs.

## Installation

```bash
pip install hypercube-cnn
```

Pre-built wheels for Python 3.10–3.13 on Windows (x64), Linux (x86_64,
aarch64), and macOS (x86_64, arm64). No compiler required.

### From source

```bash
git clone https://github.com/dliptak001/HypercubeCNN.git
cd HypercubeCNN
pip install .
```

Requires Python 3.10+, a C++23 compiler, and CMake ≥ 3.21. On Windows with
CLion’s bundled MinGW, put that toolchain’s `bin` (and Ninja) on `PATH`, set
`CMAKE_GENERATOR=Ninja`, and point `CC`/`CXX` at the MinGW gcc/g++ — exact
install paths change with the CLion version. Then:

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

## Quick start

```python
import numpy as np
import hypercube_cnn as hc

net = hc.HCNNConfig(
    dim=6,
    num_outputs=3,
    layers=[
        hc.LayerSpec.conv(8, bn=True),
        hc.LayerSpec.pool("max"),
        hc.LayerSpec.conv(8),
    ],
    weight_seed=1,
).build()

x = np.random.randn(net.N).astype(np.float32)  # full capacity N = 2**dim
logits = net.predict(x)
cls = net.predict_class(x)
net.train_step(x, target=0, params=hc.TrainParams(learning_rate=1e-3))
net.save("model")  # model.hcnw + model.arch.json
```

## Features

- **Core train/infer** — classification (CE) and regression (MSE); NumPy float32
- **Architecture product** — `LayerSpec` / `HCNNConfig`, export/import arch JSON
- **Model I/O** — HCNW weights + arch sidecar (C++ interop); pickle as secondary
- **Spatial pack** — `SpatialEmbedder` / `SpatialAugmenter` for H×W → length N
- **Train helpers** — `evaluate_classification` / `evaluate_regression`, `cosine_lr`
- **Contracts** — capacity `input_channels * 2**dim`; after packing, pass length-N inputs

## Documentation

Full API reference: [docs/Python_SDK.md](https://github.com/dliptak001/HypercubeCNN/blob/main/docs/Python_SDK.md)

C++ contracts: [docs/CPP_SDK.md](https://github.com/dliptak001/HypercubeCNN/blob/main/docs/CPP_SDK.md)

In-repo recipes: [examples/python/](https://github.com/dliptak001/HypercubeCNN/tree/main/examples/python)

Project repository: [github.com/dliptak001/HypercubeCNN](https://github.com/dliptak001/HypercubeCNN)

## License

Apache-2.0
