Metadata-Version: 2.4
Name: bispectrum
Version: 0.3.6
Summary: Bispectrum analysis for machine learning
Project-URL: Homepage, https://github.com/geometric-intelligence/bispectrum
Project-URL: Repository, https://github.com/geometric-intelligence/bispectrum
Project-URL: Issues, https://github.com/geometric-intelligence/bispectrum/issues
Author-email: Johan Mathe <johan.mathe@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: deep learning,machine learning,neural networks,scientific computations,tensor manipulation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.12
Requires-Dist: numpy>=1.22.4
Requires-Dist: torch-harmonics>=0.9
Requires-Dist: torch>=2.10
Provides-Extra: dev
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pre-commit>=3.3.3; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5.0; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: experiments
Requires-Dist: h5py; extra == 'experiments'
Requires-Dist: matplotlib>=3.7.0; extra == 'experiments'
Requires-Dist: medmnist; extra == 'experiments'
Requires-Dist: scipy>=1.10; extra == 'experiments'
Requires-Dist: torchvision; extra == 'experiments'
Description-Content-Type: text/markdown

<img width="1374" height="431" alt="bispectrum_logo" src="https://github.com/user-attachments/assets/337d367b-9838-470e-89b8-057dba584bcd" />

# bispectrum

[![Tests](https://github.com/geometric-intelligence/bispectrum/actions/workflows/tests.yml/badge.svg)](https://github.com/geometric-intelligence/bispectrum/actions/workflows/tests.yml)
[![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)

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

```bash
pip install bispectrum
```

Or with [uv](https://github.com/astral-sh/uv):

```bash
uv pip install bispectrum
```

### Development

```bash
git clone https://github.com/geometric-intelligence/bispectrum.git
cd bispectrum
uv pip install -e ".[dev]"
pre-commit install
```

### Pre-commit Hooks

This project uses [pre-commit](https://pre-commit.com/) for code quality checks. After installing dev dependencies, the hooks run automatically on each commit.

```bash
# Run hooks on all files (useful for first-time setup or CI)
pre-commit run --all-files

# Run a specific hook
pre-commit run ruff --all-files

# Update hooks to latest versions
pre-commit autoupdate
```

## Usage

### Cyclic group on itself

```python
from bispectrum import CnonCn

bsp = CnonCn(n=8)
f = torch.randn(4, 8)       # signal on Z/8Z
beta = bsp(f)                # shape (4, 8), complex64
f_rec = bsp.invert(beta)     # reconstructed up to cyclic shift
```

### SO(3) on the 2-sphere

```python
from bispectrum import SO3onS2

# Selective bispectrum: O(L²) entries with generic completeness
bsp = SO3onS2(lmax=5, nlat=64, nlon=128, selective=True)
f = torch.randn(1, 64, 128)  # signal on S²
beta = bsp(f)                 # shape (1, 35), complex64

# Full bispectrum: O(L³) entries
bsp_full = SO3onS2(lmax=5, nlat=64, nlon=128, selective=False)
beta_full = bsp_full(f)       # shape (1, 69), complex64
```

### Octahedral group

```python
from bispectrum import OctaonOcta

bsp = OctaonOcta()
f = torch.randn(4, 24)       # signal on O (|O| = 24)
beta = bsp(f)                 # shape (4, 172), complex64
f_rec = bsp.invert(beta)      # reconstructed up to group action
```

## License

MIT
