Reference

AbelianBlocks{T,N,A<:AbelianGradedArray{T,<:Any,N}} <: AbstractSparseArray{AbelianSectorArray,N}

Lazy view of an AbelianGradedArray's block storage as an AbstractSparseArray whose stored entries are the parent's allowed, allocated blocks. Following the BlockArrays convention, a stored entry is view(parent, Block(I)...) (shares data); an unstored entry is a fresh zero block. Being an AbstractSparseArray means generic zero!, map!, and the offset range-assignment used by the concatenation machinery visit only the stored blocks.

AbelianGradedArray{T,S<:SectorRange,N,D<:AbstractArray{T,N}} <: AbstractGradedArray{T,S,N}

A graded array that stores non-zero blocks in a dictionary keyed by block indices. Each axis is a GradedOneTo carrying sectors, sector lengths, and a dual flag.

Blocks are stored as plain dense arrays of type D (default Array{T,N}). Accessing a block via a[Block(i,j)] returns a AbelianSectorArray wrapping the data with the appropriate sectors.

AbelianSectorArray{T,S,N,A} <: AbstractSectorArray{T, S, N}

Unfused N-D data tensor for abelian symmetries. Stores one SectorRange per axis, plus a dense data array. Implements the Wigner-Eckart decomposition: the full tensor is the Kronecker product of an AbelianSectorDelta (structural) with the data array (reduced matrix elements).

AbelianSectorDelta{T,S<:SectorRange,N} <: AbstractSectorDelta{T, S, N}

Unfused N-D structural tensor for abelian symmetries. Stores one SectorRange per axis. For abelian symmetries, every element equals one(T) (the Kronecker delta selection rule).

AbstractGradedArray{T,S,N} <: AbstractArray{T,N}

Abstract supertype for graded (symmetry-structured) arrays whose axes carry sector labels. Concrete subtypes include AbelianGradedArray and FusedGradedMatrix.

AbstractSectorArray{T,S,N} <: AbstractArray{T,N}

Abstract supertype for data tensors labeled by sector information. Concrete subtypes:

• AbelianSectorArray: unfused N-D abelian data tensor (one sector per axis)
• SectorMatrix: fused 2D data matrix (one coupled sector label)

AbstractSectorDelta{T,S,N} <: AbstractArray{T,N}

Abstract supertype for structural (Kronecker/identity) tensors associated to sector labels. Concrete subtypes:

• AbelianSectorDelta: unfused N-D abelian structural tensor (product of Kronecker deltas)
• SectorIdentity: fused 2D structural factor (identity matrix per coupled sector)

Data{N}

Block-data indexing type analogous to BlockArrays.Block{N}. Indexing a graded array with Data(i, j, ...) accesses the raw data array for that block, without sector metadata wrappers.

FusedGradedMatrix{T,S<:SectorRange,D<:AbstractMatrix{T}}

Block-diagonal matrix produced by matricizing an AbstractGradedArray. Each stored block corresponds to a coupled sector that lives on both the codomain and the domain.

Fields:

• codomain::Dictionary{S,Int} — codomain (row) axis, mapping each sector to its row-block size. Keys are sorted and unique. Sectors are stored non-dual (codomain convention).
• domain::Dictionary{S,Int} — domain (column) axis, mapping each sector to its column-block size. Keys are sorted and unique. Stored non-dual; the actual axis is dual (the keys are dualed by axes(m, 2)).
• blocks::Dictionary{S,D} — stored data blocks, keyed by sector. Each key must be in both codomain and domain, and size(blocks[s]) must equal (codomain[s], domain[s]).

FusedGradedMatrix(sectors::Vector{S}, blocks::Vector{D})

Build a FusedGradedMatrix whose codomain and domain carry the same sector list. codomain[sectors[i]] is size(blocks[i], 1) and domain[sectors[i]] is size(blocks[i], 2).

FusedGradedMatrix(a::AbelianGradedMatrix{T})

Convert a 2D block-sparse AbelianGradedArray (as produced by matricize) into a FusedGradedMatrix. The codomain dict comes from the row axis sectors and lengths; the domain dict comes from dual.(domain_axis_sectors) and lengths. Stored entries of a populate blocks.

FusedGradedMatrix{T}(undef, sectors, rowlengths, collengths)
FusedGradedMatrix{T}(undef, sectors, lengths)
FusedGradedMatrix{T}(undef, sectors .=> rowlengths, sectors .=> collengths)
FusedGradedMatrix{T}(undef, sectors .=> lengths)
FusedGradedMatrix{T}(undef, codomain::GradedOneTo, domain::GradedOneTo)
FusedGradedMatrix{T}(undef, codomain::GradedOneTo)

