.. SPDX-License-Identifier: MIT

Command-Line Tools
==================

Purpose
-------

The optional tools print coefficients, coupling tables, and rotation matrices
for quick inspection. They are intended for convention checks, teaching, and
small reference tables. Analysis code should call the library directly.

Build them with ``WIGNER_BUILD_EXECUTABLES=ON``. A normal top-level build and
``./scripts/build.sh`` already enable them. Installed tools are placed in the
installation prefix's ``bin`` directory.

All angular-momentum command-line arguments use doubled notation.

Coupling and 3j Tools
---------------------

``print_cg`` prints Clebsch-Gordan coefficients for two input angular momenta
and either one specified or every allowed coupled momentum:

.. code-block:: console

   print_cg <two_j1> <two_j2> [two_j]

``print_cg_table`` scans canonical rows for a selected output momentum:

.. code-block:: console

   print_cg_table <target_two_j> [--two-j-max=N] [--all-rows]

``print_3j`` prints the magnetic-projection table for a fixed angular-momentum
triple:

.. code-block:: console

   print_3j <two_j1> <two_j2> <two_j3>

``print_3j_table`` performs a broader canonical scan ending at the requested
third angular momentum:

.. code-block:: console

   print_3j_table <target_two_j3> [--two-j-max=N] [--all-rows]

The ``--all-rows`` option retains rows whose coefficients vanish; by default,
table output focuses on nonzero content.

6j and 9j Tools
---------------

``print_6j`` and ``print_9j`` evaluate one symbol in the standard displayed
layout:

.. code-block:: console

   print_6j <two_a> <two_b> <two_c> <two_d> <two_e> <two_f>
   print_9j <two_a> <two_b> <two_c> <two_d> <two_e> <two_f> \
            <two_g> <two_h> <two_i>

``print_6j_table`` and ``print_9j_table`` generate small canonical tables. The
default maximum doubled angular momentum is six and can be changed with
``--two-j-max=N`` or a positional integer:

.. code-block:: console

   print_6j_table --two-j-max=4
   print_9j_table 4

Canonical scans grow rapidly. Keep the requested maximum modest, particularly
for ``9j`` output.

Recoupling Tool
---------------

``print_recoupling`` prints admissible intermediate momenta and coefficients
for one of the supported three-angular-momentum coupling-scheme changes:

.. code-block:: console

   print_recoupling <two_j1> <two_j2> <two_j3> [two_J] \
       [--matrix] [--symbolic] [--scheme=12-23|12-13|13-23]

Without ``two_J``, the tool visits all allowed totals. ``--matrix`` prints the
complete transformation matrix. ``--symbolic`` supplements decimals with
simple square-root forms when recognized.

Rotations and Triangle Coefficients
-----------------------------------

``print_wigner_d_matrix`` prints a reduced rotation matrix for a fixed ``j``:

.. code-block:: console

   print_wigner_d_matrix <two_j> [--symbolic]

``print_triangle_table`` prints nonzero triangle coefficients up to a selected
maximum:

.. code-block:: console

   print_triangle_table [--two-j-max=N]

Reading Output Safely
---------------------

Tool output is presentation-oriented, not a stable machine-readable file
format. Scripts that need coefficients should link ``wigner::wigner`` and
write a format with an explicit schema. This avoids coupling an analysis to
column widths or symbolic-printing heuristics.