hc

Adding this is equivalent to adding the hermitian conjugate.

AdditiveConstraint(allowed_values, subspaces=missing, functions)

Constraint enforcing that the sum of user-specified per-subspace contributions lies in allowed_values.

The constraint is evaluated on the factors used during state generation. For a composite Hilbert space this means atomic_factors(space).

FockNumber

A type representing a Fock state as the bitstring of an integer.

A source factor that is split into several pieces (or reshaped into one non-identical piece) by an inner leaf mapper.

HC

Represents the Hermitian conjugate.

LazyOperator{O,S,T,C,P}

A matrix-free (lazy) representation of a symbolic operator on a Hilbert space. Acts directly on vectors and matrices via without constructing a sparse matrix.

Constructed via matrix_representation(op, space, :lazy). LazyOperator conforms to the SciMLOperators.AbstractSciMLOperator interface.

NoSymmetry()

Constraint that leaves a Hilbert space unchanged.

NumberConservation(total=missing, subspaces=missing, weights=missing)

Constraint enforcing conservation of a (possibly weighted) particle number. total can be a single value or collection of allowed values.

ParityConservation(parities=[-1, 1], subspaces=missing)

Constraint enforcing allowed fermion parities, optionally on selected subspaces.

A source factor that goes unchanged into exactly one target slot. The trivial inner mapper is kept only for phase-factor computation; split/combine bypass it entirely.

PieceIndex{block, slot}

A routing index carried in the type domain. getpiece(blocks, ref) extracts blocks[block][slot] with compile-time-known indices, so heterogeneous tuples can be indexed without type instability.

ProductSpaceMapper(source::ProductSpace, targets)

Mapper between source and the partition (or sub-collection) targets.

Fields:

