.. SPDX-License-Identifier: MIT

Overview and Quick Start
========================

Purpose
-------

``wigner`` collects the SU(2) angular-momentum operations used repeatedly in
partial-wave, finite-volume, and scattering calculations. It is independent
of ADAT and of the other spectrum-suite packages, and its only library
requirement is the C++23 standard library.

The package provides:

* Wigner ``3j``, ``6j``, ``9j``, and first- and second-kind ``12j`` symbols;
* Clebsch-Gordan, Racah-W, and three-angular-momentum recoupling coefficients;
* Wigner little-``d`` and full-``D`` rotation matrices and SU(2) characters;
* complex spherical harmonics and Gaunt coefficients;
* selection rules and helpers for enumerating admissible couplings; and
* small command-line programs for inspecting coefficients and tables.

Numerical algorithms are compiled into a static library. The small discrete
selection rules remain ``constexpr`` so they can also be used while building
fixed bases at compile time.

Requirements
------------

A normal build needs:

* CMake 3.24 or newer; and
* a compiler with the C++23 language mode.

The project is routinely checked with AppleClang and GCC. Documentation adds
Doxygen, Python with the packages in ``docs/requirements.txt``, and, for the
PDF manual, a LaTeX distribution containing ``latexmk``.

Build and Test
--------------

From the package root, run:

.. code-block:: console

   ./scripts/build.sh

This performs a fresh strict build, runs the numerical tests, stages an
installation, and verifies that a separate CMake project can find and link the
installed archive. Documentation remains optional during routine work:

.. code-block:: console

   ./scripts/build.sh --docs

Use ``./scripts/build.sh --help`` for the complete short interface.

First Program
-------------

The aggregate header exposes the complete public API:

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

The integer arguments are deliberately doubled. For example, the call

.. code-block:: cpp

   wigner::wigner_3j(1, 1, 0, 1, -1, 0)

represents

.. math::

   \begin{pmatrix}
      \tfrac12 & \tfrac12 & 0 \\
      \tfrac12 & -\tfrac12 & 0
   \end{pmatrix}.

This convention represents both integer and half-integer quantum numbers
exactly without a rational-number type. It is developed carefully in
:doc:`conventions`.

Using Only What You Need
------------------------

Applications may include the umbrella header:

.. code-block:: cpp

   #include <wigner/wigner.hpp>

or a narrow header such as:

.. code-block:: cpp

   #include <wigner/clebsch_gordan.hpp>

The narrow form documents the actual dependency of a translation unit and can
reduce recompilation. Both forms link to the same target:

.. code-block:: cmake

   find_package(wigner CONFIG REQUIRED)
   target_link_libraries(my_analysis PRIVATE wigner::wigner)

Where to Continue
-----------------

Read :doc:`conventions` before comparing signs with another implementation.
Then use :doc:`coefficients` for coupling and recoupling objects,
:doc:`rotations_harmonics` for angular functions, and :doc:`numerics` for the
tested range and current limitations. Installation and dependency patterns are
collected in :doc:`building`.