SymGroups API

AbstractSymSpec

An abstract type representing a symmetry specification. Concrete subtypes of AbstractSymSpec define specific symmetry specifications that can be used to create symmetry groups.

CombSymGroup{B,T_s,T<:Integer,Ti<:Integer,T_f<:Number}
CombSymGroup(
    dofo::DoFObject{B,T_s,T,Ti},
    cycles::AbstractArray{<:Tuple{Vararg{NamedTuple}}},
    check::Tuple{Vararg{Function}},
    apply::Tuple{Vararg{Function}},
    phase::Tuple{Vararg{Function}},
    factors::AbstractArray{T_f},
    N::Integer
) where {B,T_s,T<:Integer,Ti<:Integer,T_f<:Number}

A combined symmetry group formed by the composition of multiple symmetry groups acting on the same DoF-object. This structure allows for the representation of more complex symmetry operations by combining simpler ones.

Internally the per-dimension data is stored as tuples (each cycle is a Tuple of named tuples, and check/apply/phase are Tuples of functions) so that the per-dimension types stay known to the compiler in the hot loops. The constructor also accepts the legacy layout (array of vectors of named tuples, and vectors of functions) and converts it.

Fields

• dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}: The DoF-object on which the combined symmetry group acts.
• cycles::AbstractArray{<:Tuple{Vararg{NamedTuple}}}: An array of tuples of named tuples representing the combined symmetry cycles.
• check::Tuple{Vararg{Function}}: A tuple of functions to check the validity of each set of symmetry operations.
• apply::Tuple{Vararg{Function}}: A tuple of functions to apply each set of symmetry operations.
• phase::Tuple{Vararg{Function}}: A tuple of functions to compute phase factors for each set of symmetry operations.
• factors::AbstractArray{T_f}: An array of factors associated with each combined symmetry cycle.
• N::Int: The total number of the DoF-objects in the system. This is used to check the validity of the symmetry operations.

Constructor Arguments

• dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}: The DoF-object on which the combined symmetry group acts.
• cycles::AbstractArray{<:Tuple{Vararg{NamedTuple}}}: An array of tuples of named tuples representing the combined symmetry cycles.
• check::Tuple{Vararg{Function}}: A tuple of functions to check the validity of each set of symmetry operations.
• apply::Tuple{Vararg{Function}}: A tuple of functions to apply each set of symmetry operations.
• phase::Tuple{Vararg{Function}}: A tuple of functions to compute phase factors for each set of symmetry operations.
• factors::AbstractArray{T_f}: An array of factors associated with each combined symmetry cycle.
• N::Integer: The total number of the DoF-objects in the system. This is used to check the validity of the symmetry operations.

A legacy outer constructor also accepts the array-of-vectors/vector-of-functions layout (cycles::AbstractArray{<:AbstractVector{<:NamedTuple}}, check/apply/phase::AbstractVector{<:Function}) and converts it to the tuple-based layout above.

Returns

• CombSymGroup{B,T_s,T,Ti,T_f}: A new CombSymGroup instance initialized with the provided parameters.

The constructor checks that the size of cycles matches the size of factors and that the number of dimensions matches the number of check and apply functions to ensure consistency.

Rotational{T_r<:Integer,Ti} <: SymBasis.SymGroups.AbstractSymSpec

A concrete subtype of SymBasis.SymGroups.AbstractSymSpec representing the specification of rotational symmetry of space. The type parameter T_r represents the spatial rotation number, while Ti represents the type of the permutation indices.

Fields

• r::T_r: The spatial rotation number.
• perm::AbstractVector{Ti}: The permutation vector defining the rotation.

Constructor Arguments

• r::T_r: The spatial rotation number.
• perm::AbstractVector{Ti}: The permutation vector defining the rotation.

Returns

• Rotational{T_r,Ti}: An instance of Rotational representing the specified rotational symmetry of space.

SpatialReflection{T_p<:Integer,Ti} <: SymBasis.SymGroups.AbstractSymSpec

A concrete subtype of SymBasis.SymGroups.AbstractSymSpec representing a spatial reflection symmetry specification. The type parameter T_p represents the parity quantum number, while Ti represents the type of the permutation indices.

Fields

