Types

Base.Matrix(p::Pauli{N}) where N

Build dense matrix representation in standard basis

Base.Matrix(ps::PauliSum{N}; T=ComplexF64) where N

Create a dense Matrix of type T in the standard basis

Base.Matrix(p::PauliBasis{N}) where N

Build dense matrix representation in standard basis

Base.Matrix(O::PauliSum{N,T}, S::Vector{Ket{N}}) where {N,T}

Construct the matrix representation of operator O in the subspace spanned by kets S.

Returns an nS × nS matrix where M[i,j] = ⟨S[i]|O|S[j]⟩.

Uses X-bitstring grouping for efficiency: for each ket pair (i,j), only Pauli terms whose X-bitstring matches S[i].v ⊻ S[j].v are visited, rather than all terms in O.

Base.Vector(k::KetSum{N,T}) where {N,T}

Create a dense vector representation of the KetSum in the standard computational basis.

Base.Vector(K::KetSum{N,T}, S::Vector{Ket{N}}) where {N,T}

Project a KetSum onto the subspace defined by basis kets S.

Returns a vector of length length(S) with v[i] = K[S[i]].

Base.Vector(k::Union{Ket{N}, Bra{N}}; T=Int64) where N

Create dense vector representation in standard basis

AbstractQuantumChannel

Forward-compatibility supertype for quantum channels acting on PauliSums. The current implementation provides only top-level functions for single-qubit Pauli channels (depolarizing, dephasing/phase-flip, bit-flip, bit-phase-flip, plus a general pauli_channel!). Future channel types (generic Kraus, amplitude damping, Lindblad, …) will subtype this and dispatch on a uniform apply_channel! method.

AdaptiveTruncation(max_terms::Int, min_thresh::Float64)

If the number of terms exceeds max_terms, increase the clipping threshold to reduce the operator size. Otherwise clip at min_thresh.

CoeffTruncation(thresh::Float64)

Remove Pauli terms with |coefficient| <= thresh.

CompositeTruncation(strategies...)

Apply multiple truncation strategies in sequence.

Strategies are stored as a typed Tuple rather than Vector{TruncationStrategy}, so the per-element dispatches inside _apply! resolve at compile time and the inner coeff_clip! / weight_clip! calls inline. Constructing via the variadic form (CompositeTruncation(CoeffTruncation(1e-4), WeightTruncation(5))) is the supported call style; an AbstractVector constructor is also provided for convenience but converts to a tuple internally.

CorrectionAccumulator

Abstract supertype for truncation-error trackers passed to truncate! and evolve!: observables are measured before and after each truncation and the differences accumulate. See EnergyCorrection, EnergyVarianceCorrection, NoCorrection. Define a new accumulator by subtyping and implementing _measure(O, corr) and _accumulate!(corr, before, after).

A scaled dyad operator s * |ket><bra|, up to 128 qubits.

Dyad(N::Integer, k::Integer, b::Integer)

Create an N-qubit Dyad with scalar 1 from integer ket index k and bra index b.

Dyad(ket::Vector{T}, bra::Vector{T}) where T<:Union{Bool, Integer}

Create a Dyad with scalar 1 from vectors of 0s and 1s for the ket and bra.

A basis for Dyad's, which is not closed under multiplication. Since the product of two arbitrary dyad's don't generally create another dyad (e.g., while |i><j| * |j><l| = |i><l|, most products create scalars: |i><j| * |k><l| = 0). As such the product of two DyadBasis objects is not a DyadBasis object, but a Dyad, which contains a scalar factor. This type is primarily used to provide a basis for linear combinations of Dyad's, e.g., DyadSum's.

DyadBasis(N::Integer, k::Integer, b::Integer)

Create an N-qubit DyadBasis from integer ket index k and bra index b.

DyadBasis(ket::Vector{T}, bra::Vector{T}) where T<:Union{Bool, Integer}

Create a DyadBasis from vectors of 0s and 1s for the ket and bra.

EnergyCorrection(ψ::Ket{N})

Track accumulated change in ⟨ψ|O|ψ⟩ due to truncation.

EnergyDropSink{W}

Drop sink for EnergyCorrection on SparsePauliVector kernels: Δ⟨O⟩ = −⟨B⟩ needs only the dropped diagonal (x = 0) terms, each contributing ±c by the z/ψ parity. No run tracking, no phases beyond a sign, kept terms ignored.

EnergyVarianceCorrection(ψ::Ket{N})

Track accumulated changes in both ⟨ψ|O|ψ⟩ and Var(O,ψ) due to truncation.

An occupation number vector, up to 128 qubits

Ket(N::Integer, v::Integer)

