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).
