9. API Reference

This reference documents the public C++ interface exposed by include/wigner. Functions and argument structures are grouped under the wigner namespace; internal numerical helpers are intentionally omitted.

namespace wigner

Numerical SU(2) angular-momentum coefficients and selection rules.

Functions

std::vector<int> allowed_projections(int two_j)

Return all allowed magnetic projections for a fixed j.

The returned values are doubled projections 2m, ordered from -j to j.

Parameters:: two_j – 2j
Returns:: All admissible doubled projections 2m.

std::vector<wigner_3j_args> allowed_canonical_3j_arguments( int max_two_j )

Return canonical Wigner 3j arguments up to a maximum j.

Only one representative from each symmetry orbit is returned. Two argument sets are considered equivalent if they differ by:

a permutation of the three columns
the simultaneous sign flip m_i \mapsto -m_i

The representative chosen is the lexicographically smallest tuple (j1, j2, j3, m1, m2, m3) among those symmetry-related forms.

Parameters:: max_two_j – Maximum 2j to enumerate.
Returns:: Canonical admissible 3j argument sets.

std::vector<wigner_6j_args> allowed_canonical_6j_arguments( int max_two_j )

Return canonical Wigner 6j arguments up to a maximum j.

Only one representative from each tetrahedral symmetry orbit is returned. The canonical representative is the lexicographically smallest tuple (a,b,c,d,e,f) among the variants generated by column permutations and by interchanging the upper and lower entries in any two columns.

Parameters:: max_two_j – Maximum 2j to enumerate.
Returns:: Canonical admissible 6j argument sets.

std::vector<wigner_9j_args> allowed_canonical_9j_arguments( int max_two_j )

Return canonical Wigner 9j arguments up to a maximum j.

Only one representative from each symmetry orbit is returned, using row permutations, column permutations, and transpose symmetry. The chosen representative is the lexicographically smallest tuple (a,b,c,d,e,f,g,h,i) among those equivalent forms.

Parameters:: max_two_j – Maximum 2j to enumerate.
Returns:: Canonical admissible 9j argument sets.

std::vector<wigner_12j_first_args> allowed_canonical_12j_first_arguments( int max_two_j )

Return canonical 12j first-kind arguments up to a maximum j.

The current canonicalization uses the ring symmetries already exercised in the test suite: cyclic rotations and interchange of the j and l rows. The function is intended primarily for controlled enumeration in tests and future table-generation experiments.

Parameters:: max_two_j – Maximum 2j to enumerate.
Returns:: Canonical admissible first-kind 12j argument sets.

std::vector<wigner_12j_second_args> allowed_canonical_12j_second_arguments( int max_two_j )

Return canonical 12j second-kind arguments up to a maximum j.

As for the first-kind helper, the current canonicalization uses cyclic ring rotations and interchange of the j and l rows.

Parameters:: max_two_j – Maximum 2j to enumerate.
Returns:: Canonical admissible second-kind 12j argument sets.

std::vector<int> allowed_couplings(int two_j1, int two_j2)

Return all admissible coupled angular momenta for j1 \otimes j2.

The returned values are doubled angular momenta 2j, ordered from |j1-j2| up to j1+j2.

Arguments use doubled-spin notation.

Note

This is convenient when constructing coupled bases or when iterating over all channels contributing to a Clebsch-Gordan or recoupling table.

Parameters:

two_j1 – 2j1
two_j2 – 2j2

Returns:

All admissible doubled coupled angular momenta.

std::vector<int> allowed_couplings_12( int two_j1, int two_j2, int two_j3, int two_j )

Return all admissible j12 values for ((j1 j2)j12, j3)J.

Arguments use doubled-spin notation.

Parameters:

two_j1 – 2j1
two_j2 – 2j2
two_j3 – 2j3
two_j – 2J

Returns:

All admissible doubled intermediate angular momenta 2j12.

std::vector<int> allowed_couplings_13( int two_j1, int two_j2, int two_j3, int two_j )

Return all admissible j13 values for ((j1 j3)j13, j2)J.

Arguments use doubled-spin notation.