Create an N-qubit Ket from the integer v (bits beyond N are masked off).

Ket(vec::Vector{T}) where T<:Union{Bool, Integer}

Create a Ket from a vector of 0s and 1s representing qubit occupations.

MajoranaWeightTruncation(max_weight::Int)

Remove Pauli terms with Majorana weight > max_weight.

MergeFilter

Compiled truncation predicate for the SparsePauliVector kernels. Sentinels disable individual checks: typemax(Int) for the weight cutoffs, negative thresholds for the coefficient cutoffs (thresh = -1.0 keeps exact zeros, matching NoTruncation; coeff_clip! semantics are "drop |c| <= thresh"). Built from a TruncationStrategy by _compile_filter.

NoCorrection()

Track nothing during truncation. Zero overhead.

NoTruncation()

Identity truncation — does nothing.

Pauli{N}

is our basic type for representing Pauli operators acting on N. Assume we want to represent a Pauli string of the following form:

σ1 ⊗ σ2 ⊗ σ3 ⊗ ⋯ ⊗ σN,

where, σ ∈ {X, Y, Z, I}. To do this efficiently, we use the symplectic representation of the Pauli group, where we factor each Pauli into a product of X and Z operators:

σ = i^(3*(z+x)%2) Zᶻ Xˣ,

with z,x ∈ {0,1}. The phase factor comes from the fact that Z*X = iY. In this representation, any tensor product of Pauli's is represented as two binary strings, one for x and one for z, along with the associated phase accumulated from each site. The format is as follows:

i^θ   Z^z₁ ⋅ X^x₁ ⊗ Z^z₂ ⋅ X^x₂ ⊗ ⋯ ⊗ Z^zₙ ⋅ X^xₙ

Products of operators simply concatonate the left and right strings separately. For example, To create a Y operator, bits in the same locations in z and x should be on.

XYZIy = 11001|01101     where y = iY

Since we get a factor of i each time we create a Y operator, we need to keep track of this to cancel the phase θs, arising from the ZX factorization.

P₁⊗...⊗Pₙ = i^θs ⋅ z₁...|x₁...  where Pᵢ ∈ {I,X,Y,Z}.

similarly,

z₁...|x₁... = i^-θs ⋅ P₁⊗...⊗Pₙ

We use θs to denote the phase needed to make the Pauli operator Hermitian and positive, and we refer to this as the symplectic_phase, since it arises solely from the symplectic representation of the Pauli. However, this is not the only phase we need to worry about. Since various phases accumulate during Pauli multiplication, we allow a given Pauli to have an arbitrary global phase, θg, so that the Pauli type can be closed under multiplication. As such, our Pauli phases are defined according to the following:

Pauli{N}(s,z,x)  =  s ⋅ z₁...|x₁... 
                 =  s ⋅ i^-θs ⋅ P₁⊗...⊗Pₙ
                 =  coeff ⋅ P₁⊗...⊗Pₙ

PauliBasis{N}(z,x)  =  i^θs ⋅ z₁...|x₁... 
                        =  P₁⊗...⊗Pₙ

Phase definitions:

• symplectic_phase: θs - phase needed to cancel the phase arising from the ZX factorized form: θs = θ-θg

Since we need to keep track of a phase for a Pauli, we might as well let it become a general scalar value for broader use. As such, Pauli.s is a arbitrary complex number.

Pauli(N::Integer; X=[], Y=[], Z=[])

constructor for creating PauliBoolVec by specifying the qubits where each X, Y, and Z gates exist

Pauli(str::String)

Create a Pauli from a string, e.g.,

a = Pauli("XXYZIZ")

This is convenient for manual manipulations, but is not type-stable so will be slow.

Pauli(z::Integer, x::Integer, N)

Construct a Pauli{N} from integer bitstrings z and x with scalar s=1.

z::Int128
x::Int128

A positive, Hermitian Pauli, used as a basis for more general Pauli's (which can have a complex phase). These are primarily used to provide a basis for linear combinations of Paulis, e.g., PauliSum's.

PauliBasis{N}(z,x)  =  i^θs ⋅ z₁...|x₁... 
                        =  P₁⊗...⊗Pₙ

Phase definitions:

• symplectic_phase: θs - phase needed to cancel the phase arising from the ZX factorized form: θs = θ-θg

PauliBasis(p::Pauli{N}) where N

Return the PauliBasis with the same operator part as p

PauliSum{N, T} = Dict{Tuple{Int128,Int128},T}

A collection of Paulis, joined by addition. This uses a Dict to store them, however, the specific use cases should probably dictate the container type, so this will probably be removed.

PauliSum(v::SparsePauliVector)

