FLUE_SU3MatrixOps

Module FLUE_SU3MatrixOps Purpose Provides high-performance, pure procedures for manipulating SU(3) matrices and vectors in the context of lattice gauge theory.

Physical Context: In lattice QCD, the fundamental dynamical variables are SU(3)-valued link matrices:

   U_mu(x) ∈ SU(3)

representing parallel transporters of the colour gauge field between neighbouring lattice sites. These matrices are unitary and have determinant equal to 1.

This module supports: - Algebra on SU(3) group elements (matrix multiplication, traces) - Operations in the Lie algebra su(3) (traceless Hermitian matrices) - Projection/reunitarisation of matrices back onto SU(3) - Conversion between matrix and generator (Gell-Mann) representations - Efficient computation of exp(iQ), used in gauge updates

Typical Use in Simulations:

Gauge field updates (heatbath, overrelaxation)
Projection of numerically drifted matrices back to SU(3)
Observables such as Wilson loops involving traces of products

Mathematical Conventions:

Matrices are 3x3 complex arrays.
Hermitian conjugate: A^\dagger = CONJG(TRANSPOSE(A))
Trace: Tr(A)
Generators: λ_i (Gell-Mann matrices)

Dependencies:

FLUE_constants: working precisions WC (complex), WP (real)
FLUE_matrixConstants: identity matrix Ident3x3

Notes:

All procedures are pure and suitable for parallel execution.
Explicitly unrolled operations improve performance on CPUs/GPUs.

Source: src/SU3MatrixOps.f90

Dependencies

orthogonalise_vectors
vector_product
FixSU3Matrix
normalise_vector
MultiplyMatMat
MultiplyMatMatDag
MultiplyMatdagMatdag
TraceMultMatMat
RealTraceMultMatMat
TraceLessConjgSubtract
colourDecomp
RealTraceMat
TraceMat
ExpIQ

Subroutines

orthogonalise_vectors

Orthogonalise a colour vector against another.

Physical Interpretation: Used during reunitarisation of SU(3) link matrices, where rows (or columns) must form an orthonormal basis in complex colour space.

Mathematics: $w \leftarrow w - v (v^{†} w)$

Attributes: pure

fortran

subroutine orthogonalise_vectors(w, v)

Arguments

Name	Type	Intent	Attributes	Description
`w`	complex(kind=WC)	inout	dimension(3)	Colour vector to be orthogonalised.
`v`	complex(kind=WC)	in	dimension(3)	Reference vector (typically already normalised).

Call graph

vector_product

Compute SU(3) vector product.

Physical Interpretation: Constructs a third orthogonal colour vector from two existing ones, analogous to a cross product, ensuring a complete orthonormal basis.

Mathematics: $x_{i} = c o n j u g a t e (v_{j} w_{k} - v_{k} w_{j})$ , cyclic indices.

Attributes: pure

fortran

subroutine vector_product(x, v, w)

Arguments

Name	Type	Intent	Attributes	Description
`x`	complex(kind=WC)	out	dimension(3)	Resulting orthogonal vector.
`v`	complex(kind=WC)	in	dimension(3)	v,w : input colour vectors.
`w`	complex(kind=WC)	in	dimension(3)	v,w : input colour vectors.

Call graph

FixSU3Matrix

Project a 3x3 matrix back onto SU(3).

Physical Interpretation: Numerical updates can cause link variables U_mu(x) to drift away from SU(3). This routine restores:

 - Unitarity: U U^\dagger = I
 - Determinant: det(U) ≈ 1

Method:

Gram-Schmidt orthonormalisation of rows
Third row constructed from SU(3) vector product

Usage: Typically called after each gauge update or smearing step.

Attributes: pure

fortran

subroutine FixSU3Matrix(U_x)

Arguments

Name	Type	Intent	Attributes	Description
`U_x`	complex(kind=WC)	inout	dimension(3, 3)	Gauge link matrix, overwritten with SU(3)-projected version.

Call graph

normalise_vector

Normalise a colour vector.

Physical Interpretation: Ensures unit norm of vectors forming SU(3) matrix rows/columns.

