.. SPDX-License-Identifier: MIT

Rotations and Spherical Harmonics
=================================

Wigner d Matrices
-----------------

``wigner_d(two_j, two_m, two_n, beta)`` evaluates the real reduced rotation
matrix element :math:`d^j_{mn}(\beta)`. Angular-momentum arguments are doubled
integers and ``beta`` is in radians.

.. code-block:: cpp

   const double value = wigner::wigner_d(2, 2, 0, beta);

Here the call requests :math:`d^1_{1,0}(\beta)`. Invalid spin states return
zero. For fixed ``j`` and ``beta``, the reduced Wigner matrix is real and
orthogonal:

.. math::

   \sum_{n=-j}^{j}
   d^j_{mn}(\beta)d^j_{m'n}(\beta)
   =\delta_{mm'}.

Equivalently, its columns obey

.. math::

   \sum_{m=-j}^{j}
   d^j_{mn}(\beta)d^j_{mn'}(\beta)
   =\delta_{nn'}.

The familiar row-normalization relation follows from the first equation by
setting :math:`m'=m`.

Wigner D Matrices
-----------------

``wigner_D`` adds the outer Euler-angle phases and returns
``std::complex<double>``:

.. code-block:: cpp

   const auto value = wigner::wigner_D(
       two_j, two_m, two_n,
       alpha, beta, gamma);

The convention is stated explicitly in :doc:`conventions`. This is important
when using these matrices to rotate helicity amplitudes or define subduction
coefficients, since active/passive rotation choices can complex-conjugate the
result.

The full matrix is unitary rather than merely real-orthogonal:

.. math::

   \sum_{n=-j}^{j}
   D^j_{mn}(\alpha,\beta,\gamma)
   D^{j*}_{m'n}(\alpha,\beta,\gamma)
   =\delta_{mm'}.

SU(2) Characters
----------------

``character(two_j, omega)`` evaluates

.. math::

   \chi^j(\omega)=
   \frac{\sin[(2j+1)\omega/2]}{\sin(\omega/2)}.

The removable limits at zero, :math:`\pi`, and :math:`2\pi` are handled
explicitly. Characters are useful for representation checks and group
projection formulas without constructing the complete rotation matrix.

Complex Spherical Harmonics
---------------------------

``spherical_harmonic`` implements standard complex
:math:`Y_l^m(\theta,\phi)` with the Condon-Shortley phase. Unlike the Wigner
symbols, ``l`` and ``m`` are ordinary integers.

The angular overload accepts ``theta`` and ``phi``. The Cartesian overload
accepts ``x``, ``y``, and ``z`` and uses only the vector's direction:

.. code-block:: cpp

   const auto angular = wigner::spherical_harmonic(l, m, theta, phi);
   const auto cartesian = wigner::spherical_harmonic(l, m, x, y, z);

The complete example evaluates both forms at the same direction:

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

At the zero Cartesian vector, no direction exists; the implementation returns
zero rather than choosing an arbitrary axis.

Gaunt Coefficients
------------------

``gaunt`` evaluates the integral of three complex spherical harmonics,

.. math::

   \int d\Omega\,
   Y_{l_1m_1}(\Omega)Y_{l_2m_2}(\Omega)Y_{l_3m_3}(\Omega),

through two Wigner ``3j`` symbols. It is nonzero only when the projection sum
vanishes, the orbital angular momenta satisfy the triangle condition, and
:math:`l_1+l_2+l_3` is even.

.. code-block:: cpp

   const double integral = wigner::gaunt(
       l1, m1, l2, m2, l3, m3);

Using ``gaunt`` instead of reproducing the formula in client code keeps the
spherical-harmonic and Wigner-symbol phase conventions synchronized.