Gather back into a Dict-based PauliSum. Only valid on merged state (no pending appends), which is what every public operation leaves behind.

SparsePauliVector(N, T=ComplexF64; capacity=16)

Empty N-qubit sum with coefficient type T and initial term capacity capacity. The packed word type is chosen automatically.

SparsePauliVector{N,W,T}

A sum of N-qubit Pauli terms stored as flat sorted parallel arrays — the zero-allocation replacement for the Dict-backed PauliSum{N,T}. W is the packed bit-word type (UInt64 for N ≤ 64, chosen automatically by the constructors), T the coefficient type (Float64 suffices for Hermitian operators and halves coefficient bandwidth).

Three parallel-array buffer sets:

• live z/x/c[1:n]: current terms, sorted by strictly increasing (z, x) key, duplicate-free.
• append az/ax/ac[1:an]: sin-branch terms created during an evolution window, unsorted. an == 0 whenever any public API other than the evolve internals runs.
• scratch sz/sx/sc: merge output; swapped with live by field assignment (pointer swap, never a copy).

ws is the preallocated sort/merge workspace, hist a fixed-size |c| exponent histogram for adaptive truncation thresholds.

The struct is deliberately mutable: n/an change constantly and the merge pointer-swaps live↔scratch via field reassignment. This costs nothing in hot loops — kernels take the raw Vectors as arguments.

Supports the full PauliSum API (arithmetic, evolve!, truncate!, expectation values, clips, ...). Convert with PauliSum(v) / SparsePauliVector(O). Note setindex!/delete! are O(n) (sorted insert); build from a PauliSum or with sum! for bulk construction.

SparsePauliVector(O::PauliSum{N}; T, capacity_factor=2.0, append_factor=1.0,
                  min_capacity=16, imag_tol=1e-10)

Convert a Dict-backed PauliSum into flat sorted storage.

capacity_factor sizes the live buffer relative to length(O) (headroom for population growth between truncations); append_factor sizes the evolve-time append buffer relative to the live buffer. Exhaustion during evolution triggers an early merge and, if the population genuinely needs more room, chunked buffer doubling at the window boundary — never a hot-loop reallocation.

Real T requires (numerically) real coefficients: terms with |imag(c)| > imag_tol·max(1,|c|) are an error.

StochasticCoeffTruncation(epsilon::Float64; rng=Random.default_rng())

Unbiased stochastic compression (Russian Roulette). Wraps stochastic_clip!.

For each term with |c| < epsilon:

• Keep with probability |c|/epsilon (promote to epsilon·sign(c))
• Delete with probability 1 - |c|/epsilon

StochasticSamplingTruncation(n_keep::Int; rng=Random.default_rng())

Stochastically sample n_keep terms via importance sampling with probabilities proportional to |c_i|^2. Kept terms are rescaled to preserve norm.

TruncationStrategy

Abstract supertype for term-truncation strategies applied by truncate! and the truncation/local_truncation keywords of evolve!. Define a new strategy by subtyping and implementing _apply!(O, s).

WeightDampedTruncation(alpha::Float64, thresh::Float64)

Remove Pauli terms with |coefficient|·exp(-alpha·weight) <= thresh, i.e. a coefficient threshold that grows exponentially with Pauli weight. alpha = 0 reduces to CoeffTruncation(thresh); large alpha approaches a hard weight cutoff.

WeightTruncation(max_weight::Int)

Remove Pauli terms with Pauli weight > max_weight.

WindowCounters(nwindows)

Preallocated per-window instrumentation for evolve! (design invariant: everything measurable, nothing allocated in the hot path). allocd[w] is the Base.gc_num() allocation delta across window w — any nonzero entry after warm-up is a bug, enforced by the test suite. Early (capacity-forced) merges accumulate into the window they occur in.

XRunDelta{W}

Drop/keep sink for EnergyVarianceCorrection on SparsePauliVector kernels. Carries the current x-run's kept/dropped amplitude sums and the finished cross-run accumulators (see the block comment above).

XWeightDampedTruncation(alpha::Float64, thresh::Float64)

Remove Pauli terms with |coefficient|·exp(-alpha·x_weight) <= thresh, i.e. a coefficient threshold that grows exponentially with X-weight (the number of X/Y factors). alpha = 0 reduces to CoeffTruncation(thresh); large alpha approaches a hard X-weight cutoff.

XWeightTruncation(max_weight::Int)

Remove Pauli terms with X-weight (number of X/Y factors) > max_weight.

AnyPauliSum{N,T}

Union of the two Pauli-sum representations, for methods that only iterate (PauliBasis, coefficient) pairs and work identically on both.