Parameters:

two_j1 – 2j1
two_j2 – 2j2
two_j3 – 2j3
two_j – 2J

Returns:

All admissible doubled intermediate angular momenta 2j13.

std::vector<int> allowed_couplings_23( int two_j1, int two_j2, int two_j3, int two_j )

Return all admissible j23 values for (j1, (j2 j3)j23)J.

Arguments use doubled-spin notation.

Parameters:

two_j1 – 2j1
two_j2 – 2j2
two_j3 – 2j3
two_j – 2J

Returns:

All admissible doubled intermediate angular momenta 2j23.

double clebsch_gordan( int two_j1, int two_m1, int two_j2, int two_m2, int two_j3, int two_m3 ) noexcept

Compute a Clebsch-Gordan coefficient in doubled-spin notation.

This is implemented from the standard relation to the Wigner 3j symbol rather than as a separate algorithm. Arguments use doubled-spin notation.

The coefficient vanishes unless the coupled state is admissible:

(j_1, m_1) and (j_2, m_2) are valid states,
(j_3, m_3) is a valid output state,
m_1 + m_2 = m_3,
(j_1, j_2, j_3) satisfies the triangle condition.

The phase convention used here is

\[\begin{split} \langle j_1 m_1, j_2 m_2 \mid j_3 m_3 \rangle = (-1)^{j_1 - j_2 + m_3}\sqrt{2j_3+1} \begin{pmatrix} j_1 & j_2 & j_3 \\ m_1 & m_2 & -m_3 \end{pmatrix}. \end{split}\]

Together with the explicit Racah sum for the 3j symbol, this gives the direct evaluation used by the library.

Note

Primary reference: Varshalovich, Moskalev, and Khersonskii, Quantum Theory of Angular Momentum, Section 8.7. See also Edmonds, Angular Momentum in Quantum Mechanics, for the phase convention relating Clebsch-Gordan coefficients and Wigner 3j symbols.

Parameters:

two_j1 – 2j1
two_m1 – 2m1
two_j2 – 2j2
two_m2 – 2m2
two_j3 – 2j3
two_m3 – 2m3

Returns:

The Clebsch-Gordan coefficient \(\langle j_1 m_1, j_2 m_2 \mid j_3 m_3 \rangle\).

double gaunt( int l1, int m1, int l2, int m2, int l3, int m3 ) noexcept

Compute a Gaunt coefficient for integer orbital angular momentum.

This is the integral of three standard complex spherical harmonics, expressed through Wigner 3j symbols.

The coefficient vanishes unless:

all l_k are integers,
all three states (l_k, m_k) are valid,
m_1 + m_2 + m_3 = 0,
(l_1, l_2, l_3) satisfies the triangle condition,
l_1 + l_2 + l_3 is even.

In terms of Wigner 3j symbols,

\[\begin{split} \begin{aligned} &\int Y_{l_1m_1}(\Omega)Y_{l_2m_2}(\Omega) Y_{l_3m_3}(\Omega)\,d\Omega \\ &\quad = \sqrt{\frac{(2l_1+1)(2l_2+1)(2l_3+1)}{4\pi}} \begin{pmatrix} l_1 & l_2 & l_3 \\ 0 & 0 & 0 \end{pmatrix} \begin{pmatrix} l_1 & l_2 & l_3 \\ m_1 & m_2 & m_3 \end{pmatrix}. \end{aligned} \end{split}\]

The Gaunt coefficient is invariant under any permutation of the three spherical harmonics, and also under simultaneous sign reversal of all magnetic quantum numbers.

Note

Primary reference: Varshalovich, Moskalev, and Khersonskii, Quantum Theory of Angular Momentum, Section 8.7.3. See also the relation between Gaunt coefficients and 3j symbols in Edmonds, Angular Momentum in Quantum Mechanics.

Parameters:

l1 – l1
m1 – m1
l2 – l2
m2 – m2
l3 – l3
m3 – m3

Returns:

The Gaunt coefficient

