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}