Mathematics: v <- v / sqrt(sum(|v_i|^2))

Attributes: pure

fortran

subroutine normalise_vector(v)

Arguments

Name	Type	Intent	Attributes	Description
`v`	complex(kind=WC)	inout	dimension(3)	vector which is normallised

Call graph

MultiplyMatMat

Multiply two SU(3) matrices.

Physical Interpretation: Represents sequential parallel transport of colour fields:

 U_total = U_1 * U_2

Common in staples, Wilson loops, and path-ordered products.

Arguments: left, right : input SU(3) matrices

MM : result

Attributes: pure

fortran

subroutine MultiplyMatMat(MM, left, right)

Arguments

Name	Type	Intent	Attributes	Description
`MM`	complex(kind=WC)	out	dimension(3, 3)	resulting matrix
`left`	complex(kind=WC)	in	dimension(3, 3)	input SU(3) matrices
`right`	complex(kind=WC)	in	dimension(3, 3)	input SU(3) matrices

Call graph

MultiplyMatMatDag

Multiply matrix by Hermitian conjugate.

Physical Interpretation: Appears in gauge-invariant quantities such as:

 U(x, μ) U^\dagger(x, μ)

Computes: MM = left * right^\dagger

Attributes: pure

fortran

subroutine MultiplyMatMatDag(MM, left, right)

Arguments

Name	Type	Intent	Attributes	Description
`MM`	complex(kind=WC)	out	dimension(3, 3)	Resulting matrix
`left`	complex(kind=WC)	in	dimension(3, 3)	Input SU(3) matrices
`right`	complex(kind=WC)	in	dimension(3, 3)	Input SU(3) matrices

Call graph

MultiplyMatdagMatdag

Compute dagger of matrix product.

Physical Interpretation: Used when reversing direction of transport paths in gauge loops.

Computes: MM = (left * right)^\dagger

Attributes: pure

fortran

subroutine MultiplyMatdagMatdag(MM, left, right)

Arguments

Name	Type	Intent	Attributes	Description
`MM`	complex(kind=WC)	out	dimension(3, 3)	Resulting Matrix
`left`	complex(kind=WC)	in	dimension(3, 3)	Input SU(3) matrices
`right`	complex(kind=WC)	in	dimension(3, 3)	Input SU(3) matrices

Call graph

TraceMultMatMat

Trace of a product of matrices.

Physical Interpretation: Used in evaluating gauge-invariant observables such as Wilson loops.

Computes: Tr(left * right)

Attributes: pure

fortran

subroutine TraceMultMatMat(TrMM, left, right)

Arguments

Name	Type	Intent	Attributes	Description
`TrMM`	complex(kind=WC)	out		Resulting (complex) trace
`left`	complex(kind=WC)	in	dimension(3, 3)	Input SU(3) matrices
`right`	complex(kind=WC)	in	dimension(3, 3)	Input SU(3) matrices

Call graph

RealTraceMultMatMat

Real trace of matrix product.

Physical Interpretation: Direct contribution to gauge action and observables.

Computes: Real(Tr(left * right))

Attributes: pure

fortran

subroutine RealTraceMultMatMat(RTrMM, left, right)

Arguments

Name	Type	Intent	Attributes	Description
`RTrMM`	real(kind=WP)	out		Resulting ReTrace
`left`	complex(kind=WC)	in	dimension(3, 3)	Input SU(3) Matrices
`right`	complex(kind=WC)	in	dimension(3, 3)	Input SU(3) Matrices

Call graph

TraceLessConjgSubtract

Traceless anti-Hermitian projection.

Physical Interpretation: Maps matrices into the Lie algebra su(3), required for: - Gauge updates

Computes: TrSub = left - right^\dagger TrSub <- TrSub - (1/3) Tr(TrSub) I

Result: Traceless matrix in su(3).

Attributes: pure

fortran

subroutine TraceLessConjgSubtract(TrSub, left, right)

Arguments

