Bases Reference

AbstractBasis

Abstract supertype for all basis objects used by EDKit.

Every concrete basis stores a mutable digit buffer dgt together with enough metadata to move between three related descriptions of a many-body state:

• a concrete digit string such as [0, 1, 0, 1],
• a representative index stored in the basis contents,
• and, for symmetry-reduced bases, the normalization or phase needed to recover the corresponding physical state.

The two most important operations on any basis are:

• index: interpret the current dgt buffer as coordinates in the basis and return a coefficient/index pair,
• change!: load the ith stored basis state into dgt and return its normalization.

This abstraction is what allows operator construction, matrix assembly, entanglement calculations, and inter-basis maps to work with the same code across full and symmetry-reduced Hilbert spaces.

content(b::AbstractBasis, i::Integer)

Return the stored representative label for the ith basis state.

For most symmetry-reduced bases this is not the full state vector itself, but an integer encoding of the canonical representative digit string associated with that basis element. For TensorBasis, this is simply the ordinary tensor-basis index.

index(dgt::AbstractVector{T}; base::Integer=2, dtype::DataType=T) where T <: Integer

Convert a full digit string into EDKit's 1-based integer index.

The mapping is:

number = ∑ᵢ bits[i] * base^(L-i) + 1

Arguments:

• dgt: digit representation of a product state.
• base: local base used to interpret the digits.

Returns:

• The 1-based linear index corresponding to dgt.

Notes:

• This is the low-level indexing convention used throughout the package.
• The computation uses iterative polynomial evaluation rather than explicit powers for speed.

index(dgt::AbstractVector{T}, sites::AbstractVector{<:Integer}; base::Integer=2) where T <: Integer

Convert a subset of sites from a digit buffer into a 1-based local index.

Arguments:

• dgt: full digit buffer.
• sites: site positions to read, in the order they should appear in the local tensor product.
• base: local base used for interpretation.

Returns:

• The 1-based index of the subsystem specified by sites.

This is a central helper in local operator application, where a sparse local matrix acts only on a selected subset of sites.

index(b::ProjectedBasis; check=false)

Interpret the current digit buffer b.dgt as coordinates in the projected basis.

Arguments:

• b: projected basis whose working digit buffer has already been set.
• check: if true, throw an error when the current digits are not contained in the basis; otherwise return a zero coefficient.

Returns:

• (1, i) when the state is present as the ith projected basis vector.
• (0, 1) when the state is not present and check == false.

The zero-coefficient branch is important during operator assembly, where an off-sector state should silently contribute nothing instead of aborting the matrix construction.

index(b::TranslationalBasis)

Interpret the current digit buffer as coordinates in the translational basis.

Outputs:

• N: Normalization for the state b.dgt.
• i: Index for the state b.dgt.

Notes:

To calculate the index of a given digits, we first shift the digits to that of the minimum index, then search for the place in the basis. Because of the restriction from the momentum, some state with zero normalization (which is not included in the basis) will appear. To avoid exception in the matrix constructon of Operation, we allow the index to not in the basis content. When this happend, we return index 1, and normalization 0, so it has no effect on the matrix being filled.

index(b::TranslationParityBasis)

Return the coefficient/index pair for the current digit buffer in the translation-parity basis.

The returned coefficient includes both translation phase and reflection parity contributions relative to the stored representative.

index(b::TranslationFlipBasis)

Return the coefficient/index pair for the current digit buffer in the translation-flip basis.

index(b::ParityBasis)

Interpret the current digit buffer as coordinates in the parity-reduced basis.

The returned coefficient is either ±R[i] depending on whether the current digits match the stored representative directly or through reflection.

index(b::FlipBasis)

Interpret the current digit buffer as coordinates in the spin-flip basis.

index(b::ParityFlipBasis)

Interpret the current digit buffer in the combined parity/flip basis and return the coefficient/index pair for the corresponding representative.

index(B::AbelianBasis)

Interpret the current digit buffer as coordinates in the Abelian-reduced basis.

The returned coefficient includes both the stored normalization and the phase associated with the group element that maps the current digits to the canonical representative.

change!(b::AbstractBasis, i::Integer)

Load the ith basis state into b.dgt and return its normalization factor.

This is the inverse companion to index at the basis-object level: change! goes from stored basis coordinates to the current working digit representation, whereas index interprets the current digits in basis coordinates.

The method mutates b.dgt.

change!(dgt::AbstractVector{<:Integer}, ind::Integer; base::Integer=2)

Overwrite dgt with the product-state digits corresponding to ind.

Arguments:

