Operators Reference

Operator{Tv}

Many-body operator stored as a sum of local terms on a chosen basis.

Each term is represented by a sparse local matrix M[n] acting on lattice sites I[n], while B controls how those local actions are embedded into the full Hilbert space.

operator(mats::AbstractVector{<:AbstractMatrix}, inds::AbstractVector{<:AbstractVector}, B::AbstractBasis)

Construct an Operator from local matrices and the sites they act on.

Arguments:

• mats: local operator matrices.
• inds: site lists matching mats, using 1-based site labels.
• B: basis in which the operator should act.

Repeated site patterns are merged automatically by summing their local matrices.

Examples:

mat = spin((1.0, "xx"), (1.0, "yy"))
H = operator(fill(mat, L), [[i, mod(i, L) + 1] for i in 1:L], TensorBasis(L=L))

operator(s::String, inds, basis)

Convenience wrapper around spin and operator that builds a local operator matrix from a symbolic string before embedding it in the many-body basis.

operator(s::String, inds, L; base=2)

Construct an Operator from a symbolic local operator string acting on the full tensor-product basis of a length-L system.

trans_inv_operator(mat::AbstractMatrix, ind, basis_or_length)

Construct a translationally invariant operator by translating one local term around the lattice.

ind specifies the support of the seed term, for example 1:2 for a nearest- neighbor bond term. The function then generates all translated copies with periodic boundary conditions and sums them into a single Operator.

This accepts either a concrete basis or just a system size L.

trans_inv_operator(s::String, inds, basis)

Convenience wrapper around spin and trans_inv_operator for translation-invariant symbolic local terms.

trans_inv_operator(s::String, basis)

Construct a translation-invariant many-body operator from a symbolic local operator string whose support size is inferred from length(s).

trans_inv_operator(s::String, L; base=2)

Construct a translation-invariant symbolic operator on the full tensor-product basis of a length-L system.

spin(s::String; D::Integer=2)

Return the local operator encoded by the string s.

For D = 2, uppercase Pauli-style labels such as "X", "Y", "Z" are supported, as well as lowercase spin-operator labels such as "x", "y", "z", "+", "-", and "1". Multi-site strings like "xx" or "x1z" build Kronecker products in the given order.

Returns:

• A sparse local operator matrix acting on length(s) sites.

spin(spins::Tuple{<:Number, String}...; D::Integer=2)

Build a linear combination of local operators.

Each argument should be a pair (coefficient, "operator_string"), for example spin((1.0, "xx"), (1.0, "yy"), (0.5, "zz")).

Returns:

• The sparse linear combination of all requested local operator strings.

addto!(S::SchmidtMatrix, val)

Accumulate a contribution val into the Schmidt matrix entry selected by the current subsystem digits stored in S.A and S.B.

addto!(M::AbstractMatrix, opt::Operator)

Accumulate the matrix representation of opt into the preallocated array M.

This is useful when you want control over the output array type or want to reuse existing storage instead of calling Array(opt) or sparse(opt).

mul(opt::Operator, v)
mul(opt::Operator, m)

Multi-threaded multiplication of an Operator with a vector or matrix.

Unlike opt * v, this version parallelizes over input columns / basis states using Threads.@threads.

sparse!(opt::Operator) -> SparseMatrixCSC

Pre-compute and cache the sparse matrix representation of opt.

After calling sparse!(opt), subsequent opt * m and mul(opt, m) calls for matrix inputs will automatically use the cached sparse matrix via SparseArrays SpMM, which is typically 10–1000× faster than the default matrix-free path. Vector multiplication (opt * v) is unaffected and always uses the matrix-free kernel.

The cache holds up to 8 operators (LRU eviction). Call clear_sparse_cache! when you no longer need the cached matrices and want to reclaim memory.

When to use

Call sparse! when you plan to multiply the same operator by a matrix more than once (e.g. applying H to a block of eigenvectors, or inside an iterative solver). The one-time cost of building the sparse matrix is amortized over all subsequent multiplications.

Memory cost

The cached sparse matrix stores one ComplexF64 and one Int per structural nonzero, plus one Int per column. For a typical Heisenberg chain at half filling:

For very large systems where this overhead is prohibitive, skip sparse! and rely on the matrix-free path instead.

Example

H = trans_inv_operator(spin("xx","yy","zz"), 1:2, basis)

sparse!(H)             # one-time build + cache
result = H * states    # uses fast SpMM automatically
clear_sparse_cache!()  # free memory when done

clear_sparse_cache!()

Release all cached sparse matrices created by sparse!.

Call this after you are done with cached operator multiplication to free the memory occupied by the sparse representations.