.. SPDX-License-Identifier: MIT

Coupling and Recoupling Coefficients
====================================

Selection Rules First
---------------------

Angular-momentum coefficients are sparse. Before evaluating a large table, it
is often clearer to construct only admissible labels with
``triangle_condition``, ``allowed_couplings``, and ``allowed_projections``.
Direct numerical calls remain safe for forbidden tuples and return zero.

Wigner 3j and Clebsch-Gordan
----------------------------

``wigner_3j`` accepts either six doubled integers or ``wigner_3j_args``.
The value vanishes unless every ``(j,m)`` pair is valid, the three angular
momenta satisfy the triangle condition, and
:math:`m_1+m_2+m_3=0`.

.. code-block:: cpp

   const wigner::wigner_3j_args args{
       1, 1, 0,
       1, -1, 0
   };
   const double symbol = wigner::wigner_3j(args);

``clebsch_gordan`` is evaluated from the same ``3j`` implementation and phase
convention. Use it when the coupled-state interpretation is more natural than
the symmetric ``3j`` notation:

.. code-block:: cpp

   const double cg = wigner::clebsch_gordan(
       1, 1,       // j1=1/2, m1=1/2
       1, -1,      // j2=1/2, m2=-1/2
       0, 0);      // J=0, M=0

Wigner 6j, Racah-W, and Recoupling
----------------------------------

``wigner_6j`` describes a change in the order used to couple three angular
momenta. It accepts positional values or ``wigner_6j_args``. The four triangle
conditions represented by the tetrahedral arrangement are enforced by the
evaluator.

``racah_w`` supplies the corresponding Racah notation with the phase fixed in
:doc:`conventions`. For basis transformations, the higher-level functions are
usually more readable:

* ``recoupling_12_23`` transforms the ``(12)3`` scheme to ``1(23)``;
* ``recoupling_12_13`` transforms the ``(12)3`` scheme to ``(13)2``;
* ``recoupling_13_23`` transforms the ``(13)2`` scheme to ``1(23)``; and
* ``recoupling`` is the established alias for ``recoupling_12_23``.

For example:

.. code-block:: cpp

   const double change_of_basis = wigner::recoupling_12_23(
       two_j1, two_j2, two_j12,
       two_j3, two_J, two_j23);

These functions include the square-root dimension factors and phase. Do not
multiply them by an additional Racah normalization.

Wigner 9j
---------

``wigner_9j`` represents recoupling between four-angular-momentum schemes and
is arranged as

.. math::

   \left\{\begin{matrix}
      a&b&c\\d&e&f\\g&h&i
   \end{matrix}\right\}.

The named struct is particularly useful here:

.. code-block:: cpp

   const wigner::wigner_9j_args args{
       two_a, two_b, two_c,
       two_d, two_e, two_f,
       two_g, two_h, two_i
   };
   const double value = wigner::wigner_9j(args);

Wigner 12j
----------

The package includes first- and second-kind ``12j`` symbols through
``wigner_12j_first`` and ``wigner_12j_second``. Both use ring-ordered argument
structs so the twelve entries cannot be mistaken for an undocumented
positional convention.

These implementations have selection-rule, symmetry, and internal
factorization tests. Their current validation is less extensive than for the
``3j``, ``6j``, and ``9j`` families. Consult :doc:`numerics` before using them
outside low-angular-momentum exploratory work.

Triangle Coefficient
--------------------

``triangle_coefficient`` evaluates

.. math::

   \Delta(a,b,c)=\sqrt{
      \frac{(a+b-c)!(a-b+c)!(-a+b+c)!}
           {(a+b+c+1)!}}

and returns zero when the triple is not admissible. It is exposed because it
is useful in direct formula checks and in algorithms built from the same
normalization as the Wigner-symbol backend.

Choosing an Interface
---------------------

Use direct symbols when implementing an equation written in ``3nj`` notation.
Use Clebsch-Gordan or recoupling functions when code represents a physical
basis transformation. This keeps dimension factors and phases in one tested
place and makes the intended coupling scheme visible to readers.