A single-qubit Pauli symbol.

The four standard Paulis are encoded so that the low two bits identify the operator (I = 0b00, X = 0b01, Z = 0b10, Y = 0b11), which is the same encoding stabilizer-formalism tools commonly use. The extra variant Pauli::L marks a qubit as lost, used by the loss-aware portions of the runtime.

Examples

use ppvm_traits::char::Pauli;

assert_eq!(Pauli::I.to_string(), "I");
assert_eq!(Pauli::X.to_string(), "X");
assert_eq!(Pauli::Y.to_string(), "Y");
assert_eq!(Pauli::Z.to_string(), "Z");
assert_eq!(Pauli::L.to_string(), "L");

Compile-time configuration bundle for a PauliSum.

Config is a zero-cost generic dispatch mechanism: it pins down the storage backing (Storage), coefficient type (Coeff), truncation strategy (Strategy), hasher (BuildHasher), Pauli-word representation (PauliWordType), and concrete map (Map) used by a single PauliSum instantiation. Pre-built bundles live in the submodules (fxhash, indexmap, …); user code may define its own.

Rotation about an axis in the x/y plane: R(axis_angle, θ) = exp(-i θ/2 · (cos(axis_angle)·X + sin(axis_angle)·Y)).

The in-plane axis is X rotated about Z by axis_angle, so R(axis_angle, θ) = RZ(axis_angle)·RX(θ)·RZ(−axis_angle).

Two-qubit Pauli rotations, generated by P_a ⊗ P_b for any pair of non-identity Paulis. Provides the named convenience methods rxx, rxy, …, rzz on top of the generic rotate_2.

The non-Clifford T gate and its adjoint.

T = diag(1, e^{iπ/4}). Implemented by the simulator backends; see the example in ppvm_tableau.

The minimal Clifford gate set: the single-qubit Paulis (X, Y, Z), Hadamard (H), phase gate (S), and the two entangling Cliffords CNOT and CZ.

Implemented by PauliSum, by every tableau type, and — via the blanket impl in this module — by every PauliWordTrait implementor.

Examples

Build the GHZ-preparation circuit on a PauliSum (Heisenberg picture, so gates are applied in reverse). PauliSum lives in the downstream ppvm-pauli-sum crate, so this example is ignored here:

use ppvm_pauli_sum::prelude::*;

let mut state: PauliSum<config::indexmap::ByteFxHashF64<1>> =
    PauliSum::builder().n_qubits(2).build();
state += ("ZZ", 1.0);
state.cnot(0, 1);
state.h(0);
assert_eq!(state.len(), 1);

Batched Clifford gates: apply the same gate to many qubits in one call.

Default implementations loop over the corresponding single-qubit (or single-pair) method on Clifford. Types like the stabilizer Tableau override these methods with a fused inner-loop or bitmask implementation. Types that don't need specialization can implement this trait with an empty impl to use the defaults.

Numeric coefficient type usable inside a PauliSum.

Coefficient bundles every arithmetic operation a Pauli-propagation step needs — addition, multiplication, signed multiplication, half, sin/cos, and a cutoff predicate used by truncation strategies. The built-in f64 impl covers the common case; Complex<f64> is available when phase tracking is required.

Post-processing that a PauliWord's hasher applies to its raw 64-bit digest before it is cached as the map-key hash.

The cached value is what hashbrown ultimately splits into a bucket index (low bits) and a control-byte tag (top 7 bits). Whether the raw digest is good enough for that split is a property of the hasher, not of the Pauli word: an AES-based hasher such as gxhash avalanches well even for an 8-byte key, whereas FxHasher — a couple of multiply-rotate rounds — leaves the low bits of a short key highly correlated and needs a fold to fix them.

Keeping this on the hasher is what makes the abstraction correct. An earlier version folded based on storage width alone, which conflated "narrow storage" with "weak hasher" and so wrongly folded gxhash too. Here each hasher declares how (if at all) its output must be adjusted, and PauliWord::rehash just defers to it. The default is the identity — the right choice for any hasher that already distributes its low bits well — so a custom hasher opts in with a bare impl HashFinalize for MyHasher {}.

Aggregate trait combining every operation a backing map must support to be usable as the storage for a PauliSum.

You don't normally implement ACMap directly: the blanket impl below covers any type that implements all the constituent traits.

