WaveRider

The geometry of your data tells you the exact size of network you need. Most of what your model is computing is noise.

Eric G. Suchanek, PhD — Flux-Frontiers

Technical Paper (PDF)

📡 Breaking News — WaveRider renders to holographic displays

As of v0.10.0, any WaveRider scene can be pushed to real Looking Glass holographic hardware. Two device families are supported, and they take different media — render for the display you own:

• Light-field quilts — waverider.lfd, 9 device presets, stills, MP4, and live casting via Looking Glass Bridge → docs/waverider/lfd.md
• Hololuminescent video — waverider.hld, 4K turntable masters to the official spec → docs/waverider/hld.md
• CT / MRI demo mode — real biomedical volumes, no model fitting → docs/waverider/voxel_viz.md
• TVB brain mode — cortical surfaces and structural connectomes from The Virtual Brain, downloaded on demand → docs/waverider/tvb_data.md

waverider-voxel-viz --dataset iris --quilt portrait --out iris --cast   # light-field, live cast
waverider-voxel-viz --dataset iris --hld --out iris                     # HLD video
waverider-voxel-viz --ct-demo --ct-dataset brain --hld --out brain_hld  # MRI brain → HLD
waverider-voxel-viz --tvb-demo --tvb-dataset connectome --quilt portrait # connectome → quilt

Needs the viz extras (poetry install --with viz); --quilt and --hld are mutually exclusive.

The Core Finding

Machine learning spaces are 99% noise by dimension. CIFAR-10 images live in a roughly 19-dimensional manifold inside a 3,072-dimensional ambient space. Tiny ImageNet: 20 intrinsic dimensions inside 12,288. Pope et al. (ICLR 2021) reach the same conclusion from a different estimator, putting CIFAR-10 at 13–26 by Levina–Bickel MLE. Standard algorithms treat every dimension equally — spending 99%+ of their compute on dimensions that carry no signal, while momentum, distance metrics, and gradient updates are polluted by that noise.

WaveRider measures the actual geometry, builds models constrained to the signal manifold, and derives a closed-form formula for optimal network width from first principles:

w* = d* + C − 1

Measure the intrinsic dimensionality d*. Count the classes C. That's your optimal bottleneck width. No grid search. No hyperparameter sweep.

What d* means here, exactly. d* is not a property of the dataset on its own — it is the output of an estimator, and it moves with that estimator's settings. Every d* quoted below is local PCA at k=25 neighbours, τ=0.90, taking the per-class maximum — the default the benchmark scripts now share, and the one that produced these rows, though the older result JSONs record τ without recording k. Change any one of those three and the number changes: CIFAR-10 reads 19 at k=25 and 34 at k=50 on identical data with identical preprocessing, and 16 if you take the global mean instead of the per-class maximum. Those are not conflicting measurements of one quantity, they are three different quantities, and the sensitivity table is in docs/RESULTS.md. Published estimators disagree at least this much: Pope et al. report CIFAR-10 as 21 / 96 / 11 / 7 under MLE / GeoMLE / TwoNN / kNN-graph. Quote k, τ and the aggregation with any d* taken from this library.

Headline Results

Universal Bottleneck — formula-derived architectures beat ResNet

UB+Drop = w* filters with dropout=0.3 — dropout is the regularizer that lets the formula-derived width generalize.

Two more results families, in docs/RESULTS.md with full tables and provenance notes:

• Zero-parameter classifiers — ManifoldModel beats a trained MLP on Heart Disease (83.82% vs 80.96%) and stays within 1 pp on Breast Cancer and Dermatology, with zero trained parameters.
• Parameter efficiency — manifold-constrained models match or beat dense baselines with 105×–724× fewer parameters (MNIST, CIFAR-10) and beat them outright on Tiny ImageNet and CIFAR-100.

All benchmark reports are indexed in docs/INDEX.md; every figure traces to a results JSON committed beside its script.

The Dimension Probe

When a network is given a bottleneck of exactly w* = d* + C − 1 neurons, it spontaneously partitions that space — with zero instruction — into a geometry subspace plus exactly C−1 class-separation coordinates, and the two together recover d* precisely.

On CIFAR-10 the probe reads d*=16 — the global mean of the same local-PCA field whose per-class maximum is the 19 in the table above, not a different measurement — so C=10 and w*=25. PCA on the w*-dimensional bottleneck yields k₉₀ = 7 geometry components (the on-manifold subspace) and n_extra = 9 class-separation coordinates:

k₉₀ + n_extra = 7 + 9 = 16 = d* and n_extra = 9 = C − 1

Read those two carefully, because only one of them is a finding. n_extra is defined as w* − k₉₀, so the first identity restates w* = d* + C − 1 rather than evidencing it. The substantive claim is the second: that exactly C−1 of the bottleneck directions fall outside the 90% variance shell. It is a one-dataset result, stated against the global-mean convention, and untested under the per-class maximum that every w* in the table above is derived from. Both conventions are being re-run before this is claimed as confirmation.

The semantic content is interpretable: PC11 selects four-legged animals, PC9 flat/low-profile objects, PC12 wheeled vehicles. (Paper, Table 8.)

Gradient descent independently discovers the theorem's decomposition.

The Stack

All 17 modules in src/waverider, by layer. Full per-component detail lives in the stack summary; worked code examples in docs/USAGE.md.

Getting Started

Requirements: Python 3.12

