.. SPDX-License-Identifier: MIT

Numerical Design and Validation
===============================

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.

Independent Reference Checks
----------------------------

The implementation has been compared with GSL 2.8 over the following ranges:

.. list-table:: Numerical audit
   :header-rows: 1
   :widths: 20 52 28

   * - Quantity
     - Audit range
     - Largest absolute difference
   * - Wigner ``3j``
     - All admissible values with each ``two_j <= 30``
     - ``5.2e-14``
   * - Wigner ``6j``
     - Nonzero values with each ``two_j <= 14``
     - ``3.4e-16``
   * - Wigner ``9j``
     - Nonzero values with each ``two_j <= 5``
     - ``5.0e-16``

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 :math:`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.

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.

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.

Reproducible Validation
-----------------------

Run the complete local checks with:

.. code-block:: console

   ./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.