• leaves : per source factor, an Uncovered, Passthrough or Fractured leaf describing how that factor fractures.
• factor_routes : per source factor, one PieceIndex{target, group_slot} per piece (in the factor's piece order). Drives combine.
• target_routes : per target, one PieceIndex{factor, piece_slot} per group (in the target's group order). Drives split.
• target_spaces : the targets themselves.

factor_routes and target_routes are the two directional views of the same piece table; they are exact inverses of each other by construction.

SectorHilbertSpace

Hilbert space whose basis is grouped into sectors labeled by quantum numbers. Use quantumnumbers, sector, and indices to access individual sectors.

A source factor not covered by any target. It is dropped on split and cannot be reconstructed on combine.

_combined_sector_constraint(spaces)

Given a collection of Hilbert spaces, construct a combined constraint from the stored constraints of any SectorHilbertSpace inputs (localized to their respective subspaces). Returns missing if no usable sector information exists.

Parity of #{(i,j) : bit j set in a, bit i set in b, j > i (0-indexed positions)}. Returns true for odd count (contributes phase -1).

apply_local_operator(op::SpinSym, state::SpinState) -> (newstate, amplitude)

Apply a single spin operator to a spin state. Returns (newstate, amplitude) where amplitude is 0 if the operation is not allowed, and a nonzero value otherwise.

basisstates(H)

Return an iterable of basis states for the Hilbert space H, in the order used by matrix representations and indexing utilities.

bdg_hilbert_space(labels)

This hilbert space uses Nambu states to describe non-interacting systems with superconductive pairing. Matrix representations of quadratic operators take the form
[H Δ; -Δ* -H*]
where H is hermitian and Δ is antisymmetric.

combine_states(substates, mapper)

Combine subsystem states using mapper.

Contract: returns a states and weights states, weights.

constrain_space(space, constraint; kwargs...)
constrain_space(space, states)

Build a constrained Hilbert space from space, either by applying a constraint or by explicitly providing a list of allowed basis states.

dim(H)

Return the Hilbert-space dimension of H, i.e. the number of basis states.

embed(m, Hsub => H; complement=complementary_subsystem(H, Hsub), kwargs...)

Compute the embedding of a matrix m in the basis Hsub into the basis H. Fermionic phase factors are included if the two spaces are fermionic Hilbert spaces.

embed(Hsub => H; kwargs...)

Compute the embedding map from Hsub into H. Fermionic phase factors are included if the two spaces are fermionic Hilbert spaces.

fermion_sparse_matrix(fermion_number, H::AbstractHilbertSpace)

Constructs a sparse matrix of size representing a fermionic annihilation operator at bit position fermion_number on the Hilbert space H.

fermions(H)

Return a dictionary of fermionic annihilation operators for the Hilbert space H.

fixed_particle_number_fockstates(M, n)

Generate a list of Fock states with n occupied fermions in a system with M different fermions.

generalized_kron(ms, Hs, H::AbstractHilbertSpace=tensor_product(Hs))

Compute the tensor product of matrices or vectors in ms with respect to the spaces Hs, respectively. Return a matrix in the space H, which defaults to the tensor_product product of Hs.

generate_states(spaces, constraints; partial_processor=nothing, process_result=(state, space) -> state)

Generate all tensor product states from spaces satisfying constraint. Uses backtracking with pruning via valid_branch.

partial_processor(partial_state, depth, spaces) is called whenever a branch is accepted. process_result(full_state, spaces) can transform each completed state before storing it.

hilbert_space(args...)

Construct a Hilbert space from symbolic degrees of freedom and labels, optionally with additional arguments such as constraints.

jwstring(site, focknbr)

Parity of the number of fermions to the right of site.

kron_phase_factor(mapper)

Return phase-factor function associated with mapper for fermionic tensor products.

localize_constraint(c, H::SectorHilbertSpace)

Return a version of constraint c that is bound to H as its subspace, so that when sector_function is later called on a larger combined space it knows to extract the contribution from H only. Already-localized (non-Missing subspace) or unsupported constraints are returned unchanged.

majoranas(fermions)

Return a dictionary of Majorana operators for the Hilbert space H.

matrix_representation(op, space::AbstractHilbertSpace; kwargs...)

Return the matrix representation of symbolic operator op in Hilbert space space.

Keyword arguments include projection (default false) which if true will ignore the error thrown when the operator maps outside the space. Use chunking to control NCAdd construction strategy: NoChunking(), TermChunking(scheduler), or StateChunking(scheduler).

Examples

@fermions f
H = hilbert_space(f, 1:2)
op = f[1]' * f[2] + hc
M = matrix_representation(op, H)
size(M) == (dim(H), dim(H))

numberoperator(H)

Return the number operator for the Hilbert space H.

parityoperator(H)

Return the fermionic parity operator for the Hilbert space H.

partial_trace!(mout, m, H::AbstractHilbertSpace, Hsub::AbstractHilbertSpace, complement, extend_state=StateExtender((Hsub, complement), H); skipmissing=true, phase_factors=true)

Compute the partial trace of m from H to Hsub.

partial_trace(m, H => Hsub; complement=complementary_subsystem(H, Hsub))

Compute the partial trace of m from H to Hsub. Fermionic phase factors are included if both H and Hsub are Fermionic, unless specified otherwise in kwargs.

partial_trace(H => Hsub; kwargs...)

Compute the partial trace map from H to Hsub, represented by a sparse matrix of dimension dim(Hsub)^2 x dim(H)^2 that can be multiplied with a vectorized density matrix.

partition_factors_by_basis(factors::Vector, bases::Vector)

Partition a vector of operator factors into groups by their symbolic basis.

permutation_operator(H, Hs, perm)

Gives the matrix representation on H of a permutation perm of the partition Hs.

permutation_projector(H, Hs, perms, weights=nothing, T = Float64; normalize=true)

Build a group-averaged projector/operator from permutation operators: P = sum(weights[g] * R_g for g).

Hs may be either a full partition of H (covering all atomic factors) or a proper subsystem list (covering only a subset of atomic factors). In the subsystem case the projector is first constructed on Hsub = tensor_product(Hs...) and then embedded back into H via embed(Psub, Hsub => H).

quantumnumbers(H)

Return the quantum-number labels that define the sectors of H. For spaces without sector structure, this returns (nothing,).

removefermion(digitposition, f::FockNumber)

Return (newfocknbr, fermionstatistics) where newfocknbr is the state obtained by removing a fermion at digitposition from f and fermionstatistics is the phase from the Jordan-Wigner string, or 0 if the operation is not allowed.

representation(op_or_state, space::AbstractHilbertSpace; kwargs...)

Return a concrete representation of op_or_state in Hilbert space space.

• For symbolic operators, returns a sparse matrix (or lazy operator when lazy=true).
• For AbstractBasisState, returns a one-hot sparse column vector.
• For SymbolicState (ket/bra), returns the corresponding column/row vector.

sector(qn, H)

Return the sector of H corresponding to quantum number qn. For qn === nothing, this returns H for non-sector spaces.

sectors(H)

Return all sectors of H in the same order as quantumnumbers(H).

single_particle_hilbert_space(labels)

A hilbert space suitable for non-interacting systems with fermion number conservation. Matrix representations of symbolic operators give the single particle hamiltonian, without any contribution from the identity matrix.

indices(Hsub, H)
indices(qn, H)

Return the basis-state indices in H belonging to a given sector, specified either by a sector Hilbert space Hsub or by a quantum number qn.

split_state(state, mapper)

Split a state using mapper.

Contract: returns a tuple with one entry per target subsystem. Each entry is a weighted collection ((substate, weight), ...) for that target.

state_mapper(H, Hs)

Create a mapper object for decomposing states in H into the target subsystems Hs. The returned object must subtype AbstractStateMapper.

subregion(Hs, H::AbstractHilbertSpace)

Return the subsystem of H spanned by the factors Hs.

This is primarily used for product spaces where the subsystem is specified by a list/tuple of factor spaces.

Examples

H1 = hilbert_space(1:1)
H2 = hilbert_space(2:2)
H3 = hilbert_space(3:3)
H = tensor_product((H1, H2, H3))
Hsub = subregion((H1, H3), H)

symbolic_groups(op)

Extract all unique symbolic bases from an operator expression. Returns a set of unique bases found in the operator.

symmetric_sector(H, Hs, sector=:symmetric, T=Float64; normalize=true, cutoff=0.9, atol=1e-10)

Construct the projector onto symmetric sectors of H under permutations of the partition Hs.

If Combinatorics.jl is loaded, sector can be :symmetric or :antisymmetric to automatically generate the full set of permutations and weights for the symmetric or antisymmetric representation. Otherwise, sector must be a tuple of (perms, weights) to specify the permutations and their corresponding weights directly.

Hs may be either a full partition of H or a proper subsystem list; in the latter case the sector is constructed on tensor_product(Hs...) and embedded back into H.

tensor_product(ms, Hs, H::AbstractHilbertSpace; kwargs...)

Compute the ordered product of the fermionic embeddings of the matrices ms in the spaces Hs into the space H. kwargs can be passed a bool phase_factors.

tensor_product(spaces; constraint=NoSymmetry())

Construct the composite Hilbert space from the spaces in spaces, with optional keyword argument constraint.

togglefermions(digitpositions, daggers, f::FockNumber)

Return (newfocknbr, fermionstatistics) where newfocknbr is the state obtained by toggling fermions at digitpositions with daggers in the Fock state f, and fermionstatistics is the phase from the Jordan-Wigner string. If the operation puts two fermions one the same site, the resulting state is undefined.

valid_branch(constraint, partial_state, remaining_spaces) -> Bool

Return `true` if the branch should be explored, `false` to prune. By default this calls `constraint.f(partial_state, remaining_spaces)`.

vector_representation(op::NCMul, space) -> vector or adjoint-vector

For a product of ket SymbolicStates, apply each ket's operator action in sequence and return a sparse column vector. For bras, return the adjoint row vector.

@boson b

Create a symbolic bosonic annihilation operator b. Use b' for the corresponding creation operator.

@bosons b

Create a bosonic basis b. Index into it to get bosonic mode operators: b[i] returns the annihilation operator for mode i, b[i]' for the creation operator.

@fermions a b ...

Create one or more fermion species with the given names. Indexing into fermions species gives a concrete fermion. Fermions in one @fermions block anticommute with each other, and commute with fermions in other @fermions blocks.

Examples:

• @fermions a b creates two species of fermions that anticommute:
  • a[1]' * a[1] + a[1] * a[1]' == 1
  • a[1]' * b[1] + b[1] * a[1]' == 0
• @fermions a; @fermions b creates two species of fermions that commute with each other:
  • a[1]' * a[1] + a[1] * a[1]' == 1
  • a[1] * b[1] - b[1] * a[1] == 0

See also @majoranas.

@majoranas a b ...

Create one or more Majorana species with the given names. Indexing into Majorana species gives a concrete Majorana. Majoranas in one @majoranas block anticommute with each other, and commute with Majoranas in other @majoranas blocks.

Examples:

• @majoranas a b creates two species of Majoranas that anticommute:
  • a[1] * a[1] + a[1] * a[1] == 1
  • a[1] * b[1] + b[1] * a[1] == 0
• @majoranas a; @majoranas b creates two species of Majoranas that commute with each other:
  • a[1] * a[1] + a[1] * a[1] == 1
  • a[1] * b[1] - b[1] * a[1] == 0

See also @fermions.

@spin s

Create a symbolic spin basis s for constructing spin operators such as s[:z], s[:+], and s[:-].

@spins s

Create a spin basis s. Index into it to get site-specific spin bases: s[1][:z] gives the z-operator on site 1.