StabMps/StabVec: stabilizer+MPS simulator, Python bindings, Selene plugins

Comprehensive stabilizer tensor network simulation crate (exp/pecos-stab-tn)
plus Python/Selene integration and repo-wide naming cleanup.

## Naming (Stab{Variant} convention)
- CliffordRz → StabVec (sum of stabilizer states)
- Stn/CliffordMps → StabMps (stabilizer tableau + MPS)
- S/Sdg → SZ/SZdg in enums
- Selene plugins: pecos-selene-stab-vec, pecos-selene-stab-mps, pecos-selene-mast

## StabMps simulator (exp/pecos-stab-tn)
- Hybrid stabilizer-tableau + MPS for Clifford+rotation circuits
- MAST magic state injection (deferred ancilla projection)
- Lazy virtual-frame measurement with DeferredOp queue
- Pauli frame tracking (Y-direct rep, exact decomposition-based flush)
- merge_rz: same-qubit RZ batching with Clifford commutation
- QEC API: reset_qubit, pz/px, extract_syndromes, inject_paulis_in_frame
- Builder: for_qec() preset, auto_grow_bond_dim, pauli_frame_tracking
- Diagnostics: pragmatic_drift_count, is_state_exact, StabMpsStats, OFD nullity
- 238 lib tests + 81 verification tests (tiered: quick + ignored deep fuzz)

## Python bindings (python/pecos-rslib-exp)
- PyO3/maturin: StabMps and Mast classes
- Gate dispatch (run_gate/run_1q_gate/run_2q_gate), QEC helpers
- Qubit bounds checking on all methods

## Selene plugins
- pecos-selene-stab-mps, pecos-selene-mast: SimulatorInterface impls
- Conformance tests pass
- Added to CI workflow matrix, Justfile, workspace configs

## Merge reconciliation
- QuantumSimulator::num_qubits() added to all impls across repo
- StabilizerTableauSimulator stale num_qubits removed
- ForeignSimulator/PyForeignSimulator: num_qubits threaded through FFI

## Code quality
- Zero clippy warnings, zero rustc warnings
- All .unwrap() in production code replaced with .expect()
- design/ docs stubbed (moved to pecos-docs vault)
- Python backward-compat aliases: CliffordRz = StabVec

Author: ciaranra

.github/workflows/selene-plugins.yml

@@ -11,13 +11,15 @@ on:
       - 'python/selene-plugins/**'
       - 'crates/pecos-simulators/**'
       - 'crates/pecos-core/**'
+      - 'exp/pecos-stab-tn/**'
       - '.github/workflows/selene-plugins.yml'
   pull_request:
     branches: [master, development, dev]
     paths:
       - 'python/selene-plugins/**'
       - 'crates/pecos-simulators/**'
       - 'crates/pecos-core/**'
+      - 'exp/pecos-stab-tn/**'
       - '.github/workflows/selene-plugins.yml'
   workflow_dispatch:
 
@@ -120,8 +122,12 @@ jobs:
             package: pecos_selene_stabilizer
           - name: pecos-selene-statevec
             package: pecos_selene_statevec
-          - name: pecos-selene-clifford-rz
-            package: pecos_selene_clifford_rz
+          - name: pecos-selene-stab-vec
+            package: pecos_selene_stab_vec
+          - name: pecos-selene-stab-mps
+            package: pecos_selene_stab_mps
+          - name: pecos-selene-mast
+            package: pecos_selene_mast
 
     steps:
       - uses: actions/checkout@v6

Cargo.lock

