6. Numerical Design and Validation
6.1. Floating-Point Policy
Coefficient evaluators are runtime double functions. Factorials and
binomial coefficients are also represented in double so the implementation
does not inherit the small signed-integer overflow range of the historical
code.
The factorial cache contains finite values through 170!. Direct Racah-style
formulas combine these values with alternating sums. This is simple and
effective for the low and moderate angular momenta expected in current
scattering analyses, but it is neither arbitrary precision nor an
asymptotically stable large-j backend.
6.2. Independent Reference Checks
The implementation has been compared with GSL 2.8 over the following ranges:
Quantity |
Audit range |
Largest absolute difference |
|---|---|---|
Wigner |
All admissible values with each |
|
Wigner |
Nonzero values with each |
|
Wigner |
Nonzero values with each |
|
The in-tree regression suite retains representative values from these audits.
It also tests selection rules, permutation symmetries, Clebsch-Gordan
orthogonality, recoupling matrices, spherical-harmonic identities, and a
finite, orthonormal Wigner-d matrix at \(j=10\).
These are tested ranges, not hard API limits. A value outside the table can be accurate, but the package does not claim a uniform error bound there.
6.3. The 12j Boundary
The first- and second-kind 12j implementations are checked with
selection-rule, symmetry, and internal factorization tests. Independent,
nontrivial published reference tables have not yet been incorporated into the
regression suite. Treat broad 12j production use as provisional until that
validation is complete.
6.4. Failure Modes at Large j
Direct factorial formulas eventually encounter three related problems:
factorial intermediates exceed the finite range of
double;large alternating terms lose digits through cancellation; and
a finite final coefficient can be assembled from non-finite intermediates.
Calculations substantially beyond the audited ranges should be compared with
an independent implementation. For a future large-j requirement, a
log-factorial, scaled-sum, recurrence, or established specialized backend is a
better direction than extending the current cache.
6.5. Reproducible Validation
Run the complete local checks with:
./scripts/build.sh
The tests use only the C++ standard library and stored reference values; GSL is
not a runtime or build dependency. WIGNER_WARNINGS_AS_ERRORS=ON is enabled
by the script so portability regressions are caught with the numerical tests.
When adding a new coefficient or algorithm, retain:
at least one independent nonzero reference value;
forbidden-input tests;
a symmetry or orthogonality identity; and
a test near the intended upper angular-momentum range.
This combination catches convention errors, indexing mistakes, and numerical range failures more reliably than a long list of isolated values alone.