API reference

GroupFunctions.jl computes symbolic and numeric matrix elements of irreducible representations of U(d) and SU(d) using Gelfand-Tsetlin patterns and Young tableaux.

Repository: https://github.com/davidamaro/GroupFunctions.jl

Documentation: https://davidamaro.github.io/GroupFunctions.jl

group_function(λ::Irrep, tu::YoungTableau, tv::YoungTableau)

Returns the symbolic group function corresponding to irrep λ and Young tableaux tu and tv.

Example:

julia> t = YoungTableau([2,1]); fill!(t, [1,2,3]);
julia> group_function([2,1,0], t, t)

group_function(λ::Irrep, tab_u::YTableau, tab_v::YTableau) -> Basic

Compute group theoretical function based on Young tableaux and irreducible representations.

Arguments:

• λ::Irrep: Irreducible representation
• tab_u::YTableau: First Young tableau
• tab_v::YTableau: Second Young tableau

Returns:

• Complex: Group function evaluated

Notes:

• Uses SymEngine for symbolic computation
• Involves matrix operations and coset calculations

group_function(λ::Irrep, tu::GTPattern, tv::GTPattern)

Returns the symbolic group function corresponding to irrep λ and GT patterns tu and tv.

Example:

julia> t = GTPattern([[2,1,0],[2,1],[2]],[2]);
julia> group_function([2,1,0], t, t)

group_function(λ::Irrep, pat_u::GTPattern, pat_v::GTPattern) -> Basic

Compute group theoretical function based on Gelfand-Tsetlin patterns and irreducible representations.

Arguments:

• λ::Irrep: Irreducible representation
• pat_u::GTPattern: First Gelfand-Tsetlin pattern
• pat_v::GTPattern: Second Gelfand-Tsetlin pattern

Returns:

• Basic: Computed polynomial expression in SymEngine format

Notes:

• Converts GT patterns to Young tableaux for calculations
• Uses SymEngine for symbolic computation

group_function(λ::Irrep, i::Integer, j::Integer)

Return the symbolic group function for the i, j entry in the GT basis returned by basis_states(λ). This is equivalent to group_function(λ, basis_states(λ)[i], basis_states(λ)[j]).

group_function(λ::Irrep, pat_u::GTPattern, pat_v::GTPattern, mat::AbstractMatrix{T}) where T

Returns the group function for an SU(n) element mat, corresponding to irrep λ and a pair of GT patterns pat_u and pat_v. Converts GT patterns to Young tableaux and delegates to the main implementation.

julia> using RandomMatrices
julia> mat = rand(Haar(2),3)
julia> t = GTPattern([[2,1,0],[2,1],[2]],[2]);
julia> group_function([2,1,0], t, t, mat)

group_function(λ::Irrep, i::Integer, j::Integer, mat::AbstractMatrix{T}) where T

Return the group function for the i, j entry in the GT basis returned by basis_states(λ), evaluated on mat. This is equivalent to group_function(λ, basis_states(λ)[i], basis_states(λ)[j], mat).

group_function(λ::Irrep, tab_u::YTableau, tab_v::YTableau, mat::AbstractMatrix{T}) where T

Returns the group function for an SU(n) element mat, corresponding to irrep λ and Young tableaux tab_u and tab_v. For numeric mat (real or complex floating point), computes the group function numerically. Otherwise, uses exact coefficients internally, and the result is a polynomial in the entries of mat.

Example:

julia> using RandomMatrices
julia> mat = rand(Haar(2),3)
julia> t = YoungTableau([2,1]); fill!(t, [1,2,3]);
julia> group_function([2,1,0], t, t, mat)

group_function(λ::Irrep) -> Tuple{Matrix{Basic}, Vector{GTPattern}}

Compute all symbolic group functions associated with the partition λ. The routine builds every valid GT pattern for λ and evaluates the group function for each pair. For the trivial irrep [0, 0, ..., 0], the first tuple entry is the scalar 1 + 0im instead of a 1x1 matrix.

Arguments:

• λ::Irrep: Partition describing the irrep

Returns:

• Tuple: (values, patterns) where values[i,j] corresponds to group_function(λ, patterns[i], patterns[j]) and patterns is the basis returned by basis_states(λ)

group_function(λ::Irrep, mat::AbstractMatrix{T}) where T