• p::T_p: The parity number (either -1 or 1).
• perm::AbstractVector{Ti}: The permutation vector defining the spatial reflection.

Constructor Arguments

• p::T_p: The parity number (either -1 or 1).
• perm::AbstractVector{Ti}: The permutation vector defining the spatial reflection.

Returns

• SpatialReflection{T_p,Ti}: An instance of SpatialReflection representing the specified

spatial reflection symmetry.

SpinInversion{T_z<:Integer,T_N<:Integer} <: SymBasis.SymGroups.AbstractSymSpec

A concrete subtype of SymBasis.SymGroups.AbstractSymSpec representing a spin inversion symmetry specification. The type parameter T_z represents the spin inversion quantum number, while T_N represents the total number of DoF-objects in the system.

Fields

• z::T_z: The parity quantum number (either -1 or 1).
• N::T_N: The total number of DoF-objects in the system.

Constructor Arguments

• z::T_z: The parity quantum number (either -1 or 1).
• N::T_N: The total number of DoF-objects in the system.

Returns

• SpinInversion{T_z,T_N}: An instance of SpinInversion representing the specified spin inversion symmetry.

SpinMultipole{RANK,T_q<:Real,T_w<:Real,T_N<:Integer,T_tol<:Real} <:
    SymBasis.SymGroups.AbstractSymSpec

A concrete subtype of SymBasis.SymGroups.AbstractSymSpec representing a spin multipole symmetry specification.

Fields

• qₛ::AbstractArray{T_q,RANK}: The target multipole values for the symmetry specification.
• weights::AbstractMatrix{T_w}: The weights used to compute the multipole sum from the spin projections.
• N::T_N: The total number of DoF-objects in the system.
• atol::T_tol: The absolute tolerance for comparing the computed multipole sum to the target values.
• rtol::T_tol: The relative tolerance for comparing the computed multipole sum to the target values.

Constructor Arguments

• qₛ::AbstractArray{T_q,RANK}: The target multipole values for the symmetry specification.
• weights::AbstractMatrix{T_w}: The weights used to compute the multipole sum from the spin projections.
• N::T_N: The total number of DoF-objects in the system.

Constructor Keyword Arguments

• atol::T_tol=0.0: The absolute tolerance for comparing the computed multipole sum to the target values.
• rtol::T_tol=rtoldefault(T_q, T_w, atol): The relative tolerance for comparing the computed multipole sum to the target values. By default, it is determined based on the types of T_q and T_w, and the value of atol.

Returns

• SpinMultipole{RANK,T_q,T_w,T_N,T_tol}: An instance of SpinMultipole representing the specified spin multipole symmetry.

SpinMultipole(
    q::T_q, weights::AbstractVector{T_w}, N;
    rank::Integer=1, kwargs...
) where {T_q<:Real,T_w<:Real}

Convenience constructor for SymBasis.SymGroups.SpinMultipole that accepts a single target multipole value q and a vector of weights, and constructs the full qₛ array by filling it with q values. The rank keyword argument specifies the rank of the multipole, which determines the number of dimensions in the qₛ array. The remaining keyword arguments are passed to the main constructor.

Arguments

• q::T_q: The target multipole value for the symmetry specification.
• weights::AbstractVector{T_w}: The weights used to compute the multipole sum from the spin projections.
• N: The total number of DoF-objects in the system.

Keyword Arguments

• rank::Integer=1: The rank of the multipole, which determines the number of dimensions in the qₛ array. Default is 1.
• kwargs...: Additional keyword arguments to be passed to the main constructor.

Returns

• SymBasis.SymGroups.SpinMultipole: An instance of SpinMultipole representing the specified spin multipole symmetry.

SymGroup{B,T_s,T<:Integer,Ti<:Integer,T_f<:Number}
SymGroup(
    dofo::DoFObject{B,T_s,T,Ti},
    cycles::AbstractVector{<:NamedTuple},
    check::Function,
    apply::Function,
    phase::Function,
    factors::AbstractVector{T_f},
    N::Integer
) where {B,T_s,T<:Integer,Ti<:Integer,T_f<:Number}

A symmetry group acting on a DoF-object. The symmetry group is defined by its associated DoF-object, a set of cycles representing the symmetry operations, functions to check and apply these operations, and factors associated with each symmetry cycle.

