Replacing Python implementation of CoinToss with Rust implementation

Author: ciaranra

crates/pecos-qsim/src/coin_toss.rs

@@ -11,6 +11,7 @@
 // the License.
 
 pub mod clifford_gateable;
+pub mod coin_toss;
 pub mod gens;
 pub mod pauli_prop;
 // pub mod paulis;
@@ -23,6 +24,7 @@ pub mod state_vec;
 
 pub use arbitrary_rotation_gateable::ArbitraryRotationGateable;
 pub use clifford_gateable::{CliffordGateable, MeasurementResult};
+pub use coin_toss::CoinToss;
 pub use gens::Gens;
 // pub use paulis::Paulis;
 pub use pauli_prop::{PauliProp, StdPauliProp};

crates/pecos-qsim/src/lib.rs

@@ -0,0 +1,179 @@
+// Copyright 2025 The PECOS Developers
+//
+// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+// in compliance with the License.You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software distributed under the License
+// is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+// or implied. See the License for the specific language governing permissions and limitations under
+// the License.
+
+use pecos::prelude::*;
+use pecos_qsim::CoinToss;
+use pyo3::prelude::*;
+use pyo3::types::PyDict;
+
+/// The struct represents the coin toss simulator exposed to Python
+///
+/// This simulator ignores all quantum gates and returns random measurement results
+/// based on a configurable probability. It's useful for debugging classical logic
+/// paths and testing error correction protocols with random noise.
+#[pyclass(name = "CoinToss")]
+pub struct RsCoinToss {
+    inner: CoinToss,
+}
+
+#[pymethods]
+impl RsCoinToss {
+    /// Creates a new coin toss simulator with the specified number of qubits
+    ///
+    /// # Arguments
+    /// * `num_qubits` - Number of qubits in the system
+    /// * `prob` - Probability of measuring |1⟩ (default: 0.5)
+    /// * `seed` - Optional seed for the random number generator
+    #[new]
+    #[pyo3(signature = (num_qubits, prob=0.5, seed=None))]
+    pub fn new(num_qubits: usize, prob: f64, seed: Option<u64>) -> PyResult<Self> {
+        if !(0.0..=1.0).contains(&prob) {
+            return Err(PyErr::new::<pyo3::exceptions::PyValueError, _>(format!(
+                "Probability must be between 0.0 and 1.0, got {prob}"
+            )));
+        }
+
+        let inner = match seed {
+            Some(s) => CoinToss::with_prob_and_seed(num_qubits, prob, Some(s)),
+            None => CoinToss::with_prob(num_qubits, prob),
+        };
+
+        Ok(RsCoinToss { inner })
+    }
+
+    /// Resets the simulator (no-op for coin toss, but maintains interface compatibility)
+    fn reset(&mut self) {
+        self.inner.reset();
+    }
+
+    /// Returns the number of qubits in the system
+    #[getter]
+    fn num_qubits(&self) -> usize {
+        self.inner.num_qubits()
+    }
+
+    /// Gets the current measurement probability
+    #[getter]
+    fn prob(&self) -> f64 {
+        self.inner.prob()
+    }
+
+    /// Sets the measurement probability
+    ///
+    /// # Arguments
+    /// * `prob` - New probability (must be between 0.0 and 1.0)
+    #[setter]
+    fn set_prob(&mut self, prob: f64) -> PyResult<()> {
+        if !(0.0..=1.0).contains(&prob) {
+            return Err(PyErr::new::<pyo3::exceptions::PyValueError, _>(format!(
+                "Probability must be between 0.0 and 1.0, got {prob}"
+            )));
+        }
+        self.inner.set_prob(prob);
+        Ok(())
+    }
+
+    /// Sets the seed for reproducible randomness
+    ///
+    /// # Arguments
+    /// * `seed` - Seed value for the random number generator
+    fn set_seed(&mut self, seed: u64) -> PyResult<()> {
+        self.inner.set_seed(seed).map_err(|e| {
+            PyErr::new::<pyo3::exceptions::PyRuntimeError, _>(format!("Failed to set seed: {e}"))
+        })
+    }
+
+    /// Executes a single-qubit gate based on the provided symbol and location
+    ///
+    /// All gates are no-ops in the coin toss simulator.
+    ///
+    /// # Arguments
+    /// * `symbol` - The gate symbol (e.g., "X", "H", "Z") - ignored
+    /// * `location` - The qubit index to apply the gate to - ignored
+    /// * `params` - Optional parameters for parameterized gates - ignored
+    ///
+    /// # Returns
+    /// Always returns an empty dictionary since all gates are no-ops
+    #[allow(clippy::unused_self)]
+    fn run_gate_1(
+        &mut self,
+        _symbol: &str,
+        _location: usize,
+        _params: Option<PyObject>,
+    ) -> PyResult<PyObject> {
+        // All gates are no-ops in coin toss simulator
+        Python::with_gil(|py| Ok(PyDict::new(py).into()))
+    }
+
+    /// Executes a two-qubit gate based on the provided symbol and locations
+    ///
+    /// All gates are no-ops in the coin toss simulator.
+    ///
+    /// # Arguments
+    /// * `symbol` - The gate symbol (e.g., "CX", "CZ", "SWAP") - ignored
+    /// * `location_1` - First qubit index - ignored
+    /// * `location_2` - Second qubit index - ignored
+    /// * `params` - Optional parameters for parameterized gates - ignored
+    ///
+    /// # Returns
+    /// Always returns an empty dictionary since all gates are no-ops
+    #[allow(clippy::unused_self)]
+    fn run_gate_2(
+        &mut self,
+        _symbol: &str,
+        _location_1: usize,
+        _location_2: usize,
+        _params: Option<PyObject>,
+    ) -> PyResult<PyObject> {
+        // All gates are no-ops in coin toss simulator
+        Python::with_gil(|py| Ok(PyDict::new(py).into()))
+    }
+
+    /// Performs a measurement in the Z basis
+    ///
+    /// Returns a random result (0 or 1) based on the configured probability.
+    ///
+    /// # Arguments
+    /// * `location` - The qubit index to measure (ignored - result is always random)
+    ///
+    /// # Returns
+    /// Dictionary containing the measurement result: {location: outcome}
+    /// where outcome is 0 or 1 based on the probability
+    fn run_measure(&mut self, location: usize) -> PyResult<PyObject> {
+        let result = self.inner.mz(location);
+        let outcome = i32::from(result.outcome);
+
+        Python::with_gil(|py| {
+            let dict = PyDict::new(py);
+            dict.set_item(location, outcome)?;
+            Ok(dict.into())
+        })
+    }
+
+    /// String representation of the simulator
+    fn __repr__(&self) -> String {
+        format!(
+            "CoinToss(num_qubits={}, prob={})",
+            self.inner.num_qubits(),
+            self.inner.prob()
+        )
+    }
+
+    /// String representation of the simulator
+    fn __str__(&self) -> String {
+        format!(
+            "CoinToss simulator with {} qubits, P(|1⟩) = {:.3}",
+            self.inner.num_qubits(),
+            self.inner.prob()
+        )
+    }
+}