Minimal interface for any "associative coefficient map" backing a PauliSum — construction, length, and clear.

Implementations exist for HashMap, IndexMap, and DashMap; pick one via a Config.

State-dependent ("asymmetric") single-qubit loss channel: a qubit is lost from |0⟩ with probability p0 and from |1⟩ with probability p1. Unlike LossChannel, the total loss probability depends on the qubit's populations, so the channel reads the current ⟨Z⟩.

Backing storage for a PauliWord — a fixed-size, Copy-able block of bits (typically [u8; N] or [u64; N]).

The bytemuck::Pod bound guarantees the storage is a plain-old-data type with no padding and all bit patterns valid, which lets PauliWord::rehash view it as a &[u8] for fast byte-slice hashing without unsafe. Every concrete storage used here ([u8; N], [u64; N]) is already Pod.

A truncation policy applied to a PauliSum during Pauli propagation.

The strategy controls two things: the initial capacity allocated for the underlying map (estimating how many Pauli paths the simulation is expected to generate) and the cut applied when truncate is called explicitly. Implementations include NoStrategy, the coefficient-magnitude threshold, the max-Pauli-weight bound, etc.

Trait for computing trace(self * RHS).

If a type implements Trace, a corresponding TraceBy implementation is also provided automatically.

Word-level Pauli operations. Types implementing this trait automatically gain crate::traits::Clifford and crate::traits::CliffordExtensions behavior via blanket impls in the crate::traits::clifford module, using get_lbit / get_xbit / set_xbit / set_zbit / rehash to transform Pauli words.

Word-level vs. state-level gate semantics

The blanket Clifford impl applies gates at the bit level of a single Pauli word. X / Y / Z are bit-level no-ops on a Pauli word — they affect phase, not the X/Z bits — so word.x(i), word.y(i), word.z(i) are deliberately silent. Phase is tracked separately by PhasedPauliWord, which implements Clifford manually.

If you need a word representation whose gate behavior is not pure bit manipulation (phase tracking, fused multi-qubit updates, alternative loss semantics), do not implement PauliWordTrait on it — define a specialized Clifford impl instead, the way PhasedPauliWord does. Implementing both PauliWordTrait and a custom impl Clifford for ... for the same type will not compile: the blanket impl overlaps with your custom impl (coherence error), not silently shadows it.

A PauliWord-like type that additionally tracks per-qubit loss.

In neutral-atom hardware (and in any loss-aware error model), a measurement can return "lost" instead of 0 or 1. LossyPauliWord adds a parallel lbits array marking which qubits have been lost; a set loss bit excludes that qubit from the standard Pauli operations and shows up as the [Pauli::L] symbol.

Examples

use ppvm_traits::char::Pauli;
use ppvm_pauli_word::loss::LossyPauliWord;
use ppvm_traits::traits::PauliWordTrait;

let w: LossyPauliWord<[u8; 1]> = "XLZL".into();
assert_eq!(w.weight(), 4);          // X, L, Z, L are all non-identity
assert_eq!(w.loss_weight(), 2);     // two qubits are lost
assert!(w.is(1, Pauli::L));
assert!(w.is(0, Pauli::X));

A Pauli pattern representing a set of matching Pauli words.

Example

[XY]2Z3 represents X2Z3 or Y2Z3. Z? represents any Pauli word with I or Z.

A PauliWord paired with one of the four fourth-roots of unity.

The phase field encodes the scalar prefactor:

(i.e. the low bit is the imaginary flag and the high bit is the sign.)

Examples

use ppvm_pauli_word::phase::PhasedPauliWord;

// Parse from a "[sign][i]<PauliString>" literal.
let pw: PhasedPauliWord<u64> = "+iXYZI".into();
assert_eq!(pw.n_qubits(), 4);
assert_eq!(pw.phase, 1);            // +i
assert!(pw.is_positive());

let neg: PhasedPauliWord<u64> = "-XYZI".into();
assert_eq!(neg.phase, 2);           // -1
assert!(!neg.is_positive());

A fixed-width Pauli string stored as parallel x and z bit arrays.

Each qubit slot is encoded by two bits, (x, z), giving the four Pauli operators I = (0,0), X = (1,0), Z = (0,1), Y = (1,1) — the same encoding stabilizer-formalism tools use. The bit arrays live in a single PauliStorage blob (typically [u8; N] or [u64; N]), so a PauliWord<[u8; 1]> packs up to 8 qubits, [u8; 2] up to 16, etc.