Allocate a block-diagonal FusedGradedMatrix with uninitialized blocks keyed by a shared set of sectors. rowlengths[i]/collengths[i] give the reduced row and column lengths of the block at sectors[i]. The pairs forms mirror the dictionary(pairs) constructor from Dictionaries; the forms taking a single lengths vector, single-argument pairs, or single-GradedOneTo set the domain equal to the codomain (square blocks). Bare TKS.Sectors are accepted alongside SectorRanges. Pair with randn!/rand! to fill.

FusedGradedVector{T,S<:SectorRange,D<:AbstractVector{T}}

Block-structured 1-D graded array produced by a sector-preserving operation on a FusedGradedMatrix (e.g. svd_vals, eig_vals, eigh_vals).

Fields:

• axis::Dictionary{S,Int} — axis layout, mapping each sector to its block size. Keys are sorted and unique. Stored non-dual (codomain convention).
• blocks::Dictionary{S,D} — stored data blocks, keyed by sector. Keys match keys(axis) exactly and length(blocks[s]) == axis[s].

FusedGradedVector(sectors::Vector{S}, blocks::Vector{D})

Build a FusedGradedVector whose axis and blocks carry the same sector list. axis[sectors[i]] is length(blocks[i]).

FusedGradedVector{T}(undef, sectors, datalengths)
FusedGradedVector{T}(undef, sectors .=> datalengths)

Allocate a FusedGradedVector with uninitialized blocks, datalengths[i] the reduced length of the block at sectors[i]. The two forms mirror the Dictionary(keys, values) and dictionary(pairs) constructors from Dictionaries. Bare TKS.Sectors are accepted alongside SectorRanges. Pair with randn!/rand! to fill.

FusionArray{T,S,N} <: AbstractGradedArray{T,S,N}

Always-fused symmetric array: an N-dimensional graded array with a codomain/domain split, backed by a matricized FusedGradedMatrix. The external axes are GradedOneTo and may be unfused or unsorted (a sector repeated, or out of SectorRange order); the matricized backing is always over the fused-sorted coupled space, and the per-leg sort permutation relates the two.

FusionArray(fm::FusionMap)

View a FusionMap back as a FusionArray, sharing its matricized blocks (zero-copy).

FusionArray(t::TK.AbstractTensorMap)

Build a FusionArray from a TensorMap, taking the per-leg external axes from its codomain and domain spaces.

FusionMap{T,S,N₁,N₂} <: TK.AbstractTensorMap{T,S,N₁,N₂}

An AbstractTensorMap view of a matricized FusedGradedMatrix with a given codomain/domain HomSpace. It shares the underlying blocks with the FusionArray it comes from, so TensorKit operations (permute, twist, …) mutate those blocks in place instead of round-tripping through a scratch TensorMap. block/subblock present the stored blocks as the reduced coupled-sector matrices and their per-fusion-tree strided views.

FusionMap(fa::FusionArray)

View a FusionArray as an AbstractTensorMap, sharing its matricized blocks (zero-copy).

GradedOneTo{S<:SectorRange}

Represents a graded axis — a collection of sectors with sector lengths and a dual flag. This is the axis type for AbelianGradedArray.

Stores non-dual SectorRange values in sectors, sector lengths, and a single isdual flag. The sectors accessor returns those stored non-dual sectors; query the duality separately with isdual. The dual flag is applied per block by eachblockaxis (and hence eachsectoraxis).

SectorIdentity{T,S<:SectorRange} <: AbstractSectorDelta{T, S, 2}

Fused 2D structural factor for a single coupled sector. By Schur's lemma, the structural part of each block in the fused (matricized) basis is the identity matrix for the irrep. Carries no free data — completely determined by the sector. The codomain axis is non-dual, the domain axis is dual.

SectorMatrix{T,S<:SectorRange,D<:AbstractMatrix{T}} <: AbstractSectorArray{T, S, 2}

Fused 2D data matrix for a single coupled sector. One block of a FusedGradedMatrix. In the representation-theoretic sense, this is an element of HomG(Vc, W_c) for coupled sector c — the reduced matrix element (degeneracy/multiplicity tensor) after Schur's lemma has factored out the structural part (SectorIdentity).

The codomain (row) axis is non-dual; the domain (column) axis is dual. The stored SectorRange is always non-dual (codomain convention).

SectorOneTo{S<:SectorRange}

Represents one sector's index space — a SectorRange (sector label + dual flag) paired with a data length (multiplicity). This is the building block for GradedOneTo.

Stores a SectorRange and a data length. The isdual accessor is derived from the stored SectorRange.

SectorOnesVector{T,S<:SectorRange} <: AbstractSectorDelta{T, S, 1}

