Clebsch-Gordan coefficient calculator

This project computes the Clebsch-Gordan coefficients for two input spin values, using symbolic math to maintain exact fractional results.

---

What it does

Given two spins $s_!$ and $s_2$, the script:

• Calculates all valid total spin states $J\in[|s_1-s_2|,s_1+s_2]$.
• For each total spin $J$, it:
  • Iterates over all valid magnetic quantum numbers $M\in[-J,J]$.
  • Expands the coupled state $|J,M>$ into the uncoupled basis $|s_1,m_1>|s_2,m_2>$ using Clebsch-Gordan coefficients.
  • Computes these coefficients using Wigner-3j symbols, which are evaluated exactly using symbolic factorials and square roots.

Example usage

Example Input:

Enter value for s1 (e.g., 1/2, 1, 3/2): 2 Enter value for s2 (e.g., 1/2, 1, 3/2): 1/2

Example Output:

Total spin J=3/2: |3/2,-3/2> = 2*sqrt(5)/5|2,-2>|1/2,1/2> - sqrt(5)/5|2,-1>|1/2,-1/2> |3/2,-1/2> = sqrt(15)/5|2,-1>|1/2,1/2> - sqrt(10)/5|2,0>|1/2,-1/2> |3/2,1/2> = sqrt(10)/5|2,0>|1/2,1/2> - sqrt(15)/5|2,1>|1/2,-1/2> |3/2,3/2> = sqrt(5)/5|2,1>|1/2,1/2> - 2*sqrt(5)/5|2,2>|1/2,-1/2> Total spin J=5/2: |5/2,-5/2> = -|2,-2>|1/2,-1/2> |5/2,-3/2> = -sqrt(5)/5|2,-2>|1/2,1/2> - 2sqrt(5)/5|2,-1>|1/2,-1/2> |5/2,-1/2> = -sqrt(10)/5|2,-1>|1/2,1/2> - sqrt(15)/5|2,0>|1/2,-1/2> |5/2,1/2> = -sqrt(15)/5|2,0>|1/2,1/2> - sqrt(10)/5|2,1>|1/2,-1/2> |5/2,3/2> = -2sqrt(5)/5|2,1>|1/2,1/2> - sqrt(5)/5|2,2>|1/2,-1/2> |5/2,5/2> = -|2,2>|1/2,1/2>

---

Dependencies

sympy - for symbolic math (exact fractions, square roots, factorials)

---

Background

This project implements well-known formulas and concepts from quantum mechancis:

• Per the Racah formula for the Wigner 3-j symbol, its value is the product of a prefactor term and a summation term:
  • The prefactor term is the product of the following terms:
    • The phase factor, $(-1)^{j_1 - j_2 - m_3}$
    • The triangle coefficient, $\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)! } }$
    • The square root of factorial terms, $\sqrt{ (j_1 + m_1)! , (j_1 - m_1)! , (j_2 + m_2)! , (j_2 - m_2)! , (j_3 + m_3)! , (j_3 - m_3)! }$
  • The summation term is given by:
    • $\sum_{k = k_{\min}}^{k_{\max}} \frac{(-1)^k}{k! ,(j_1 + j_2 - j_3 - k)! ,(j_1 - m_1 - k)! ,(j_2 + m_2 - k)! ,(j_3 - j_2 + m_1 + k)! ,(j_3 - j_1 - m_2 + k)!}$
    • ...with limits defined as:
      • $k_{min}=max(0,j_2-j_3-m_1,j_1-j_3+m_2)$
      • $k_{max}=min(j_1+j_2-j_3,j_1-m_1,j_2+m_2)$

• The expression for the Clebsch-Gordan coefficient $<j_1m_1j_2m_2|JM>$ is the product of the following terms:
  • The phase factor, $(-1)^{j_1 - j_2+M}$
    • (Note: This differs from the Wigner 3-j phase factor due to the $-M$ appearing in the Wigner 3-j argument)
  • The Wigner 3-j symbol $\begin{pmatrix} j_1 & j_2 & J \ m_1 & m_2 & -M \end{pmatrix}$
  • The square root factor $\sqrt{2J+1}$

---

Full code breakdown

