Expand description
Racah–Wigner calculus for compact Lie groups: irreducible representations, Clebsch–Gordan coefficients, and recoupling coefficients (3j / 6j / F / R) for SU(2), SU(N), SO(N), Spin(N) and Sp(2N).
Coefficients for any admissible labels are computed on demand — there is no precomputed table and no generation-time label cut. Pure representation mathematics: no fusion-category trait vocabulary, no sector identity types, no tensor-network concepts. Consumers translate the numbers into their own categorical interfaces.
§Quick start
Exact SU(2) recoupling needs no features. Spins are doubled (dj = 2j), so
2 means spin 1; a non-admissible label set returns exact zero, never an
error. Here {1 1 1; 1 1 1} = 1/6:
use racah::wigner_6j;
let sixj = wigner_6j(2, 2, 2, 2, 2, 2);
assert!((sixj.to_f64() - 1.0 / 6.0).abs() < 1e-14);§Where to look
| You want | Go to |
|---|---|
| SU(2): 3j, 6j, CG, F, R, Frobenius–Schur — exact, no feature flag | su2 (re-exported at the crate root) |
| SU(N), SU(N)/Z_k, PSU(N) — Gelfand–Tsetlin construction | sun (cgc-gen) |
| SO(N), Spin(N), Sp(2r) — generator bootstrap, B/C/D series | bcd (cgc-gen) |
| Which highest weights a global form admits | group |
| Cache ceilings, budgets, statistics | cache |
§Layers
- base (no feature): exact SU(2) — closed-form 3j/6j/CGC in big-rational arithmetic with a single final rounding to floating point.
cgc-gen: runtime coefficient generation for SU(N) (Gelfand–Tsetlin construction), and SO(N)/Sp(2N) (defining-representation seeds plus a family-generic decomposition loop). Dense factorizations and the CGC contractions producing F/R route through the Tenferro traced surface at a single seam, currently executed on the CPU faer backend; no hand-rolled kernels, and no public backend-selection API yet.
The boundary is mathematical, not organizational: SU(2) has closed forms and needs no matrix computation, so a consumer needing only SU(2) never pulls a linear-algebra stack.
§Exactness contract
Combinatorial structure and discrete data are exact; gauge fixing is a
deterministic function of the subspace; floating-point stages are
verification-gated and versioned. Concretely: labels, dimensions, duals,
Frobenius–Schur indicators and fusion multiplicities are exact integer or
rational arithmetic, while generated CGC / F / R values are f64 that
passed orthogonality, unitarity and pentagon/hexagon gates at generation
time. A gate violation is a typed error, never a silently degraded number.
§Provider contract
Each family publishes an opaque authority fingerprint naming the
convention set its coefficients are computed in
(su2_authority_fingerprint, sun::sun_authority_fingerprint,
bcd::bcd_authority_fingerprint). Persist the bytes next to anything you
derive from these coefficients and compare by equality on load; never parse
them. The base SU(2) provider adds a checked representation surface
(su2::Su2Irrep and the *_checked coefficient functions) and a cache
resource contract (cache::base_cache_stats,
cache::BASE_CACHE_MAX_BYTES, cache::reset). The
User Guide carries the prose.
§Documentation
- User Guide — task-oriented: pick a group, build irreps, fuse, get CGC, get F/R, bound the caches. Start here if you are new.
docs/theory.pdf— a self-contained note on the objects this API computes (irreps, fusion multiplicities, CGC and gauge, recoupling, the two constructions, the exactness contract).docs/gauge.md/docs/gauge_soN.md— the frozen normative gauge specifications. Reference documents, not tutorials.docs/references.md— porting provenance (file:symbol-level) and the verified bibliography.
Re-exports§
pub use su2::canonical_regge_3j;pub use su2::canonical_regge_6j;pub use su2::clebsch_gordan;pub use su2::clebsch_gordan_checked;pub use su2::su2_f_symbol;pub use su2::su2_f_symbol_checked;pub use su2::su2_frobenius_schur;pub use su2::su2_r_symbol;pub use su2::su2_r_symbol_checked;pub use su2::wigner_3j;pub use su2::wigner_3j_checked;pub use su2::wigner_6j;pub use su2::wigner_6j_checked;pub use su2::AdmissibilityViolation;pub use su2::Regge3j;pub use su2::Regge6j;pub use su2::ReggeError;pub use su2::ReggePhase;pub use su2::Su2Error;pub use su2::Su2Fusion;pub use su2::Su2Irrep;
Modules§
- bcd
- SO(N), Spin(N) and Sp(2r) — the B, C, D Cartan series: irreps from Dynkin
labels, exact Weyl dimensions, duals, Frobenius–Schur indicators,
Freudenthal weight multiplicities, the exact Brauer–Klimyk/Racah–Speiser
tensor-product decomposition $N^c_{ab}$, and the Clebsch–Gordan / F / R
coefficients built by the generator bootstrap. Compilation-gated behind
cgc-gen. SO(N)/Sp(2N) irreps and their Clebsch–Gordan / recoupling coefficients for the B, C, D Cartan series, built by the generator bootstrap. - cache
- Bounded, thread-safe coefficient caches, and the process-local policy that bounds them.
- group
- Which highest weights are genuine representations of which group:
group::RootSystem,group::GlobalForm,group::CenterSubgroup,group::GroupIdand the central-character admissibility predicategroup::GroupId::admits. - su2
- Exact SU(2) recoupling: doubled-spin labels (
dj = 2j), the infallible closed-form Wigner 3j/6j, Clebsch–Gordan, F/R/Frobenius–Schur functions (exact zero for an inadmissible tuple), and an additive checked surface (su2::Su2Irrep,su2::wigner_6j_checked, …) that returns a typed error instead of requiring consumers to infer validity from a zero coefficient. Its items are re-exported at the crate root. Exact SU(2) recoupling coefficients: Wigner 3j, 6j, Clebsch-Gordan, F, R, the Frobenius-Schur indicator, and the canonical Regge key for 6j symbols. - sun
- SU(N),
SU(N)/Z_kandPSU(N): irreps from Dynkin labels, exact Weyl dimensions, duals, Littlewood–Richardson products, and the Clebsch–Gordan / F / R coefficients built by the Gelfand–Tsetlin construction. Compilation-gated behindcgc-gen. SU(N) irreps and their Clebsch–Gordan / recoupling coefficients, built by the Gelfand–Tsetlin (GT) construction.
Structs§
- Signed
Sqrt Rational - Signed square root of a nonnegative rational: the value
sign * sqrt(radicand).