Migration

To v0.5

q3j is the quantum 3j symbol

q3j is now the 3j symbol of U_q(sl₂): the q-Clebsch–Gordan coefficient qcg with the 3j phase and normalisation. It includes the deformation-dependent weights missing in v0.4. Classical values are unchanged; deformed values change, and level values are complex.

q3j and qcg support numerical evaluation and exact classical values through Exact(). Exact(k) and Symbolic() are not yet implemented for these weighted coefficients.

For existing code that requires the former formula, QRecoupling.q3j_factorial remains available with its previous targets.

Negative real q is complex

At negative real q every symbol uses the square-root branch of complex(q), so results are complex and agree with the same point supplied as complex. Positive real q, classical values and levels are unchanged.

using QRecoupling
q6j(1, 1, 1, 1, 1, 1; q = -0.8) == q6j(1, 1, 1, 1, 1, 1; q = complex(-0.8))

true

T is a precision floor in fmatrix

As in the scalar functions, T in fmatrix no longer narrows a complex or higher-precision result.

A smaller export list

These names are no longer exported. They still exist: call them as QRecoupling.name, or bring them in with using QRecoupling: name.

smatrix, tmatrix, bmatrix, twist, rmatrix and fmatrix remain exported.

DCR compatibility

The DCR constructors, monomial helpers, callback form of qseries, and raw projection functions remain available for existing code and are planned for retirement. New code should use FactorialSum or factorial-triple qseries, qeval, and the evaluation targets. value.dcr still constructs a compatibility representation lazily; callbacks must return cyclotomic monomials. The public phi_form(value) operation remains available for cyclotomic factorization.

New

qcg, qcg_matrix and qcg_row give coupling coefficients, whole coupling matrices and the coupled decomposition of a product state. qcg accepts its labels flat, qcg(j1, m1, j2, m2, j, m), or as pairs, qcg((j1, m1), (j2, m2), (j, m)).

To v0.4

Numerical defaults now include the product helpers

Symbol functions, qeval, qint, qfact, and qbinomial evaluate classically when no q or k is supplied. Code that used their return values as symbolic objects must request Symbolic() explicitly.

using QRecoupling
q6j(1,1,1,1,1,1)                      # approximately 1/6
q6j(Exact(),1,1,1,1,1,1)          # exact classical coefficient
s = q6j(Symbolic(),1,1,1,1,1,1)       # rule-backed symbolic x-form
qint(Symbolic(),5)

Exact value for generic q   (x = q + q⁻¹)
  = F(5) / (F(4))
  F(n) = ∏[r=1:n] U_{r-1}(x/2), with F(0) = 1
  1 term; the sum has not been expanded
  `x_form(v)` carries out the sum in x; `phi_form(v)` carries it out in q and factors it

SymbolicValue retains a factorial rule; it does not have the old monomial multiplication interface. Build product rules using factorial prefactors or expand with x_form when algebra is needed.

Exact classical evaluation

Prefer q6j(Exact(), js...) over q6j(js...; exact=true), and qeval(Exact(), rule) for a classical factorial sum. Exact() is an alias for Classical(exact=true) and preserves the existing exact result types and fast evaluator. It also works with the other recoupling symbols and product helpers.

exact=true and Classical(exact=true) remain supported without deprecation warnings in v0.4. A future release may deprecate the keyword after a migration period; this release does not remove it. Exact() takes no level or form option: use Exact(k) for level arithmetic, or Symbolic() for a generic formula.

Exact levels use x

v = q6j(Exact(10),1,1,1,1,1,1)
v

Exact value at level k = 10   (x = 2cos(π/12), degree 4 over ℚ)
  = (2x² − 7)/3

This also applies to k=10, exact=true for the recoupling and product functions. Read coefficients with v.x_value, QRecoupling.xpolynomial, and QRecoupling.radicand, request nested square roots with radical(v) (or v.rad), and convert numerically with Float64, BigFloat, or numeric_value. Printing shows the stored x-form; radicals and numerical approximations are explicit requests. radical returns RadExpr or a reasoned NoRadical result.

Exact(k; form=:canonical) retains the deprecated cyclotomic representation for compatibility. form=:deferred, ExactLevelWorkspace, canonicalize_exact, and dedicated Biedenharn–Elliott verifier functions from development drafts are not current APIs. Write identities from the public exact arithmetic as in the identity tutorial. Raw DCR/monomial projection remains a separate compatibility path; it is not automatically converted into an x-form by qeval(Symbolic(), object).

Symbolic output is bounded and lazy

Use x_form(value) to expand a symbolic rule. The earlier QRecoupling.xvalue(value) spelling is deprecated; value.x_value on an exact level result instead exposes its stored polynomials.

Symbolic expressions display their finite factorial rule in x without carrying out the sum, for both small and large labels. Radicals use ψ factors. x_form(value) explicitly expands and caches the generic formula, returning an owned copy.

Dimensions and theta graphs use this interface too. R matrices and twists retain QPhase objects with an explicit branch over x. A classical exact R value is an integer sign; a symbolic or exact-level R value remains a phase.

Targets and scratch storage

Level(k), Exact(), Exact(k), At(q), and Classical() select evaluation. Conflicting targets and keywords are rejected. exact=true requires a classical or level target; use Symbolic() for generic formulas.

EvaluationWorkspace() can be reused sequentially by supported scalar calls. Batches manage worker workspaces automatically. eager=true is deprecated and delegates to the standard rule evaluator; it does not enable a different fast path.