Internals

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

Supertype of the fused (coupled-sector-block) graded arrays, FusedGradedMatrix and FusedGradedVector. Holds the code shared between the two.

AbstractGradedOneTo{S<:SectorRange} <: AbstractUnitRange{Int}

Supertype for graded axes — a unit range carved into sectors (its blocks), each with a data length (multiplicity), plus a range-level isdual arrow. Concrete subtypes differ only in storage and invariants:

• GradedOneTo stores parallel sectors/datalengths vectors and may hold repeated or unsorted sectors (the intermediate state of a not-yet-merged fusion).
• FusedGradedOneTo stores a sector-to-length Dictionary and is always fused and sorted (each sector once, in sorted order).

Subtypes must provide the primitive accessors sectors, datalengths, and isdual, plus dual and flip (which return the same concrete type). Everything below is derived from those.

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

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

• UniqueSectorArray: unfused N-D abelian data tensor (one sector per axis)
• FusedSectorMatrix: 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:

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

AdjointFusedGradedArray{T,S<:SectorRange,N,P<:AbstractFusedGradedArray{T,S,N}} <: AbstractFusedGradedArray{T,S,N}

Lazy adjoint (conjugate transpose) of a fused graded array, produced by adjoint/' on a fused graded matrix. Analogous to TensorKit's AdjointTensorMap and LinearAlgebra.Adjoint.

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.

FusedGradedDiagonal{T,S<:SectorRange,V<:DenseVector{T}} <: AbstractFusedGradedMatrix{T,S}

Square block-diagonal fused matrix whose every coupled-sector block is a Diagonal, the diagonal factor produced by a factorization (SVD singular values, eigenvalues). Analogous to TensorKit's DiagonalTensorMap. Wraps a FusedGradedVector of the diagonals; the Diagonal blocks are the lazy sectordata(d) view over that vector.

FusedGradedDiagonal(buffer, axis)

Wrap a contiguous buffer (shared, not copied) as a FusedGradedDiagonal with the given axis; the Diagonal blocks are the lazy sectordata view over the buffer. The axis is fused into canonical form. To build from per-sector diagonal data instead, use fusedgradeddiagonal.

FusedGradedMatrix{T,S<:SectorRange,V<:DenseVector{T}}

Block-diagonal matrix produced by matricizing a GradedArray. Stores a contiguous buffer in TensorKit .data layout plus the fused codomain/domain axes; the per-coupled-sector blocks are the lazy sectordata(m) view carved from the buffer on demand.

FusedGradedMatrix(buffer, codomain, domain)

Wrap a contiguous buffer (shared, not copied), already in TensorKit .data layout, as a FusedGradedMatrix with the given codomain and domain axes; the per-coupled-sector blocks are the lazy sectordata view over the buffer. The axes are fused into canonical form. To build from per-sector block data instead, use fusedgradedmatrix.

FusedGradedOneTo{S<:SectorRange}

A graded axis whose sectors are fused and sorted: each sector appears once and the sectors are in sorted order. This is the canonical form of the coupled-sector axes of a FusedGradedMatrix, and it also matches the sorted-and-merged convention TensorKit uses for a GradedSpace.

Stores a Dictionary mapping each (non-dual) SectorRange to its data length (multiplicity), plus a single isdual flag.

FusedGradedVector{T,S<:SectorRange,V<:DenseVector{T}}

Block-structured 1-D graded array produced by a sector-preserving operation on a FusedGradedMatrix (e.g. svd_vals, eig_vals, eigh_vals). Stores a contiguous buffer plus the fused axis; the per-sector blocks are the lazy sectordata(v) view carved from the buffer on demand.

FusedGradedVector(buffer, axis)

Wrap a contiguous buffer (shared, not copied) as a FusedGradedVector with the given axis; the per-sector blocks are the lazy sectordata view over the buffer. The axis is fused into canonical form. To build from per-sector block data instead, use fusedgradedvector.

FusedSectorMatrix{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).

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

A single sector with a data vector. Analogous to FusedSectorMatrix 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).

GradedOneTo{S<:SectorRange}

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

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).

SectorData{S,T,P,I} <: Dictionaries.AbstractDictionary{S,T}