A cached hash speeds up use as a map key; pass REHASH = false if you build words in bulk and want to control rehashing manually.

Examples

use ppvm_traits::char::Pauli;
use ppvm_traits::traits::PauliWordTrait;
use ppvm_pauli_word::word::PauliWord;

// Build a word from a string …
let w: PauliWord<[u8; 1]> = "XYZI".into();
assert_eq!(w.n_qubits(), 4);
assert_eq!(w.get(0), Pauli::X);
assert_eq!(w.get(3), Pauli::I);

// … or build it slot-by-slot.
let mut w2: PauliWord<[u8; 1]> = PauliWord::new(2);
w2.set(0, Pauli::X).set(1, Pauli::Y);
assert_eq!(w2.to_string(), "XY");
assert_eq!(w2.weight(), 2);

Membership test for pattern types.

Implemented by Pauli patterns over symbols (Contains<Pauli>) and over whole words (Contains<W: PauliIter>); used by the masking machinery to ask "does this pattern accept this concrete word?"

HashMap-backed Config with native-word ([usize; N]) storage and FxHasher.

The storage element is usize, i.e. the target's native machine word: u64 on 64-bit targets (identical layout and performance to a hardcoded [u64; N]) and u32 on 32-bit targets such as wasm32. Using usize rather than u64 keeps this config available on every target — bitvec only implements BitStore for u64 on 64-bit pointer widths, but always implements it for usize. (The Byte8 name refers to the 64-bit word this config packs into on native targets.)

IndexMap-backed Config with [u8; N] storage and gxhash.

gxhash is AES-based and native-only, so this config is unavailable on wasm32; use ByteFxHash there.

Drop terms whose coefficient magnitude falls below the given threshold. Defaults to 1e-12.

Examples

use ppvm_pauli_sum::prelude::*;
use ppvm_pauli_sum::strategy::CoefficientThreshold;

let strict = CoefficientThreshold(1e-6);
let mut state: PauliSum<config::indexmap::ByteFxHashF64<1, CoefficientThreshold>> =
    PauliSum::builder().n_qubits(2).strategy(strict).build();
state += ("ZZ", 1.0);
state += ("XX", 1e-9);              // below threshold
state.truncate();
assert_eq!(state.len(), 1);         // the XX term was dropped

Two strategies run in sequence: S1 then S2.

The capacity hint is the smaller of the two; truncation applies both policies in order, so use this when you want, e.g., "drop by coefficient threshold and cap maximum Pauli weight".

Drop terms whose Pauli weight (number of non-identity slots) exceeds the given bound.

Examples

use ppvm_pauli_sum::prelude::*;
use ppvm_pauli_sum::strategy::MaxPauliWeight;

// Keep only weight-1 terms.
let strat = MaxPauliWeight(1);
let mut state: PauliSum<config::indexmap::ByteFxHashF64<1, MaxPauliWeight>> =
    PauliSum::builder().n_qubits(3).strategy(strat).build();
state += ("XII", 1.0);              // weight 1, kept
state += ("XYI", 1.0);              // weight 2, dropped
state.truncate();
assert_eq!(state.len(), 1);

Represents a [State] that has [IsUnset] implemented for all members.

This is the initial state of the builder before any setters are called.

Represents a [State] that has [IsSet] implemented for [State::Capacity].

The state for all other members is left the same as in the input state.

Represents a [State] that has [IsSet] implemented for [State::NQubits].

The state for all other members is left the same as in the input state.

Represents a [State] that has [IsSet] implemented for [State::PreserveStrings].

The state for all other members is left the same as in the input state.

Represents a [State] that has [IsSet] implemented for [State::Strategy].

The state for all other members is left the same as in the input state.

A sparse formal sum Σ cᵢ Pᵢ of Pauli strings.

The central data type of the Pauli-propagation backend. Keys are PauliWord-shaped Pauli strings; values are numeric coefficients. Generic over a Config that fixes the concrete storage / hasher / coefficient / strategy.

Internally PauliSum holds two maps — a primary and an auxiliary — and swaps between them during gate propagation to avoid repeated allocations. The [PauliSum::data] / [PauliSum::aux] accessors expose the current orientation; most callers will only ever touch the primary side via the high-level gate / measurement traits.

