Metadata-Version: 2.4
Name: zxtalori
Version: 0.3.0
Summary: Orientation grids and Quey relaxation on SO(3)/K, one Zig + WGSL engine for Python and the browser
Author: Zachary T. Varley
License-Expression: MIT
License-File: LICENSE
License-File: licenses/MIT-Gao.txt
License-File: THIRD_PARTY_NOTICES.md
License-File: scripts/licenses/wgpu-native-LICENSE.MIT
Keywords: 
Requires-Python: >=3.10
Requires-Dist: numpy
Description-Content-Type: text/markdown

# zxtalori

Orientation grids on SO(3)/K: generate, measure, relax and lower the covering radius on the GPU,
in the browser or from Python.

**[Open the web app](https://zacharyvarley.github.io/zxtalori/)**: it runs on your GPU inside the
page (Chrome or Edge 137+, which have WebGPU and WebAssembly promise integration). It opens on an
octahedral grid; pick a group and a count, then relax or optimize the covering.

## What it does

- **Generates** samples for all eleven proper point groups, up to 10,000,000 orientations: product
  grids on the inverse Hopf fibration (the default for every group, never cut at the zone boundary;
  about a second for 10 million), FCC lattice transports for T, O and I, seeded Haar-random
  samples, and exact counts from 32 to 1,000,000 (a smaller grid filled at its largest empty
  Delaunay circumcentres).
- **Measures** minimum separation, mean geodesic repulsion energy, Riesz s = 1, 2, 3, Green and
  logarithmic energy ratios, and the **covering radius**: the largest empty cap, from a GPU
  Delaunay triangulation of the fundamental zone and a symmetry shell (a port of Gao and Chen's
  parallel 3D Delaunay method) with exact predicates and a shell-completeness certificate.
- **Relaxes** by Quey–Villani–Maurice geodesic repulsion with Barzilai–Borwein steps. Forces sum
  over all pairs, or over each point's near field (about 7,500 neighbours within 20 mean
  orientation radii, faded smoothly), which costs time linear in the count.
- **Lowers the covering radius** by disjoint local moves around the largest empty caps, judged
  against an exact triangulation that is updated in place as points move. An optional
  separation floor keeps every pair apart, and the best sample is kept.
- **Shows** the sample in homochoric, Rodrigues or axis–angle space, in the fundamental zone or
  all of SO(3): small samples drawn on the CPU, large ones as GPU discs, and very large ones (or
  their SO(3) images, hundreds of millions) as a per-pixel density, chosen automatically. Points
  are colored by symmetry zone, nearest-neighbour distance, largest adjacent cap or Voronoi face
  count, on a scale relative to the median that shows where a sample is denser or sparser than
  the rest, with the values' distribution and spread in the legend. Nearest neighbours come from a
  pass linear in the count, so every size can be colored by them. Every measure has a history plot.
- **Reads and writes** JSON and CSV quaternions (scalar first, right action `q*g`).

One engine (Zig and WGSL) runs natively through wgpu-native and as WebAssembly on WebGPU, so the
app and the Python package do the same thing. Symmetry images are evaluated implicitly; the
expanded orbit is never stored.

## Python

```bash
pip install zxtalori
python -m zxtalori          # the same app, served locally
```

```python
import zxtalori as zo

with zo.generate("O", count=1000) as sample:   # inverse Hopf grid nearest 1,000: 1,048 orientations
    sample.relax(30)
    print(sample.measure()["separation_deg"], sample.covering()["covering_radius_deg"])
    sample.optimize_covering(2000)             # lowers it; the best sample is kept
    q = sample.quaternions                     # NumPy (N, 4), scalar first
    sample.save("octahedral.json")             # opens in the web app

with zo.generate("D6", h=12) as sample:         # frequency f=12: 2,936 orientations
    print(sample.covering()["covering_excess"])

with zo.generate("O", h=6, kind="transport") as sample:   # FCC transport, semi-edge 6: 1,043
    sample.relax(30)

with zo.haar("O", count=100_000, seed=193) as sample:
    sample.relax(100, neighbourhood=20)        # near-field forces; 0 for all pairs
    sample.covering()
    sizes = sample.point_values("covering")    # per point: largest adjacent cap (degrees)

with zo.generate("I", count=10_000_000) as sample:   # f=228: 9,876,998 orientations, about a second
    sample.spacing()                           # each one's nearest neighbour, linear in the count
    gaps = sample.point_values("separation")   # per point (degrees)

with zo.generate("D2", count=1000, exact=True, fixed_identity=True) as sample:
    sample.relax(30)                           # identity included and held fixed
```

`h` sets the frequency (or, with `kind="transport"`, the T/O/I lattice semi-edge) and `count` the
approximate size, up to 10,000,000; `exact=True` reaches `count` exactly, up to 1,000,000. Separation and covering radius are SO(3) rotation angles
in degrees; the repulsion objective uses S³ geodesic distances in radians. Lower repulsion energy
does not by itself certify a lower covering radius.

## More

- [Methods](docs/methods.md): generation, measures, relaxation and covering optimization, with
  conventions and numerical limits; [workbench methods](docs/workbench-methods.md) for zone
  membership and exact counts.
- [GPU Delaunay triangulation](docs/gpu-delaunay.md): the parallel construction after Gao and Chen,
  exact predicates and the covering certificate.
- [CONTRIBUTING.md](CONTRIBUTING.md): building, testing, conventions.

Generation, spacing and drawing are tested to 10 million orientations and covering checks to
about a million, natively and in the browser; CI runs the test suite on Apple M1 (Metal).

MIT ([LICENSE](LICENSE)). Third-party components keep their notices
([THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)). The wheels bundle
[wgpu-native](https://github.com/gfx-rs/wgpu-native) (MIT / Apache-2.0).