Fields

• dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}: The DoF-object on which the symmetry group acts.
• cycles::AbstractVector{<:NamedTuple}: A vector of named tuples representing the symmetry cycles.
• check::Function: A function to check the validity of symmetry operations.
• apply::Function: A function to apply the symmetry operations.
• phase::Function: A function to compute the phase of symmetry operations.
• factors::AbstractVector{T_f}: A vector of factors associated with each symmetry cycle.
• N::Int: The total number of the DoF-objects in the system. This is used to check the validity of the symmetry operations.

Constructor Arguments

• dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}: The DoF-object on which the symmetry group acts.
• cycles::AbstractVector{<:NamedTuple}: A vector of named tuples representing the symmetry cycles.
• check::Function: A function to check the validity of symmetry operations.
• apply::Function: A function to apply the symmetry operations.
• phase::Function: A function to compute the phase of symmetry operations.
• factors::AbstractVector{T_f}: A vector of factors associated with each symmetry cycle.
• N::Integer: The total number of the DoF-objects in the system. This is used to check the validity of the symmetry operations.

Returns

• SymGroup{B,T_s,T,Ti,T_f}: A new SymGroup instance initialized with the provided parameters.

The constructor checks that the number of cycles matches the number of factors to ensure consistency.

TotalBosonicNumber{T_b<:Integer,T_N<:Integer} <: SymBasis.SymGroups.AbstractSymSpec

A concrete subtype of SymBasis.SymGroups.AbstractSymSpec representing a bosonic particle number conservation specification. The type parameter T_b represents the target total number of particles, while T_N represents the total number of DoF-objects in the system.

Fields

• n_particles::T_b: The target total number of particles.
• N::T_N: The total number of DoF-objects in the system.

Constructor Arguments

• n_particles::T_b: The target total number of particles.
• N::T_N: The total number of DoF-objects in the system.

Returns

• SymBasis.SymGroups.TotalBosonicNumber: An instance of TotalBosonicNumber with the number of particles converted to an integer.

TotalMagnetization{T_s<:Rational,T_N<:Integer} <: SymBasis.SymGroups.AbstractSymSpec

A concrete subtype of SymBasis.SymGroups.AbstractSymSpec representing a total magnetization symmetry specification. The type parameter T_s represents the target total magnetization value, while T_N represents the total number of DoF-objects in the system.

Fields

• mag::T_s: The target total magnetization value for the symmetry specification.
• N::T_N: The total number of DoF-objects in the system.

Constructor Arguments

• mag::T_s: The target total magnetization value for the symmetry specification.
• N::T_N: The total number of DoF-objects in the system.

Returns

• TotalMagnetization{T_s,T_N}: An instance of TotalMagnetization representing the specified total magnetization symmetry.

TotalMagnetization(mag::AbstractFloat, N)

Convenience constructor for TotalMagnetization that accepts a floating-point magnetization value and converts it to a rational number.

Arguments

• mag::AbstractFloat: The target total magnetization value as a floating-point number.
• N: The total number of DoF-objects in the system.

Returns

• SymBasis.SymGroups.TotalMagnetization: An instance of TotalMagnetization with the magnetization value converted to a rational number.

TotalMagnetization(mag::Integer, N)

Convenience constructor for TotalMagnetization that accepts an integer magnetization value and converts it to a rational number.

Arguments

• mag::Integer: The target total magnetization value as an integer.
• N: The total number of DoF-objects in the system.

Returns

• SymBasis.SymGroups.TotalMagnetization: An instance of TotalMagnetization with the magnetization value converted to a rational number.

TotalSpinlessFermionicNumber{T_b<:Integer,T_N<:Integer}
    <: SymBasis.SymGroups.AbstractSymSpec

A concrete subtype of SymBasis.SymGroups.AbstractSymSpec representing a total spinless fermionic number symmetry specification. The type parameter T_b represents the target total number of fermions, while T_N represents the total number of DoF-objects in the system.

This symmetry selects the subspace with fixed total fermion number, i.e. states whose binary occupations sum to n_particles.

Fields