\[ \int Y_{l_1 m_1}(\Omega) Y_{l_2 m_2}(\Omega) Y_{l_3 m_3}(\Omega)\,d\Omega. \]

double racah_w( int two_a, int two_b, int two_c, int two_d, int two_e, int two_f ) noexcept

Compute the Racah-W coefficient in doubled-spin notation.

All angular momenta are passed as doubled integers. This function uses the convention

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

Arguments use doubled-spin notation.

Note

Primary reference: Varshalovich, Moskalev, and Khersonskii, Quantum Theory of Angular Momentum, Chapter 9. See also Edmonds, Angular Momentum in Quantum Mechanics.

Parameters:

two_a – 2a
two_b – 2b
two_c – 2c
two_d – 2d
two_e – 2e
two_f – 2f

Returns:

The Racah-W coefficient.

double recoupling_12_23( int two_j1, int two_j2, int two_j12, int two_j3, int two_j, int two_j23 ) noexcept

Compute the recoupling coefficient between ((j1 j2)j12, j3)J and (j1, (j2 j3)j23)J.

This is the standard 12-23 recoupling coefficient and matches the long-standing wigner::recoupling(...) default.

Arguments use doubled-spin notation.

Parameters:

two_j1 – 2j1
two_j2 – 2j2
two_j12 – 2j12
two_j3 – 2j3
two_j – 2J
two_j23 – 2j23

Returns:

The 12-23 recoupling coefficient.

double recoupling_12_13( int two_j1, int two_j2, int two_j12, int two_j3, int two_j, int two_j13 ) noexcept

Compute the recoupling coefficient between ((j1 j2)j12, j3)J and ((j1 j3)j13, j2)J.

Arguments use doubled-spin notation.

Parameters:

two_j1 – 2j1
two_j2 – 2j2
two_j12 – 2j12
two_j3 – 2j3
two_j – 2J
two_j13 – 2j13

Returns:

The 12-13 recoupling coefficient.

double recoupling_13_23( int two_j1, int two_j2, int two_j13, int two_j3, int two_j, int two_j23 ) noexcept

Compute the recoupling coefficient between ((j1 j3)j13, j2)J and (j1, (j2 j3)j23)J.

Arguments use doubled-spin notation.

Parameters:

two_j1 – 2j1
two_j2 – 2j2
two_j13 – 2j13
two_j3 – 2j3
two_j – 2J
two_j23 – 2j23

Returns:

The 13-23 recoupling coefficient.

double recoupling( int two_j1, int two_j2, int two_j12, int two_j3, int two_j, int two_j23 ) noexcept

Compute the three-angular-momentum recoupling coefficient in doubled-spin notation.

This function returns the transformation coefficient between the two coupling schemes

\[ ((j_1 j_2)j_{12}, j_3)JM \quad\text{and}\quad (j_1, (j_2 j_3)j_{23})JM. \]

Denoting this transformation coefficient by \(C_{12\to23}\), the convention used here is

\[\begin{split} \begin{aligned} C_{12\to23} &= (-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\} \\ &= \sqrt{(2j_{12}+1)(2j_{23}+1)} W(j_1 j_2 j j_3; j_{12}j_{23}). \end{aligned} \end{split}\]

Arguments use doubled-spin notation.

Note

Primary reference: Varshalovich, Moskalev, and Khersonskii, Quantum Theory of Angular Momentum, Chapter 9. See also Edmonds, Angular Momentum in Quantum Mechanics.

Parameters:

two_j1 – 2j1
two_j2 – 2j2
two_j12 – 2j12
two_j3 – 2j3
two_j – 2J
two_j23 – 2j23

Returns:

The recoupling coefficient.

constexpr bool valid_spin_state(int two_j, int two_m) noexcept

Check whether a doubled-spin state (two_j, two_m) is valid.

A valid state must have non-negative angular momentum, magnetic quantum number within the usual bounds, and matching parity between two_j and two_m.

Parameters:

two_j – Doubled total angular momentum, two_j = 2j.
two_m – Doubled magnetic quantum number, two_m = 2m.

Returns:

true if the state is admissible, false otherwise.

