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

**URL:** <https://discourse.julialang.org/t/ann-qrecoupling-jl-exact-stable-evaluation-of-quantum-recoupling-symbols-fusion-tensors-and-q-hypergeometric-series/137135>\
**Category:** Package Announcements\
**Tags:** package, quantum, physics, math\
**Created:** [May 15, 2026, 5:31pm UTC](https://discourse.julialang.org/t/ann-qrecoupling-jl-exact-stable-evaluation-of-quantum-recoupling-symbols-fusion-tensors-and-q-hypergeometric-series/137135 "2026-05-15T17:31:16Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![seth](https://avatars.discourse-cdn.com/v4/letter/s/f14d63/32.png) [@seth](https://discourse.julialang.org/u/seth)\
**Post date:** [May 15, 2026, 5:31pm UTC](https://discourse.julialang.org/t/ann-qrecoupling-jl-exact-stable-evaluation-of-quantum-recoupling-symbols-fusion-tensors-and-q-hypergeometric-series/137135/1 "2026-05-15T17:31:16Z")

</div>

I’m happy to share [QRecoupling.jl](https://github.com/sethkasante/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:

```julia

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

- **GitHub:** [https://github.com/sethkasante/QRecoupling.jl](https://github.com/sethkasante/QRecoupling.jl)

- **Documentation:** [https://sethkasante.github.io/QRecoupling.jl/stable/](https://sethkasante.github.io/QRecoupling.jl/stable/)

- **Preprint:** [arXiv:2604.13196](https://arxiv.org/abs/2604.13196) (Details on the DCR mathematics)

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!

---

<div class="post-metadata">

**Author:** ![lkdvos](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lkdvos/32/43091_2.png) [@lkdvos](https://discourse.julialang.org/u/lkdvos)\
**Post date:** [May 19, 2026, 8:44pm UTC](https://discourse.julialang.org/t/ann-qrecoupling-jl-exact-stable-evaluation-of-quantum-recoupling-symbols-fusion-tensors-and-q-hypergeometric-series/137135/2 "2026-05-19T20:44:17Z")

</div>

Hi Seth, this definitely looks cool!

I have been experimenting a bit with these kinds of expressions in the past, and this would have definitely solved a lot of my issues then. I ended up just dealing with the numerical precision of `Float64` entries, and trying to avoid expressions that have are too ill-conditioned in favor of other variants. The context for me is that TensorKit.jl has support for (symmetric) tensor computations, where the symmetry can be a generic (unitary) fusion category. The implementation that glues the topological data is found in QWignerSymbols.jl. This is is useful for doing DMRG-like computations in for example the Heisenberg spin chain.

Anyways, I am no longer really using this myself all that much, but I would definitely be interested in seeing if the two could be connected, e.g. by making QWignerSymbols.jl depend on your package to provide the data instead. I probably wont have time to experiment with this myself, but I did want to let you know that this is definitely appreciated, and fits a cool spot in the community!

---

<div class="post-metadata">

**Author:** ![seth](https://avatars.discourse-cdn.com/v4/letter/s/f14d63/32.png) [@seth](https://discourse.julialang.org/u/seth)\
**Post date:** [May 20, 2026, 12:11am UTC](https://discourse.julialang.org/t/ann-qrecoupling-jl-exact-stable-evaluation-of-quantum-recoupling-symbols-fusion-tensors-and-q-hypergeometric-series/137135/3 "2026-05-20T00:11:36Z")

</div>

Hi Lukas,

Thank you so much for the kind words!  
It is great to hear from someone in the [TensorKit.jl](https://github.com/Jutho/TensorKit.jl) ecosystem. Dealing with the ill-conditioned numerical precision of generic floating-point tensors was exactly the original motivation for building the Deferred Cyclotomic Representation (DCR).

Connecting this package to [QWignerSymbols.jl](https://github.com/Jutho/QWignerSymbols.jl) to provide topological data for DMRG and symmetric tensor computations sounds like a fantastic use case. This is precisely where I was hoping this package could be useful!

I’m slowly working on building out `v0.4` (which will focus heavily on arbitrary tensor network contractions), I would love to take a look at the `QWignerSymbols.jl` source code and see what a backend integration or Pull Request would entail.

Thanks again for the encouragement and the context, it’s highly appreciated!