• n_particles::T_b: The target total number of spinless fermions for the symmetry specification.
• N::T_N: The total number of DoF-objects in the system.

Constructor Arguments

• n_particles::T_b: The target total number of spinless fermions for the symmetry specification.
• N::T_N: The total number of DoF-objects in the system.

Returns

• TotalSpinlessFermionicNumber{T_b,T_N}: An instance of TotalSpinlessFermionicNumber representing the specified total spinless fermionic number symmetry.

Translational{T_k<:Integer,Ti} <: SymBasis.SymGroups.AbstractSymSpec

A concrete subtype of SymBasis.SymGroups.AbstractSymSpec representing a translational symmetry specification. The type parameter T_k represents the momentum quantum number, while Ti represents the type of the permutation indices.

Fields

• k::T_k: The momentum number.
• perm::AbstractVector{Ti}: The permutation vector defining the translation.

Constructor Arguments

• k::T_k: The momentum number.
• perm::AbstractVector{Ti}: The permutation vector defining the translation.

Returns

• Translational{T_k,Ti}: An instance of Translational representing the specified

translational symmetry.

∘(
    csg1::CombSymGroup{B,T_s,T,Ti,<:T_f},
    csg2::CombSymGroup{B,T_s,T,Ti,<:T_f}
) where {B,T_s,T<:Integer,Ti<:Integer,T_f<:Number}

Composition of two combined symmetry groups acting on the same DoF-object. The resulting symmetry group combines the cycles, check functions, apply functions, and factors of the input symmetry groups.

Arguments

• csg1::SymBasis.SymGroups.CombSymGroup{B,T_s,T,Ti,<:T_f}: The first combined symmetry group.
• csg2::SymBasis.SymGroups.CombSymGroup{B,T_s,T,Ti,<:T_f}: The second combined symmetry group.

Returns

• SymBasis.SymGroups.CombSymGroup{B,T_s,T,Ti,T_f}: The combined symmetry group.

∘(
    csg::CombSymGroup{B,T_s,T,Ti,<:T_f},
    sg::SymGroup{B,T_s,T,Ti,<:T_f}
) where {B,T_s,T,Ti,T_f<:Number}

Composition of a combined symmetry group with a symmetry group acting on the same DoF-object. The resulting symmetry group combines the cycles, check functions, apply functions, and factors of the input symmetry groups.

Arguments

• csg::SymBasis.SymGroups.CombSymGroup{B,T_s,T,Ti,T_f}: The combined symmetry group.
• sg::SymBasis.SymGroups.SymGroup{B,T_s,T,Ti,T_f}: The symmetry group.

Returns

• SymBasis.SymGroups.CombSymGroup{B,T_s,T,Ti,T_f}: The combined symmetry group.

∘(
    csg::SymGroup{B,T_s,T,Ti,<:T_f},
    sg::CombSymGroup{B,T_s,T,Ti,<:T_f}
) where {B,T_s,T<:Integer,Ti<:Integer,T_f<:Number}

Composition of a combined symmetry group with a symmetry group acting on the same DoF-object. The resulting symmetry group combines the cycles, check functions, apply functions, and factors of the input symmetry groups.

Arguments

• csg::SymBasis.SymGroups.SymGroup{B,T_s,T,Ti,<:T_f}: The symmetry group.
• sg::SymBasis.SymGroups.CombSymGroup{B,T_s,T,Ti,<:T_f}: The combined symmetry group.

Returns

• SymBasis.SymGroups.CombSymGroup{B,T_s,T,Ti,T_f}: The combined symmetry group.

∘(
    sg1::SymGroup{B,T_s,T,Ti,<:T_f},
    sg2::SymGroup{B,T_s,T,Ti,<:T_f}
) where {B,T_s,T,Ti,T_f<:Number}

Composition of two symmetry groups acting on the same DoF-object. The resulting symmetry group combines the cycles, check functions, apply functions, and factors of the input symmetry groups.

Arguments

• sg1::SymBasis.SymGroups.SymGroup{B,T_s,T,Ti,<:T_f}: The first symmetry group.
• sg2::SymBasis.SymGroups.SymGroup{B,T_s,T,Ti,<:T_f}: The second symmetry group.

Returns