constexpr bool triangle_condition( int two_j1, int two_j2, int two_j3 ) noexcept

Check the triangle condition in doubled-spin notation.

This is the standard SU(2) admissibility condition for a triple of angular momenta. The parity check on two_j1 + two_j2 + two_j3 enforces that j1 + j2 + j3 is an integer.

Parameters:

two_j1 – Doubled angular momentum 2j1.
two_j2 – Doubled angular momentum 2j2.
two_j3 – Doubled angular momentum 2j3.

Returns:

true if the triple is triangular, false otherwise.

std::complex<double> spherical_harmonic( int l, int m, double theta, double phi ) noexcept

Compute the standard complex spherical harmonic \(Y_l^m(\theta,\phi)\).

The angular arguments are in radians. This helper is for ordinary orbital angular momentum, so the public API uses the natural integer quantum numbers l and m.

The convention is

\[ Y_l^m(\theta,\phi) = \sqrt{\frac{2l+1}{4\pi}} e^{i m \phi} d^l_{m0}(\theta), \]

which matches the Condon-Shortley phase convention used throughout the rest of the library.

Note

Primary reference: Varshalovich, Moskalev, and Khersonskii, Quantum Theory of Angular Momentum, Sections 4.1 and 4.16. This implementation is expressed through the Wigner d function in the same convention used throughout the library.

Parameters:

l – l
m – m
theta – Polar angle in radians.
phi – Azimuthal angle in radians.

Returns:

The complex spherical harmonic \(Y_l^m(\theta,\phi)\).

std::complex<double> spherical_harmonic( int l, int m, double x, double y, double z ) noexcept

Compute the standard complex spherical harmonic \(Y_l^m(\mathbf{r})\), interpreted as a function of the direction of a Cartesian vector.

This overload uses the direction of r = (x,y,z) and ignores its magnitude, in the same convention as the angular overload \(Y_l^m(\theta,\phi)\). Equivalently,

\[ Y_l^m(\mathbf{r}) = Y_l^m(\theta,\phi), \qquad \mathbf{r} = r(\sin\theta\cos\phi,\sin\theta\sin\phi,\cos\theta). \]

This is the direction-only spherical harmonic associated with the solid harmonics discussed in Varshalovich. The value is undefined at r = 0; this helper returns zero there.

Note

Primary reference: Varshalovich, Moskalev, and Khersonskii, Quantum Theory of Angular Momentum, Chapter 5, especially the discussion around the solid harmonics and the Cartesian form on p. 146 (printed page 133 in the scan).

Parameters:

l – l
m – m
x – Cartesian x component of the vector r.
y – Cartesian y component of the vector r.
z – Cartesian z component of the vector r.

Returns:

The complex spherical harmonic associated with the direction of (x,y,z).

double triangle_coefficient( int two_j1, int two_j2, int two_j3 ) noexcept

Compute the triangle coefficient \(\Delta(j_1,j_2,j_3)\) in doubled-spin notation.

The coefficient is

\[ \Delta(j_1,j_2,j_3) = \sqrt{ \frac{ (j_1+j_2-j_3)!\, (j_1-j_2+j_3)!\, (-j_1+j_2+j_3)! }{ (j_1+j_2+j_3+1)! } }. \]

It vanishes when the triple fails the usual triangle conditions.

Arguments use doubled-spin notation.

Note

Primary reference: Varshalovich, Moskalev, and Khersonskii, Quantum Theory of Angular Momentum, Chapter 8.

Note

The coefficient is evaluated at runtime in double precision. The discrete triangle test remains available for constant evaluation.

Parameters:

two_j1 – 2j1
two_j2 – 2j2
two_j3 – 2j3

Returns:

The triangle coefficient.

double wigner_12j_first(const wigner_12j_first_args &args) noexcept

Compute the 12j symbol of the first kind.

The implementation follows Wei’s factorized 3n-j formula for the first kind specialized to n = 4:

\[ \{12j\}_1 = \left(\prod\Delta\right) \sum_x (-1)^{S+3x}(2x+1)\prod_{r=1}^{4}R_r(x). \]