Lazy dictionary of the per-coupled-sector block data of a fused graded array, wrapping the array itself. Keys are the coupled sectors; each value materializes on access as a view into the array's contiguous buffer (a 1-D view for a FusedGradedVector, a reshaped 2-D view for a FusedGradedMatrix), so no block-shaped storage is held and writes through a value land in the buffer. The value type is datatype(parent). A sectorindices dictionary (sector → offset/shape), the per-sector slice-and-reshape into the buffer, is precomputed from the fused axes so each block lookup is O(1).

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.

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.

UniqueSectorArray{T,S,N,NC,ND,A} <: AbstractSectorArray{T,S,N}

Unfused N-D data tensor for abelian symmetries. Stores a dense data array plus one SectorRange per axis with a codomain/domain split (NC codomain legs, ND domain legs, NC + ND == N). Implements the Wigner-Eckart decomposition: the full tensor is the Kronecker product of the structural UniqueSectorDelta (sector) with the data array (reduced matrix elements). The all-codomain case (NC == N) is the block a GradedArray yields (via fa[Block]).

UniqueSectorDelta{T,S<:SectorRange,N,NC,ND} <: AbstractSectorDelta{T,S,N}

Unfused N-D structural tensor for abelian symmetries. Stores one SectorRange per axis, split into NC codomain legs and ND domain legs (NC + ND == N); the all-codomain case (NC == N) is the block a GradedArray yields (via fa[Block]). For abelian symmetries, every element equals one(T) (the Kronecker delta selection rule).

TK.TensorMap(fa::GradedArray)

Convert a GradedArray 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, but filling every symmetry-allowed block with v (the element type is taken from v).

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

Construct a graded array (GradedArray) 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, 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 a graded array (GradedArray{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::UniqueSectorArray, 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.

fusedgradeddiagonal(sectors .=> data)
fusedgradeddiagonal(sectordata::Dictionary)

Build a FusedGradedDiagonal from the per-sector diagonal data (sector => data pairs, any iterator of pairs, or a Dictionary keyed by sector): the pair sectors[i] => data[i] gives the diagonal entries of the block at sectors[i]. The axis is derived from the blocks, as for fusedgradedvector. To wrap an existing contiguous buffer instead, use FusedGradedDiagonal.

fusedgradedmatrix(sectors .=> data, codomain, domain)
fusedgradedmatrix(sectordata::Dictionary, codomain, domain)

Build a block-diagonal FusedGradedMatrix from per-coupled-sector block data (sector => block pairs, any iterator of pairs, or a Dictionary keyed by sector) with the given codomain and domain axes. The codomain and domain sectors need not coincide; the stored blocks are keyed by the sectors common to both. Bare TKS.Sectors are accepted alongside SectorRanges; the sectors must be unique. To wrap an existing contiguous buffer instead, use FusedGradedMatrix.

fusedgradedmatrix(sectors .=> data)
fusedgradedmatrix(sectordata::Dictionary)

Build a block-diagonal FusedGradedMatrix from per-coupled-sector block data, deriving the codomain and domain from the blocks' row and column lengths (codomain[sectors[i]] is size(data[i], 1), domain[sectors[i]] is size(data[i], 2)). Valid only when the codomain, domain, and block sectors all coincide; pass explicit axes otherwise. Bare TKS.Sectors are accepted alongside SectorRanges; the sectors must be sorted and unique.

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

Construct a non-dual FusedGradedOneTo from sector => multiplicity pairs. The sectors must be non-dual and already in canonical fused form (each once, in sorted order); non-canonical or dual input is rejected by the constructor. Wrap the result in dual for a dual axis.

fusedgradedvector(sectors .=> data)
fusedgradedvector(sectordata::Dictionary)

Build a FusedGradedVector from per-sector block data (sector => data pairs, any iterator of pairs, or a Dictionary keyed by sector). The axis is derived from the blocks: axis[sectors[i]] is length(data[i]). Bare TKS.Sectors are accepted alongside SectorRanges; the sectors must be sorted and unique. To wrap an existing contiguous buffer instead, use FusedGradedVector.

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

to_tensorkit_space(sectors)

Convert a vector of sector => multiplicity pairs into a native TensorKit GradedSpace, used by the TensorKit interop layer to move a GradedOneTo into TensorKit's space representation. The method that builds the space is defined in src/tensorkit.jl.