Compute all group functions associated with the partition λ and a matrix mat. Generates the GT patterns for λ and evaluates every pair using the provided matrix. For numeric matrices, returns numeric values; for symbolic matrices, returns polynomials. For the trivial irrep [0, 0, ..., 0], the first tuple entry is the scalar one(eltype(mat)) instead of a 1x1 matrix.

Arguments:

• λ::Irrep: Partition describing the irrep
• mat::AbstractMatrix{T}: Matrix representing the SU(n) element

Returns:

• Tuple: (values, patterns) where values[i,j] corresponds to group_function(λ, patterns[i], patterns[j], mat) and patterns is the basis returned by basis_states(λ)

character(λ::Irrep) -> Basic

Compute the symbolic character of the irrep λ by summing the diagonal group functions over the GT basis. This avoids constructing the full representation matrix when only the trace is needed.

Arguments:

• λ::Irrep: Partition describing the irrep

Returns:

• Basic: Symbolic character polynomial in the entries of the implicit symbolic SU(n) matrix

character(λ::Irrep, mat::AbstractMatrix{T}) where T

Compute the character of the irrep λ evaluated on mat by summing only the diagonal group functions over the GT basis. For numeric matrices, the result is numeric; for symbolic matrices, the result is a symbolic polynomial.

Arguments:

• λ::Irrep: Partition describing the irrep
• mat::AbstractMatrix{T}: Matrix representing the SU(n) element

Returns:

• The character value with the same inferred type as the diagonal group functions for the provided matrix

schur_polynomial(λ::AbstractVector{<:Integer}; prefix::String = "x") -> Basic
schur_polynomial(λ::AbstractVector{<:Integer}; variables::AbstractVector)
schur_polynomial(λ::AbstractVector{<:Integer}, variables::AbstractVector)

Compute the Schur polynomial s_λ for the partition/top-row label λ. The length of λ sets the group dimension d, following the same convention as basis_states, group_function, and character for the one-argument symbolic method.

The one-argument method returns a symbolic polynomial in variables named x_1, ..., x_d by default. The two-argument method evaluates the same polynomial in the supplied variables, which may be numeric or symbolic. When variables are supplied explicitly, trailing zeroes in λ are ignored and shorter partitions are padded with zeroes to match the number of variables.

Mathematically this is the SU(d)/U(d) character evaluated on a diagonal matrix with diagonal entries variables.

Examples

julia> using GroupFunctions

julia> schur_polynomial([2, 0])
x_1*x_2 + x_1^2 + x_2^2

julia> schur_polynomial([2, 1, 0], [2, 3, 5])
280

find_tableaux_fillings(A::Vector{Int}, B::Vector{Int})
was: encontrar_prototablones
see the following discussion for context:
    https://discourse.julialang.org/t/right-solver-for-jump-to-find-every-solution-of-a-linear-system-of-equations-with-integer-solutions/44709/6

find_double_coset_representative_matrices(c_a::Content, c_b::Content) -> Vector{Matrix{Int}}

Return the frequency matrices (proto-tableaux) used to build the double coset representative permutations.

find_double_coset_representative_matrices(t_a, t_b) -> Vector{Matrix{Int}}

Return the frequency matrices (proto-tableaux) for two tableaux by using their contents.

GTPattern(arrayofarrays) Stucture to hold Gelfand-Tsetlin patterns. Data fields:

• rows
• last_row, copied from rows during initialization (for internal algorithm purposes, mathematically irrelevant)

TODO: either make it immutable, or somehow auto-change last_row upon change in rows (and vice versa).

Example:

julia> gt=GTPattern([[2,1,0],[2,1],[2]])
│ 2   1   0 ╲
│   2   1    〉
│     2     ╱


julia> gt.rows
3-element Vector{Vector{Int64}}:
 [2, 1, 0]
 [2, 1]
 [2]

julia> gt.last_row
1-element Vector{Int64}:
 2

basis_states(weight::Row)
Generate basis states (GTPatterns) of a given representation.

determine_next_pattern(x::GTPattern)

was: siguientepatron Determine next GT pattern by decreasing one entry (if possible) and propagating the change to rows below. Note: With incomplete patterns e.g. GTPattern([[2,1,0],[2,0]]) outputs of determinenextpattern and determinenextpattern! differ.

determine_next_pattern!(x::GTPattern)

was: siguientepatron! Determine next GT pattern by decreasing one entry (if possible) and propagating the change to rows below.

Computes zweight of a GTPattern. This array, if applied to each state of the irrep, is commonly known as the weight diagram of an SU(n) irrep.

