hypercube-cascade 1.0.0__tar.gz

hypercube_cascade-1.0.0/CMakeLists.txt

@@ -0,0 +1,88 @@
+cmake_minimum_required(VERSION 3.20)
+project(HypercubeCascadePython LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 23)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# ── pybind11 ──
+find_package(pybind11 CONFIG REQUIRED)
+
+# ── Optimization flags (match main project / sibling python builds) ──
+# HYPERCUBE_ARCH controls -march. Defaults to "native" for local dev builds.
+# cibuildwheel overrides to "x86-64-v2" (x86_64) or "none" (ARM, MSVC).
+set(HYPERCUBE_ARCH "native" CACHE STRING "Target architecture for -march (native, x86-64-v2, none)")
+
+if(MSVC)
+    add_compile_options(/O2 /fp:fast)
+else()
+    add_compile_options(-O3 -ffast-math)
+    if(NOT HYPERCUBE_ARCH STREQUAL "none")
+        if(HYPERCUBE_ARCH STREQUAL "native")
+            add_compile_options(-march=native -mtune=native)
+        else()
+            add_compile_options(-march=${HYPERCUBE_ARCH} -mtune=generic)
+        endif()
+    endif()
+    add_compile_options(-Wall -Wextra -Wno-unknown-pragmas)
+endif()
+
+# ── Core sources compiled directly into the module (PIC required) ──
+set(CORE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/..")
+set(CORE_SOURCES
+    ${CORE_DIR}/Exciter.cpp
+    ${CORE_DIR}/Reservoir.cpp
+    ${CORE_DIR}/Readout.cpp
+    ${CORE_DIR}/Cascade.cpp
+)
+
+# ── HypercubeCNN dependency ──
+# Vendored read-only snapshot at ../third_party/HypercubeCNN (see VENDORED.md).
+# No sibling checkout, no pre-built .a, no network fetch — offline & version-pinned.
+# third_party/ lies outside this source tree, so a binary dir arg is required.
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../third_party/HypercubeCNN
+                 ${CMAKE_BINARY_DIR}/HypercubeCNN-build)
+set(HCNN_LIBS HypercubeCNNCore)
+
+# ── Package version (single source: hypercube_cascade/_version.py) ──
+set(_HCAS_VERSION_FILE "${CMAKE_CURRENT_SOURCE_DIR}/hypercube_cascade/_version.py")
+set(HYPERCUBE_CASCADE_VERSION "")
+file(STRINGS "${_HCAS_VERSION_FILE}" _HCAS_VERSION_LINES)
+foreach(_line IN LISTS _HCAS_VERSION_LINES)
+    # Strip CR (Windows) and match: __version__ = "x.y.z"
+    string(REPLACE "\r" "" _line "${_line}")
+    if(_line MATCHES "^__version__[ \t]*=[ \t]*\"([^\"]+)\"")
+        set(HYPERCUBE_CASCADE_VERSION "${CMAKE_MATCH_1}")
+        break()
+    endif()
+endforeach()
+if(HYPERCUBE_CASCADE_VERSION STREQUAL "")
+    message(FATAL_ERROR
+        "Could not parse __version__ from hypercube_cascade/_version.py")
+endif()
+message(STATUS "hypercube_cascade version: ${HYPERCUBE_CASCADE_VERSION}")
+
+# ── Build the Python extension module ──
+# HypercubeCNNCore's PUBLIC include dir propagates through the link below.
+pybind11_add_module(_core bindings.cpp ${CORE_SOURCES})
+target_include_directories(_core PRIVATE ${CORE_DIR})
+target_link_libraries(_core PRIVATE ${HCNN_LIBS})
+target_compile_definitions(_core PRIVATE
+    "HYPERCUBE_CASCADE_VERSION=\"${HYPERCUBE_CASCADE_VERSION}\"")
+
+# ── Linking ──
+if(MINGW)
+    # Static libgcc/libstdc++ keep the .pyd free of those DLLs. Do NOT static-link
+    # winpthread: mingw-w64 15.2.0's libwinpthread.a references __intrinsic_setjmpex
+    # and fails at link (same constraint as the top-level CMakeLists.txt exes).
+    # Posix-model MinGW still needs libwinpthread-1.dll at runtime — ship the DLL
+    # from THIS toolchain (stale copies miss symbols like nanosleep64).
+    target_link_options(_core PRIVATE -static-libgcc -static-libstdc++)
+    find_file(WINPTHREAD_DLL libwinpthread-1.dll PATHS ENV PATH NO_DEFAULT_PATH)
+    if(WINPTHREAD_DLL)
+        install(FILES ${WINPTHREAD_DLL} DESTINATION hypercube_cascade)
+    endif()
+endif()
+
+# ── Install into the hypercube_cascade package directory ──
+install(TARGETS _core DESTINATION hypercube_cascade)