@@ -2,9 +2,12 @@
 resolver = "2"
 members = [
   "python/pecos-rslib",
+  "python/pecos-rslib-exp",
   "python/pecos-rslib-cuda",
   "python/pecos-rslib-llvm",
-  "python/selene-plugins/pecos-selene-clifford-rz",
+  "python/selene-plugins/pecos-selene-mast",
+  "python/selene-plugins/pecos-selene-stab-mps",
+  "python/selene-plugins/pecos-selene-stab-vec",
   "python/selene-plugins/pecos-selene-stabilizer",
   "python/selene-plugins/pecos-selene-statevec",
   "julia/pecos-julia-ffi",

Cargo.toml

@@ -504,7 +504,7 @@ sync-deps:
     set -euo pipefail
     # Quick check: ensure the packages used by the default dev/test lane are importable.
     # This catches newly added workspace members that an older .venv may be missing.
-    if uv run --frozen python -c "import importlib.util, sys; required = ('pecos', 'pecos_rslib', 'pecos_selene_clifford_rz', 'pecos_selene_stabilizer', 'pecos_selene_statevec'); missing = [name for name in required if importlib.util.find_spec(name) is None]; sys.exit(1 if missing else 0)" 2>/dev/null; then
+    if uv run --frozen python -c "import importlib.util, sys; required = ('pecos', 'pecos_rslib', 'pecos_selene_stab_vec', 'pecos_selene_stabilizer', 'pecos_selene_statevec', 'pecos_selene_stab_mps', 'pecos_selene_mast'); missing = [name for name in required if importlib.util.find_spec(name) is None]; sys.exit(1 if missing else 0)" 2>/dev/null; then
         exit 0
     fi
     echo "Python deps incomplete, running uv sync..."

Justfile

@@ -18,6 +18,7 @@ parallel = ["pecos-simulators/parallel"]
 gpu-sims = ["dep:pecos-gpu-sims"]
 cuquantum = ["dep:pecos-cuquantum"]
 cppsparsestab = ["dep:pecos-cppsparsestab"]
+stab-tn = ["dep:pecos-stab-tn"]
 all-sims = ["gpu-sims", "cuquantum", "cppsparsestab"]
 
 [dependencies]
@@ -27,6 +28,9 @@ pecos-cuquantum = { workspace = true, optional = true }
 pecos-cppsparsestab = { workspace = true, optional = true }
 pecos-core.workspace = true
 pecos-simulators.workspace = true
+pecos-stab-tn = { path = "../../exp/pecos-stab-tn", optional = true }
+nalgebra.workspace = true
+num-complex.workspace = true
 
 [dev-dependencies]
 criterion.workspace = true

crates/benchmarks/Cargo.toml

@@ -17,12 +17,12 @@ use criterion::{Criterion, criterion_group, criterion_main};
 
 mod modules {
     pub mod allocation_overhead;
-    pub mod clifford_rz;
     pub mod cpu_stabilizer_comparison;
     pub mod dem_builder;
     pub mod dem_sampler;
     pub mod dod_statevec;
     pub mod quizx_eval;
+    pub mod stab_vec;
     // TODO: pub mod hadamard_ops;
     #[cfg(feature = "cuquantum")]
     pub mod cuquantum;
@@ -34,6 +34,8 @@ mod modules {
     #[cfg(feature = "cppsparsestab")]
     pub mod sparse_stab_vs_cpp;
     pub mod sparse_stab_w_vs_y;
+    #[cfg(feature = "stab-tn")]
+    pub mod stab_mps_vs_stab_vec;
     // TODO: pub mod pauli_ops;
     pub mod pecos_neo_comparison;
     pub mod rng;
@@ -51,16 +53,18 @@ use modules::cuquantum;
 use modules::gpu_influence_sampler;
 #[cfg(feature = "cppsparsestab")]
 use modules::sparse_stab_vs_cpp;
+#[cfg(feature = "stab-tn")]
+use modules::stab_mps_vs_stab_vec;
 use modules::{
-    allocation_overhead, clifford_rz, cpu_stabilizer_comparison, dem_builder, dem_sampler,
-    dod_statevec, measurement_sampling, native_statevec_comparison, noise_models,
-    pecos_neo_comparison, quizx_eval, rng, set_ops, sparse_stab_w_vs_y, sparse_state_vec,
-    stabilizer_sims, state_vec_sims, surface_code, trig,
+    allocation_overhead, cpu_stabilizer_comparison, dem_builder, dem_sampler, dod_statevec,
+    measurement_sampling, native_statevec_comparison, noise_models, pecos_neo_comparison,
+    quizx_eval, rng, set_ops, sparse_stab_w_vs_y, sparse_state_vec, stab_vec, stabilizer_sims,
+    state_vec_sims, surface_code, trig,
 };
 
 fn all_benchmarks(c: &mut Criterion) {
     allocation_overhead::benchmarks(c);
-    clifford_rz::benchmarks(c);
+    stab_vec::benchmarks(c);
     cpu_stabilizer_comparison::benchmarks(c);
     quizx_eval::benchmarks(c);
     #[cfg(feature = "cuquantum")]
@@ -83,6 +87,8 @@ fn all_benchmarks(c: &mut Criterion) {
     sparse_stab_vs_cpp::benchmarks(c);
     sparse_stab_w_vs_y::benchmarks(c);
     surface_code::benchmarks(c);
+    #[cfg(feature = "stab-tn")]
+    stab_mps_vs_stab_vec::benchmarks(c);
     trig::benchmarks(c);
     // TODO: pauli_ops::benchmarks(c);
     // TODO: hadamard_ops::benchmarks(c);

crates/benchmarks/benches/benchmarks.rs

@@ -13,7 +13,7 @@
 //! Evaluate `QuiZX` circuit simplification for T-count reduction.
 //!
 //! Tests whether ZX-calculus simplification meaningfully reduces the number
-//! of non-Clifford gates in circuits relevant to the `CliffordRz` simulator.
+//! of non-Clifford gates in circuits relevant to the `StabVec` simulator.
 
 use criterion::{BenchmarkId, Criterion, measurement::Measurement};
 use quizx::circuit::Circuit;