Here \(R_1(x)=[j_1\,l_1\,x;\,l_2\,j_2\,k_1]\), with the next two factors obtained by cycling the ring indices. The closing factor is \(R_4(x)=[j_4\,l_4\,x;\,j_1\,l_1\,k_4]\). Brackets denote the ordered binomial factor \(\mathcal{R}\) defined in the wigner_6j documentation; they do not denote a complete 6j symbol.

Arguments use doubled-spin notation.

Note

Primary reference: Wei and Dalgarno, J. Phys. A: Math. Gen. 37 (2004) 3259, equations (8)-(9), with n = 4. See also the 2013 corrigendum for the first-kind tabulations.

Warning

Independent nontrivial reference-table validation is still pending. Current tests cover selection rules, symmetries, and internal consistency of the factorized implementation.

Parameters:: args – Ring-ordered 12j arguments.
Returns:: The 12j symbol of the first kind.

double wigner_12j_second( const wigner_12j_second_args &args ) noexcept

Compute the 12j symbol of the second kind.

The implementation follows Wei’s factorized 3n-j formula for the second kind specialized to n = 4:

\[ \{12j\}_2 = \left(\prod\Delta\right) \sum_x (-1)^{S+4x}(2x+1)\prod_{r=1}^{4}R_r(x). \]

The first three ordered binomial factors match the first-kind ring. The closing factor is \(R_4(x)=[j_4\,l_4\,x;\,l_1\,j_1\,k_4]\).

Arguments use doubled-spin notation.

Note

Primary reference: Wei and Dalgarno, J. Phys. A: Math. Gen. 37 (2004) 3259, equations (10)-(11), with n = 4.

Warning

Independent nontrivial reference-table validation is still pending. Current tests cover selection rules, symmetries, and internal consistency of the factorized implementation.

Parameters:: args – Ring-ordered 12j arguments.
Returns:: The 12j symbol of the second kind.

double wigner_3j( int two_j1, int two_j2, int two_j3, int two_m1, int two_m2, int two_m3 ) noexcept

Compute the Wigner 3j symbol in doubled-spin notation.

Arguments are passed as integers two_j = 2j and two_m = 2m, so the same API supports both integer and half-integer angular momenta.

The symbol vanishes unless the usual SU(2) selection rules hold:

each pair (j_k, m_k) is a valid angular-momentum state,
m_1 + m_2 + m_3 = 0,
(j_1, j_2, j_3) satisfies the triangle condition,
j_1 + j_2 + j_3 is an integer.

Useful symmetries include any column permutation, with the phase (-1)^{j_1+j_2+j_3} for odd permutations, and simultaneous sign flip of all magnetic quantum numbers:

\[\begin{split} \begin{aligned} \begin{pmatrix} j_1 & j_2 & j_3 \\ m_1 & m_2 & m_3 \end{pmatrix} &= (-1)^{j_1+j_2+j_3} \begin{pmatrix} j_2 & j_1 & j_3 \\ m_2 & m_1 & m_3 \end{pmatrix} \\ &= (-1)^{j_1+j_2+j_3} \begin{pmatrix} j_1 & j_2 & j_3 \\ -m_1 & -m_2 & -m_3 \end{pmatrix}. \end{aligned} \end{split}\]

The implementation uses the standard direct Racah-style finite sum for the 3j symbol in the Condon-Shortley phase convention:

\[\begin{split} \begin{aligned} \begin{pmatrix} j_1 & j_2 & j_3 \\ m_1 & m_2 & m_3 \end{pmatrix} &= (-1)^{j_2-j_1-m_3}\Delta(j_1,j_2,j_3) \sqrt{A/B} \\ &\quad \times \sum_k (-1)^k \binom{j_1+j_2-j_3}{k} \binom{j_1-j_2+j_3}{j_1-m_1-k} \binom{-j_1+j_2+j_3}{j_2+m_2-k}, \end{aligned} \end{split}\]

where the sum runs over admissible integer values of \(k\) and