• A function triangle_coeff(j1,j2,j3) is defined to compute the triangle coefficient (to ensure proper angular momentum coupling rules)
  • The triangle coefficient is found per the following formula: $\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)!}}$ (Racah formula's triangle relation)

• Another function wigner_3j is then defined to compute the Wigner 3-j expression
  • First, the selection rules are applied:
    • A check is carried out to apply the first selection rule, ie that the magnetic quantum numbers sum to zero.
    • The code checks if the sum is not equal to zero, returning 0 as the Wigner-3j symbol value if so (aka if the rule is violated).
    • The second selection rule ($m_i\leq j_i$) is then applied.
      • Each magnetic quantum number $m$ and corresponding total angular momentum $j$ is represented in a list by a tuple, and a generator expression is then used to loop throuh each pair, and check whether the magnitude of $m$ exceeds the corresponding $j$ (ie, if abs(m)>j), and returns 0.0 if so (aka, if any pair violates the $m_i\leq j_i$ rule).
    • Finally, the third selection rule is applied - checking to see whether the traingle inequality ($|j_1-j_2|\leq j_3\leq j_1+j_2$) is violated.
      • The code checks both parts of the expression for violation (ie, if $j_3<|j_1-j_2|$ or $j_3>j_1+j_2$), and returns 0 if so.
  • The next part of the function computes the Wigner-3j prefactor.
    • The first term (phase factor) is computed per the expression $(-1)^{j_1-j_2-m_3}$.
    • This is then multiplied by the second term (triangle coefficient).
    • And that product is then multiplied by the third term (square root of factorial terms) to find the overall prefactor value.
  • The next part of the function computes the summation term of the Wigner-3j expression - ie, $\sum_{k = k_{\min}}^{k_{\max}} \frac{(-1)^k}{k! ,(j_1 + j_2 - j_3 - k)! ,(j_1 - m_1 - k)! ,(j_2 + m_2 - k)! ,(j_3 - j_2 + m_1 + k)! ,(j_3 - j_1 - m_2 + k)!}$.
    • First, the valid range of k values (ie, $k_{max}$ and $k_{min}$) for the summation is computed to ensure all factorial terms in the denominator are non-negative, and the summation is initialised.
    • A for loop is then used to loop through each value k, compute the denominator for each, and add each $\frac{(-1)^k}{denominator}$ term to the summation (skipping where the denominator is zero as this would mean an invalid factorial).
  • Finally, the product of the prefactor term and the complex sum term (aka the Wigner-3j symbol is returned.

• Another function clebsch_gordan_coeff is then defined to compute the Clebsch-Gordan coefficient:
  • First, each input is converted to a rational number to keep fractions in exact form.
  • m3 is defined as -M, since that's how Wigner-3j symbols are defined in terms of Clebsch-Gordan.
  • The Wigner-3j function defined earlier is then called to calculate the Wigner 3-j symbol value.
  • A check is performed to see if the Wigner-3j symbol evaluates to zero, returning zero if this is the case as this would mean the Clebsch-Gordan coefficient would also be zero.
  • The phase factor is again calculated (taking into account m3=-M)
  • Finally, the function returns the product of the phase factor, the Wigner-3j symbol, and the square root factor (aka the Clebsch-Gordan coefficient).

• The user is then prompted to enter two spins values, which are then converted to Rationals.

• The total spin values (J_values) are then calculated per angular momentum rules, ie $J=|s_1-s_2|,|s_1-s_2|+1,...,|s_1+s_2|$.

• A for loop is then used to loop through each total spin J. For each J value:
  • A header is printed to state the total spin value.
  • The corresponding M values are found (per $M=-J,-J+1,...,J$).
  • Another for loop is then used to loop through each state $|J,M>$ to build its expansion in the uncoupled basis $|s_1,m_1>|s_2,m_2>$. For each state:
    • The state is printed.
    • A list to contain terms is initialised.
    • The m1 values for spin $s_1$ are found (per $m_1=-s_1,-s_1+1,...,s_1$).
    • A third for loop is then used to loop through each m1 value. For each m1:
      • The corresponding m2 is calculated per $m_2=M-m_1$ (since $M=m_1+m_2$)
      • A check is performed to ensure only valid values of m2 are allowed for.
      • The Clebsch-Gordan coefficient function defined earlier is then called, and if the result is non-zero, it is added to the list of terms.
    • Each resulting term is then printed.