zweight(x::GTPattern)

Examples:

julia> t = GTPattern([[2,1,0],[2,1],[2]],[2])
julia> zweight(t)
>[0.5,0.5]

pweight(x::GTPattern)

Compute the pweight of a GTPattern.

This array is related to the occupation number.

Examples

julia> using GroupFunctions

julia> t = GTPattern([[2, 1, 0], [2, 1], [2]]);

julia> pweight(t)
3-element Vector{Int64}:
 0
 1
 2

occupation_number(x::GTPattern)

Return the bosonic occupation-number vector associated with x. This is equivalent to reverse(pweight(x)).

YoungTableau(part::AbstractVector{<:Integer})
YoungTableau(part::AbstractVector{<:Integer}, fill::AbstractVector{<:Integer})

Minimal Young tableau type used by GroupFunctions. The part argument is the partition describing the tableau shape by row lengths.

axialdistance(Y::YoungTableau, i, j)

Return the hook-length of an element in Y at position (i,j), i.e the number of cells in the i-th row to the right of (i,j)-th box, plus the number of cells in the j-th column below the (i,j)-th box, plus 1.

Return 0 for (i,j) not in the tableau Y.

Examples

julia> y = YoungTableau([4,3,1])
┌───┬───┬───┬───┐
│ 1 │ 2 │ 3 │ 4 │
├───┼───┼───┼───┘
│ 5 │ 6 │ 7 │
├───┼───┴───┘
│ 8 │
└───┘

julia> axialdistance(y, 1,1)
6

julia> axialdistance(y, 1,3)
3

julia> axialdistance(y, 2,4)
0

matrix_repr(Y::YoungTableau)

Construct sparse integer matrix representing the tableau.

Examples:

julia> y = YoungTableau([4,3,1]);


julia> matrix_repr(y)
3×4 SparseArrays.SparseMatrixCSC{Int64,Int64} with 8 stored entries:
  [1, 1]  =  1
  [2, 1]  =  5
  [3, 1]  =  8
  [1, 2]  =  2
  [2, 2]  =  6
  [1, 3]  =  3
  [2, 3]  =  7
  [1, 4]  =  4

first_young_tableau_lexicographic(YoungTableau) -> YoungTableau
Computes the first ---in lexicographic order---
Standard Tableaux.

Examples:

julia> pat = YoungTableau([2,1]);

julia> first_young_tableau_lexicographic(pat).fill
3-element Vector{Int64}:
 1
 3
 2

StandardYoungTableaux(part::Array{Int64,1}) -> list of YoungTableaux

Return a list of Standard YoungTableaux.

Examples:

julia> map(t -> t.fill, StandardYoungTableaux([2,1]))
2-element Vector{Vector{Int64}}:
 [1, 3, 2]
 [1, 2, 3]

generate_matrix(Y::Array{YoungTableau}, p::Perm, λ::Array{Int64,1}) -> SparseMatrixCSC

Return non-zero entries of the orthogonal irrep given by the permutation 'p' The information of the irrep is introduced via 'Y' which is a list of Standard Young tableaux

Examples

julia> guilty = StandardYoungTableaux([3,2])
julia> generate_matrix(guilty, Perm([2,1,3,4,5]), [3,2])
[1, 1]  =  -1.0
[2, 2]  =  1.0
[3, 3]  =  -1.0
[4, 4]  =  1.0
[5, 5]  =  1.0

julia> generate_matrix(guilty, Perm([1,3,2,4,5]), [3,2])
[1, 1]  =  0.5
[2, 1]  =  0.866025
[1, 2]  =  0.866025
[2, 2]  =  -0.5
[3, 3]  =  0.5
[4, 3]  =  0.866025
[3, 4]  =  0.866025
[4, 4]  =  -0.5
[5, 5]  =  1.0

index_of_semistandard_tableau(p::YoungTableau)
was: indice_tablon_semistandard

Returns the index of the standard YoungTableau such that the function mapping the filling of the semistandard to the standard Tableau is non decreasing

TODO add examples

content(p::YoungTableau, λ::Irrep)

Return the size of the vector which represents the partition. WARNING calling content without an irrep λ assumes you are working with SU(d) with d the length of the partition p.

Examples:

julia> ss = YoungTableau(GTPattern([[2,1,0,0],[2,1,0],[2,1],[2]]));

julia> content(ss, [2,1,0,0])
4-element Vector{Int64}:
 2
 2
 0
 0

