bispectrum 0.3.2__tar.gz → 0.3.6__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: bispectrum
3
- Version: 0.3.2
3
+ Version: 0.3.6
4
4
  Summary: Bispectrum analysis for machine learning
5
5
  Project-URL: Homepage, https://github.com/geometric-intelligence/bispectrum
6
6
  Project-URL: Repository, https://github.com/geometric-intelligence/bispectrum
@@ -34,13 +34,54 @@ Requires-Dist: scipy>=1.10; extra == 'experiments'
34
34
  Requires-Dist: torchvision; extra == 'experiments'
35
35
  Description-Content-Type: text/markdown
36
36
 
37
+ <img width="1374" height="431" alt="bispectrum_logo" src="https://github.com/user-attachments/assets/337d367b-9838-470e-89b8-057dba584bcd" />
38
+
37
39
  # bispectrum
38
40
 
39
41
  [![Tests](https://github.com/geometric-intelligence/bispectrum/actions/workflows/tests.yml/badge.svg)](https://github.com/geometric-intelligence/bispectrum/actions/workflows/tests.yml)
40
42
  [![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)
41
43
  [![codecov](https://codecov.io/github/geometric-intelligence/bispectrum/graph/badge.svg?token=J6GGY4VK1E)](https://codecov.io/github/geometric-intelligence/bispectrum)
42
44
 
43
- Bispectrum analysis for machine learning.
45
+ 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.
46
+
47
+ 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².
48
+
49
+ ## Supported Groups
50
+
51
+ | Module | Group / Domain | Output mode | Complexity (selective) |
52
+ | -------------- | --------------------------------- | ---------------- | ---------------------- |
53
+ | `CnonCn` | C_n on C_n | selective + full | O(n) |
54
+ | `SO2onS1` | SO(2) on S¹ | selective + full | O(n) |
55
+ | `TorusOnTorus` | T^d | selective + full | O(n) |
56
+ | `DnonDn` | D_n on D_n | selective | O(n) |
57
+ | `SO2onDisk` | SO(2) on disk | selective | O(L) |
58
+ | `SO3onS2` | SO(3) on S² | selective + full | Θ(L²) |
59
+ | `OctaonOcta` | chiral octahedral O (24 elements) | selective | 172 coefficients |
60
+
61
+ `SO2onS1` is the continuous-n limit of `CnonCn` and shares its implementation.
62
+
63
+ ## API
64
+
65
+ Every module exposes a uniform interface:
66
+
67
+ - **`forward(f)`** — selective (default) or full bispectral invariants
68
+ - **`fourier(f)`** — group Fourier coefficients
69
+ - **`invert(beta)`** — signal reconstruction up to group-action indeterminacy (where available)
70
+
71
+ 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`).
72
+
73
+ ## Benchmarks
74
+
75
+ Median wall-clock on a single NVIDIA H100 80 GB GPU (batch=16, `torch.utils.benchmark`):
76
+
77
+ | Module | Group | \|G\| / L_max | Coefs (sel.) | Coefs (full) | Fwd sel. (ms) | Fwd full (ms) |
78
+ | -------------- | ----------- | ------------- | ------------ | ------------ | ------------- | ------------- |
79
+ | `CnonCn` | C_128 | 128 | 128 | 8,256 | 0.14 | 8.53 |
80
+ | `TorusOnTorus` | C_32 × C_32 | 1,024 | 1,024 | 524,800 | 0.07 | 0.31 |
81
+ | `DnonDn` | D_32 | 64 | 245 | — | 0.57 | — |
82
+ | `SO2onDisk` | SO(2) | L=16 | 105 | — | 0.22 | — |
83
+ | `SO3onS2` | SO(3) | L=16 | 430 | — | 0.48 | — |
84
+ | `OctaonOcta` | O | 24 | 172 | — | 0.68 | — |
44
85
 
45
86
  ## Installation
46
87
 
@@ -117,8 +158,6 @@ beta = bsp(f) # shape (4, 172), complex64
117
158
  f_rec = bsp.invert(beta) # reconstructed up to group action
118
159
  ```
119
160
 
120
- See [DESIGN.md](DESIGN.md) for the full API and all supported groups.
121
-
122
161
  ## License
123
162
 
124
163
  MIT
@@ -0,0 +1,127 @@
1
+ <img width="1374" height="431" alt="bispectrum_logo" src="https://github.com/user-attachments/assets/337d367b-9838-470e-89b8-057dba584bcd" />
2
+
3
+ # bispectrum
4
+
5
+ [![Tests](https://github.com/geometric-intelligence/bispectrum/actions/workflows/tests.yml/badge.svg)](https://github.com/geometric-intelligence/bispectrum/actions/workflows/tests.yml)
6
+ [![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)
7
+ [![codecov](https://codecov.io/github/geometric-intelligence/bispectrum/graph/badge.svg?token=J6GGY4VK1E)](https://codecov.io/github/geometric-intelligence/bispectrum)
8
+
9
+ 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.
10
+
11
+ 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².
12
+
13
+ ## Supported Groups
14
+
15
+ | Module | Group / Domain | Output mode | Complexity (selective) |
16
+ | -------------- | --------------------------------- | ---------------- | ---------------------- |
17
+ | `CnonCn` | C_n on C_n | selective + full | O(n) |
18
+ | `SO2onS1` | SO(2) on S¹ | selective + full | O(n) |
19
+ | `TorusOnTorus` | T^d | selective + full | O(n) |
20
+ | `DnonDn` | D_n on D_n | selective | O(n) |
21
+ | `SO2onDisk` | SO(2) on disk | selective | O(L) |
22
+ | `SO3onS2` | SO(3) on S² | selective + full | Θ(L²) |
23
+ | `OctaonOcta` | chiral octahedral O (24 elements) | selective | 172 coefficients |
24
+
25
+ `SO2onS1` is the continuous-n limit of `CnonCn` and shares its implementation.
26
+
27
+ ## API
28
+
29
+ Every module exposes a uniform interface:
30
+
31
+ - **`forward(f)`** — selective (default) or full bispectral invariants
32
+ - **`fourier(f)`** — group Fourier coefficients
33
+ - **`invert(beta)`** — signal reconstruction up to group-action indeterminacy (where available)
34
+
35
+ 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`).
36
+
37
+ ## Benchmarks
38
+
39
+ Median wall-clock on a single NVIDIA H100 80 GB GPU (batch=16, `torch.utils.benchmark`):
40
+
41
+ | Module | Group | \|G\| / L_max | Coefs (sel.) | Coefs (full) | Fwd sel. (ms) | Fwd full (ms) |
42
+ | -------------- | ----------- | ------------- | ------------ | ------------ | ------------- | ------------- |
43
+ | `CnonCn` | C_128 | 128 | 128 | 8,256 | 0.14 | 8.53 |
44
+ | `TorusOnTorus` | C_32 × C_32 | 1,024 | 1,024 | 524,800 | 0.07 | 0.31 |
45
+ | `DnonDn` | D_32 | 64 | 245 | — | 0.57 | — |
46
+ | `SO2onDisk` | SO(2) | L=16 | 105 | — | 0.22 | — |
47
+ | `SO3onS2` | SO(3) | L=16 | 430 | — | 0.48 | — |
48
+ | `OctaonOcta` | O | 24 | 172 | — | 0.68 | — |
49
+
50
+ ## Installation
51
+
52
+ ```bash
53
+ pip install bispectrum
54
+ ```
55
+
56
+ Or with [uv](https://github.com/astral-sh/uv):
57
+
58
+ ```bash
59
+ uv pip install bispectrum
60
+ ```
61
+
62
+ ### Development
63
+
64
+ ```bash
65
+ git clone https://github.com/geometric-intelligence/bispectrum.git
66
+ cd bispectrum
67
+ uv pip install -e ".[dev]"
68
+ pre-commit install
69
+ ```
70
+
71
+ ### Pre-commit Hooks
72
+
73
+ This project uses [pre-commit](https://pre-commit.com/) for code quality checks. After installing dev dependencies, the hooks run automatically on each commit.
74
+
75
+ ```bash
76
+ # Run hooks on all files (useful for first-time setup or CI)
77
+ pre-commit run --all-files
78
+
79
+ # Run a specific hook
80
+ pre-commit run ruff --all-files
81
+
82
+ # Update hooks to latest versions
83
+ pre-commit autoupdate
84
+ ```
85
+
86
+ ## Usage
87
+
88
+ ### Cyclic group on itself
89
+
90
+ ```python
91
+ from bispectrum import CnonCn
92
+
93
+ bsp = CnonCn(n=8)
94
+ f = torch.randn(4, 8) # signal on Z/8Z
95
+ beta = bsp(f) # shape (4, 8), complex64
96
+ f_rec = bsp.invert(beta) # reconstructed up to cyclic shift
97
+ ```
98
+
99
+ ### SO(3) on the 2-sphere
100
+
101
+ ```python
102
+ from bispectrum import SO3onS2
103
+
104
+ # Selective bispectrum: O(L²) entries with generic completeness
105
+ bsp = SO3onS2(lmax=5, nlat=64, nlon=128, selective=True)
106
+ f = torch.randn(1, 64, 128) # signal on S²
107
+ beta = bsp(f) # shape (1, 35), complex64
108
+
109
+ # Full bispectrum: O(L³) entries
110
+ bsp_full = SO3onS2(lmax=5, nlat=64, nlon=128, selective=False)
111
+ beta_full = bsp_full(f) # shape (1, 69), complex64
112
+ ```
113
+
114
+ ### Octahedral group
115
+
116
+ ```python
117
+ from bispectrum import OctaonOcta
118
+
119
+ bsp = OctaonOcta()
120
+ f = torch.randn(4, 24) # signal on O (|O| = 24)
121
+ beta = bsp(f) # shape (4, 172), complex64
122
+ f_rec = bsp.invert(beta) # reconstructed up to group action
123
+ ```
124
+
125
+ ## License
126
+
127
+ MIT
@@ -11,12 +11,11 @@ packages = ["src/bispectrum"]
11
11
  [tool.hatch.build]
12
12
  include = [
13
13
  "src/bispectrum/**/*.py",
14
- "src/bispectrum/**/*.json",
15
14
  ]
16
15
 
17
16
  [project]
18
17
  name = "bispectrum"
19
- version = "0.3.2"
18
+ version = "0.3.6"
20
19
  description = "Bispectrum analysis for machine learning"
21
20
  readme = "README.md"
22
21
  license = "MIT"
@@ -64,19 +63,6 @@ urls.Homepage = "https://github.com/geometric-intelligence/bispectrum"
64
63
  urls.Repository = "https://github.com/geometric-intelligence/bispectrum"
65
64
  urls.Issues = "https://github.com/geometric-intelligence/bispectrum/issues"
66
65
 
67
- # Pin torch and torchvision to the cu128 wheels so they match systems with
68
- # NVIDIA driver >= 12.8 (e.g. the local 8x H100 box). PyPI's default torch
69
- # wheels target a newer CUDA runtime and crash with
70
- # "NVIDIA driver on your system is too old (found version 12080)".
71
- [[tool.uv.index]]
72
- name = "pytorch-cu128"
73
- url = "https://download.pytorch.org/whl/cu128"
74
- explicit = true
75
-
76
- [tool.uv.sources]
77
- torch = { index = "pytorch-cu128" }
78
- torchvision = { index = "pytorch-cu128" }
79
-
80
66
  [tool.ruff]
81
67
  target-version = "py312"
82
68
  line-length = 120
@@ -1,7 +1,6 @@
1
1
  """Clebsch-Gordan coefficient utilities for SO(3).
2
2
 
3
- Computes CG matrices analytically via the Wigner 3j symbol (Racah formula). Also supports loading
4
- precomputed matrices from the bundled JSON file for validation.
3
+ Computes CG matrices analytically via the Wigner 3j symbol (Racah formula).
5
4
  """
6
5
 
7
6
  from __future__ import annotations
@@ -14,8 +13,6 @@ from pathlib import Path
14
13
  import numpy as np
15
14
  import torch
16
15
 
17
- _DATA_PATH = Path(__file__).parent / 'data' / 'cg_lmax5.json'
18
-
19
16
  # ---------------------------------------------------------------------------
20
17
  # Log-factorial table (precomputed up to a generous ceiling; extended lazily)
21
18
  # ---------------------------------------------------------------------------
@@ -28,6 +28,7 @@ Reference: Kakarala (1992), Cohen et al.
28
28
 
29
29
  import hashlib
30
30
  import logging
31
+ import pickle # nosec B403 — only used for UnpicklingError type reference
31
32
  from collections import OrderedDict
32
33
  from pathlib import Path
33
34
 
@@ -514,8 +515,13 @@ class SO3onS2(nn.Module):
514
515
  cached_meta = data['entry_meta']
515
516
  if len(cached_meta) != len(entries_for_cg):
516
517
  return None
518
+ expected_meta = [
519
+ [l1, l2, l_val, int(is_power)] for _, l1, l2, l_val, is_power in entries_for_cg
520
+ ]
521
+ if cached_meta != expected_meta:
522
+ return None
517
523
  return data['cg_vals'], data['m1_idx'], data['m_idx'], data['offsets'], cached_meta
518
- except (OSError, RuntimeError, KeyError):
524
+ except (OSError, RuntimeError, KeyError, pickle.UnpicklingError):
519
525
  return None
520
526
 
521
527
  def _build_group_tables(
@@ -1003,9 +1009,7 @@ class SO3onS2(nn.Module):
1003
1009
  NotImplementedError: Selective bispectrum and inversion for
1004
1010
  continuous groups remain open mathematical problems.
1005
1011
  """
1006
- raise NotImplementedError(
1007
- 'Inversion for SO(3) on S^2 is an open mathematical problem. See DESIGN.md TODO-M1 and TODO-M4.'
1008
- )
1012
+ raise NotImplementedError('Inversion for SO(3) on S^2 is an open mathematical problem.')
1009
1013
 
1010
1014
  @property
1011
1015
  def output_size(self) -> int:
@@ -1,88 +0,0 @@
1
- # bispectrum
2
-
3
- [![Tests](https://github.com/geometric-intelligence/bispectrum/actions/workflows/tests.yml/badge.svg)](https://github.com/geometric-intelligence/bispectrum/actions/workflows/tests.yml)
4
- [![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)
5
- [![codecov](https://codecov.io/github/geometric-intelligence/bispectrum/graph/badge.svg?token=J6GGY4VK1E)](https://codecov.io/github/geometric-intelligence/bispectrum)
6
-
7
- Bispectrum analysis for machine learning.
8
-
9
- ## Installation
10
-
11
- ```bash
12
- pip install bispectrum
13
- ```
14
-
15
- Or with [uv](https://github.com/astral-sh/uv):
16
-
17
- ```bash
18
- uv pip install bispectrum
19
- ```
20
-
21
- ### Development
22
-
23
- ```bash
24
- git clone https://github.com/geometric-intelligence/bispectrum.git
25
- cd bispectrum
26
- uv pip install -e ".[dev]"
27
- pre-commit install
28
- ```
29
-
30
- ### Pre-commit Hooks
31
-
32
- This project uses [pre-commit](https://pre-commit.com/) for code quality checks. After installing dev dependencies, the hooks run automatically on each commit.
33
-
34
- ```bash
35
- # Run hooks on all files (useful for first-time setup or CI)
36
- pre-commit run --all-files
37
-
38
- # Run a specific hook
39
- pre-commit run ruff --all-files
40
-
41
- # Update hooks to latest versions
42
- pre-commit autoupdate
43
- ```
44
-
45
- ## Usage
46
-
47
- ### Cyclic group on itself
48
-
49
- ```python
50
- from bispectrum import CnonCn
51
-
52
- bsp = CnonCn(n=8)
53
- f = torch.randn(4, 8) # signal on Z/8Z
54
- beta = bsp(f) # shape (4, 8), complex64
55
- f_rec = bsp.invert(beta) # reconstructed up to cyclic shift
56
- ```
57
-
58
- ### SO(3) on the 2-sphere
59
-
60
- ```python
61
- from bispectrum import SO3onS2
62
-
63
- # Selective bispectrum: O(L²) entries with generic completeness
64
- bsp = SO3onS2(lmax=5, nlat=64, nlon=128, selective=True)
65
- f = torch.randn(1, 64, 128) # signal on S²
66
- beta = bsp(f) # shape (1, 35), complex64
67
-
68
- # Full bispectrum: O(L³) entries
69
- bsp_full = SO3onS2(lmax=5, nlat=64, nlon=128, selective=False)
70
- beta_full = bsp_full(f) # shape (1, 69), complex64
71
- ```
72
-
73
- ### Octahedral group
74
-
75
- ```python
76
- from bispectrum import OctaonOcta
77
-
78
- bsp = OctaonOcta()
79
- f = torch.randn(4, 24) # signal on O (|O| = 24)
80
- beta = bsp(f) # shape (4, 172), complex64
81
- f_rec = bsp.invert(beta) # reconstructed up to group action
82
- ```
83
-
84
- See [DESIGN.md](DESIGN.md) for the full API and all supported groups.
85
-
86
- ## License
87
-
88
- MIT
@@ -1 +0,0 @@
1
- # Package data directory for bispectrum.