hypercube_cascade-1.0.0/PKG-INFO

@@ -0,0 +1,366 @@
+Metadata-Version: 2.4
+Name: hypercube-cascade
+Version: 1.0.0
+Summary: Python bindings for HypercubeCascade: frozen etalon transit + frozen reservoir orbit + HypercubeCNN on end state
+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 :: Python :: 3.14
+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/HypercubeCascade
+Project-URL: Repository, https://github.com/dliptak001/HypercubeCascade
+Project-URL: Documentation, https://github.com/dliptak001/HypercubeCascade/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
+
+# HypercubeCascade
+
+**HypercubeCascade** is for high-dimensional data that has no natural clock —
+spectra, sensor frames, packed images, stills. Those are the same kinds of
+static fields people usually feed a spatial CNN, an MLP, or a similar
+feed-forward stack. HypercubeCascade puts **two frozen hypercube
+preprocessors in series** in front of the CNN: first an **etalon transit**
+(the [HypercubeEtalon](https://github.com/dliptak001/HypercubeEtalon)
+mechanism — a deterministic wave swept across every vertex/antipode cavity of
+the cube), then a short **reservoir orbit** (the
+[HypercubeWTF](https://github.com/dliptak001/HypercubeWTF) mechanism — a
+frozen recurrent core driven by re-addressing the same field for T synthetic
+passes). A small
+[HypercubeCNN](https://github.com/dliptak001/HypercubeCNN) head trains on the
+**end state only**. The CNN never sees the original field — it sees what the
+transit and the orbit leave behind.
+
+That is the product idea: take a static field, pass it through two different
+frozen nonlinearities, and train a spatial readout on what remains. The aim is
+a preprocessor effective enough that the readout can be a single convolutional
+layer with a single channel and no pooling.
+
+This package is the **Python** surface for that product
+(`import hypercube_cascade`).
+Full API reference: **[docs/Python_SDK.md](https://github.com/dliptak001/HypercubeCascade/blob/main/docs/Python_SDK.md)**.
+C++ integration guide: **[docs/CPP_SDK.md](https://github.com/dliptak001/HypercubeCascade/blob/main/docs/CPP_SDK.md)**.
+Project home: **[github.com/dliptak001/HypercubeCascade](https://github.com/dliptak001/HypercubeCascade)**.
+
+---
+
+<p align="center">
+  <strong>HypercubeAI ecosystem</strong><br/>
+</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>
+  &nbsp;·&nbsp;
+  <a href="https://github.com/dliptak001/HypercubeEtalon"><strong>HypercubeEtalon</strong></a>
+  &nbsp;·&nbsp;
+  <a href="https://github.com/dliptak001/HypercubeCascade"><strong>HypercubeCascade</strong></a>
+</p>
+
+HypercubeCascade 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** — the graph is specified: connectivity is
+  implicit in the vertex indices; with a seed and a few config scalars the whole
+  preprocessor 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 preprocessor 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.
+
+---
+
+## What is HypercubeCascade?
+
+[HypercubeEtalon](https://github.com/dliptak001/HypercubeEtalon) preprocesses a
+static field with **one etalon transit**.
+[HypercubeWTF](https://github.com/dliptak001/HypercubeWTF) preprocesses a
+static field with **one reservoir orbit**. HypercubeCascade is **both of them,
+in series, on one cube**: the transit output, times a gain, becomes the orbit
+drive, and the orbit's end state, times a second gain, is what the CNN head
+trains on.
+
+In classical reservoir computing (and in both single-stage siblings):
+
+- Preprocessor weights are **frozen**
+- Only a **readout** is trained
+- Nonlinear dynamics expand and mix the drive into a rich state
+
+Whether the two-stage pipeline has **real product value** is still an open
+question. Early studies suggest the second stage adds filtering on top of what
+the first stage already adds (see
+[Early observations](#early-observations-exploratory)).
+
+---
+
+## Pipeline
+
+```text
+x  (your length-N field — already on the cube, no natural time)
+    │
+    ▼
+ frozen etalon transit (one wave over every cavity)
+    │
+    ▼
+ × interstage_scale → frozen reservoir orbit (T re-addressed passes)
+    │
+    ▼
+ end-of-orbit state × readout_scale → HypercubeCNN → logits / values
+```
+
+- Cube size from **dim** (N = 2<sup>dim</sup>; dim 5…12). One dim serves all
+  three stages.
+- Only the readout trains.
+- Everyday loop in this package:
+  `collect_batch` → `train` → `predict` / `predict_class`,
+  or one-shot `fit` (collect + train).
+
+Unlike HypercubeESN’s Python API, there is no stream of small samples over real
+time and no next-step `fit` on a 1D signal. Each sample is one full field; the
+“time” is the short synthetic orbit; the CNN only ever sees the state at the end.
+
+Full method list and knobs:
+**[docs/Python_SDK.md](https://github.com/dliptak001/HypercubeCascade/blob/main/docs/Python_SDK.md)**.
+
+---
+
+## Early observations (exploratory)
+
+On the MNIST white-noise study (train clean, test with Gaussian field noise),
+the cascade behaves as a near-unity passthrough on clean fields and pulls
+ahead of both the etalon-only path and the pack-only bypass from σ = 0.3
+upward. On a Raman baseline-extraction regression it matches the etalon-only
+sibling to within ~1% RMSE while training with a visibly more stable epoch
+profile. The write-ups have the details and how we ran them:
+
+| Document | Question |
+|----------|----------|
+| [WhiteNoiseFilter.md](https://github.com/dliptak001/HypercubeCascade/blob/main/examples/mnist/WhiteNoiseFilter.md) | Noisy test fields: do two stages help vs one stage vs pack-only → CNN? |
+| [RamanBaselineExtraction/README.md](https://github.com/dliptak001/HypercubeCascade/blob/main/examples/RamanBaselineExtraction/README.md) | Baseline regression: cascade vs etalon-only, overlays and training profiles |
+
+The MNIST study uses small cubes because they are handy to pack and run, not
+because we are chasing digit accuracy. A more rigorous study is still needed
+before treating any of those results as settled. You can reproduce the same
+ideas from Python with this package (pack fields yourself, then collect,
+train, and predict). The original write-ups and C++ demos that produced the
+numbers live under
+[`examples/`](https://github.com/dliptak001/HypercubeCascade/tree/main/examples).
+
+---
+
+## Installation
+
+**Preferred:** install a pre-built wheel from PyPI (no compiler).
+
+```bash
+pip install hypercube-cascade
+```
+
+```python
+import hypercube_cascade as hc
+print(hc.__version__)
+```
+
+Package name on PyPI: **`hypercube-cascade`**. Import name:
+**`hypercube_cascade`**. Main type: **`hc.Cascade`**.
+
+Wheels target Python 3.10–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 and
+vendored HypercubeCNN live next to `python/`). You need Python 3.10+, a C++23
+compiler, and CMake ≥ 3.20.
+
+```bash
+git clone https://github.com/dliptak001/HypercubeCascade.git
+cd HypercubeCascade/python
+pip install .
+```
+
+On Windows with CLion’s MinGW, put that compiler’s `bin` folder (and Ninja) on
+your `PATH`, then:
+
+```bash
+pip install . --no-build-isolation --force-reinstall --no-deps
+```
+
+(Exact CLion paths change with the version.) Step-by-step toolchain notes:
+[docs/Python_SDK.md](https://github.com/dliptak001/HypercubeCascade/blob/main/docs/Python_SDK.md).
+
+---
+
+## Quick start
+
+You bring each sample as a length-**N** float array (N = 2<sup>dim</sup>). How
+you get there — pad an image, reshape a spectrum, invent a layout — is up to
+you. This package does not pack 784 pixels or 300 bins for you.
+
+Shapes that matter:
+
+| Array | Shape | Notes |
+|-------|-------|-------|
+| `fields` | `(count, N)` | one length-N field per row |
+| `labels` (classification) | `(count,)` | integer class indices |
+| `targets` (regression) | `(count, num_outputs)` | float targets |
+
+```python
+import numpy as np
+import hypercube_cascade as hc
+
+dim = 7
+N = 2**dim
+rng = np.random.default_rng(0)
+fields = rng.standard_normal((200, N), dtype=np.float32)
+labels = rng.integers(0, 4, size=200)
+
+cas = hc.Cascade(
+    dim=dim,
+    exciter_subcube_dim=5,
+    history_depth=4,
+    T=50,
+    ic_seed=2,
+    readout_num_outputs=4,
+    readout_task="classification",
+    readout_epochs=80,
+)
+cas.fit(fields, labels)  # collect_batch + train
+
+print(cas.N, cas.T, cas.num_collected)
+print(f"train sanity check: {cas.accuracy_on_collected():.3f}")
+print(cas.predict_class(fields[0]), cas.predict(fields[0]).shape)
+
+cas.save("model.pkl")
+loaded = hc.Cascade.load("model.pkl")
+```
+
+### Step by step (same loop, more control)
+
+```python
+cas = hc.Cascade(
+    dim=7,
+    exciter_subcube_dim=5,
+    readout_num_outputs=4,
+    readout_task="classification",
+)
+cas.collect_batch(fields_train, labels_train)
+cas.train()
+logits = cas.predict(fields_test[0])       # (num_outputs,) float32
+cls = cas.predict_class(fields_test[0])    # int
+test_acc = cas.accuracy(fields_test, labels_test)  # held-out, fresh maps
+```
+
+For regression, set `readout_task="regression"` and pass float targets instead
+of class labels. Then use `r2_on_collected()` / `r2(fields, targets)` the same
+way.
+
+`accuracy_on_collected` and `r2_on_collected` only look at the samples you
+already trained on — they are a quick sanity check, not a test score. For real
+evaluation, hold fields out and call `accuracy` / `r2` (or `predict` /
+`predict_class` yourself).
+
+---
+
+## Features
+
+- **One class** — `hypercube_cascade.Cascade` is the whole product surface
+- **Map loop** — `collect` / `collect_batch` → `train` →
+  `predict` / `predict_class`
+- **`fit`** — clear, collect, and train when your arrays are ready
+- **dim 5–12** — field length N = 2<sup>dim</sup>; one dim for all three
+  stages; orbit length `T`; etalon face `exciter_subcube_dim`
+- **Two gains** — `interstage_scale` (transit → orbit) and `readout_scale`
+  (orbit → readout)
+- **Classification or regression** — `readout_task` fixed at construction
+- **Held-out scoring** — `accuracy(fields, labels)` / `r2(fields, targets)`
+  map fresh in bulk
+- **Bulk calls can parallelize** — `collect_threads` (0 = auto)
+- **Inspect a map** — `run(x)` then `last_features()`, plus per-stage probes
+  `last_exciter()` / `last_interstage()` / `last_reservoir()` for gain tuning
+- **Save / load** — `save` / `load` (pickle: config + readout weights;
+  collected samples are not stored). Optional `save_readout_hcnn_model` /
+  `load_readout_hcnn_model` for portable HCNW + arch JSON
+- **NumPy float32** — arrays converted for you; prefer contiguous float32
+
+---
+
+## Examples
+
+For a first try, paste the [Quick start](#quick-start) after
+`pip install hypercube-cascade`. That is self-contained.
+
+If you want a longer walk-through, the demo scripts on GitHub under
+[`python/examples/`](https://github.com/dliptak001/HypercubeCascade/tree/main/python/examples)
+are there to open or download — they are not added to your machine by pip.
+
+| Script | What it is for |
+|--------|----------------|
+| [synthetic_classification.py](https://github.com/dliptak001/HypercubeCascade/blob/main/python/examples/synthetic_classification.py) | Multi-class toy fields: `fit`, then train and test accuracy |
+
+```bash
+# from a clone of HypercubeCascade, after: pip install hypercube-cascade
+python python/examples/synthetic_classification.py
+```
+
+These use easy made-up fields so the API is obvious — not scores to publish.
+More notes:
+[python/examples/README.md](https://github.com/dliptak001/HypercubeCascade/blob/main/python/examples/README.md).
+
+---
+
+## Documentation
+
+| Doc | Role |
+|-----|------|
+| **[docs/Python_SDK.md](https://github.com/dliptak001/HypercubeCascade/blob/main/docs/Python_SDK.md)** | Canonical Python API — every method, layout, pickle, limits |
+| [python/examples/README.md](https://github.com/dliptak001/HypercubeCascade/blob/main/python/examples/README.md) | Demo scripts on GitHub |
+| [Project README](https://github.com/dliptak001/HypercubeCascade#readme) | Product story and C++ demos from the repo root |
+| [docs/CPP_SDK.md](https://github.com/dliptak001/HypercubeCascade/blob/main/docs/CPP_SDK.md) | Native library guide (same product, C++) |
+| [docs/CascadeWhitePaper.md](https://github.com/dliptak001/HypercubeCascade/blob/main/docs/CascadeWhitePaper.md) | The two-stage concept, mechanism by mechanism |
+| [WhiteNoiseFilter.md](https://github.com/dliptak001/HypercubeCascade/blob/main/examples/mnist/WhiteNoiseFilter.md) | Early white-noise study (MNIST as a test bed) |
+
+---
+
+## Ecosystem
+
+- **[HypercubeEtalon](https://github.com/dliptak001/HypercubeEtalon)** — the etalon transit alone; Cascade’s first stage.
+- **[HypercubeWTF](https://github.com/dliptak001/HypercubeWTF)** — the reservoir orbit alone; Cascade’s second stage.
+- **[HypercubeCNN](https://github.com/dliptak001/HypercubeCNN)** — cube-native conv stack; Cascade’s trainable head.
+- **[HypercubeESN](https://github.com/dliptak001/HypercubeESN)** — echo-state / reservoir computing on streams.
+- **[HypercubeHopfield](https://github.com/dliptak001/HypercubeHopfield)** — Hopfield-style dynamics on the cube.
+
+---
+
+## License
+
+Apache 2.0. See [LICENSE](https://github.com/dliptak001/HypercubeCascade/blob/main/LICENSE).