• SymBasis.SymGroups.CombSymGroup{B,T_s,T,Ti,T_f}: The combined symmetry group.

_apply_perm(
    perm::BitPermutations.BitPermutation{T,<:BitPermutations.PermutationBackend{T}},
    state::SymBasis.DigitBase.BaseInt{T,Ti,2}
) where {T,Ti}

Internal helper backing apply_perm: apply the bit permutation perm to the given binary state in a more efficient way via BitPermutations.bitpermute. This method is selected when the cycle's perm field is a BitPermutation (base 2 only); it is called as _apply_perm(p.perm, state) from apply_perm, receiving the permutation directly rather than the wrapping cycle NamedTuple.

Arguments

• perm::BitPermutations.BitPermutation{T,<:BitPermutations.PermutationBackend{T}}: The bit permutation to apply.
• state::SymBasis.DigitBase.BaseInt{T,Ti,2}: The binary state to which the bit permutation will be applied.

Returns

• SymBasis.DigitBase.BaseInt{T,Ti,2}: The binary state after applying the bit permutation.

_candidate_states(check, cycles, ::Type{BaseInt{T,Ti,B}}, N) where {T,Ti,B}

Return a sorted Vector of all states that can pass check for at least one cycle in cycles, or nothing when the check does not admit direct enumeration. Used by SymBasis.Bases.basis to skip the full B^N scan: any state outside the returned superset fails check for every cycle and therefore never enters the basis, so replacing the full range by this set leaves the result unchanged.

_check_Nₛ(
    state::SymBasis.DigitBase.BaseInt{T,Ti,2},
    p::NamedTuple{N0::TN, N1::TN, N::TN}
) where {T,Ti,TN<:Integer}

Internal function to check if the given binary state has the specified counts of 0s and 1s as defined in the named tuple p.

Arguments

• state::SymBasis.DigitBase.BaseInt{T,Ti,2}: The binary state to be checked.
• p::NamedTuple{N0::TN, N1::TN, N::TN}: A named tuple containing the counts of 0s and 1s.

Returns

• Bool: true if the state has the specified counts of 0s and 1s, false otherwise.

_check_Nₛ(
    state::SymBasis.DigitBase.BaseInt{T,Ti,B},
    p::NamedTuple{names}
) where {T,Ti,B,names}

Internal function to check if the given state has the specified digit counts as defined in the named tuple p. Accepts any named tuple that contains the fields N, N0, N1, ..., N(B-1) (e.g. from both check_Nₛ and check_flip parameter tuples).

Arguments

• state::SymBasis.DigitBase.BaseInt{T,Ti,B}: The state to be checked.
• p::NamedTuple{names}: A named tuple containing at least the digit count fields.

Returns

• Bool: true if the state has the specified digit counts, false otherwise.

_perm_cycle(perm::AbstractVector{Ti}, dofo::DoFObject{B,T_s,T,Ti}) where {B,T_s,T,Ti}

Build the cycle named tuple for a permutation symmetry element. Besides the (possibly bit-wrapped) permutation itself, the tuple carries data precomputed once per cycle so the hot loop stays allocation-free: the inverse permutation (needed for fermionic phases), and, for bases B > 2, the digit power table pows[k] = B^(k-1) used to permute digits in a single pass.

apply_Nₛ(
    p::NamedTuple{names,NT},
    state::SymBasis.DigitBase.BaseInt
) where {names,NT<:Tuple{Vararg{Integer}}}

Apply the symmetry operation defined by the digit counts in p to the given state. Since this is a symmetry where the state remains unchanged, the function simply returns the input state.

Arguments

• p::NamedTuple{names,NT}: A named tuple containing the digit counts.
• state::SymBasis.DigitBase.BaseInt: The state to which the symmetry operation will be applied.

Returns

• SymBasis.DigitBase.BaseInt: The unchanged state.

apply_flip(
    p::NamedTuple{is_flipped::Bool, sites::T_site, N0::TN, N1::TN, N::TN},
    state::SymBasis.DigitBase.BaseInt{T,Ti,2}
) where {T,Ti,TN<:Integer,T_site<:AbstractVector{Ti}}

Apply the flip operation defined by p to the given binary state if p.is_flipped is true. If the state is flipped, the function returns the flipped state; otherwise, it returns the original state.

