Struct DistributedStatevectorBackend 

pub struct DistributedStatevectorBackend { /* private fields */ }

Available on crate feature distributed only.

Distributed state vector backend over an Arc-shared DistributedContext.

Implementations

impl DistributedStatevectorBackend

pub fn new(context: Arc<DistributedContext>, seed: u64) -> Self

Create a backend bound to the given rank context and RNG seed.

pub fn set_relabel(&mut self, enabled: bool)

Enable or disable qubit relabeling for this backend instance, overriding the PRISM_DIST_RELABEL default. With relabeling off, every gate on a global qubit uses the direct per-gate exchange paths.

pub fn exchange_messages(&self) -> u64

Number of sendrecv messages this rank has issued since init.

Cost proxy for this backend. One host cannot measure real network latency, so routing changes are evaluated against this count. Counts gate and relabel exchanges; the query paths take &self and cannot record theirs.

pub fn exchange_amplitudes(&self) -> u64

Total amplitudes this rank has sent across all exchanges since init.

pub fn sample_state_indices( &mut self, num_shots: usize, seed: u64, ) -> Result<Vec<u64>>

Sample num_shots computational basis indices in circuit qubit order without gathering the dense state or probability vector on any rank.

Relabeled qubits are first restored to their circuit positions with bounded exchanges, so each rank owns a contiguous slice in circuit order. Each rank then builds a cumulative distribution for its local slice. One gather shares a single mass value from each rank. Every rank assigns each shot to an owning rank from the same seeded draw stream, so every rank knows the owner sequence. Each owner samples its local distribution for its shots, one variable-count gather concatenates the owned indices in rank order, and each rank scatters them back into shot order. Buffers scale with the rank count and shot count, not the global state size.

Collective: every rank must call this with identical num_shots and seed. The result is identical on every rank and reproduces the dense sampling path draw for draw, independent of the rank count, except when accumulated rounding differences move a draw across an interval edge in the cumulative distribution.

Trait Implementations

impl Backend for DistributedStatevectorBackend

fn init_from_amplitudes( &mut self, amplitudes: Vec<Complex64>, num_classical_bits: usize, ) -> Result<()>

Load this rank’s shard from the full 2^n vector.

Every rank receives the whole vector and keeps the 2^(n - p) amplitudes from rank * 2^(n - p), the identity layout init establishes; a map left permuted by an earlier relabeled run is reset, not written into. Collective: every rank must call it with an identical vector.

fn sample_basis_states( &mut self, num_shots: usize, seed: u64, ) -> Result<BasisSamples>

Trait-level entry to DistributedStatevectorBackend::sample_state_indices, so a caller holding a dyn Backend gets the same rank-local draw the shot route takes instead of falling back to the dense vector.

Collective: every rank must call it with identical num_shots and seed.

fn pauli_expectations(&self, observables: &[Vec<PauliTerm>]) -> Result<Vec<f64>>

Evaluate each observable on the sharded state with no dense gather.

A Z factor on a rank bit is a constant sign for the whole slice, so an observable whose X and Y factors are all local costs one Allreduce and no transfer. X and Y factors on rank bits displace the bra by the same rank offset for every amplitude, so however many there are they name one partner rank, and one slice exchange covers them. That is the direct route rather than a relabel because relabeling mutates the state, which a &self query cannot do.

Collective: every rank must call it with identical observables.

fn apply_1q_matrix( &mut self, qubit: usize, matrix: &[[Complex64; 2]; 2], ) -> Result<()>

Apply a 2x2 matrix to one circuit qubit across the rank split, on the same route apply_gate takes for a one-qubit gate: relabel a non-diagonal target into a local position when a victim exists, apply locally when the physical position is local, otherwise exchange with the partner rank.

Collective when the target is global, so every rank must call it with the same qubit.

fn name(&self) -> &'static str

Human-readable backend name (for error messages, logging, and benchmarks).

fn as_any(&self) -> Option<&dyn Any>

The concrete backend behind a &dyn Backend, so Backend::overlap_sq can recognize its own representation on the other side of the inner product. An implementor that wants the fast paths writes Some(self); the default hides the concrete type, which costs only the dense route.

fn resolved(&self) -> ResolvedBackend

Which engine this is, for the provenance attached to every result. The default names an out-of-tree backend by its Backend::name.

