Skip to main content

qualia_q_forge/sim/
mod.rs

1//! Zero-allocation local StateVector Simulator trait and utilities.
2//!
3//! Enforces that all execution happens within caller-supplied buffers
4//! to guarantee zero heap allocations.
5
6use qualia_core_db::NQuin;
7
8pub mod statevector;
9pub use statevector::*;
10
11/// StateVector simulation backend trait.
12pub trait LocalSimulator {
13    /// Applies a circuit execution path onto the provided state vector buffer.
14    ///
15    /// # Arguments
16    ///
17    /// * `state_vector` - Fixed-size complex amplitude array (real, imaginary) interleaved.
18    /// * `instructions` - Sequence of circuit opcodes/instructions.
19    fn execute_circuit(
20        &self,
21        state_vector: &mut [(f64, f64)],
22        instructions: &[NQuin],
23    ) -> Result<(), &'static str>;
24
25    /// Samples the state vector to produce measurement results in a caller-supplied buffer.
26    fn sample(
27        &self,
28        state_vector: &[(f64, f64)],
29        shots: u32,
30        out_samples: &mut [u64],
31    ) -> Result<usize, &'static str>;
32}