\[\begin{split} \begin{aligned} A &= (j_1+j_2-j_3)!(j_1-m_1)! (j_2-m_2)!(j_3-m_3)!, \\ B &= (j_1-j_2+j_3)!(-j_1+j_2+j_3)! \\ &\quad \times (j_1+m_1)!(j_2+m_2)!(j_3+m_3)!. \end{aligned} \end{split}\]

Note

Primary reference: Varshalovich, Moskalev, and Khersonskii, Quantum Theory of Angular Momentum, Sections 8.2-8.5. See also Edmonds, Angular Momentum in Quantum Mechanics. For an implementation-oriented binomial reformulation, see Wei, Computer Physics Communications 120 (1999) 222-230.

Note

The numerical Racah sum uses double-precision factorial and binomial intermediates. Values have been independently audited against GSL for all admissible tuples with each two_j <= 30.

Parameters:

two_j1 – 2j1
two_j2 – 2j2
two_j3 – 2j3
two_m1 – 2m1
two_m2 – 2m2
two_m3 – 2m3

Returns:

The Wigner 3j symbol

\[\begin{split} \begin{pmatrix} j_1 & j_2 & j_3 \\ m_1 & m_2 & m_3 \end{pmatrix} \end{split}\]

in standard phase convention.

double wigner_3j(const wigner_3j_args &args) noexcept

Compute the Wigner 3j symbol from a bundled argument struct.

Parameters:: args – Bundled 3j arguments.
Returns:: The same value as the positional wigner_3j(...) overload.

double wigner_6j( int two_a, int two_b, int two_c, int two_d, int two_e, int two_f ) noexcept

Compute the Wigner 6j symbol in doubled-spin notation.

As with wigner_3j, all angular momenta are passed as doubled integers so integer and half-integer values share one interface.

The symbol vanishes unless each of the four triples (a,b,c), (a,e,f), (d,b,f), and (d,e,c) satisfies the triangle condition.

It is invariant under any permutation of the columns and under interchange of the upper and lower entries in any two columns.

The standard Racah formula is

\[\begin{split} \begin{aligned} \left\{ \begin{matrix} a & b & c \\ d & e & f \end{matrix} \right\} &= \Delta(a,b,c)\Delta(d,e,c)\Delta(d,b,f)\Delta(a,e,f) \,\mathcal{S}(a,b,c;d,e,f), \\ \mathcal{S} &= \sum_n (-1)^n \frac{(n+1)!} {\prod_{r=1}^{4}(n-A_r)!\prod_{s=1}^{3}(B_s-n)!}. \end{aligned} \end{split}\]

The sum is restricted to admissible integer values of \(n\), with

\[\begin{split} \begin{aligned} (A_1,A_2,A_3,A_4) &= (a+e+f,\ b+d+f,\ c+d+e,\ a+b+c), \\ (B_1,B_2,B_3) &= (a+b+d+e,\ a+c+d+f,\ b+c+e+f). \end{aligned} \end{split}\]

Internally, the factorial sum is evaluated through the ordered binomial factor

\[\begin{split} \begin{aligned} \mathcal{R}(a,b,c;d,e,f) &= \Delta(a,e,f)^2\,\mathcal{S}(a,b,c;d,e,f) \\ &= \sum_n (-1)^n \binom{n+1}{n-A_1} \binom{C_1}{n-A_2} \binom{C_2}{n-A_3} \binom{C_3}{n-A_4}, \end{aligned} \end{split}\]

where

\[ (C_1,C_2,C_3)=(a+e-f,\ a-e+f,\ -a+e+f). \]

Thus the equivalent form used by the implementation is

\[\begin{split} \left\{ \begin{matrix} a & b & c \\ d & e & f \end{matrix} \right\} = \frac{\Delta(a,b,c)\Delta(d,e,c)\Delta(d,b,f)} {\Delta(a,e,f)} \,\mathcal{R}(a,b,c;d,e,f). \end{split}\]

The ordering of the six arguments is therefore part of the definition of \(\mathcal{R}\), even though the completed 6j symbol has the usual tetrahedral symmetries.

Note

