Add shot argument to PECOS CLI and ensure deterministic output

Author: ciaranra

Cargo.lock

@@ -21,5 +21,10 @@ pecos.workspace = true
 clap.workspace = true
 env_logger.workspace = true
 
+[dev-dependencies]
+assert_cmd = "2.0"
+predicates = "3.0"
+tempfile = "3.8"
+
 [lints]
 workspace = true

crates/pecos-cli/Cargo.toml

@@ -45,6 +45,10 @@ struct RunArgs {
     /// Depolarizing noise probability (between 0 and 1)
     #[arg(short = 'p', long = "noise", value_parser = parse_noise_probability)]
     noise_probability: Option<f64>,
+
+    /// Seed for random number generation (for reproducible results)
+    #[arg(short = 'd', long)]
+    seed: Option<u64>,
 }
 
 fn parse_noise_probability(arg: &str) -> Result<f64, String> {
@@ -68,7 +72,7 @@ fn run_program(args: &RunArgs) -> Result<(), Box<dyn Error>> {
         prob,
         args.shots,
         args.workers,
-        None,
+        args.seed,
     )?;
 
     results.print();
@@ -100,3 +104,46 @@ fn main() -> Result<(), Box<dyn Error>> {
 
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn verify_cli_seed_argument() {
+        let cmd = Cli::parse_from([
+            "pecos",
+            "run",
+            "program.json",
+            "-d",
+            "42",
+            "-s",
+            "100",
+            "-w",
+            "2",
+        ]);
+
+        match cmd.command {
+            Commands::Run(args) => {
+                assert_eq!(args.seed, Some(42));
+                assert_eq!(args.shots, 100);
+                assert_eq!(args.workers, 2);
+            }
+            Commands::Compile(_) => panic!("Expected Run command"),
+        }
+    }
+
+    #[test]
+    fn verify_cli_no_seed_argument() {
+        let cmd = Cli::parse_from(["pecos", "run", "program.json", "-s", "100", "-w", "2"]);
+
+        match cmd.command {
+            Commands::Run(args) => {
+                assert_eq!(args.seed, None);
+                assert_eq!(args.shots, 100);
+                assert_eq!(args.workers, 2);
+            }
+            Commands::Compile(_) => panic!("Expected Run command"),
+        }
+    }
+}

crates/pecos-cli/src/main.rs

@@ -0,0 +1,98 @@
+use assert_cmd::prelude::*;
+use std::path::PathBuf;
+use std::process::Command;
+
+#[test]
+fn test_seed_produces_consistent_results() -> Result<(), Box<dyn std::error::Error>> {
+    let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
+    let test_file = manifest_dir.join("../../examples/phir/bell.json");
+
+    // Run multiple times with seed 42
+    let seed_42_run1 = Command::cargo_bin("pecos")?
+        .env("RUST_LOG", "info")
+        .arg("run")
+        .arg(&test_file)
+        .arg("-s")
+        .arg("10") // Fewer shots for faster tests
+        .arg("-w")
+        .arg("1") // Single worker to avoid thread scheduling differences
+        .arg("-p")
+        .arg("0.1")
+        .arg("-d")
+        .arg("42")
+        .output()?;
+
+    let seed_42_run2 = Command::cargo_bin("pecos")?
+        .env("RUST_LOG", "info")
+        .arg("run")
+        .arg(&test_file)
+        .arg("-s")
+        .arg("10")
+        .arg("-w")
+        .arg("1")
+        .arg("-p")
+        .arg("0.1")
+        .arg("-d")
+        .arg("42")
+        .output()?;
+
+    // Run multiple times with seed 43
+    let seed_43_run1 = Command::cargo_bin("pecos")?
+        .env("RUST_LOG", "info")
+        .arg("run")
+        .arg(&test_file)
+        .arg("-s")
+        .arg("10")
+        .arg("-w")
+        .arg("1")
+        .arg("-p")
+        .arg("0.1")
+        .arg("-d")
+        .arg("43")
+        .output()?;
+
+    let seed_43_run2 = Command::cargo_bin("pecos")?
+        .env("RUST_LOG", "info")
+        .arg("run")
+        .arg(&test_file)
+        .arg("-s")
+        .arg("10")
+        .arg("-w")
+        .arg("1")
+        .arg("-p")
+        .arg("0.1")
+        .arg("-d")
+        .arg("43")
+        .output()?;
+
+    // Check that all commands ran successfully
+    assert!(seed_42_run1.status.success(), "First seed 42 run failed");
+    assert!(seed_42_run2.status.success(), "Second seed 42 run failed");
+    assert!(seed_43_run1.status.success(), "First seed 43 run failed");
+    assert!(seed_43_run2.status.success(), "Second seed 43 run failed");
+
+    // Convert outputs to strings
+    let seed_42_output1 = String::from_utf8(seed_42_run1.stdout)?;
+    let seed_42_output2 = String::from_utf8(seed_42_run2.stdout)?;
+    let seed_43_output1 = String::from_utf8(seed_43_run1.stdout)?;
+    let seed_43_output2 = String::from_utf8(seed_43_run2.stdout)?;
+
+    // Verify consistency within each seed group
+    assert_eq!(
+        seed_42_output1, seed_42_output2,
+        "Results with seed 42 should be identical across runs"
+    );
+
+    assert_eq!(
+        seed_43_output1, seed_43_output2,
+        "Results with seed 43 should be identical across runs"
+    );
+
+    // Verify that different seeds produce different results
+    assert_ne!(
+        seed_42_output1, seed_43_output1,
+        "Results with different seeds (42 vs 43) should differ"
+    );
+
+    Ok(())
+}