Name	Type	Intent	Attributes	Description
`TrSub`	complex(kind=WC)	out	dimension(3, 3)	Resulting traceless conjgugate subtraction matrix
`left`	complex(kind=WC)	in	dimension(3, 3)	Input SU(3) matrices
`right`	complex(kind=WC)	in	dimension(3, 3)	Input SU(3) matrices

Call graph

colourDecomp

Decompose matrix into Gell-Mann basis.

Physical Interpretation: Converts matrix representation into Lie algebra coefficients:

 A = sum_i com(i) λ_i

Useful for: - Analysing gauge fields - Constructing Lie algebra updates - Diagnostics and measurements

Arguments: A : SU(3) or general complex matrix

com : coefficients in Gell-Mann basis (8 generators)

Attributes: pure

fortran

subroutine colourDecomp(com, A)

Arguments

Name	Type	Intent	Attributes	Description
`com`	complex(kind=WC)	out	dimension(8)	Output coefficients in Gell-Mann basis
`A`	complex(kind=WC)	in	dimension(3, 3)	Input SU(3) matrice

Call graph

Functions

RealTraceMat

Real(Trace of a matrix.)

Physical Interpretation: Central observable in lattice QCD:

 - Action terms: Re Tr(U_plaquette)

Returns: Real trace.

Attributes: pure

Returns: real(kind=WP)

fortran

function RealTraceMat(left) result(TrMM)

Arguments

Name	Type	Intent	Attributes	Description
`left`	complex(kind=WC)	in	dimension(3, 3)	Input SU(3) matrix

Call graph

TraceMat

Trace of a matrix.

Physical Interpretation: Central observable in lattice QCD:

 - Wilson loops: Tr(path-ordered product)
 - Action terms: Re Tr(U_plaquette)

Attributes: pure

Returns: complex(kind=WC)

fortran

function TraceMat(left) result(TrMM)

Arguments

Name	Type	Intent	Attributes	Description
`left`	complex(kind=WC)	in	dimension(3, 3)	Input SU(3) matrix

Call graph

ExpIQ

Compute exponential of Lie algebra element.

Physical Interpretation: Core operation in gauge field evolution:

 U_new = exp(i Q) * U_old

where: Q ∈ su(3) is Hermitian and traceless (momentum field).

Used in: - Heatbath

Algorithm: Uses Cayley-Hamilton theorem to avoid explicit diagonalisation:

 exp(iQ) = f1 * I + f2 * Q + f3 * Q^2

with coefficients determined from invariants: c0 = (1/3) Tr(Q^3) c1 = (1/2) Tr(Q^2)

Numerical Stability:

Uses Taylor expansion for small eigenvalues
Clamps acos argument for safety
Handles sign structure explicitly

Arguments: Q : Hermitian, traceless matrix (su(3) element)

Returns: V : SU(3) matrix

Notes:

Produces unitary matrix up to numerical precision.
Avoids costly eigen-decomposition.

Attributes: pure

Returns: complex(kind=WC)

fortran

function ExpIQ(Q) result(V)

Arguments

Name	Type	Intent	Attributes	Description
`Q`	complex(kind=WC)	in	dimension(3, 3)	Input Hermitian, traceless (su(3) element)

Call graph

FLUE_SU3MatrixOps ​

Contents ​

Subroutines ​

orthogonalise_vectors ​

vector_product ​

FixSU3Matrix ​

normalise_vector ​

MultiplyMatMat ​

MultiplyMatMatDag ​

MultiplyMatdagMatdag ​

TraceMultMatMat ​

RealTraceMultMatMat ​

TraceLessConjgSubtract ​

colourDecomp ​

Functions ​

RealTraceMat ​

TraceMat ​

ExpIQ ​

FLUE_SU3MatrixOps

Contents

Subroutines

orthogonalise_vectors

vector_product

FixSU3Matrix

normalise_vector

MultiplyMatMat

MultiplyMatMatDag

MultiplyMatdagMatdag

TraceMultMatMat

RealTraceMultMatMat

TraceLessConjgSubtract

colourDecomp

Functions

RealTraceMat

TraceMat

ExpIQ