julia> ss = YoungTableau(GTPattern([[2,1,0,0],[2,1,0],[2,1],[2]]));

julia> content(ss, [2,1,0])
3-element Vector{Int64}:
 2
 1
 0

content(p::YoungTableau) -> Vector{Int}

Return the content vector of the tableau fill (counts of each label). In simple terms: it counts how many times each label (1, 2, 3, ...) appears in the tableau.

Examples:

julia> t = YoungTableau([2,1]); fill!(t, [1,2,2]);
julia> content(t)
2-element Vector{Int64}:
 1
 2

Θ(semistandard_table::YoungTableau)

Computes coefficient Θ. Returns a Float64

su2_block(size::Int, position::Int, angles::NTuple{3,Float64})
su2_block(size::Int, indices::NTuple{2,Int}, angles::NTuple{3,Float64})

Embed a 2×2 SU(2) rotation defined by Euler angles (α, β, γ) into a size × size identity matrix.

Method 1: Adjacent indices

su2_block(size, position, angles) acts on rows/cols position and position+1.

Method 2: Arbitrary indices

su2_block(size, (i, j), angles) acts on rows/cols i and j where 1 ≤ i < j ≤ size. This allows creating SU(2) blocks at non-adjacent positions.

Examples

# Adjacent indices (traditional usage)
mat = su2_block(4, 2, (0.1, 0.2, 0.3))  # acts on rows/cols (2, 3)

# Non-adjacent indices
mat = su2_block(5, (1, 4), (0.1, 0.2, 0.3))  # acts on rows/cols (1, 4)

su2_block_symbolic(size::Int, position::Int; prefix::String = "v")
su2_block_symbolic(size::Int, indices::NTuple{2,Int}; prefix::String = "v")

Create a symbolic size × size matrix with a generic 2×2 block represented by symbolic variables. The rest of the matrix is an identity.

This is the symbolic analog of su2_block, where instead of numeric angles, the 2×2 block elements are symbolic variables. This is useful for symbolic computations similar to how group_function creates symbolic expressions in terms of matrix elements u_i_j.

Method 1: Adjacent indices

su2_block_symbolic(size, position; prefix) creates a 2×2 block at position and position+1.

Method 2: Arbitrary indices

su2_block_symbolic(size, (i, j); prefix) creates a 2×2 block at rows/cols i and j where 1 ≤ i < j ≤ size. This allows creating symbolic blocks at non-adjacent positions.

Arguments

• size::Int: Dimension of the square matrix
• position::Int: Starting row/column for the 2×2 block (must satisfy 0 < position < size)
• indices::NTuple{2,Int}: Tuple (i, j) specifying arbitrary row/column indices
• prefix::String: Prefix for symbolic variable names (default: "v")

Returns

• Matrix{Basic}: A symbolic matrix with identity everywhere except a 2×2 symbolic block

Examples

julia> using GroupFunctions, SymEngine

# Adjacent indices (traditional usage)
julia> mat = su2_block_symbolic(3, 1)
3×3 Matrix{Basic}:
 v_1_1  v_1_2  0
 v_2_1  v_2_2  0
     0      0  1

# Non-adjacent indices
julia> mat = su2_block_symbolic(5, (1, 4))
5×5 Matrix{Basic}:
 v_1_1  0  0  v_1_4  0
     0  1  0      0  0
     0  0  1      0  0
 v_4_1  0  0  v_4_4  0
     0  0  0      0  1

julia> mat = su2_block_symbolic(4, 2, prefix="w")
4×4 Matrix{Basic}:
 1      0      0      0
 0  w_2_2  w_2_3      0
 0  w_3_2  w_3_3      0
 0      0      0      1

Notes

• The symbolic variables are named $(prefix)_i_j where i,j are the row and column indices
• Unlike su2_block, this does not enforce SU(2) constraints (unitarity, determinant = 1)
• The resulting matrix can be used in symbolic group function computations

bs_block(size::Int, position::Int)
bs_block(size::Int, indices::NTuple{2,Int})

Embed a 2×2 beamsplitter matrix [[1, -1], [1, 1]] / √2 into a size × size identity matrix.

This is a U(2) operation commonly used in quantum optics for modeling 50:50 beamsplitters.

Method 1: Adjacent indices

bs_block(size, position) acts on rows/cols position and position+1.

Method 2: Arbitrary indices

bs_block(size, (i, j)) acts on rows/cols i and j where 1 ≤ i < j ≤ size.