python/pecos-rslib/rust/src/coin_toss_bindings.rs

@@ -17,6 +17,7 @@
 // the License.
 
 mod byte_message_bindings;
+mod coin_toss_bindings;
 mod cpp_sparse_sim_bindings;
 mod engine_bindings;
 mod noise_helpers;
@@ -31,6 +32,7 @@ mod state_vec_bindings;
 mod state_vec_engine_bindings;
 
 use byte_message_bindings::{PyByteMessage, PyByteMessageBuilder};
+use coin_toss_bindings::RsCoinToss;
 use cpp_sparse_sim_bindings::CppSparseSim;
 use pecos_rng_bindings::RngPcg;
 use pyo3::prelude::*;
@@ -46,6 +48,7 @@ fn _pecos_rslib(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<CppSparseSim>()?;
     m.add_class::<phir_bridge::PHIREngine>()?;
     m.add_class::<RsStateVec>()?;
+    m.add_class::<RsCoinToss>()?;
     m.add_class::<PyByteMessage>()?;
     m.add_class::<PyByteMessageBuilder>()?;
     m.add_class::<PyStateVecEngine>()?;

python/pecos-rslib/rust/src/lib.rs

@@ -23,7 +23,7 @@ pub struct RsStateVec {
 #[pymethods]
 impl RsStateVec {
     /// Creates a new state-vector simulator with the specified number of qubits
-    /// 
+    ///
     /// # Arguments
     /// * `num_qubits` - Number of qubits in the system
     /// * `seed` - Optional seed for the random number generator

python/pecos-rslib/rust/src/state_vec_bindings.rs

@@ -21,6 +21,7 @@
 from pecos_rslib.rssparse_sim import SparseSimRs
 from pecos_rslib.cppsparse_sim import CppSparseSimRs
 from pecos_rslib.rsstate_vec import StateVec
+from pecos_rslib.rscoin_toss import CoinToss
 from pecos_rslib._pecos_rslib import ByteMessage
 from pecos_rslib._pecos_rslib import ByteMessageBuilder
 from pecos_rslib._pecos_rslib import StateVecEngineRs
@@ -63,6 +64,7 @@
     "SparseSimRs",
     "CppSparseSimRs",
     "StateVec",
+    "CoinToss",
     "ByteMessage",
     "ByteMessageBuilder",
     "StateVecEngineRs",