Arguments

• p::@NamedTuple{is_flipped::Bool, sites::T_site, N0::TN, N1::TN, N::TN}: A named tuple containing the flip flag, sites to be flipped, and the expected counts of 0s and 1s.
• state::SymBasis.DigitBase.BaseInt{T,Ti,2}: The binary state to which the flip operation will be applied.

Returns

• SymBasis.DigitBase.BaseInt{T,Ti,2}: The state after applying the flip operation.

apply_multipole(
    p::NamedTuple,
    state::SymBasis.DigitBase.BaseInt{T,Ti,B}
) where {T,Ti,B}

Apply the multipole symmetry operation defined by p to the given state. Since this is a symmetry where the state remains unchanged, the function simply returns the input state.

Arguments

• p::NamedTuple: A named tuple containing the multipole symmetry parameters.
• state::SymBasis.DigitBase.BaseInt{T,Ti,B}: The state to which the multipole symmetry operation will be applied.

Returns

• SymBasis.DigitBase.BaseInt{T,Ti,B}: The unchanged state.

apply_perm(
    p::NamedTuple,
    state::SymBasis.DigitBase.BaseInt{T,Ti,B}
) where {T,Ti,B}

Apply the permutation p.perm to the given state.

p accepts any NamedTuple containing at least a perm field. When p also carries the precomputed invperm and (for bases B > 2) pows fields produced by _perm_cycle — as is the case for cycles built by SymBasis.SymGroups.sym for Translational/SpatialReflection/Rotational symmetries — the permutation is applied via a single allocation-free digit pass instead of going through SymBasis.DigitBase.permute. (haskey on a NamedTuple is resolved at compile time, so this dispatch adds no runtime branching cost.) Otherwise it falls back to permute(state, p.perm) for a plain vector perm, or to a specialized bit-permutation path (via BitPermutations.bitpermute) when p.perm is a BitPermutation (base 2 only).

Arguments

• p::NamedTuple: A named tuple containing at least a perm field.
• state::SymBasis.DigitBase.BaseInt{T,Ti,B}: The state to which the permutation will be applied.

Returns

• SymBasis.DigitBase.BaseInt{T,Ti,B}: The state after applying the permutation.

apply_perm_fermionic(p, state)

Apply the permutation p.perm to the given binary state, and compute the fermionic phase arising from the permutation of occupied sites. The function returns a tuple containing the permuted state and the fermionic phase factor.

Arguments

• p: A parameter containing the permutation (e.g. a named tuple with a perm field).
• state: The binary state to which the permutation will be applied.

Returns

• A tuple containing the permuted state and the fermionic phase factor (1 or -1).

check_Nₛ(
    p::NamedTuple{names,NT},
    state::SymBasis.DigitBase.BaseInt,
    prev_bool::Bool,
) where {names,NT<:Tuple{Vararg{Integer}}}

Check if the given state has the specified digit counts as defined in the named tuple p. Since this is a symmetry check, the result is combined with prev_bool.

Arguments

• p::NamedTuple{names,NT}: A named tuple containing the digit counts.
• state::SymBasis.DigitBase.BaseInt: The state to be checked.
• prev_bool::Bool: The previous boolean value to be combined with the check result.

Returns

• Bool: The combined result of the previous boolean and the digit count check.

check_flip(
    p::NamedTuple{names,<:Tuple{Bool,<:AbstractVector{Ti},Vararg{Integer}}},
    state::SymBasis.DigitBase.BaseInt{T,Ti,B},
    prev_bool::Bool
) where {names,T,Ti,B}

Check if the given state (for base B > 2) has the specified digit counts as defined in the named tuple p. The function checks if the flipped state has the specified digit counts. The result is combined with prev_bool.

Arguments

• p::NamedTuple{names,<:Tuple{Bool,<:AbstractVector{Ti},Vararg{Integer}}}: A named tuple containing is_flipped, sites, and digit count fields N0, N1, ..., N(B-1), N.
• state::SymBasis.DigitBase.BaseInt{T,Ti,B}: The state to be checked.
• prev_bool::Bool: The previous boolean value to be combined with the check result.

Returns

• Bool: The combined result of the previous boolean and the digit count check.

