Struct SU2

Source

pub struct SU2 { /* private fields */ }

Expand description

SU(2) group element represented as a 2×2 unitary matrix.

SU(2) is the group of 2×2 complex unitary matrices with determinant 1:

U ∈ SU(2)  ⟺  U†U = I  and  det(U) = 1

§Applications

Represents rotations and spin transformations
Acts on spinor fields: ψ → U ψ
Preserves inner products (unitarity)

Implementations§

Source §

impl SU2

Source

pub fn matrix(&self) -> &Array2<Complex64>

Access the underlying 2×2 unitary matrix

Source

pub fn identity() -> Self

Identity element: I₂

Source

pub fn pauli_x() -> Array2<Complex64>

Get Pauli X generator (σ_x / 2)

Returns: (1/2) * [[0, 1], [1, 0]]

Source

pub fn pauli_y() -> Array2<Complex64>

Get Pauli Y generator (σ_y / 2)

Returns: (1/2) * [[0, -i], [i, 0]]

Source

pub fn pauli_z() -> Array2<Complex64>

Get Pauli Z generator (σ_z / 2)

Returns: (1/2) * [[1, 0], [0, -1]]

Source

pub fn rotation_x(theta: f64) -> Self

Rotation around X-axis by angle θ

Uses closed form: U = cos(θ/2) I + i sin(θ/2) σ_x

Source

pub fn rotation_y(theta: f64) -> Self

Rotation around Y-axis by angle θ

Uses closed form: U = cos(θ/2) I + i sin(θ/2) σ_y

Source

pub fn rotation_z(theta: f64) -> Self

Rotation around Z-axis by angle θ

Uses closed form: U = cos(θ/2) I + i sin(θ/2) σ_z

Source

pub fn random_haar<R: Rng>(rng: &mut R) -> Self

Random SU(2) element uniformly distributed according to Haar measure

Requires the rand feature (enabled by default).

Samples uniformly from SU(2) ≅ S³ (the 3-sphere) using the quaternion representation and Gaussian sampling method.

§Mathematical Background

SU(2) is diffeomorphic to the 3-sphere S³ ⊂ ℝ⁴:

SU(2) = {(a,b,c,d) ∈ ℝ⁴ : a² + b² + c² + d² = 1}

represented as matrices:

U = [[a+ib,  c+id ],
     [-c+id, a-ib]]

§Haar Measure Sampling

To sample uniformly from S³:

Generate 4 independent standard Gaussian variables (μ=0, σ=1)
Normalize to unit length

This gives the uniform (Haar) measure on SU(2) due to the rotational invariance of the Gaussian distribution.

§References

Shoemake, K.: “Uniform Random Rotations” (Graphics Gems III, 1992)
Diaconis & Saloff-Coste: “Comparison Theorems for Random Walks on Groups” (1993)

§Examples

use lie_groups::SU2;
use rand::SeedableRng;

let mut rng = rand::rngs::StdRng::seed_from_u64(42);
let g = SU2::random_haar(&mut rng);

// Verify it's unitary
assert!(g.verify_unitarity(1e-10));

Source

pub fn inverse(&self) -> Self

Group inverse: U⁻¹ = U† (conjugate transpose for unitary matrices)

Source

pub fn conjugate_transpose(&self) -> Self

Hermitian conjugate transpose: U†

For unitary matrices U ∈ SU(2), we have U† = U⁻¹ This is used in gauge transformations: A’ = g A g†

Source

pub fn act_on_vector(&self, v: &[Complex64; 2]) -> [Complex64; 2]

Act on a 2D vector: ψ → U ψ

Source

pub fn trace(&self) -> Complex64

Trace of the matrix: Tr(U)

Source

pub fn distance_to_identity(&self) -> f64

Distance from identity (geodesic distance in Lie group manifold)

Computed as: d(U, I) = ||log(U)||_F (Frobenius norm of logarithm)

§Numerical Behavior

For valid SU(2) matrices, |Re(Tr(U))/2| ≤ 1 exactly. Small violations (within UNITARITY_VIOLATION_THRESHOLD) are clamped silently. Larger violations trigger a debug assertion, indicating matrix corruption.

Source

pub fn angle_and_axis(&self) -> (f64, [f64; 3])

Extract rotation angle θ and axis n̂ from SU(2) element.

For U = cos(θ/2)·I + i·sin(θ/2)·(n̂·σ), returns (θ, n̂).

§Returns

Tuple of:

angle: Rotation angle θ ∈ [0, 2π]
axis: Unit 3-vector n̂ = [n_x, n_y, n_z] (or [0,0,1] if θ ≈ 0)

§Usage in Topological Charge

For computing topological charge, the product F_μν · F_ρσ involves the dot product of the orientation axes: (n_μν · n_ρσ).

Source

pub fn verify_unitarity(&self, tolerance: f64) -> bool

Verify this is approximately in SU(2)

Checks both:

Unitarity: U†U ≈ I
Special: |det(U) - 1| < tolerance

Source

pub fn to_matrix(&self) -> [[Complex64; 2]; 2]

Convert to 2×2 array format

Source

pub fn from_matrix(arr: [[Complex64; 2]; 2]) -> Self

Create from 2×2 array format

Source

pub fn log_stable(&self) -> LogResult<Su2Algebra>

Compute logarithm using numerically stable atan2 formulation.

This is more stable than the standard log() method, especially for rotation angles approaching π. Uses atan2(sin(θ/2), cos(θ/2)) instead of acos(cos(θ/2)) for improved numerical conditioning.

§Stability Improvements

Angle θ	acos stability	atan2 stability
θ ≈ 0	Poor (derivative ∞)	Good
θ ≈ π/2	Good	Good
θ ≈ π	Good	Good

The atan2 formulation avoids the derivative singularity at θ = 0 where d(acos)/dx → ∞.

§Returns

Same as log(), but with improved numerical stability.

Source

pub fn log_with_condition(&self) -> ConditionedLogResult<Su2Algebra>

Compute logarithm with conditioning information.

Returns both the logarithm and a LogCondition structure that provides information about the numerical reliability of the result.

Unlike log(), this method also provides condition number information so callers can assess the numerical reliability of the result near the cut locus (θ → 2π, U → -I).

§Example

use lie_groups::SU2;

let g = SU2::rotation_x(2.9); // Close to π
let (log_g, cond) = g.log_with_condition().unwrap();

if cond.is_well_conditioned() {
    println!("Reliable result: {:?}", log_g);
} else {
    println!("Warning: condition number = {:.1}", cond.condition_number());
}

§Cut Locus Behavior

The SU(2) cut locus is at θ = 2π (U = -I), where sin(θ/2) = 0 and the axis is undefined. As θ → 2π, the condition number diverges as 1/sin(θ/2). The method still returns a result — it’s up to the caller to decide whether to use it based on the conditioning information.