HypercubeCNN

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.

HypercubeAI ecosystem
_{One geometry. Topology-native intelligence.}

HypercubeESN · HypercubeCNN · HypercubeHopfield · HypercubeWTF

HypercubeCNN 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	Low-dim streams over time	Frozen reservoir stepped each sample; multi-slice state → HypercubeCNN readout
HypercubeCNN	Static patterns on the cube	Trainable spatial conv/pool on the cube (no recurrent reservoir)
HypercubeHopfield	Patterns / attractors	Associative memory dynamics on the cube
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

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

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:

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

Quick start

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

C++ contracts: docs/CPP_SDK.md

In-repo recipes: examples/python/

Project repository: github.com/dliptak001/HypercubeCNN

License

Apache-2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hypercube_cnn-1.0.4.tar.gz (174.3 kB view details)

Uploaded Aug 7, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

hypercube_cnn-1.0.4-cp313-cp313-win_amd64.whl (448.1 kB view details)

Uploaded Aug 7, 2026 CPython 3.13Windows x86-64

hypercube_cnn-1.0.4-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (297.3 kB view details)

Uploaded Aug 7, 2026 CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

hypercube_cnn-1.0.4-cp313-cp313-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl (268.1 kB view details)

Uploaded Aug 7, 2026 CPython 3.13manylinux: glibc 2.26+ ARM64manylinux: glibc 2.28+ ARM64

hypercube_cnn-1.0.4-cp313-cp313-macosx_13_0_x86_64.whl (278.9 kB view details)

Uploaded Aug 7, 2026 CPython 3.13macOS 13.0+ x86-64

hypercube_cnn-1.0.4-cp313-cp313-macosx_13_0_arm64.whl (249.3 kB view details)

Uploaded Aug 7, 2026 CPython 3.13macOS 13.0+ ARM64

hypercube_cnn-1.0.4-cp312-cp312-win_amd64.whl (448.1 kB view details)

Uploaded Aug 7, 2026 CPython 3.12Windows x86-64

hypercube_cnn-1.0.4-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (296.9 kB view details)

Uploaded Aug 7, 2026 CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

hypercube_cnn-1.0.4-cp312-cp312-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl (268.2 kB view details)

Uploaded Aug 7, 2026 CPython 3.12manylinux: glibc 2.26+ ARM64manylinux: glibc 2.28+ ARM64

hypercube_cnn-1.0.4-cp312-cp312-macosx_13_0_x86_64.whl (278.8 kB view details)

Uploaded Aug 7, 2026 CPython 3.12macOS 13.0+ x86-64

hypercube_cnn-1.0.4-cp312-cp312-macosx_13_0_arm64.whl (249.2 kB view details)

Uploaded Aug 7, 2026 CPython 3.12macOS 13.0+ ARM64

hypercube_cnn-1.0.4-cp311-cp311-win_amd64.whl (444.7 kB view details)

Uploaded Aug 7, 2026 CPython 3.11Windows x86-64

hypercube_cnn-1.0.4-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (295.8 kB view details)

Uploaded Aug 7, 2026 CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

hypercube_cnn-1.0.4-cp311-cp311-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl (267.0 kB view details)

Uploaded Aug 7, 2026 CPython 3.11manylinux: glibc 2.26+ ARM64manylinux: glibc 2.28+ ARM64

hypercube_cnn-1.0.4-cp311-cp311-macosx_13_0_x86_64.whl (274.1 kB view details)

Uploaded Aug 7, 2026 CPython 3.11macOS 13.0+ x86-64

hypercube_cnn-1.0.4-cp311-cp311-macosx_13_0_arm64.whl (246.7 kB view details)

Uploaded Aug 7, 2026 CPython 3.11macOS 13.0+ ARM64

hypercube_cnn-1.0.4-cp310-cp310-win_amd64.whl (443.9 kB view details)

Uploaded Aug 7, 2026 CPython 3.10Windows x86-64

hypercube_cnn-1.0.4-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (295.6 kB view details)

Uploaded Aug 7, 2026 CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

hypercube_cnn-1.0.4-cp310-cp310-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl (267.3 kB view details)

Uploaded Aug 7, 2026 CPython 3.10manylinux: glibc 2.26+ ARM64manylinux: glibc 2.28+ ARM64