Examples

# Adjacent modes
BS = bs_block(4, 2)  # acts on modes (2, 3)

# Non-adjacent modes
BS = bs_block(5, (1, 4))  # acts on modes (1, 4)

Notes

• The beamsplitter matrix has determinant 1 and is unitary
• Common in quantum optics: implements a 50:50 beamsplitter

bs_block_symbolic(size::Int, position::Int)
bs_block_symbolic(size::Int, indices::NTuple{2,Int})

Embed a symbolic 2×2 beamsplitter matrix into a size × size identity matrix.

This creates a beamsplitter with the standard structure [[1, -1], [1, 1]] / √2 but using symbolic Basic types for further symbolic manipulation.

Examples

# Adjacent indices
BS_sym = bs_block_symbolic(3, 1)

# Non-adjacent indices
BS_sym = bs_block_symbolic(5, (1, 4))

swap_block(size::Int, position::Int)
swap_block(size::Int, indices::NTuple{2,Int})

Embed a 2×2 swap matrix [[0, 1], [1, 0]] into a size × size identity matrix.

This is a U(2) operation (not SU(2), as det = -1) that swaps two modes or particles.

Method 1: Adjacent indices

swap_block(size, position) acts on rows/cols position and position+1.

Method 2: Arbitrary indices

swap_block(size, (i, j)) acts on rows/cols i and j where 1 ≤ i < j ≤ size.

Examples

# Adjacent modes
SWAP = swap_block(4, 2)  # swaps modes (2, 3)

# Non-adjacent modes
SWAP = swap_block(5, (1, 4))  # swaps modes (1, 4)

Notes

• The swap matrix has determinant -1 (U(2) but not SU(2))
• The swap matrix is unitary and self-inverse: SWAP² = I

swap_block_symbolic(size::Int, position::Int)
swap_block_symbolic(size::Int, indices::NTuple{2,Int})

Embed a symbolic 2×2 swap matrix into a size × size identity matrix.

This creates a swap with the standard structure [[0, 1], [1, 0]] but using symbolic Basic types for further symbolic manipulation.

Examples

# Adjacent indices
SWAP_sym = swap_block_symbolic(3, 1)

# Non-adjacent indices
SWAP_sym = swap_block_symbolic(5, (2, 5))

su2_factorization(size::Int; skip_tail::Int = 0)

Build a random size × size unitary (SU(d)) as a product of SU(2) blocks; setting skip_tail skips the last skip_tail layers of factors.

sud_from_angles(angles::Vector{Float64}, size::Int; quotient::Bool = false)

Construct an SU(d) matrix from a supplied list of Euler angles, optionally zeroing the earliest layers when quotient is true.

julia_to_mma(expr::SymEngine.Basic)

Convert a SymEngine expression using u_i_j symbols into a Mathematica-style string using u[i,j], adding light operator spacing for readability.

mma_to_julia(s::String)

Convert a Mathematica-style string using x[i,j] into a SymEngine expression with u_i_j symbols.

Example:

julia> mma_to_julia("x[1, 1]")
u_1_1

expand(expr)

Re-export SymEngine.expand through GroupFunctions so symbolic group functions can be expanded without importing SymEngine explicitly.

bloquesun(args...; kwargs...)

Deprecated compatibility alias for su2_block.

simple(args...; kwargs...)

Deprecated compatibility alias for sud_from_angles.

simplefactorization(size::Int, quotient::Int)
simplefactorization(size::Int)

Deprecated compatibility wrapper for su2_factorization. Prefer su2_factorization(size; skip_tail = quotient).

indice_tablon_semistandard(semistandard_tableau::YoungTableau)

Deprecated alias for index_of_semistandard_tableau.

genera_funcion(semi_tableau::YoungTableau, irrep)
genera_funcion(semi_tableau::YoungTableau)

Deprecated alias for standard_to_semistandard_map.

enumerate_matrices(lambda, mu)

Input:

• lambda: vector of row sums.
• mu: vector of column sums.

Output:

• matrices: all nonnegative integer matrices (as lists of rows) with row sums lambda and column sums mu. If the margins are incompatible, the output is an empty list. If input element types differ, the output uses the promoted integer type.

Examples: julia> enumerate_matrices([2, 2], [3, 1]) 2-element Vector{Vector{Vector{Int64}}}: [[1, 1], [2, 0]] [[2, 0], [1, 1]]