git clone https://github.com/Flux-Frontiers/waverider.git
cd waverider
poetry install                          # core
poetry install --with viz               # + PyVista visualization & holographic output
poetry install --with benchmarks        # + TensorFlow (Metal GPU on Apple Silicon)
poetry install --with viz,benchmarks    # everything

As a dependency: poetry add git+https://github.com/Flux-Frontiers/waverider.git (or pip install git+…).

Complete code examples for every component: docs/USAGE.md. The full documentation map is docs/INDEX.md; code lives in src/waverider/, locked benchmarks in benchmarks/canonical_tests/, and papers in papers/.

Visualization & Holographic Output

Looking Glass holographic displays — new in v0.10.0

WaveRider renders any PyVista scene to real Looking Glass holographic hardware, validated end-to-end on a physical Gen3 16″ panel. Both device families are supported — they take different media, so render for the display you own:

• waverider.lfd — light-field quilts. Off-axis asymmetric-frustum view sweep tiled into a quilt; 9 official device presets (Portrait, Go, 16″–65″), stills, MP4, and live casting to a connected display via Looking Glass Bridge. → docs/waverider/lfd.md
• waverider.hld — Hololuminescent video. 4K turntable masters to the official spec (3840×2160, HEVC, bt709); white renders invisible, so the subject floats. → docs/waverider/hld.md

waverider-voxel-viz --dataset iris --quilt portrait --out iris --cast   # light-field, live cast
waverider-voxel-viz --dataset iris --hld --out iris                     # HLD video

Voxel Visualizer

waverider-voxel-viz makes high-dimensional manifolds visible: the ManifoldObserver's scalar fields (curvature, height, local intrinsic dimensionality, …) are projected into a 3-D PCA subspace, voxelised, and served as interactive orthogonal slice planes in PyVista. A CT/MRI demo mode (--ct-demo) renders real biomedical volumes with no model fitting — and both modes output straight to the holographic paths above.

waverider-voxel-viz --dataset iris --multi-scalar         # manifold mode, all fields
waverider-voxel-viz --ct-demo                             # T1 MRI brain, interactive
waverider-voxel-viz --ct-demo --ct-dataset brain --hld --out brain_hld  # MRI → HLD video
waverider-voxel-viz --ct-demo --ct-dataset brain --quilt portrait --out brain --cast  # MRI → light-field

• Full CLI + API reference (all datasets, scalar fields, flags): docs/waverider/voxel_viz.md
• Worked examples: docs/USAGE.md · Method paper: papers/voxel_viz/voxel_viz.pdf

Method

Gradient-diversity PCA finds the tangent space of the loss manifold: decompose the covariance of mini-batch gradients, and the top-d eigenvectors span the gradient's active subspace while the remaining P−d point into noise. Every update is then projected onto that subspace before Adam sees it — momentum accumulates signal, never noise, and its state lives in global R^P so nothing is lost when the PCA basis rotates. The eigenvalue weighting is a form of natural gradient using the data covariance as an empirical Fisher matrix (Amari, 1998).

Full derivations, the projected-step algorithm, and the ambient-space failure modes (noise-inflated KNN distances, noise-adapted Adam denominators) are in the technical paper and the ManifoldWalker spec.

Benchmarks

Every benchmark in benchmarks/canonical_tests/ is a standalone script, run directly with Python:

python benchmarks/canonical_tests/cifar10_manifold_architecture.py             # per-dataset (cifar100, mnist, tiny_imagenet, digits, iris likewise)
python benchmarks/canonical_tests/clinical/disease_manifold_architecture.py    # all clinical datasets
python benchmarks/canonical_tests/mnist_ub_phase_boundary.py                   # Universal Bottleneck phase boundary

Seed-locked results (seeds 42–51, 3–10 trials) are committed as JSON alongside each script — the locked numbers cited in the papers. Each benchmark ships a rendered report (*_report.md / .tex / .pdf) generated from its JSON by report_generator.py. Full report index: docs/INDEX.md; all results tables and provenance notes: docs/RESULTS.md.

References

• Bengio, Y. et al. (2013). Representation Learning: A Review and New Perspectives. TPAMI.
• Gur-Ari, G. et al. (2018). Gradient Descent Happens in a Tiny Subspace. arXiv:1812.04754.
• Ghorbani, B. et al. (2019). An Investigation into Neural Net Optimization via Hessian Eigenvalue Density. ICML.
• Amari, S. (1998). Natural Gradient Works Efficiently in Learning. Neural Computation.
• Kingma, D. & Ba, J. (2015). Adam: A Method for Stochastic Optimization. ICLR.

Citation

If you use WaveRider in your research or project, please cite it. Citation metadata is also provided machine-readably in CITATION.cff.

Suchanek, E. G. (2026). WaveRider: Manifold-Aware Geometric Machine Learning (Version 0.16.2) [Software]. Flux-Frontiers. https://doi.org/10.5281/zenodo.20383650

@software{suchanek_waverider,
  author    = {Suchanek, Eric G.},
  title     = {{WaveRider}: Manifold-Aware Geometric Machine Learning},
  version   = {0.16.2},
  year      = {2026},
  publisher = {Flux-Frontiers},
  url       = {https://github.com/Flux-Frontiers/waverider},
  doi       = {10.5281/zenodo.20383650}
}

License

Elastic License 2.0 (ELv2) — see LICENSE.

Free to use, modify, and distribute. May not be offered as a hosted or managed service to third parties.

Looking Glass is a trademark of Looking Glass Factory, Inc. WaveRider is an independent project; its author is a customer and user of Looking Glass hardware, not affiliated with, sponsored by, or endorsed by Looking Glass Factory.