check_multipole(
    p::NamedTuple,
    state::SymBasis.DigitBase.BaseInt{T,Ti,B},
    prev_bool::Bool
) where {T,Ti,B}

Check if the given state satisfies the multipole symmetry defined by p. The function computes the multipole sum for the state using the weights and compares it to the target qₛ values. The result is combined with prev_bool.

Arguments

• p::NamedTuple: A named tuple containing the multipole symmetry parameters.
• state::SymBasis.DigitBase.BaseInt{T,Ti,B}: The state to be checked.
• prev_bool::Bool: The previous boolean value to be combined with the check result.

Returns

• Bool: The combined result of the previous boolean and the multipole symmetry check.

check_perm(
    p::NamedTuple,
    state::SymBasis.DigitBase.BaseInt{T,Ti,B},
    prev_bool::Bool
) where {T,Ti,B}

Check if the given state is invariant under the permutation p.perm. Since permutations are symmetries, this function always returns prev_bool unchanged.

p accepts any NamedTuple containing at least a perm field: besides plain (; perm=...) cycles, this includes the extended cycles built by SymBasis.SymGroups.sym for Translational/SpatialReflection/Rotational symmetries, which additionally carry a precomputed invperm (and, for bases B > 2, a digit power table pows) used by apply_perm and SymBasis.SymGroups.phase_perm_fermionic.

Arguments

• p::NamedTuple: A named tuple containing at least a perm field.
• state::SymBasis.DigitBase.BaseInt{T,Ti,B}: The state to be checked.
• prev_bool::Bool: The previous boolean value to be combined with the check result.

Returns

• Bool: The combined result of the previous boolean and the check (always prev_bool).

phase_perm_fermionic(
    p::NamedTuple,
    state::SymBasis.DigitBase.BaseInt{T,Ti,B}
) where {T,Ti,B}

Compute the fermionic sign (1 or -1) that arises from applying the permutation p.perm to the occupied sites of state, i.e. the parity of the permutation restricted to the subset of sites where state has a nonzero digit.

p accepts any NamedTuple containing at least a perm field. When p also carries the precomputed invperm field — as produced for cycles built by SymBasis.SymGroups.sym for Translational/SpatialReflection/Rotational symmetries applied to spinless fermions — that inverse permutation is used directly; otherwise it is computed on the fly via SymBasis.Miscs.invperm.

The sign itself is obtained by counting inversions of the occupied-site permutation with a bitmask sweep over already-mapped positions (count_ones on a shifted mask), rather than by materializing an intermediate list of mapped sites. Base 2 uses a dedicated fast path that iterates set bits of state.value directly (trailing_zeros, clearing the lowest set bit each step); other bases use a sequential digit-by-digit divrem pass.

Arguments

• p::NamedTuple: A named tuple containing at least a perm field.
• state::SymBasis.DigitBase.BaseInt{T,Ti,B}: The state whose occupied sites define the permutation parity to compute.

Returns

• Int: 1 for an even permutation of the occupied sites, -1 for an odd one.

phase_unity(p, state)

Return a phase factor of true (implying a phase factor of 1) for any given input. This function is used as the default phase function for symmetries that do not involve any nontrivial phase factors.

Arguments

• p: A parameter containing the symmetry operation (not used in this function).
• state: The state to which the symmetry operation is applied (not used in this function).

Returns

• true: A constant phase factor of 1.

sym(
    ss::SymBasis.SymGroups.SpinInversion{T_z,T_N},
    dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}
) where {B,T_s,T,Ti,T_z,T_N}

Create a spin inversion symmetry group for the given DoF-object dofo, and spin inversion symmetry specification ss. The function generates all combinations of spin projections that sum to zero.

Arguments

• ss::SymBasis.SymGroups.SpinInversion{T_z,T_N}: The spin inversion symmetry specification.
• dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}: The DoF-object.

Returns

• SymBasis.SymGroups.SymGroup: The spin inversion symmetry group.

sym(
    ss::TotalBosonicNumber{T_b,T_N},
    dofo::DoFObject{B,T_b,T,Ti}
) where {B,T_b,T,Ti,T_N}

Create a symmetry group for particle conservation for the given bosonic DoF-object dofo, and target total particle number specification ss.

