Added documentation fro Groups module

src/Groups/AlgebraSU2.jl

@@ -11,11 +11,21 @@
 
 SU2alg(x::T)                       where T <: AbstractFloat = SU2alg{T}(x,0.0,0.0)
 SU2alg(v::Vector{T})               where T <: AbstractFloat = SU2alg{T}(v[1],v[2],v[3])
+
+"""
+    projalg([z::Complex,] g::T) where T <: Union{Group, GMatrix}
+
+Projects the group element/matrix `g` (or `zg`) to the algebra. This amounts to the following operation:
+
+\`\` X = {\\rm projalg}(g) = -X^a\\frac{1}{2} {\\rm tr}\\{T^a(g - g^{\\dagger})\\} \`\`
+
+where the substraction of group elements has to be understood in the matrix sense. This method returns an [`Algebra`](@ref) type. The generators of the algebra are the elements \`\` T^a\`\`. 
+"""
 projalg(g::SU2{T})                 where T <: AbstractFloat = SU2alg{T}(imag(g.t2), real(g.t2), imag(g.t1))
 projalg(z::Complex{T}, g::SU2{T})  where T <: AbstractFloat = SU2alg{T}(imag(z*g.t2), real(z*g.t2), imag(z*g.t1))
 dot(a::SU2alg{T}, b::SU2alg{T})    where T <: AbstractFloat = a.t1*b.t1 + a.t2*b.t2 + a.t3*b.t3
-norm(a::SU2alg{T})             where T <: AbstractFloat = sqrt(a.t1^2 + a.t2^2 + a.t3^2)
-norm2(a::SU2alg{T})            where T <: AbstractFloat = a.t1^2 + a.t2^2 + a.t3^2
+norm(a::SU2alg{T})                 where T <: AbstractFloat = sqrt(a.t1^2 + a.t2^2 + a.t3^2)
+norm2(a::SU2alg{T})                where T <: AbstractFloat = a.t1^2 + a.t2^2 + a.t3^2
 
 Base.:+(a::SU2alg{T})              where T <: AbstractFloat = SU2alg{T}(a.t1,a.t2,a.t3)
 Base.:-(a::SU2alg{T})              where T <: AbstractFloat = SU2alg{T}(-a.t1,-a.t2,-a.t3)