fn supports_fused_gates(&self) -> bool

Whether this backend can handle Gate::Fused variants.

fn supports_qft_block(&self) -> bool

Whether this backend has a native kernel for Gate::QftBlock.

fn supports_pauli_rotation(&self) -> bool

Whether this backend has a native kernel for Gate::PauliRot.

fn apply_instructions(&mut self, instructions: &[Instruction]) -> Result<()>

Apply a batch of instructions to the current state.

fn init(&mut self, num_qubits: usize, num_classical_bits: usize) -> Result<()>

Initialize (or reset) state for a circuit with the given dimensions.

fn supports_initial_state(&self) -> bool

Whether Backend::init_from_amplitudes can start this backend from a caller-supplied state.

fn apply(&mut self, instruction: &Instruction) -> Result<()>

Apply a single instruction to the current state.

fn classical_results(&self) -> &[bool]

Read classical measurement results.

fn probabilities(&self) -> Result<Vec<f64>>

Compute the probability of each computational basis state.

fn num_qubits(&self) -> usize

Number of qubits the backend is currently configured for.

fn export_statevector(&self) -> Result<Vec<Complex64>>

Export the current quantum state as a dense statevector.

fn qubit_probability(&self, qubit: usize) -> Result<f64>

Compute P(qubit = |1⟩) without collapsing the state.

fn supports_native_sampling(&self) -> bool

Whether Backend::sample_basis_states draws from this backend’s own representation.

fn supports_pauli_expectation(&self) -> bool

Whether Backend::pauli_expectations evaluates observables on this backend’s own representation.

fn reset(&mut self, qubit: usize) -> Result<()>

Reset a qubit to |0⟩, discarding any prior amplitude on that qubit.

fn exactness(&self) -> Exactness

Whether this representation can discard state weight, and how much it discarded on the run just executed. Called once per run, after the circuit has been applied; the default reports an exact representation.

fn placement(&self) -> Placement

Where the state lived during the run. Only the statevector has a device path, and only when the gpu feature is on.

fn block_probabilities(&self) -> Option<Probabilities>

Per-block probabilities for a backend holding a product of independent sub-states, skipping the 2^n Kronecker expansion Backend::probabilities would materialize.

fn apply_region(&mut self, region: &GuardedRegion) -> Result<()>

Execute a guarded region’s body iff its condition holds.

fn fusion_state_qubits(&self, num_qubits: usize) -> usize

Width in qubits of the buffer this backend sweeps for an n-qubit circuit.

fn reduced_density_matrix_1q( &self, _qubit: usize, ) -> Result<[[Complex64; 2]; 2]>

Compute the one-qubit reduced density matrix without collapsing the state.

fn supports_two_qubit_kraus(&self) -> bool

Whether this backend can run a NoiseChannel::Kraus2q branch, which needs both Backend::reduced_density_matrix_2q and a Gate::Fused2q kernel. Checked before a shot starts, so an incapable backend is named at dispatch rather than part way through a trajectory.

fn reduced_density_matrix_2q( &self, _q0: usize, _q1: usize, ) -> Result<[[Complex64; 4]; 4]>

Compute the two-qubit reduced density matrix without collapsing the state.

fn schmidt_values(&mut self, _subsystem: &[usize]) -> Result<Vec<f64>>

Schmidt values of the state across the cut between subsystem and its complement: descending, numerically zero values dropped, squares summing to 1 whatever norm the representation carries.

fn entanglement_entropy(&mut self, subsystem: &[usize]) -> Result<f64>

Entanglement entropy of subsystem in nats: -sum p ln p over p = s^2 / sum s^2 for the Backend::schmidt_values s, which is where the default reads it from.

fn reduced_density_matrix( &mut self, _subsystem: &[usize], ) -> Result<Vec<Complex64>>

Reduced density matrix of subsystem, row major with side 2^k for k qubits: rho[t * 2^k + t'] is <t|rho|t'>, where bit i of t is the state of subsystem[i], so subsystem[0] is the lowest bit as q[0] is in a basis index. Trace one whatever norm the representation carries; Hermitian to rounding.

fn overlap_sq(&self, other: &dyn Backend) -> Result<f64>

|<self|other>|^2 over the two normalized states: 1 for the same state up to phase, 0 for orthogonal ones.