Arguments

• ss::TotalBosonicNumber{T_b,T_N}: The particle number conservation specification, containing the target total number of particles and the total number of DoF-objects.
• dofo::DoFObject{B,T_b,T,Ti}: The bosonic DoF-object for which to create the symmetry group.

Returns

• SymBasis.SymGroups.SymGroup: The symmetry group for particle conservation.

sym(
    ss::SymBasis.SymGroups.TotalSpinlessFermionicNumber{T_b,T_N},
    dofo::SymBasis.DoFObjects.DoFObject{B,T_b,T,Ti}
) where {B,T_b,T,Ti,T_N}

Create a total spinless fermionic number symmetry group for the given spinless fermionic DoF-object dofo, and target total spinless fermionic number specification ss. The function generates all combinations of occupation numbers that sum to the target number of particles.

Arguments

• ss::SymBasis.SymGroups.TotalSpinlessFermionicNumber{T_b,T_N}: The total spinless fermionic number symmetry specification.
• dofo::SymBasis.DoFObjects.DoFObject{B,T_b,T,Ti}: The DoF-object representing spinless fermions.

Returns

• SymBasis.SymGroups.SymGroup: The total spinless fermionic number symmetry group.

sym(
    ss::SymBasis.SymGroups.TotalMagnetization{T_s,T_N},
    dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}
) where {B,T_s,T,Ti,T_N}

Create a total magnetization symmetry group for the given spin DoF-object dofo, and target total magnetization specification ss.

Arguments

• ss::SymBasis.SymGroups.TotalMagnetization{T_s,T_N}: The total magnetization symmetry specification.
• dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}: The DoF-object.

Returns

• SymBasis.SymGroups.SymGroup: The total magnetization symmetry group.

sym(
    ss::SymBasis.SymGroups.Translational{T_k,Ti},
    dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}
) where {B,T_s,T,Ti,T_k}

Create a translational symmetry group for the given DoF-object dofo, and translational symmetry specification ss.

Arguments

• ss::SymBasis.SymGroups.Translational{T_k,Ti}: The translational symmetry specification.
• dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}: The DoF-object.

Returns

• SymBasis.SymGroups.SymGroup: The translational symmetry group.

sym(
    ss::SymBasis.SymGroups.SpatialReflection{T_p,Ti},
    dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}
) where {B,T_s,T,Ti,T_p}

Create a spatial reflection symmetry group for the given DoF-object dofo, and spatial reflection symmetry specification ss.

Arguments

• ss::SymBasis.SymGroups.SpatialReflection{T_p,Ti}: The spatial reflection symmetry specification.
• dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}: The DoF-object.

Returns

• SymBasis.SymGroups.SymGroup: The spatial reflection symmetry group.

sym(
    ss::SymBasis.SymGroups.SpinMultipole{RANK,T_q,T_w,T_N},
    dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}
) where {B,T_s,T,Ti,RANK,T_q,T_w,T_N}

Create a spin multipole symmetry group for the given DoF-object dofo, and spin multipole symmetry specification ss. The function computes the multipole sum for each state using the weights and checks if it matches the target qₛ values within the specified tolerances.

Arguments

• ss::SymBasis.SymGroups.SpinMultipole{RANK,T_q,T_w,T_N}: The spin multipole symmetry specification.
• dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}: The DoF-object.

Returns

• SymBasis.SymGroups.SymGroup: The spin multipole symmetry group.

sym(
    ss::SymBasis.SymGroups.Rotational{T_r,Ti},
    dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}
) where {B,T_s,T,Ti,T_r}

Create a group of rotational symmetry of space for the given DoF-object dofo, and rotational symmetry specification ss. The function generates the rotational symmetry group by applying the permutation defined in ss repeatedly until it returns to the identity, and constructs the rotational symmetry group using the check_perm and apply_perm functions.

Arguments

• ss::SymBasis.SymGroups.Rotational{T_r,Ti}: The specification of rotational symmetry of space.
• dofo::SymBasis.DoFObjects.DoFObject{B,T_s,T,Ti}: The DoF-object.

Returns

• SymBasis.SymGroups.SymGroup: The group of rotational symmetry of space.