.. SPDX-License-Identifier: MIT

Conventions
===========

Doubled Quantum Numbers
-----------------------

Most public functions accept angular momenta and projections as doubled
integers:

.. math::

   \texttt{two\_j}=2j, \qquad \texttt{two\_m}=2m.

Thus ``two_j = 1`` means :math:`j=1/2`, ``two_j = 2`` means :math:`j=1`,
and ``two_m = -3`` means :math:`m=-3/2`. Public parameter names use the
``two_`` prefix whenever this convention applies.

The complete compiled example is:

.. literalinclude:: examples/doubled_spin.cpp
   :language: cpp
   :linenos:

For a valid state, ``two_j`` is non-negative, ``abs(two_m) <= two_j``, and
``two_j`` and ``two_m`` have the same parity. The helper
``valid_spin_state`` checks all three conditions.

Orbital Exceptions
------------------

``gaunt`` and ``spherical_harmonic`` use ordinary integer ``l`` and ``m``.
These APIs describe orbital spherical harmonics, for which half-integer
angular momentum is not meaningful. Angles are always expressed in radians.

Phase and Normalization
-----------------------

The package follows the Condon-Shortley convention used by Varshalovich and
Edmonds. In particular,

.. math::

   \langle j_1m_1,j_2m_2\mid jm\rangle
   =(-1)^{j_1-j_2+m}\sqrt{2j+1}
   \begin{pmatrix}
      j_1&j_2&j\\m_1&m_2&-m
   \end{pmatrix}.

The Racah-W convention is

.. math::

   W(abcd;ef)=(-1)^{a+b+c+d}
   \left\{\begin{matrix}a&b&e\\d&c&f\end{matrix}\right\}.

The default three-body recoupling coefficient transforms
``((j1 j2)j12, j3)J`` to ``(j1, (j2 j3)j23)J`` and is

.. math::

   (-1)^{j_1+j_2+j_3+J}
   \sqrt{(2j_{12}+1)(2j_{23}+1)}
   \left\{\begin{matrix}
      j_1&j_2&j_{12}\\j_3&J&j_{23}
   \end{matrix}\right\}.

These definitions matter whenever values are compared with tables or another
software package. A disagreement by a sign can indicate a convention mismatch
rather than a numerical failure.

Rotations
---------

``wigner_D`` uses the Euler-angle factorization

.. math::

   D^j_{mn}(\alpha,\beta,\gamma)
   =e^{-im\alpha}d^j_{mn}(\beta)e^{-in\gamma}.

The reduced matrix ``d`` is real in this convention. The full matrix is
complex. Euler angles are accepted as ``double`` values in radians.

Invalid Inputs and Mathematical Zeros
-------------------------------------

Public numerical functions are ``noexcept``. A tuple that fails its spin,
projection-sum, or triangle selection rules returns zero. This behavior is
convenient during matrix assembly because a forbidden coupling contributes no
matrix element and does not require an exception path.

Zero is not, however, a validity flag. An admissible coefficient can vanish
mathematically. Use ``valid_spin_state``, ``triangle_condition``, and the
allowed-coupling helpers when code must distinguish a forbidden tuple from an
allowed zero.

Argument Order
--------------

Positional overloads follow the array displayed in each API's documentation.
The ``3j``, ``6j``, and ``9j`` APIs also accept named argument structs. The
struct form is preferable when a value is stored, passed between algorithms,
or assembled from a channel label because each member keeps its role visible.

The first- and second-kind ``12j`` functions accept only their corresponding
argument structs. Their ring ordering is documented with the declarations in
the :doc:`api` chapter.