Enum BackendKind 

pub enum BackendKind {
    Auto,
    Statevector,
    Stabilizer,
    Sparse,
    Mps {
        max_bond_dim: usize,
    },
    ProductState,
    TensorNetwork,
    Factored,
    StabilizerRank,
    FactoredStabilizer,
    DensityMatrix,
    StochasticPauli {
        num_samples: usize,
    },
    DeterministicPauli {
        epsilon: f64,
        max_terms: usize,
    },
    PauliPath {
        epsilon: f64,
        max_terms: usize,
    },
    AutoGpu {
        context: Arc<GpuContext>,
    },
    StatevectorGpu {
        context: Arc<GpuContext>,
    },
    DensityMatrixGpu {
        context: Arc<GpuContext>,
    },
    StabilizerGpu {
        context: Arc<GpuContext>,
    },
    StatevectorDistributed {
        context: Arc<DistributedContext>,
    },
}

Backend selection for a simulation run.

Auto resolves per call from circuit shape. Two routes run before the family tree: circuits that decompose into independent blocks run per block (Clifford-only circuits at 128 qubits and above with a 16+ qubit block use FactoredStabilizer), and Clifford+T circuits up to 25 qubits whose T count fits the size-derived stabilizer-rank budget run the exact StabilizerRank expansion (shot paths to 40 T gates; MAX_AUTO_T_COUNT_EXACT and MAX_AUTO_T_COUNT_SHOTS above). The pruned expansion is reachable only through run_stabilizer_rank_approx, never from Auto; marginal queries on Clifford+T circuits at 12 qubits and above answer via Sparse Pauli Dynamics. The remaining tree:

1. No entangling gates → ProductState (O(n))
2. All Clifford gates → Stabilizer (O(n²))
3. Above the statevector memory cap: a. Sparse-friendly → Sparse (O(k) where k = non-zero amplitudes) b. Otherwise → MPS (bounded bond dimension)
4. Partial independence → Factored (per-group dense sub-states)
5. Otherwise → Statevector (exact, general-purpose)

Variants

Auto

Statevector

Stabilizer

Tableau simulation for Clifford-only circuits.

Sparse

Sparse state vector holding only nonzero amplitudes.

Mps

Matrix Product State simulation with a bounded bond dimension.

Fields

max_bond_dim: usize

ProductState

Per-qubit product state for circuits without entangling gates.

TensorNetwork

Deferred-contraction tensor network for low-treewidth circuits.

Factored

Dynamic split-state simulation for sparse-entanglement circuits.

StabilizerRank

Clifford+T decomposition into weighted stabilizer branches.

FactoredStabilizer

Independent Clifford blocks, each on its own tableau.

DensityMatrix

Exact density-matrix backend for mixed-state evolution.

Explicit-dispatch only: BackendKind::Auto never selects it. Stores 4^n Complex64 amplitudes, so the qubit ceiling is roughly half the statevector cap (14 on a 16 GiB host); PRISM_MAX_DM_QUBITS moves it within that bound. Fused payloads are accepted, with every fusion floor gated on the 2n-qubit buffer the backend sweeps rather than on the circuit width.

Under an attached noise model this is the exact route: the mixture is evolved once and every terminal reads it, so shot counts carry sampling noise only and observables carry none.

StochasticPauli

Stochastic Pauli propagation (SPP); serves marginal and observable queries only.

Fields

num_samples: usize

DeterministicPauli

Deterministic sparse Pauli dynamics (SPD); serves marginal and observable queries only. Terms below epsilon are dropped once the weighted sum exceeds max_terms (0 disables truncation).

Fields

epsilon: f64

max_terms: usize

PauliPath

Heisenberg Pauli propagation through a noise model; serves expectation values and observable expectations only.

Explicit-dispatch only: BackendKind::Auto never selects it. Noise enters as the channel’s action on the Pauli basis, which shrinks coefficients while the circuit’s rotations grow the term count, so the weighted sum stays small exactly when noise outpaces the branching rotations. Terms below epsilon are dropped once the sum exceeds max_terms (0 disables truncation and makes the run exact).