• dgt: mutable digit buffer to overwrite.
• ind: 1-based product-state index.
• base: local base used for the decoding.

Returns:

• The mutated digit buffer dgt.

This is the inverse of index(dgt; base=...).

change!(dgt::AbstractVector{<:Integer}, sites::AbstractVector{<:Integer}, ind::Integer; base::Integer=2)

Overwrite only the selected entries of dgt with the subsystem digits encoded by ind.

Arguments:

• dgt: mutable full-system digit buffer.
• sites: site positions to overwrite.
• ind: 1-based subsystem index.
• base: local base used for decoding.

Returns:

• The mutated digit buffer dgt.

This is the inverse of index(dgt, sites; base=...) and is heavily used inside matrix-free operator application.

TensorBasis

Full tensor-product basis with no symmetry reduction.

The digit buffer dgt stores one local state label per site in base B. The corresponding global index is computed by:

I(i₁, i₂, ⋯, iₙ) = i₁ B^(n-1) + i₂ B^(n-2) + ⋯ + iₙ

TensorBasis is the reference basis against which more structured bases can be understood. Many EDKit workflows do not need to build it explicitly, but it is the conceptual full-space embedding used by maps, projections, and matrix assembly.

ProjectedBasis{Ti}

Basis obtained by selecting a subset of product states from the full tensor product Hilbert space.

This behaves like TensorBasis, but only retains basis vectors whose digit representation satisfies a user-defined predicate or a fixed charge N.

This is the standard choice for constrained Hilbert spaces where states remain product-state-labelled, but not every product state is allowed.

TranslationalBasis

Basis of lattice-momentum eigenstates, optionally combined with a projected constraint such as fixed N.

For each representative digit string dgt, the unnormalized orbit state is

|aₙ⟩ = ∑ᵢ Tⁱ |dgt⟩.

The normalized basis vector is

|n⟩ = Rₙ⁻¹ |aₙ⟩,

where T is translation by one unit cell and Rₙ is the normalization.

This basis is the core momentum-resolved state space used by EDKit. It keeps only canonical orbit representatives compatible with the requested momentum sector.

ParityBasis

Basis reduced by reflection parity.

The basis identifies each product state with its reversed digit string and keeps only one representative per reflection orbit, together with a parity eigenvalue P = ±1.

FlipBasis

Basis reduced by on-site spin-flip symmetry.

The flip operation maps each local digit d to base - 1 - d, so this basis is only compatible with sectors where the requested additional constraints are stable under that involution.

ParityFlipBasis

Basis reduced simultaneously by reflection parity and spin-flip parity.

This basis combines the two commuting involutions generated by reversal and spin flip. Each representative may have an orbit of size 1, 2, or 4 depending on stabilizers.

TranslationParityBasis

Basis reduced simultaneously by translation and reflection parity.

This basis is only valid in momentum sectors compatible with reflection, namely the sectors where the translation phase is real (k = 0 or zone-boundary equivalents). The resulting basis carries both a translation phase table C and a reflection eigenvalue P.

TranslationFlipBasis

Basis reduced simultaneously by translation and spin-flip symmetry.

Unlike TranslationParityBasis, the translation phase can be genuinely complex here because spin flip does not force the momentum sector to be reflection-compatible.

basis(dtype::DataType=Int64; L, f=nothing, base=2, N=nothing, k=nothing, a=1, p=nothing, z=nothing, threaded=base^L>3000)

High-level basis constructor for the common symmetry combinations supported by EDKit.

Keywords:

• L: system size.
• f: optional predicate used to impose additional local constraints.
• base: local Hilbert-space dimension.
• N: fixed U(1)-like charge sector.
• k: translation quantum number.
• a: unit-cell length used together with k.
• p: reflection-parity eigenvalue ±1.
• z: spin-flip eigenvalue ±1.

Return value:

• TensorBasis if no symmetry or constraint is requested.
• ProjectedBasis if only f and/or N is requested.
• AbelianBasis when one or more discrete symmetries (k, p, z) are used.

Notes:

• k and p are only simultaneously valid in the symmetry-compatible momentum sectors handled by the underlying basis implementation.
• N and z are only compatible in the half-filling sector for spin-1/2 systems, mirroring the restrictions of the dedicated basis types.
• This is the most convenient user-facing entry point when you want to combine several commuting symmetries without manually choosing a concrete basis type.

AbelianBasis

Basis built from a collection of commuting discrete symmetries represented as Abelian actions on digit strings.

This is the general symmetry-reduction backend used by the high-level basis constructor when one or more symmetry quantum numbers such as translation momentum, reflection parity, or spin-flip parity are requested.