Examples

Heisenberg-picture propagation of ZZ through the GHZ circuit:

use ppvm_pauli_sum::prelude::*;

let mut state: PauliSum<config::indexmap::ByteFxHashF64<1>> =
    PauliSum::builder().n_qubits(2).build();
state += ("ZZ", 1.0);

// Circuit: H(0); CNOT(0, 1) — apply in reverse for Heisenberg propagation.
state.cnot(0, 1);
state.h(0);

// ZZ → IZ under the GHZ circuit, with coefficient 1.0.
assert_eq!(state.len(), 1);

Marker trait that indicates that all required members are set.

In this state, you can finish building by calling the method PauliSumBuilder::build()

Builder's type state specifies if members are set or not (unset).

You can use the associated types of this trait to control the state of individual members with the [IsSet] and [IsUnset] traits. You can change the state of the members with the Set* structs available in this module.

Generalized stabilizer-tableau simulator built on top of the ppvm core crates (ppvm-traits and ppvm-pauli-word).

Provides a forward-evolving state representation using the stabilizer formalism, extended to non-Clifford gates by tracking a sparse vector of coefficients indexed over bitstrings. The two top-level types are data::Tableau (pure Clifford) and data::GeneralizedTableau (Clifford + non-Clifford with sparse coefficient tracking).

Quick example

Prepare a Bell pair and verify the two measurements are perfectly correlated:

use ppvm_tableau::prelude::*;
use ppvm_pauli_sum::config::fxhash::ByteF64;

let mut tab: GeneralizedTableau<ByteF64<1>> =
    GeneralizedTableau::new_with_seed(2, 1e-12, 0);
tab.h(0);
tab.cnot(0, 1);

let r0 = LossyMeasure::measure(&mut tab, 0);
let r1 = LossyMeasure::measure(&mut tab, 1);
assert_eq!(r0, r1);

Pauli-string expectation values and pattern traces. Pauli-string expectation values for GeneralizedTableau.

Two entry points:

• [GeneralizedTableau::expectation] — single-Pauli ⟨ψ|P|ψ⟩ for a PauliWord. Conjugates P through the tableau and overlaps the resulting Pauli with the sparse coefficient vector using the same formulas as the measurement code.
• [GeneralizedTableau::trace] — Σ_{P matches pattern} ⟨ψ|P|ψ⟩ for a PauliPattern. Enumerates the matching Paulis and sums their expectations.

Decision 9 in the multi-backend plan calls these out as the natural primitive for the tableau backend; semantics intentionally diverge from the PauliSum trace.

TableauLike — shared trait for stabilizer-tableau backends. TableauLike trait: shared interface for stabilizer-tableau backends.

Any type implementing TableauLike gets default implementations of single- and two-qubit Pauli noise channels (Depolarizing, PauliError, Depolarizing2, TwoQubitPauliError). New tableau backends only need to provide TableauLike::rng_mut and (optionally) override TableauLike::is_qubit_lost.

A Tableau extended with sparse coefficient tracking to handle non-Clifford gates.

Non-Clifford gates (T, rotations) split a single tableau into a sum of weighted branches indexed by bitstrings. GeneralizedTableau stores those weights in a SparseVector keyed by an IndexType. Choose:

• IndexType = usize for up to 64 qubits,
• IndexType = u128 for up to 128,
• IndexType = bnum::types::U256 and friends for the very wide regime.

Per-qubit loss is tracked in is_lost; gates respect it automatically.

Examples

Prepare a Bell pair and sample one shot. With a fixed seed the two measurements are perfectly correlated on every shot:

use ppvm_pauli_sum::config::fxhash::ByteF64;
use ppvm_traits::traits::{Clifford, LossyMeasure};
use ppvm_tableau::data::GeneralizedTableau;

let mut tab: GeneralizedTableau<ByteF64<1>> =
    GeneralizedTableau::new_with_seed(2, 1e-12, 0);
tab.h(0);
tab.cnot(0, 1);

let r0 = LossyMeasure::measure(&mut tab, 0);
let r1 = LossyMeasure::measure(&mut tab, 1);
assert_eq!(r0, r1);

Non-Clifford gates work through the same interface — apply a T gate followed by T† and the state is unchanged:

use ppvm_pauli_sum::config::fxhash::ByteF64;
use ppvm_traits::traits::{Clifford, TGate};
use ppvm_tableau::data::GeneralizedTableau;