A channel with no Pauli-basis form (custom Kraus, two-qubit Kraus, readout error) is rejected naming the density matrix.

Fields

epsilon: f64

max_terms: usize

AutoGpu

Available on crate feature gpu only.

Automatic backend selection with GPU acceleration opted in.

Makes the same shape-based routing decisions as BackendKind::Auto, but when the selected family (per sub-block, after subsystem decomposition) has a device capability row and the block clears the qubit-count crossover with VRAM to spare, that block runs on the supplied context. Every other choice, and every block that fails the crossover or VRAM check, runs on the identical CPU path Auto would take. Device paths resolve soft: an allocation that fails after the VRAM check degrades to the host, so a missing, unfit, or racing device stays on CPU rather than erroring.

Acceleration reaches every entry point through one resolution mechanism: single runs, terminal shot and counts sampling, expectation values, temporal-Clifford tails, and non-Pauli noisy trajectories.

The context is user-supplied and is never acquired implicitly.

Fields

context: Arc<GpuContext>

StatevectorGpu

Available on crate feature gpu only.

Statevector backed by a CUDA GPU execution context.

Circuits (or decomposed sub-blocks) with fewer than crate::gpu::min_qubits() qubits (tunable via PRISM_GPU_MIN_QUBITS, default crate::gpu::MIN_QUBITS_DEFAULT) transparently fall back to the host statevector path, since small states do not survive PCIe and launch-latency overhead. Larger circuits allocate a device-resident state and route gate application through GPU kernels.

Compose with simulate(...).backend(...).seed(...).run() to get fusion plus independent-subsystem decomposition; each sub-block is evaluated against the crossover independently.

Fields

context: Arc<GpuContext>

DensityMatrixGpu

Available on crate feature gpu only.

Density matrix held in device memory on the supplied context.

Explicit-dispatch only: neither BackendKind::Auto nor BackendKind::AutoGpu selects it. There is no crossover and no host fallback: every run allocates the 4^n mixture on the device, after a budget check against the free VRAM that errors before allocating. An 11 GiB card holds 13 qubits (1 GiB at 13, 4 GiB at 14 plus scratch). Every channel, measurement, and readout sweep runs as a kernel; the noisy terminals answer from the exact mixture as BackendKind::DensityMatrix does.

Fields

context: Arc<GpuContext>

StabilizerGpu

Available on crate feature gpu only.

Stabilizer backend backed by a CUDA GPU tableau.

Circuits (or decomposed sub-blocks) with fewer than crate::gpu::stabilizer_min_qubits() qubits (tunable via PRISM_STABILIZER_GPU_MIN_QUBITS, default crate::gpu::STABILIZER_MIN_QUBITS_DEFAULT) fall back to the CPU stabilizer path. The GPU path routes gate application to device kernels. Measurement and reset stay on device, while probabilities and export-style helpers still read back to the CPU algorithms.

Compose with simulate(...).backend(...).seed(...).run() to pick up independent-subsystem decomposition; non-Clifford circuits are rejected at dispatch time with the same error shape as BackendKind::Stabilizer.

Fields

context: Arc<GpuContext>

StatevectorDistributed

Available on crate feature distributed only.

Exact state vector distributed across 2^p ranks via a DistributedContext. The low n - p qubits are simulated locally with the standard SIMD kernels; the top p qubits select the rank.

Results are independent of the rank count. With a single rank the path is identical to BackendKind::Statevector.

Fields

context: Arc<DistributedContext>

Implementations

impl BackendKind

pub fn supports_noisy_per_shot(&self) -> bool

False for the engines without a per-shot pure state: stabilizer rank, Pauli propagation, density matrix. The density matrix still serves a noise model, by evolving the mixture once and sampling the exact distribution, so its noisy terminals route around the trajectory engine rather than through it.

pub fn supports_general_noise(&self) -> bool

True for kinds that can run non-Pauli channels (damping, thermal relaxation, custom Kraus): the trajectory engine everywhere except the density matrix, which applies the channel to the mixture instead.

Trait Implementations

impl Clone for BackendKind

fn clone(&self) -> BackendKind

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BackendKind

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.