Primary reference: Varshalovich, Moskalev, and Khersonskii, Quantum Theory of Angular Momentum, Sections 9.1-9.3. For an implementation-oriented binomial reformulation, see Wei, Computer Physics Communications 120 (1999) 222-230.

Note

The direct numerical formula uses double-precision combinatorial intermediates. Nonzero values with each two_j <= 14 have been independently audited against GSL.

Parameters:

two_a – 2a
two_b – 2b
two_c – 2c
two_d – 2d
two_e – 2e
two_f – 2f

Returns:

The Wigner 6j symbol

\[\begin{split} \left\{ \begin{matrix} a & b & c \\ d & e & f \end{matrix} \right\} \end{split}\]

in standard phase convention.

double wigner_6j(const wigner_6j_args &args) noexcept

Compute the Wigner 6j symbol from a bundled argument struct.

Parameters:: args – Bundled 6j arguments.
Returns:: The same value as the positional wigner_6j(...) overload.

double wigner_9j( int two_a, int two_b, int two_c, int two_d, int two_e, int two_f, int two_g, int two_h, int two_i ) noexcept

Compute the Wigner 9j symbol in doubled-spin notation.

All arguments are passed as doubled angular momenta so integer and half-integer values use the same interface.

The symbol vanishes unless every row and every column forms an admissible angular-momentum triple. It is invariant under even permutations of rows or columns and acquires the phase (-1)^{a+b+c+d+e+f+g+h+i} under odd row or column permutations.

The implementation follows a Racah-style finite sum over an intermediate angular momentum, written in terms of ordered binomial factors:

\[\begin{split} \begin{aligned} \left\{ \begin{matrix} a & b & c \\ d & e & f \\ g & h & i \end{matrix} \right\} &= \Delta(a,b,c)\Delta(d,e,f)\Delta(g,h,i) \Delta(a,d,g)\Delta(b,e,h)\Delta(c,f,i) \\ &\quad \times \sum_k (-1)^{2k}(2k+1) \big[ a\, b\, c;\, f\, i\, k \big] \big[ f\, d\, e;\, h\, b\, k \big] \big[ h\, i\, g;\, a\, d\, k \big], \end{aligned} \end{split}\]

where \([a\,b\,c;\,d\,e\,f]\) denotes the ordered factor \(\mathcal{R}(a,b,c;d,e,f)\) defined in the wigner_6j documentation. It is not itself a 6j symbol, and its argument ordering is significant.

Note

Primary reference: Varshalovich, Moskalev, and Khersonskii, Quantum Theory of Angular Momentum, Sections 10.1-10.3. The present computational form is closest to Wei, Computer Physics Communications 120 (1999) 222-230; see also Wei, Computers in Physics 12 (1998) 632-634 for the earlier 9j-specific formulation.

Note

The direct numerical formula uses double-precision ordered binomial factors. Nonzero values with each two_j <= 5 have been independently audited against GSL.

Parameters:

two_a – 2a
two_b – 2b
two_c – 2c
two_d – 2d
two_e – 2e
two_f – 2f
two_g – 2g
two_h – 2h
two_i – 2i

Returns:

The Wigner 9j symbol

\[\begin{split} \left\{ \begin{matrix} a & b & c \\ d & e & f \\ g & h & i \end{matrix} \right\} \end{split}\]

in standard phase convention.

double wigner_9j(const wigner_9j_args &args) noexcept

Compute the Wigner 9j symbol from a bundled argument struct.

Parameters:: args – Bundled 9j arguments.
Returns:: The same value as the positional wigner_9j(...) overload.

double wigner_d( int two_j, int two_m, int two_n, double beta ) noexcept

Compute the reduced Wigner rotation matrix element \(d^j_{mn}(\beta)\).

The angle beta is passed in radians. As elsewhere in this library, two_j = 2j, two_m = 2m, and two_n = 2n.

Note

Primary reference: Varshalovich, Moskalev, and Khersonskii, Quantum Theory of Angular Momentum, Sections 4.3-4.7.

Note