hypercube_cnn-1.0.4-cp310-cp310-macosx_13_0_x86_64.whl (272.6 kB view details)

Uploaded Aug 7, 2026 CPython 3.10macOS 13.0+ x86-64

hypercube_cnn-1.0.4-cp310-cp310-macosx_13_0_arm64.whl (245.4 kB view details)

Uploaded Aug 7, 2026 CPython 3.10macOS 13.0+ ARM64

File details

Details for the file hypercube_cnn-1.0.4.tar.gz.

File metadata

Download URL: hypercube_cnn-1.0.4.tar.gz
Upload date: Aug 7, 2026
Size: 174.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hypercube_cnn-1.0.4.tar.gz
Algorithm	Hash digest
SHA256	`d8da682612d430a65e3d62cf45f1749c32fe4d0059ef625fbc3a329b0d3e793d`
MD5	`88bbb9b4f550d29a0ebfb68ec29a4598`
BLAKE2b-256	`0dde73e9835228d826f11eb7a274a1f34a6883b5d9bc1c0e5456ce62e943c080`

Algorithm	Hash digest
SHA256	`a87569de9785944c328e98b0505a8456509c7e505f76e080495b3be91133a469`
MD5	`04022198ad45d1ea307e2cf940d31f3b`
BLAKE2b-256	`34659e63fe0c3856c84239344b376c360f0b5a40e297c0540caf4c961844497e`

Algorithm	Hash digest
SHA256	`5b27d60a90f4336c22e06b50427a5b4fae123890aed9907416523685a449b3ce`
MD5	`fbcf5d86c1a990754c028ee5df818173`
BLAKE2b-256	`5f20300132948a85496336188128e0e11fa59d033d3c0c0d83819c60feb5c90d`

Algorithm	Hash digest
SHA256	`a2ee438c4e27d92078816bc15d52942d525856459ec95b39a8a6580bfe329a84`
MD5	`0727c43d811284cf22ad355ab95a79f6`
BLAKE2b-256	`9a2c9febf1c79049cd7401b658c4af3d3e6e68f757891b8c58cc3d5787aa853b`

Algorithm	Hash digest
SHA256	`5d6c6470b2a5efca5cdc49cba1fab7e7276b1d51edd606eaa8de001e1461b58f`
MD5	`af6c3282cb2dc625f9f9f592e87a525d`
BLAKE2b-256	`5b1e008f0777585da172a7bbbaf29c8d47f9863050eb76e60e4648784175062b`

Algorithm	Hash digest
SHA256	`a209273b8e621e8863f056d26471686f46e8096b57f5a93d3ab8dbad0ac93dab`
MD5	`4efcf9e395bfe44ba0480e9bdef7c8e7`
BLAKE2b-256	`3579877e731098b83d6fbe310ee44f4dde9edd411ee461acb687107f861281d9`

Algorithm	Hash digest
SHA256	`29d6f6da7b06f0693da38ccb389741c9788bb3f53219c0df1d6b49d508e9fcbd`
MD5	`6e46093c4eb2509ffd488c09d8b67cf7`
BLAKE2b-256	`093a3287d9b34fa8599e3a008d27456165557fb98d1798c06ac5a14a7da2e771`

Algorithm	Hash digest
SHA256	`76d1e38da6152d142a1ed89d57b78fc31eb247d05f462f9b58d32c49f50ac336`
MD5	`02afb92c4175e9d4adb438fe9bdb6eda`
BLAKE2b-256	`697e11653475f3898bc8d28349a0a83895c413c00a89d9b2f67c262205e96243`

Algorithm	Hash digest
SHA256	`a260c896ca35d6e113ae275fedfa059170f3a5a7a4c038db710c3b64ce6a0f32`
MD5	`95f23a9f885908b219975b350d468461`
BLAKE2b-256	`4aa1d144ab35998b06f72dd459450d169d5442882207f0001e89286dcc3cfa5e`

Algorithm	Hash digest
SHA256	`35c7a52a3ea1146b44831a44d1b389cfec1dc85d8d79fff70468d1b3079ab7fa`
MD5	`38850cc0f42f9ef7a7457f20957fbceb`
BLAKE2b-256	`49236713eee205ba214a128b835977d0223cd0235b24912164f118efce5a8cce`