@@ -26,6 +36,11 @@ Base.:*(a::SU2alg{T},b::Number)    where T <: AbstractFloat = SU2alg{T}(a.t1*b,a
 Base.:*(b::Number,a::SU2alg{T})    where T <: AbstractFloat = SU2alg{T}(a.t1*b,a.t2*b,a.t3*b)
 Base.:/(a::SU2alg{T},b::Number)    where T <: AbstractFloat = SU2alg{T}(a.t1/b,a.t2/b,a.t3/b)
 
+"""
+    alg2mat(a::T) where T <: Algebra
+
+Returns the [`Algebra`](@ref) element as a [`GMatrix`](@ref) type.
+"""
 function alg2mat(a::SU2alg{T}) where T <: AbstractFloat
 
     u11::Complex{T} = complex(0.0, a.t3)/2
@@ -41,11 +56,10 @@ Base.:*(a::SU2,b::SU2alg) = a*alg2mat(b)
 Base.:/(a::SU2alg,b::SU2) = alg2mat(a)/b
 Base.:\(a::SU2,b::SU2alg) = a\alg2mat(b)
 
-
 """
-    function Base.exp(a::T, t::Number=1) where {T <: Algebra}
+    exp(a::T, t::Number=1) where {T <: Algebra}
 
-Computes `exp(a)`
+Computes `exp(ta)`
 """
 function Base.exp(a::SU2alg{T}) where T <: AbstractFloat
     
@@ -83,9 +97,9 @@ end
 
 
 """
-    function expm(g::G, a::A) where {G <: Algebra, A <: Algebra}
+    expm(g::G, a::A, t=1) where {G <: Group, A <: Algebra}
 
-Computes `exp(a)*g`
+Computes `g*exp(ta)`
 
 """
 function expm(g::SU2{T}, a::SU2alg{T}) where T <: AbstractFloat
@@ -105,12 +119,6 @@ function expm(g::SU2{T}, a::SU2alg{T}) where T <: AbstractFloat
     return SU2{T}(t1,t2)
 end
 
-"""
-    function expm(g::SU2, a::SU2alg, t::Float64)
-
-Computes `exp(t*a)*g`
-
-"""
 function expm(g::SU2{T}, a::SU2alg{T}, t::T) where T <: AbstractFloat
     
     rm = t*sqrt( a.t1^2+a.t2^2+a.t3^2 )/2.0

src/Groups/GroupSU2.jl

@@ -16,15 +16,39 @@
 using CUDA, Random
 
 SU2(a::T, b::T)          where T <: AbstractFloat = SU2{T}(complex(a), complex(b))
+
+"""
+    inverse(g::T) where T <: Group
+
+Returns the group inverse of `g`.
+"""
 inverse(b::SU2{T})       where T <: AbstractFloat = SU2{T}(conj(b.t1), -b.t2)
+
+"""
+    dag(g::T) where T <: Group
+
+Returns the group inverse of `g`.
+"""
 dag(a::SU2{T})           where T <: AbstractFloat = inverse(a)
 norm(a::SU2{T})          where T <: AbstractFloat = sqrt(abs2(a.t1) + abs2(a.t2))
 norm2(a::SU2{T})         where T <: AbstractFloat = abs2(a.t1) + abs2(a.t2)
-tr(g::SU2{T})            where T <: AbstractFloat = complex(2.0*real(g.t1), 0.0)
+
+"""
+    tr(g::T) where T <: Group
+
+Returns the trace of the groups element `g`.
+"""
+tr(g::SU2{T})            where T <: AbstractFloat = complex(2*real(g.t1), 0.0)
+
+"""
+    dev_one(T) where T <: Group
+
+Returns the distance to the unit group element
+"""
 dev_one(g::SU2{T})       where T <: AbstractFloat = sqrt(( abs2(g.t1 - one(T)) + abs2(g.t2))/2)
 
 """
-    function unitarize(a::T) where {T <: Group}
+    unitarize(a::T) where {T <: Group}
 
 Return a unitarized element of the group.
 """
@@ -40,6 +64,11 @@ Base.:*(a::SU2{T},b::SU2{T}) where T <: AbstractFloat = SU2{T}(a.t1*b.t1-a.t2*co
 Base.:/(a::SU2{T},b::SU2{T}) where T <: AbstractFloat = SU2{T}(a.t1*conj(b.t1)+a.t2*conj(b.t2),-a.t1*b.t2+a.t2*b.t1)
 Base.:\(a::SU2{T},b::SU2{T}) where T <: AbstractFloat = SU2{T}(conj(a.t1)*b.t1+a.t2*conj(b.t2),conj(a.t1)*b.t2-a.t2*conj(b.t1))
 
+"""
+    isgroup(g::T) where T <: Group
+
+Returns `true` if `g` is a group element, `false` otherwise.
+"""
 function isgroup(a::SU2{T}) where T <: AbstractFloat
     tol = 1.0E-10
     if (abs2(a.t1) + abs2(a.t2) - 1.0 < 1.0E-10)

src/Groups/GroupSU3.jl

@@ -12,7 +12,7 @@
 inverse(a::SU3{T})       where T <: AbstractFloat = SU3{T}(conj(a.u11),conj(a.u21),(a.u12*a.u23 - a.u13*a.u22), conj(a.u12),conj(a.u22),(a.u13*a.u21 - a.u11*a.u23))
 dag(a::SU3{T})           where T <: AbstractFloat = inverse(a)
 tr(a::SU3{T})            where T <: AbstractFloat = a.u11+a.u22+conj(a.u11*a.u22 - a.u12*a.u21)
-dev_one(g::SU3{T}) where T <: AbstractFloat = sqrt(( abs2(g.u11 - one(T)) + abs2(g.u12) + abs2(g.u13) + abs2(g.u21) + abs2(g.u22 - one(T)) + abs2(g.u23) )/6)
+dev_one(g::SU3{T})       where T <: AbstractFloat = sqrt(( abs2(g.u11 - one(T)) + abs2(g.u12) + abs2(g.u13) + abs2(g.u21) + abs2(g.u22 - one(T)) + abs2(g.u23) )/6)
 
 function unitarize(g::SU3{T}) where T <: AbstractFloat
 

src/Groups/GroupU1.jl

@@ -64,20 +64,9 @@ Base.:/(a::U1alg{T},b::Number)   where T <: AbstractFloat = U1alg{T}(a.t/b)
 
 isgroup(a::U1{T}) where T <: AbstractFloat = (abs(a.t) -1.0) < 1.0E-10
 
-"""
-    function Base.exp(a::U1alg, t::Number=1)
-
-Computes `exp(a)`
-"""
 Base.exp(a::U1alg{T}) where T <: AbstractFloat = U1{T}(CUDA.cos(a.t), CUDA.sin(a.t))
 Base.exp(a::U1alg{T}, t::T) where T <: AbstractFloat  = U1{T}(CUDA.cos(t*a.t), CUDA.sin(t*a.t))
 
-"""
-    function expm(g::U1, a::U1alg; t=1)
-
-Computes `exp(a)*g`
-
-"""
 expm(g::U1{T}, a::U1alg{T}) where T <: AbstractFloat = U1{T}(CUDA.cos(a.t), CUDA.sin(a.t))*g
 expm(g::U1{T}, a::U1alg{T}, t::T) where T <: AbstractFloat = U1{T}(CUDA.cos(t*a.t), CUDA.sin(t*a.t))*g
 

src/Groups/Groups.jl

@@ -16,10 +16,39 @@ using CUDA, Random
 import Base.:*, Base.:+, Base.:-,Base.:/,Base.:\,Base.exp,Base.one,Base.zero
 import Random.rand
 
+"""
+    abstract type Group
+
+This abstract type encapsulates group types (i.e. \`\`SU(N)\`\`). The following operations/methods are assumed to be defined for a each group.
+- `*,/,\\`: Usual group operations.
+- [`inverse`](@ref), [`dag`](@ref): The group inverse.
+- [`tr`](@ref)
+- [`dev_one`](@ref)
+- [`unitarize`](@ref)
+- [`isgroup`](@ref)
+- [`projalg`](@ref)
+"""
 abstract type Group end
+
+"""
+    abstract type Algebra
+
+This abstract type encapsulates algebra types  (i.e. \`\` {\\rm su}(N)\`\`). The following operations/methods are assumed to be defined for each algebra:
+- `+,-`: Usual operation of Algebra elements.
+- `*,/`: Multiplication/division by Numbers
+- `*`: Multiplication of [`Algebra`](@ref) and [`Group`](@ref) or [`GMatrix`](@ref) elements. These routines use the matrix form of the group elements, and return a [`GMatrix`](@ref) type.
+- [`exp`](@ref), [`expm`](@ref): Exponential map. Returns a [`Group`](@ref) element.
+"""
 abstract type Algebra end
 
-export Group, Algebra
+"""
+    abstract type GM
+
+This abstract type encapsulates \`\` N\\times N \`\` matrix types. The usual matrix operations (`+,-,*,/`) are expected to be defined for this case.
+"""
+abstract type GMatrix end
+
+export Group, Algebra, GMatrix
 
 ##
 # SU(2) and 2x2 matrix operations

src/Groups/SU2Types.jl

@@ -9,18 +9,34 @@
 ### created: Sun Oct  3 09:22:48 2021
 ###                               
 
+
+"""
+    struct SU2{T} <: Group
+
+\`\`SU(2)\`\` elements. The type `T <: AbstractFloat` can be used to define single or double precision elements.
+"""
 struct SU2{T} <: Group
     t1::Complex{T}
     t2::Complex{T}
 end
 
-struct M2x2{T}
+"""
+    struct M2x2{T} <: GMatrix
+
+Generic \`\` 2\\times 2\`\` complex matrix.
+"""
+struct M2x2{T} <: GMatrix
     u11::Complex{T}
     u12::Complex{T}
     u21::Complex{T}
     u22::Complex{T}
 end
 
+"""
+    struct SU2alg{T} <: Algebra
+
+\`\`{\\rm su}(2)\`\` Algebra elements.
+"""
 struct SU2alg{T} <: Algebra
     t1::T
     t2::T

src/Groups/SU3Types.jl

@@ -20,6 +20,11 @@
 
 import Base.convert
 
+"""
+    struct SU3{T} <: Group
+
+\`\`SU(3)\`\` elements. The type `T <: AbstractFloat` can be used to define single or double precision elements.
+"""
 struct SU3{T} <: Group
     u11::Complex{T}
     u12::Complex{T}
@@ -30,7 +35,12 @@ struct SU3{T} <: Group
 end
 Base.one(::Type{SU3{T}}) where T <: AbstractFloat = SU3{T}(one(T),zero(T),zero(T),zero(T),one(T),zero(T))
 
-struct M3x3{T} 
+"""
+    struct M3x3{T} <: Group
+
+3x3 Complex matrix. The type `T <: AbstractFloat` can be used to define single or double precision elements.
+"""
+struct M3x3{T} <: GMatrix
     u11::Complex{T}
     u12::Complex{T}
     u13::Complex{T}
@@ -44,6 +54,11 @@ end
 Base.one(::Type{M3x3{T}}) where T <: AbstractFloat = M3x3{T}(one(T),zero(T),zero(T),zero(T),one(T),zero(T),zero(T),zero(T),one(T))
 Base.zero(::Type{M3x3{T}}) where T <: AbstractFloat = M3x3{T}(zero(T),zero(T),zero(T),zero(T),zero(T),zero(T),zero(T),zero(T),zero(T))
 
+"""
+    struct SU3alg{T} <: Group
+
+\`\`su(3)\`\` elements. The type `T <: AbstractFloat` can be used to define single or double precision elements.
+"""
 struct SU3alg{T} <: Algebra
     t1::T
     t2::T

src/LatticeGPU.jl

@@ -15,7 +15,7 @@ module LatticeGPU
 include("Groups/Groups.jl")
 
 using .Groups
-export Group, Algebra
+export Group, Algebra, GMatrix
 export SU2, SU2alg, SU3, SU3alg, M3x3, M2x2, U1, U1alg, SU3fund
 export dot, expm, exp, dag, unitarize, inverse, tr, projalg, norm, norm2, isgroup, alg2mat, dev_one