.. SPDX-License-Identifier: MIT

Selection Rules and Enumeration
===============================

Basic Predicates
----------------

``valid_spin_state(two_j, two_m)`` tests whether ``m`` is an allowed
projection of ``j``. ``triangle_condition(two_j1, two_j2, two_j3)`` tests the
SU(2) triangle inequalities and the integral-sum condition. Both functions are
``constexpr`` and ``noexcept``.

.. code-block:: cpp

   static_assert(wigner::valid_spin_state(3, -1));
   static_assert(wigner::triangle_condition(1, 1, 2));

Allowed Projections and Couplings
---------------------------------

``allowed_projections(two_j)`` returns ``2m`` values in ascending order from
``-two_j`` to ``two_j``. Invalid negative angular momentum produces an empty
vector.

``allowed_couplings(two_j1, two_j2)`` returns every admissible ``2J`` in
ascending order. The three specialized helpers also enforce coupling to a
specified total angular momentum:

* ``allowed_couplings_12`` enumerates intermediate ``j12``;
* ``allowed_couplings_13`` enumerates intermediate ``j13``; and
* ``allowed_couplings_23`` enumerates intermediate ``j23``.

For example:

.. code-block:: cpp

   for (int two_j12 : wigner::allowed_couplings_12(
            two_j1, two_j2, two_j3, two_J))
   {
       // Construct the ((j1 j2)j12, j3)J basis state.
   }

This is the preferred way to construct a coupling basis. It avoids evaluating
large rectangular collections that are known to vanish.

Canonical Symbol Arguments
--------------------------

The ``allowed_canonical_*_arguments`` functions enumerate one representative
from each implemented symmetry orbit up to a maximum doubled angular
momentum. They are useful for regression scans, compact reference tables, and
future cache-generation experiments.

.. code-block:: cpp

   const auto representatives =
       wigner::allowed_canonical_6j_arguments(max_two_j);

The ``3j`` canonicalization uses column permutations and simultaneous magnetic
projection reversal. The ``6j`` canonicalization uses tetrahedral column
symmetries. The ``9j`` canonicalization uses row permutations, column
permutations, and transposition. Current ``12j`` canonicalization uses cyclic
ring rotations and interchange of the ``j`` and ``l`` rows.

Scaling Warning
---------------

Canonical enumeration is intentionally exhaustive and grows rapidly with
``max_two_j``. The ``9j`` and especially ``12j`` helpers are designed for
small controlled scans, not for constructing a production channel basis at
large angular momentum.

In analysis code, construct the physically allowed coupling tree first with
the triangle helpers, then evaluate only the coefficients required by that
tree. This preserves the physical organization of the basis and scales much
better than scanning all symbol arguments.

Ordering Guarantees
-------------------

Projection and coupling vectors are returned in ascending numerical order.
Canonical argument vectors use deterministic lexicographic representatives.
These guarantees make tables and regression files reproducible, but they are
not a persistent serialization format. If a future application stores these
objects, it should write the named quantum numbers rather than relying on a
vector index.