Algorithm	Hash digest
SHA256	`0ac6d4385411ed02e95bf7b6e165c29b70c7e6339eedf3f4c1f80446413bad4c`
MD5	`528b4a7eb45dbd757a74e0a98c503960`
BLAKE2b-256	`7ebc9a9a8d458ab5b1475959c873ccf96a7d095a4407ce88f481b53ac743e2e9`

Algorithm	Hash digest
SHA256	`28f2fbdc942933a07ca557fca56917244b55900eb3f9e35e3ce7ee66e63ee65c`
MD5	`597c3db24014e168a96e95372cd5f0f4`
BLAKE2b-256	`071b81260dea011a74e5f4d7cb6a9f3a39840fc70f70425c300983ff787adcae`

Algorithm	Hash digest
SHA256	`7c0c936beeec95cce2cad6fe044f23284b077e2a850165e2e47f9c8948ae0b8f`
MD5	`f6b64f37dee2a99b5a3620fc1c3c18ab`
BLAKE2b-256	`826682b23b17b964dc921313c5425c7a7ac5c48598c16deacc8ce4967871baa9`

Algorithm	Hash digest
SHA256	`1e8c073e5feb8d1e9c9a701c769e324bc7779f14351bc972a812bba0d5aa4228`
MD5	`941c8dc09c50fef9602642d5258ee96d`
BLAKE2b-256	`9eb82a055a4a1530c0f28246b28eb81bbd6ba77168ff6d098341a3379b1f5bcb`

Algorithm	Hash digest
SHA256	`16ed84d43d83b00aaaf3cfc6436ae5a9c462f57192dcf12f3d35c1be2218b722`
MD5	`931665b48965b7ab225eebf5108cb924`
BLAKE2b-256	`64728662a776aed999732376c2874ca0bef98848b23eeb9ce938dc35b717e430`

Algorithm	Hash digest
SHA256	`33f67f58d9330730470923ff6f7d8173fa97418bd3bdb738c061f4d2a834f864`
MD5	`f745129e81c6c49438beb3bfaac196a7`
BLAKE2b-256	`27476609e9eddeee2d6f3beb7ba1a0e7c0652deef36cbe284bca1b403215929e`

Algorithm	Hash digest
SHA256	`460450be7e9eac9103fc9ff78a2aeb375f346a03048aaa7f70b617ad94c7afd9`
MD5	`e35cc6a8a88edb32f05051dafbb3ce86`
BLAKE2b-256	`b31bc62f0b875cc6bc37745e443697103f4bd74ba9bb4ae683204f5c8b4bfa26`

Algorithm	Hash digest
SHA256	`507cd78ddd37bae5b9c3bb7c8e7a5a24efd81c984b4e20789bef259f7f40d65e`
MD5	`8c8aa22025013590ef97f1566d26e955`
BLAKE2b-256	`fdc875dc555d70a50fb1ace70e95d670a274d211437176a5860bee0a0a2cd1b6`

Algorithm	Hash digest
SHA256	`ce262147823b11327eaa655b2ab80c387b81b246770d66d1a4a988af46482aa4`
MD5	`3cc35dc616a76ac3d0f8ee2f3ca7f77e`
BLAKE2b-256	`dec29448bcb5a3ae63c9d4e0a5a78d312a8fc669a914b9a7526d1baac621e734`

Algorithm	Hash digest
SHA256	`451ac513c92517a48c96030a56d051f4393a4ba5f9b27f75ca2da31f864e58d8`
MD5	`3f7559a55cfe7727c50040de65ae558b`
BLAKE2b-256	`39fcaba405fd028c8e76ec073cac398f1ece953e32b776baea0f1a5d8d70216a`

Algorithm	Hash digest
SHA256	`2a5ca5bffa357ebcb9805e193934c6cd7f6c92db9ce1fb3eb95799a37936a267`
MD5	`596e93da91f4fa62a7722124cc734855`
BLAKE2b-256	`6f57bf671ee854ca64ac536122fc270f7b4148e4c5c48d89007d5f12f76ef222`

hypercube-cnn 1.0.4

HypercubeCNN

Installation

From source

Quick start

Features

Documentation

License

Project links

Key dates

1 maintainer

GitHub Statistics

License expression

Requires

Provides Extra

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details