Fused 1-D structural factor for a single coupled sector: the all-ones vector whose length is the sector's quantum dimension. It is the diagonal of the SectorIdentity that a FusedGradedVector picks out as the diagonal of a FusedGradedMatrix, so each reduced value is repeated once per state of the irrep. Carries no free data — completely determined by the sector. The axis is non-dual.

SectorRange(sector::TKS.Sector, isdual::Bool)

Unit range with elements of type Int that additionally stores a sector to denote the grading. Equivalent to Base.OneTo(length(sector)). Additionally holds a flag to denote the duality.

SectorVector{T, S<:SectorRange, D<:AbstractVector{T}} <: AbstractSectorArray{T, S, 1}

A single sector with a data vector. Analogous to SectorMatrix but for 1-D data (eigenvalues, singular values, etc.). Each element is a symmetry scalar — there is no Wigner-Eckart structural factor; the sector label simply identifies which block the values belong to.

The stored SectorRange is always non-dual (codomain convention).

TK.TensorMap(fa::FusionArray)

Convert a FusionArray to a TK.TensorMap, building the codomain/domain product spaces from the per-leg axes and copying each coupled-sector block.

fill(v, axs::GradedOneTo...)
fill(v, (codomain...)[, (domain...)])
fill(v, flux, (codomain...)[, (domain...)])

Like zeros for AbelianGradedArray, but filling every symmetry-allowed block with v (the element type is taken from v).

getindex(a::AbstractArray, ax1::GradedOneTo, axs::GradedOneTo...)

Construct an AbelianGradedArray by projecting the dense data of a onto the symmetry-allowed blocks of the graded axes (ax1, axs...), via TA.project (which errors if a has weight outside the allowed blocks). a is reshaped to length.((ax1, axs...)) first, so a trailing size-1 bond can be supplied implicitly. Each axis carries its own arrow, so index with dual/conj axes to set duality.

ones([T=Float64,] axs::GradedOneTo...)
ones([T=Float64,] (codomain...)[, (domain...)])
ones([T=Float64,] flux, (codomain...)[, (domain...)])

Like zeros for AbelianGradedArray, but filling every symmetry-allowed block with ones.

zeros([T=Float64,] axs::GradedOneTo...)
zeros([T=Float64,] (codomain...)[, (domain...)])
zeros([T=Float64,] flux, (codomain...)[, (domain...)])

Construct an AbelianGradedArray{T} over the given graded axes with every symmetry-allowed (zero-flux) block allocated and filled with zeros. Each axis may be a GradedOneTo or a vector of sector => multiplicity pairs. Passing a (codomain, domain) split builds a tensor map, storing the domain axes dual; a leading flux sector appends a multiplicity-1 leg carrying it, so the physical axes fuse to that total charge.

contraction_twist!(a::AbelianSectorArray, ndims_codomain::Int) -> a

Apply the twist convention for the supertrace formalism of fermionic contractions. This means that $⟨i| ⋅ |j⟩ = δᵢⱼ$, and $|i⟩ ⋅ ⟨j| = θᵢⱼ δᵢⱼ$. Here, $θᵢⱼ = ±1$ is defined as the phase from applying a self-crossing, which is always $1$ for bosonic symmetries, but can be $-1$ for odd fermion charges.

Equivalent to twist!(a, (i for i in 1:ndims_codomain if isdual(axes(a, i)))). A no-op unless BraidingStyle(sectortype(a)) is Fermionic.

See also twist!.

data(sa::AbstractSectorArray)

Return the raw data array underlying the sector array.

gradedrange(xs::AbstractVector{<:Pair})

Generic fallback that converts sector keys via to_sector before constructing GradedOneTo. This supports NamedTuple keys (for sector products) and other non-standard key types.

gradedrange(xs::AbstractVector{<:Pair{<:SectorRange, <:Integer}})

Construct a GradedOneTo from pairs of SectorRange to multiplicities. All SectorRange values must have the same isdual flag. Non-dual inputs produce a non-dual axis; dual inputs produce a dual axis.

Examples

gradedrange([U1(0) => 2, U1(1) => 3])     # non-dual
gradedrange([conj(U1(0)) => 2, conj(U1(1)) => 3])   # dual

Compute the parity of the number of inversions of a masked permutation

to_tensorkit_space(sectors)

Convert a vector of non-abelian sector => multiplicity pairs into a native TensorKit GradedSpace. Non-abelian symmetries have no block-sparse (GradedOneTo) representation, so to_range routes them here. The method that builds the space is defined in src/tensorkit.jl.

twist!(a::AbstractGradedArray, dims) -> a

Scale data(a) in place by prod(twist(sectoraxes(a, i)) for i in dims). Here, twist is defined as -1 for odd-parity fermionic charges and +1 otherwise.

This is a no-op unless BraidingStyle(sectortype(a)) is Fermionic.

See also contraction_twist!.