let mut tab: GeneralizedTableau<ByteF64<1>> =
    GeneralizedTableau::new_with_seed(1, 1e-12, 0);
tab.h(0);
tab.t(0);
tab.t_dag(0);
// T followed by T† is the identity; the |+⟩ state is restored.

A 2n-row stabilizer / destabilizer tableau.

Rows 0..n hold the destabilizers; rows n..2n hold the stabilizers. Each row is a PhasedPauliWord tracking both its X/Z bits and a phase in {±1, ±i}. Implements every Clifford-only operation natively (Hadamard, phase, CNOT, CZ, etc.).

Examples

use ppvm_pauli_sum::config::fxhash::ByteF64;
use ppvm_traits::traits::Clifford;
use ppvm_tableau::data::Tableau;

let mut tab: Tableau<ByteF64<1>> = Tableau::new(2);
tab.h(0);
tab.cnot(0, 1);
assert_eq!(tab.n_qubits, 2);
assert_eq!(tab.stabilizers().len(), 2);

Per-measurement scratch buffers, reused across qubits within a single measure_all invocation — and, when threaded through measure_all_with_scratch, across many shots of a sampler too. Reusing one scratch keeps the case-a HashMap and the b-entries Vec out of the per-shot allocator churn.

• odd_phase_mask is lazily computed and cached until the destabilizers change (i.e. until a case-a measurement runs update_tableau_according_to_outcome).
• coeff_map is the case-a HashMap holding (idx → amplitude) between the overlap, partition, and merge passes.
• b_entries is the case-a partition's "k-bit = 1" scratch Vec.

Construct one per active sampling thread; the type is not meant to be shared across threads concurrently.

A sparse vector keyed by index type I with values of type T.

Used by GeneralizedTableau to store the coefficient over each branching bitstring. The default implementation is Vec<(T, I)>; alternative backings (BTreeMap, HashMap, etc.) can be provided by downstream code.

Bit-string index type used by GeneralizedTableau to address individual branches of its sparse coefficient vector.

Blanket-implemented for every primitive (and bnum-style) integer type that supports the required bit operations. Pick:

• usize for ≤ 64 qubits,
• u128 for ≤ 128,
• bnum::types::U256 / U512 / U1024 for the wide regime.

A stabilizer-tableau-like backend that supports Clifford gates and an RNG.

Implementing this trait grants default implementations of the Pauli noise channels via [TableauLike::depolarize_impl] and friends. The associated Rng type lets each backend choose its own RNG; nothing in this trait depends on SmallRng.

Symbolic, parametric Pauli propagation.

ppvm-sym provides a Term type that represents a polynomial in sines and cosines of symbolic parameters. It is used by ppvm to propagate Pauli operators through parametric circuits (e.g., variational ansätze) without committing to specific angle values until the very end.

Quick example

Build the symbolic expression sin(x0) * cos(x1), then evaluate it at a concrete (x0, x1):

use ppvm_sym::Term;

let expr = Term::var(0).sin() * Term::var(1).cos();

let v = expr.eval(&[0.5, 1.0]).unwrap();
let expected = 0.5_f64.sin() * 1.0_f64.cos();
assert!((v - expected).abs() < 1e-12);

<coeff> sin^m cos^n

A single product of trigonometric atoms over symbolic variables. Sines and cosines are grouped by variable id; powers are tracked as totals so we can quickly compute and bound them. The order of variables is kept canonical (ascending) so two Prod values representing the same monomial compare equal.

A symbolic polynomial in sin(x_i) and cos(x_i).

Term is the public-facing wrapper around its Inner enum. It also carries two truncation parameters, applied during multiplication and addition:

Examples

use ppvm_sym::Term;

// sin²(x0) at x0 = π/2 equals 1.
let expr = Term::var(0).sin() * Term::var(0).sin();
let v = expr.eval(&[std::f64::consts::FRAC_PI_2]).unwrap();
assert!((v - 1.0).abs() < 1e-12);

• max_sin — drop terms whose total sine power exceeds this bound.
• min_eps — drop terms whose coefficient magnitude falls below this threshold.

Internal representation of a Term.

Sum holds a full formal sum; One is the optimisation for a single weighted product; Var is a bare symbolic variable used before it has been wrapped in a sin or cos; Const is a numeric scalar.