The direct factorial sum is evaluated at runtime in double precision. Regression tests verify a finite matrix with orthonormal rows and columns at j = 10.

Parameters:

two_j – 2j
two_m – 2m
two_n – 2n
beta – Euler angle beta in radians.

Returns:

The reduced Wigner rotation matrix element \(d^j_{mn}(\beta)\).

std::complex<double> wigner_D( int two_j, int two_m, int two_n, double alpha, double beta, double gamma ) noexcept

Compute the full Wigner rotation matrix element \(D^j_{mn}(\alpha,\beta,\gamma)\).

The Euler angles are passed in radians using the same phase convention as the reduced wigner_d implementation in detail. The angular-momentum arguments use doubled-spin notation.

Note

Primary reference: Varshalovich, Moskalev, and Khersonskii, Quantum Theory of Angular Momentum, Sections 4.3-4.7.

Note

The reduced matrix element is evaluated by wigner_d; the outer Euler-angle phases are applied in double-precision complex arithmetic.

Parameters:

two_j – 2j
two_m – 2m
two_n – 2n
alpha – Euler angle alpha in radians.
beta – Euler angle beta in radians.
gamma – Euler angle gamma in radians.

Returns:

The full Wigner rotation matrix element \(D^j_{mn}\).

double character(int two_j, double omega) noexcept

Compute the SU(2) character \(\chi^j(\omega)\).

The angular-momentum argument uses doubled-spin notation, two_j = 2j. The rotation angle omega is passed in radians.

Note

In closed form,

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

with the removable singular limits handled explicitly at omega = 0, pi, and 2pi.

Parameters:

two_j – 2j
omega – Rotation angle in radians.

Returns:

The SU(2) character \(\chi^j(\omega)\).

struct wigner_12j_first_args

#include <wigner_12j.hpp>

Arguments for a 12j symbol of the first kind.

The ordering follows the generic ring notation used in Wei’s factorized formulas for the 3n-j symbols of the first kind with n = 4:

\[\begin{split} \left\{ \begin{matrix} j_1 & j_2 & j_3 & j_4 \\ l_1 & l_2 & l_3 & l_4 \\ k_1 & k_2 & k_3 & k_4 \end{matrix} \right\}_1. \end{split}\]

All entries are supplied in doubled-spin notation.

This explicit bundle is used both by the public wigner_12j_first(...) overload and by the canonical argument enumerator allowed_canonical_12j_first_arguments(...).

struct wigner_12j_second_args

#include <wigner_12j.hpp>

Arguments for a 12j symbol of the second kind.

The ordering follows the generic ring notation used in Wei’s factorized formulas for the 3n-j symbols of the second kind with n = 4:

\[\begin{split} \left\{ \begin{matrix} j_1 & j_2 & j_3 & j_4 \\ l_1 & l_2 & l_3 & l_4 \\ k_1 & k_2 & k_3 & k_4 \end{matrix} \right\}_2. \end{split}\]

All entries are supplied in doubled-spin notation.

This explicit bundle is used both by the public wigner_12j_second(...) overload and by the canonical argument enumerator allowed_canonical_12j_second_arguments(...).

struct wigner_3j_args

#include <allowed_arguments.hpp>

Argument bundle for a Wigner 3j symbol.

All values use doubled-spin notation:

two_jk = 2jk
two_mk = 2mk

This struct is useful with wigner_3j(const wigner_3j_args&) and with the canonical argument enumerators used for testing and future precomputation experiments.

struct wigner_6j_args

#include <allowed_arguments.hpp>

Argument bundle for a Wigner 6j symbol.

The entries follow the standard 6j layout

\[\begin{split} \left\{ \begin{matrix} a & b & c \\ d & e & f \end{matrix} \right\} \end{split}\]

in doubled-spin notation.

struct wigner_9j_args

#include <allowed_arguments.hpp>

Argument bundle for a Wigner 9j symbol.

The entries follow the standard 9j layout

\[\begin{split} \left\{ \begin{matrix} a & b & c \\ d & e & f \\ g & h & i \end{matrix} \right\} \end{split}\]

in doubled-spin notation.