stabilizer polish

Author: ciaranra

crates/benchmarks/benches/modules/cpu_stabilizer_comparison.rs

@@ -14,7 +14,7 @@
 //!
 //! Compares all CPU-based stabilizer simulator implementations on surface code
 //! syndrome extraction to determine relative performance. This helps inform
-//! which implementation `Stab` should wrap as its default backend.
+//! which implementation `Stabilizer` should wrap as its default backend.
 //!
 //! Simulators compared:
 //! - `DenseStab` (row+column dual representation)
@@ -143,7 +143,7 @@ fn bench_cpu_stabilizer_surface_code<M: Measurement>(c: &mut Criterion<M>) {
             let ops_per_run = rounds * (params.num_ancillas * 3 + params.num_ancillas);
             group.throughput(Throughput::Elements(ops_per_run as u64));
 
-            // --- DenseStab (row+col dual, what Stab currently wraps) ---
+            // --- DenseStab (row+col dual, what Stabilizer currently wraps) ---
             group.bench_with_input(BenchmarkId::new("DenseStab", &label), &(), |b, ()| {
                 b.iter_batched(
                     || {

crates/benchmarks/benches/modules/sparse_stab_vs_cpp.rs

@@ -10,18 +10,18 @@
 // or implied. See the License for the specific language governing permissions and limitations under
 // the License.
 
-//! Performance comparison: Pure Rust `SparseStab` vs C++ `CppSparseStab` vs `Stab` (`DenseStab`).
+//! Performance comparison: Pure Rust `SparseStab` vs C++ `CppSparseStab` vs `Stabilizer` (`DenseStab`).
 //!
 //! Benchmarks surface code syndrome extraction at various distances and round counts
 //! to compare the three stabilizer simulator backends:
 //!
 //! - `SparseStab` (pure Rust, BitSet-based sparse representation)
 //! - `CppSparseStab` (C++ implementation via cxx FFI)
-//! - `Stab` (pure Rust, `DenseStab` with row+column bit-matrix layout)
+//! - `Stabilizer` (pure Rust, `DenseStab` with row+column bit-matrix layout)
 
 use criterion::{BenchmarkId, Criterion, Throughput, measurement::Measurement};
 use pecos::prelude::*;
-use pecos::simulators::{SparseStab, Stab};
+use pecos::simulators::{SparseStab, Stabilizer};
 use pecos_cppsparsesim::CppSparseStab;
 use std::hint::black_box;
 
@@ -148,8 +148,8 @@ fn run_circuit_cpp_sparse_stab(sim: &mut CppSparseStab, params: &SurfaceCodePara
     }
 }
 
-/// Run surface code syndrome extraction on Stab (`DenseStab`, pure Rust).
-fn run_circuit_stab(sim: &mut Stab, params: &SurfaceCodeParams, rounds: usize) {
+/// Run surface code syndrome extraction on Stabilizer (`DenseStab`, pure Rust).
+fn run_circuit_stab(sim: &mut Stabilizer, params: &SurfaceCodeParams, rounds: usize) {
     // Initialize data qubits in |+> state
     for i in 0..params.num_data {
         sim.h(&[QubitId::from(i)]);
@@ -178,7 +178,7 @@ fn run_circuit_stab(sim: &mut Stab, params: &SurfaceCodeParams, rounds: usize) {
     }
 }
 
-/// Compare `SparseStab` (Rust) vs `CppSparseStab` (C++) vs Stab (`DenseStab`) on surface code
+/// Compare `SparseStab` (Rust) vs `CppSparseStab` (C++) vs Stabilizer (`DenseStab`) on surface code
 /// syndrome extraction across distances and round counts.
 fn bench_rust_vs_cpp_surface_code<M: Measurement>(c: &mut Criterion<M>) {
     use criterion::BatchSize;
@@ -227,11 +227,11 @@ fn bench_rust_vs_cpp_surface_code<M: Measurement>(c: &mut Criterion<M>) {
                 );
             });
 
-            // --- DenseStab (Stab, pure Rust) ---
-            group.bench_with_input(BenchmarkId::new("Stab_DenseRust", &label), &(), |b, ()| {
+            // --- DenseStab (Stabilizer, pure Rust) ---
+            group.bench_with_input(BenchmarkId::new("Stabilizer_DenseRust", &label), &(), |b, ()| {
                 b.iter_batched(
                     || {
-                        let mut sim = Stab::new(params.num_qubits);
+                        let mut sim = Stabilizer::new(params.num_qubits);
                         sim.reset();
                         sim
                     },
@@ -264,7 +264,7 @@ mod tests {
         cpp_sim.reset();
         run_circuit_cpp_sparse_stab(&mut cpp_sim, &params, rounds);
 
-        let mut stab_sim = Stab::new(params.num_qubits);
+        let mut stab_sim = Stabilizer::new(params.num_qubits);
         stab_sim.reset();
         run_circuit_stab(&mut stab_sim, &params, rounds);
     }

crates/benchmarks/benches/modules/stabilizer_sims.rs

@@ -15,7 +15,7 @@
 //! Compares performance of:
 //! - `GpuStabMulti` (GPU via wgpu/Vulkan/Metal/DX12) - multi-shot stabilizer
 //! - `CuFrameSimulator` (GPU via NVIDIA cuQuantum/CUDA) - frame-based stabilizer
-//! - `SparseSim` (CPU) - baseline stabilizer simulator
+//! - `SparseStab` (CPU) - baseline stabilizer simulator
 //!
 //! Run with specific features:
 //! ```

crates/pecos-simulators/src/lib.rs

@@ -37,7 +37,7 @@ pub mod rotation_test_utils;
 pub mod sign_algebra;
 pub mod sparse_stab;
 pub mod sparse_stab_y;
-pub mod stab;
+pub mod stabilizer;
 pub mod stabilizer_tableau;
 pub mod stabilizer_test_utils;
 pub mod state_vec;
@@ -92,7 +92,7 @@ pub use sparse_stab_y::{
     SparseStabY, SparseStabYBitSet, SparseStabYGeneric, SparseStabYUnsortedVecSet,
     SparseStabYVecSet,
 };
-pub use stab::Stab;
+pub use stabilizer::Stabilizer;
 pub use stabilizer_tableau::StabilizerTableauSimulator;
 // StateVec uses the sparse SoA implementation optimized for QEC workloads.
 // The dense implementation is available as DenseStateVec / StateVecSoA.

crates/pecos-simulators/src/stab.rs crates/pecos-simulators/src/stabilizer.rscrates/pecos-simulators/src/stab.rs renamed to crates/pecos-simulators/src/stabilizer.rs

@@ -12,18 +12,18 @@
 
 //! Default stabilizer simulator with automatic implementation selection.
 //!
-//! [`Stab`] is the recommended stabilizer simulator for most use cases. It automatically
+//! [`Stabilizer`] is the recommended stabilizer simulator for most use cases. It automatically
 //! selects the best underlying implementation based on the number of qubits and workload
 //! characteristics.
 //!
 //! # Example
 //!
 //! ```rust
 //! use pecos_core::{QubitId, qid};
-//! use pecos_simulators::{Stab, CliffordGateable, QuantumSimulator};
+//! use pecos_simulators::{Stabilizer, CliffordGateable, QuantumSimulator};
 //!
 //! // Create a stabilizer simulator
-//! let mut sim = Stab::new(2);
+//! let mut sim = Stabilizer::new(2);
 //!
 //! // Create a Bell state
 //! sim.h(&qid(0)).cx(&[(QubitId(0), QubitId(1))]);
@@ -54,21 +54,21 @@ use pecos_random::PecosRng;
 ///
 /// See the [module documentation](self) for more details.
 #[derive(Debug, Clone)]
-pub struct Stab {
+pub struct Stabilizer {
     inner: SparseStab,
 }
 
-impl Stab {
+impl Stabilizer {
     /// Create a new stabilizer simulator with the given number of qubits.
     ///
     /// All qubits are initialized in the |0⟩ state.
     ///
     /// # Example
     ///
     /// ```rust
-    /// use pecos_simulators::Stab;
+    /// use pecos_simulators::Stabilizer;
     ///
-    /// let sim = Stab::new(10);
+    /// let sim = Stabilizer::new(10);
     /// assert_eq!(sim.num_qubits(), 10);
     /// ```
     #[inline]
@@ -86,9 +86,9 @@ impl Stab {
     /// # Example
     ///
     /// ```rust
-    /// use pecos_simulators::Stab;
+    /// use pecos_simulators::Stabilizer;
     ///
-    /// let sim = Stab::with_seed(10, 42);
+    /// let sim = Stabilizer::with_seed(10, 42);
     /// ```
     #[inline]
     #[must_use]
@@ -114,15 +114,15 @@ impl Stab {
     }
 }
 
-impl QuantumSimulator for Stab {
+impl QuantumSimulator for Stabilizer {
     #[inline]
     fn reset(&mut self) -> &mut Self {
         self.inner.reset();
         self
     }
 }
 
-impl CliffordGateable for Stab {
+impl CliffordGateable for Stabilizer {
     #[inline]
     fn h(&mut self, qubits: &[QubitId]) -> &mut Self {
         self.inner.h(qubits);
@@ -193,7 +193,7 @@ impl CliffordGateable for Stab {
     }
 }
 
-impl RngManageable for Stab {
+impl RngManageable for Stabilizer {
     type Rng = PecosRng;
 
     #[inline]
@@ -212,7 +212,7 @@ impl RngManageable for Stab {
     }
 }
 
-impl StabilizerTableauSimulator for Stab {
+impl StabilizerTableauSimulator for Stabilizer {
     fn stab_tableau(&self) -> String {
         self.inner.stab_tableau()
     }
@@ -232,13 +232,13 @@ impl StabilizerTableauSimulator for Stab {
 
 use crate::stabilizer_test_utils::{ForcedMeasurement, StabilizerSimulator};
 
-impl ForcedMeasurement for Stab {
+impl ForcedMeasurement for Stabilizer {
     fn mz_forced(&mut self, qubit: usize, forced_outcome: bool) -> MeasurementResult {
         self.inner.mz_forced(qubit, forced_outcome)
     }
 }
 
-impl StabilizerSimulator for Stab {
+impl StabilizerSimulator for Stabilizer {
     fn with_seed(num_qubits: usize, seed: u64) -> Self {
         Self::with_seed(num_qubits, seed)
     }
@@ -251,7 +251,7 @@ mod tests {
 
     #[test]
     fn test_stab_basic() {
-        let mut sim = Stab::new(2);
+        let mut sim = Stabilizer::new(2);
         sim.h(&[QubitId(0)]);
         sim.cx(&[(QubitId(0), QubitId(1))]);
         let results = sim.mz(&[QubitId(0), QubitId(1)]);
@@ -260,7 +260,7 @@ mod tests {
 
     #[test]
     fn test_stab_full_suite() {
-        let mut sim = Stab::with_seed(8, 42);
+        let mut sim = Stabilizer::with_seed(8, 42);
         run_full_stabilizer_test_suite(&mut sim, 8);
     }
 }

crates/pecos-simulators/src/stabilizer_test_utils.rs

@@ -1908,7 +1908,7 @@ mod tests {
     fn test_all_stabilizer_sims_agree_on_random_circuits() {
         use crate::{
             DenseStab, DenseStabColOnly, DenseStabRowOnly, GpuStab, GpuStabOpt, GpuStabParallel,
-            SparseColOnly, SparseRowOnly, Stab, StabilizerTableauSimulator,
+            SparseColOnly, SparseRowOnly, Stabilizer, StabilizerTableauSimulator,
         };
         use pecos_random::PecosRng;
 
@@ -1930,7 +1930,7 @@ mod tests {
             let mut dense_row = DenseStabRowOnly::<PecosRng>::new(num_qubits);
             let mut sparse_col = SparseColOnly::new(num_qubits);
             let mut sparse_row = SparseRowOnly::new(num_qubits);
-            let mut stab = Stab::new(num_qubits);
+            let mut stab = Stabilizer::new(num_qubits);
             let mut gpu_stab = GpuStab::new(num_qubits);
             let mut gpu_stab_opt = GpuStabOpt::new(num_qubits);
             let mut gpu_stab_parallel = GpuStabParallel::new(num_qubits);
@@ -1973,7 +1973,7 @@ mod tests {
             check_tableau!(dense_row, "DenseStabRowOnly");
             check_tableau!(sparse_col, "SparseColOnly");
             check_tableau!(sparse_row, "SparseRowOnly");
-            check_tableau!(stab, "Stab");
+            check_tableau!(stab, "Stabilizer");
             check_tableau!(gpu_stab, "GpuStab");
             check_tableau!(gpu_stab_opt, "GpuStabOpt");
             check_tableau!(gpu_stab_parallel, "GpuStabParallel");
@@ -2018,7 +2018,7 @@ mod tests {
             check_measurements!(dense_row, "DenseStabRowOnly");
             check_measurements!(sparse_col, "SparseColOnly");
             check_measurements!(sparse_row, "SparseRowOnly");
-            check_measurements!(stab, "Stab");
+            check_measurements!(stab, "Stabilizer");
             check_measurements!(gpu_stab, "GpuStab");
             check_measurements!(gpu_stab_opt, "GpuStabOpt");
             check_measurements!(gpu_stab_parallel, "GpuStabParallel");

crates/pecos-simulators/tests/stabilizer_suite_tests.rs

@@ -17,7 +17,7 @@
 
 use pecos_simulators::{
     DenseStab, DenseStabColOnly, DenseStabRowOnly, GpuStab, GpuStabOpt, GpuStabParallel,
-    SparseColOnly, SparseStab, SparseStabHybrid, SparseStabUnsortedVecSet, SparseStabVecSet, Stab,
+    SparseColOnly, SparseStab, SparseStabHybrid, SparseStabUnsortedVecSet, SparseStabVecSet, Stabilizer,
 };
 
 // Generate test suites for all stabilizer simulator implementations
@@ -35,7 +35,7 @@ pecos_simulators::stabilizer_test_suite!(DenseStabRowOnly);
 pecos_simulators::stabilizer_test_suite!(SparseColOnly);
 
 // Default wrapper
-pecos_simulators::stabilizer_test_suite!(Stab);
+pecos_simulators::stabilizer_test_suite!(Stabilizer);
 
 // GPU-optimized stabilizer simulators
 pecos_simulators::stabilizer_test_suite!(GpuStab);

design/ENGINES_ARCHITECTURE.md

@@ -923,7 +923,7 @@ results = engine.run(program, shots=100)
 │                         │                                    │
 │  ┌──────────────────────┴──────────────────────────────┐    │
 │  │              PyO3 Bindings (pecos-rslib)             │    │
-│  │  - SparseSim, StateVec exposed to Python             │    │
+│  │  - SparseStab, StateVec exposed to Python             │    │
 │  │  - WasmForeignObject for classical co-processors     │    │
 │  │  - Engine builders for Rust-native pipelines         │    │
 │  └──────────────────────┬──────────────────────────────┘    │

docs/user-guide/gates.md

@@ -9,10 +9,10 @@ All examples in this guide use the following setup:
 === ":fontawesome-brands-python: Python"
 
     ```python
-    from pecos.simulators import SparseSim
+    from pecos.simulators import SparseStab
 
     # Create a stabilizer simulator with 5 qubits
-    state = SparseSim(num_qubits=5)
+    state = SparseStab(num_qubits=5)
 
     # Qubit indices for examples
     q = 0
@@ -32,10 +32,10 @@ All examples in this guide use the following setup:
     ```
 
 ```hidden-python
-from pecos.simulators import SparseSim
+from pecos.simulators import SparseStab
 
 # Create a stabilizer simulator with 5 qubits
-state = SparseSim(num_qubits=5)
+state = SparseStab(num_qubits=5)
 
 # Qubit indices for examples
 q = 0
@@ -62,7 +62,7 @@ fn main() {
 
 PECOS supports two categories of quantum gates:
 
-- **Clifford Gates**: Gates that map Pauli operators to Pauli operators. These can be efficiently simulated using stabilizer simulators like `SparseSim`.
+- **Clifford Gates**: Gates that map Pauli operators to Pauli operators. These can be efficiently simulated using stabilizer simulators like `SparseStab`.
 - **Non-Clifford Gates**: Rotation gates and other operations that require state vector simulation.
 
 ## Quick Reference
@@ -113,10 +113,10 @@ The examples below use a simulator instance. Run this setup code first:
 === ":fontawesome-brands-python: Python"
 
     ```python
-    from pecos.simulators import SparseSim
+    from pecos.simulators import SparseStab
 
     # Create a stabilizer simulator with 5 qubits
-    state = SparseSim(num_qubits=5)
+    state = SparseStab(num_qubits=5)
 
     # Qubit indices for examples
     q = 0
@@ -1071,7 +1071,7 @@ These operations measure and then prepare the qubit in a specific eigenstate reg
 
 | Simulator | Clifford Gates | Non-Clifford Gates | Notes |
 |-----------|---------------|-------------------|-------|
-| **SparseSim** | All | None | Default, fastest for QEC |
+| **SparseStab** | All | None | Default, fastest for QEC |
 | **StateVec** | All | All | Pure Rust state vector |
 | **Qulacs** | All | All | High-performance C++ backend |
 | **CuStateVec** | All | All | GPU-accelerated (requires CUDA) |