[ANN] QRecoupling.jl: Exact & stable evaluation of quantum recoupling symbols, fusion tensors and q-hypergeometric series

Package Announcements
, , ,
1

Iā€™m happy to share QRecoupling.jl, a new Julia package for the exact and numerically stable evaluation of quantum recoupling coefficients ( quantum 3j- and 6j-symbols), topological fusion data (F-symbols, R-matrices), and general q-hypergeometric series.

It supports evaluations at roots of unity (e.g., \mathrm{SU}(2)_k model) as well as for generic q \in \mathbb{C}^\times.

The Problem

Direct evaluation of q-deformed symbols is highly unstable. Because these amplitudes are alternating sums of massive quantum factorials, standard approaches suffer from these bottlenecks:

  • Standard Numerics (Float64): Catastrophic cancellation destroys all significant digits at moderate spins.

  • Standard Symbolic (CAS): Expanding q-factorials as rational polynomials triggers massive intermediate expression swell, leading to GB-scale memory limits.

The Solution: Deferred Cyclotomic Representation (DCR)

QRecoupling.jl avoids both issues by fundamentally changing the order of operations. Instead of the standard expand ā†’ cancel ā†’ evaluate pipeline, we do:

factor ā†’ exact cancellation ā†’ evaluate

The package compiles each amplitude once into a Deferred Cyclotomic Representationā€”a sparse integer-exponent vector over the basis of irreducible cyclotomic polynomials \Phi_d(q^2). All cancellations happen symbolically and exactly at the integer-exponent level before any field evaluation occurs.

Why this matters (The Performance):

For a symmetric 6j-symbol at j=120:

  • Standard exact polynomial methods exceed 50 GB of memory usage.

  • DCR construction takes ~50 KB, and exact cyclotomic evaluation completes using < 400 MB.

  • For numerical evaluation, the DCR compresses the dynamic range of intermediate terms by thousands of orders of magnitude, vastly extending the accuracy of Float64.

Quick Example: Compile Once, Evaluate across many regimes

Because the DCR isolates the algebraic structure, the same compiled object can be seamlessly projected into different regimes:


using QRecoupling

julia> ex1 = q6j(1,1,1,1,1,1);

# Float64 evaluation (uses optimized Log-Sum-Exp)

julia> qeval(ex1,k=10)

0.1547005383792515

#Alternatively, get full evaluation directly

julia> q6j(1,1,1,1,1,1, k=10)

0.1547005383792515

# Exact algebraic evaluation in the cyclotomic field Q(Ī¶_n) via `Nemo.jl`

julia> qeval(ex1,k=10, exact=true)

Exact Algebraic Result in ā„š(Ī¶ā‚‚ā‚„):

Value: (-2//3*Ī¶^6 + 4//3*Ī¶^2 - 1)

# The Classical limit (q ā†’ 1)

julia> qeval(ex1,q=1)

0.16666666666666663

# The Classical limit (q ā†’ 1) compatible with `WignerSymbols.jl`

julia> q6j(2,2,2,2,2,2, q=1.0, exact=true)

-3//70

# F-symbol

julia> fsymbol(5,5,5,5,4,4, k=50)

0.40931278202373267

# deferred fractional phase

julia> rmatrix(1/2, 1/2, 1, exact=true)

q^(1//2)

Who might find this useful?

  • Mathematical Physics & Quantum Gravity: Turaev-Viro invariants and state sum models require summing 6j-symbols over all admissible colorings. The zero-allocation, thread-safe architecture of QRecoupling.jl makes massive, large-k state-sum contractions computationally tractable.

  • Topological Quantum Computation: F-symbols and R-matrices for non-abelian anyon models are directly available with exact algebraic outputs, perfect for verifying coherence identities.

  • Special Functions & Combinatorics: The underlying DCR engine can handle arbitrary q-hypergeometric series (e.g. {}_{r}\Phi_s), offering a new way to precondition combinatorial sums.

Links

If you work with q-series, q-deformed quantum gravity, spin foams, or tensor categories, Iā€™d love your feedback. Issues, ideas, and PRs are all very welcome!

2 Likes