geometric-intelligence · johmathe · May 12, 2026 · May 12, 2026
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,6 +1,6 @@
 default_stages: [pre-commit]
 fail_fast: false
-exclude: ^(docs/|paper/)
+exclude: ^(docs/|paper/|experiments/)
 
 default_language_version:
   python: python3

diff --git a/DESIGN.md b/DESIGN.md
diff --git a/README.md b/README.md
@@ -4,7 +4,46 @@
 [![Pre-commit](https://github.com/geometric-intelligence/bispectrum/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/geometric-intelligence/bispectrum/actions/workflows/pre-commit.yml)
 [![codecov](https://codecov.io/github/geometric-intelligence/bispectrum/graph/badge.svg?token=J6GGY4VK1E)](https://codecov.io/github/geometric-intelligence/bispectrum)
 
-Bispectrum analysis for machine learning.
+An open-source, fully unit-tested PyTorch library that implements *selective* G-bispectra for seven group actions as differentiable `torch.nn.Module`s, ready to plug into ML pipelines and deep learning architectures.
+
+The G-bispectrum is a principled *complete* invariant of a signal — it retains all information up to the group action. Selectivity reduces cost from O(|G|²) to O(|G|) for finite groups, and from O(L³) to Θ(L²) coefficients for SO(3) on S².
+
+## Supported Groups
+
+| Module         | Group / Domain                    | Output mode      | Complexity (selective) |
+| -------------- | --------------------------------- | ---------------- | ---------------------- |
+| `CnonCn`       | C_n on C_n                        | selective + full | O(n)                   |
+| `SO2onS1`      | SO(2) on S¹                       | selective + full | O(n)                   |
+| `TorusOnTorus` | T^d                               | selective + full | O(n)                   |
+| `DnonDn`       | D_n on D_n                        | selective        | O(n)                   |
+| `SO2onDisk`    | SO(2) on disk                     | selective        | O(L)                   |
+| `SO3onS2`      | SO(3) on S²                       | selective + full | Θ(L²)                  |
+| `OctaonOcta`   | chiral octahedral O (24 elements) | selective        | 172 coefficients       |
+
+`SO2onS1` is the continuous-n limit of `CnonCn` and shares its implementation.
+
+## API
+
+Every module exposes a uniform interface:
+
+- **`forward(f)`** — selective (default) or full bispectral invariants
+- **`fourier(f)`** — group Fourier coefficients
+- **`invert(beta)`** — signal reconstruction up to group-action indeterminacy (where available)
+
+Modules default to O(|G|) selective coefficients; pass `selective=False` for the full O(|G|²) set. CG matrices, DFT kernels, and Bessel roots are precomputed as non-learnable buffers. Dependencies: PyTorch, NumPy, and `torch_harmonics` (for `SO3onS2`).
+
+## Benchmarks
+
+Median wall-clock on a single NVIDIA H100 80 GB GPU (batch=16, `torch.utils.benchmark`):
+
+| Module         | Group       | \|G\| / L_max | Coefs (sel.) | Coefs (full) | Fwd sel. (ms) | Fwd full (ms) |
+| -------------- | ----------- | ------------- | ------------ | ------------ | ------------- | ------------- |
+| `CnonCn`       | C_128       | 128           | 128          | 8,256        | 0.14          | 8.53          |
+| `TorusOnTorus` | C_32 × C_32 | 1,024         | 1,024        | 524,800      | 0.07          | 0.31          |
+| `DnonDn`       | D_32        | 64            | 245          | —            | 0.57          | —             |
+| `SO2onDisk`    | SO(2)       | L=16          | 105          | —            | 0.22          | —             |
+| `SO3onS2`      | SO(3)       | L=16          | 430          | —            | 0.48          | —             |
+| `OctaonOcta`   | O           | 24            | 172          | —            | 0.68          | —             |
 
 ## Installation
 
@@ -81,8 +120,6 @@ beta = bsp(f)                 # shape (4, 172), complex64
 f_rec = bsp.invert(beta)      # reconstructed up to group action
 ```
 
-See [DESIGN.md](DESIGN.md) for the full API and all supported groups.
-
 ## License
 
 MIT
diff --git a/benchmarks/figures/bench1_coefficient_count.pdf b/benchmarks/figures/bench1_coefficient_count.pdf
diff --git a/benchmarks/figures/bench1_coefficient_count.png b/benchmarks/figures/bench1_coefficient_count.png
diff --git a/benchmarks/figures/bench2_forward_cpu.pdf b/benchmarks/figures/bench2_forward_cpu.pdf
diff --git a/benchmarks/figures/bench2_forward_cpu.png b/benchmarks/figures/bench2_forward_cpu.png
diff --git a/benchmarks/figures/bench2_forward_gpu.pdf b/benchmarks/figures/bench2_forward_gpu.pdf
diff --git a/benchmarks/figures/bench2_forward_gpu.png b/benchmarks/figures/bench2_forward_gpu.png
diff --git a/benchmarks/figures/bench3_inversion_cpu.pdf b/benchmarks/figures/bench3_inversion_cpu.pdf
diff --git a/benchmarks/figures/bench3_inversion_cpu.png b/benchmarks/figures/bench3_inversion_cpu.png
diff --git a/benchmarks/figures/bench3_inversion_gpu.pdf b/benchmarks/figures/bench3_inversion_gpu.pdf
diff --git a/benchmarks/figures/bench3_inversion_gpu.png b/benchmarks/figures/bench3_inversion_gpu.png
diff --git a/benchmarks/figures/bench4_gpu_scaling.pdf b/benchmarks/figures/bench4_gpu_scaling.pdf
diff --git a/benchmarks/figures/bench4_gpu_scaling.png b/benchmarks/figures/bench4_gpu_scaling.png
diff --git a/benchmarks/figures/paper_fig1.pdf b/benchmarks/figures/paper_fig1.pdf
diff --git a/benchmarks/figures/paper_fig1.png b/benchmarks/figures/paper_fig1.png
diff --git a/benchmarks/figures/paper_fig2.pdf b/benchmarks/figures/paper_fig2.pdf
diff --git a/benchmarks/figures/paper_fig2.png b/benchmarks/figures/paper_fig2.png
diff --git a/benchmarks/figures/paper_fig3.pdf b/benchmarks/figures/paper_fig3.pdf
diff --git a/benchmarks/figures/paper_fig3.png b/benchmarks/figures/paper_fig3.png
diff --git a/benchmarks/inversion_results/inversion_convergence.pdf b/benchmarks/inversion_results/inversion_convergence.pdf
diff --git a/benchmarks/inversion_results/inversion_convergence.png b/benchmarks/inversion_results/inversion_convergence.png
diff --git a/benchmarks/inversion_results/inversion_errors.pdf b/benchmarks/inversion_results/inversion_errors.pdf
diff --git a/benchmarks/inversion_results/inversion_errors.png b/benchmarks/inversion_results/inversion_errors.png
diff --git a/benchmarks/paper_benchmarks.pdf b/benchmarks/paper_benchmarks.pdf
diff --git a/docs/beamer_slides.pdf b/docs/beamer_slides.pdf