Switched WeightedSampler and related code to use BTreeMap. Added LLVM 14 errors

Author: ciaranra

.gitignore

@@ -1,3 +1,5 @@
+**/.*/settings.local.json
+
 # Ignore helper text in root
 *.txt
 

README.md

@@ -22,6 +22,7 @@ calls to Wasm VMs, conditional branching, and more.
 - Fast Simulation: Leverages a fast stabilizer simulation algorithm.
 - Multi-language extensions: Core functionalities implemented via Rust for performance and safety. Additional add-ons
 and extension support in C/C++ via Cython.
+- QIR Support: Execute Quantum Intermediate Representation programs (requires LLVM version 14 with the 'llc' tool).
 
 ## Getting Started
 
@@ -97,6 +98,17 @@ To use PECOS in your Rust project, add the following to your `Cargo.toml`:
 pecos = "0.x.x"  # Replace with the latest version
 ```
 
+#### Optional Dependencies
+
+- **LLVM version 14**: Required for QIR (Quantum Intermediate Representation) support
+  - Linux: `sudo apt install llvm-14`
+  - macOS: `brew install llvm@14`
+  - Windows: Download LLVM 14.x installer from [LLVM releases](https://releases.llvm.org/download.html#14.0.0)
+
+  **Note**: Only LLVM version 14.x is compatible. LLVM 15 or later versions will not work with PECOS's QIR implementation.
+
+  If LLVM 14 is not installed, PECOS will still function normally but QIR-related features will be disabled.
+
 ## Development Setup
 
 If you are interested in editing or developing the code in this project, see this

crates/pecos-cli/src/main.rs

@@ -29,7 +29,30 @@ struct CompileArgs {
     program: String,
 }
 
-#[derive(Args)]
+#[derive(PartialEq, Eq, Clone, Debug, Default)]
+enum NoiseModelType {
+    /// Simple depolarizing noise model with uniform error probabilities
+    #[default]
+    Depolarizing,
+    /// General noise model with configurable error probabilities
+    General,
+}
+
+impl std::str::FromStr for NoiseModelType {
+    type Err = String;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        match s.to_lowercase().as_str() {
+            "depolarizing" | "dep" => Ok(NoiseModelType::Depolarizing),
+            "general" | "gen" => Ok(NoiseModelType::General),
+            _ => Err(format!(
+                "Unknown noise model type: {s}. Valid options are 'depolarizing' (dep) or 'general' (gen)"
+            )),
+        }
+    }
+}
+
+#[derive(Args, Debug)]
 struct RunArgs {
     /// Path to the quantum program (LLVM IR or JSON)
     program: String,
@@ -42,40 +65,169 @@ struct RunArgs {
     #[arg(short, long, default_value_t = 1)]
     workers: usize,
 
-    /// Depolarizing noise probability (between 0 and 1)
+    /// Type of noise model to use (depolarizing or general)
+    #[arg(long = "model", value_parser, default_value = "depolarizing")]
+    noise_model: NoiseModelType,
+
+    /// Noise probability (between 0 and 1)
+    /// For depolarizing model: uniform error probability
+    /// For general model: comma-separated probabilities in order:
+    /// `prep,meas_0,meas_1,single_qubit,two_qubit`
+    /// Example: --noise 0.01,0.02,0.02,0.05,0.1
     #[arg(short = 'p', long = "noise", value_parser = parse_noise_probability)]
-    noise_probability: Option<f64>,
+    noise_probability: Option<String>,
 
     /// Seed for random number generation (for reproducible results)
     #[arg(short = 'd', long)]
     seed: Option<u64>,
 }
 
-fn parse_noise_probability(arg: &str) -> Result<f64, String> {
-    let prob: f64 = arg
-        .parse()
-        .map_err(|_| "Must be a valid floating point number")?;
-    if !(0.0..=1.0).contains(&prob) {
-        return Err("Noise probability must be between 0 and 1".into());
+fn parse_noise_probability(arg: &str) -> Result<String, String> {
+    // Check if it's a comma-separated list
+    if arg.contains(',') {
+        // Split by comma and parse each value
+        let probs: Result<Vec<f64>, _> = arg
+            .split(',')
+            .map(|s| {
+                s.trim().parse::<f64>().map_err(|_| {
+                    format!(
+                        "Invalid probability value '{s}': must be a valid floating point number"
+                    )
+                })
+            })
+            .collect();
+
+        // Check if all values are valid probabilities
+        let probs = probs?;
+        for prob in &probs {
+            if !(0.0..=1.0).contains(prob) {
+                return Err(format!("Noise probability {prob} must be between 0 and 1"));
+            }
+        }
+
+        // For general noise model, we expect 5 probabilities
+        if probs.len() != 5 && probs.len() != 1 {
+            return Err(format!(
+                "Expected either 1 probability for depolarizing model or 5 probabilities for general model, got {}",
+                probs.len()
+            ));
+        }
+
+        // Return the original string since it's valid
+        Ok(arg.to_string())
+    } else {
+        // Single probability value
+        let prob: f64 = arg
+            .parse()
+            .map_err(|_| "Must be a valid floating point number")?;
+
+        if !(0.0..=1.0).contains(&prob) {
+            return Err("Noise probability must be between 0 and 1".into());
+        }
+
+        Ok(arg.to_string())
     }
-    Ok(prob)
 }
 
 fn run_program(args: &RunArgs) -> Result<(), Box<dyn Error>> {
     let program_path = get_program_path(&args.program)?;
-    let prob = args.noise_probability.unwrap_or(0.0);
-
     let classical_engine = setup_engine(&program_path, Some(args.shots.div_ceil(args.workers)))?;
 
-    let results = MonteCarloEngine::run_with_classical_engine(
-        classical_engine,
-        prob,
-        args.shots,
-        args.workers,
-        args.seed,
-    )?;
+    // Process based on the selected noise model
+    match args.noise_model {
+        NoiseModelType::Depolarizing => {
+            // Single noise probability for depolarizing model
+            let prob = if let Some(noise_str) = &args.noise_probability {
+                // If it contains commas, take the first value
+                if noise_str.contains(',') {
+                    noise_str
+                        .split(',')
+                        .next()
+                        .unwrap()
+                        .trim()
+                        .parse::<f64>()
+                        .unwrap_or(0.0)
+                } else {
+                    noise_str.parse::<f64>().unwrap_or(0.0)
+                }
+            } else {
+                0.0
+            };
+
+            // Create a depolarizing noise model
+            let mut noise_model = DepolarizingNoiseModel::new_uniform(prob);
+
+            // If a seed is provided, set it on the noise model
+            if let Some(s) = args.seed {
+                let noise_seed = derive_seed(s, "noise_model");
+                noise_model.set_seed(noise_seed)?;
+            }
+
+            // Use the generic approach with noise model
+            let results = MonteCarloEngine::run_with_noise_model(
+                classical_engine,
+                Box::new(noise_model),
+                args.shots,
+                args.workers,
+                args.seed,
+            )?;
+
+            results.print();
+        }
+        NoiseModelType::General => {
+            // For general model, we need to parse the comma-separated probabilities
+            let (prep, meas_0, meas_1, single_qubit, two_qubit) =
+                if let Some(noise_str) = &args.noise_probability {
+                    if noise_str.contains(',') {
+                        // Parse the comma-separated values
+                        let probs: Vec<f64> = noise_str
+                            .split(',')
+                            .map(|s| s.trim().parse::<f64>().unwrap_or(0.0))
+                            .collect();
+
+                        // We should already have validated the length in the parser
+                        if probs.len() == 5 {
+                            (probs[0], probs[1], probs[2], probs[3], probs[4])
+                        } else {
+                            // Use the first value for all if only one value is provided
+                            let p = probs[0];
+                            (p, p, p, p, p)
+                        }
+                    } else {
+                        // Single probability value - use for all parameters
+                        let p = noise_str.parse::<f64>().unwrap_or(0.0);
+                        (p, p, p, p, p)
+                    }
+                } else {
+                    // Default: no noise
+                    (0.0, 0.0, 0.0, 0.0, 0.0)
+                };
 
-    results.print();
+            // Create the general noise model
+            let mut noise_model =
+                GeneralNoiseModel::new(prep, meas_0, meas_1, single_qubit, two_qubit);
+
+            // If a seed is provided, set it on the noise model
+            if let Some(s) = args.seed {
+                let noise_seed = derive_seed(s, "noise_model");
+                // We can now silence the non-deterministic warning since we've fixed that issue
+                noise_model.reset_with_seed(noise_seed).map_err(|e| {
+                    Box::<dyn Error>::from(format!("Failed to set noise model seed: {e}"))
+                })?;
+            }
+
+            // Use the generic function with the general noise model
+            let results = MonteCarloEngine::run_with_noise_model(
+                classical_engine,
+                Box::new(noise_model),
+                args.shots,
+                args.workers,
+                args.seed,
+            )?;
+
+            results.print();
+        }
+    }
 
     Ok(())
 }
@@ -128,6 +280,7 @@ mod tests {
                 assert_eq!(args.seed, Some(42));
                 assert_eq!(args.shots, 100);
                 assert_eq!(args.workers, 2);
+                assert_eq!(args.noise_model, NoiseModelType::Depolarizing); // Default
             }
             Commands::Compile(_) => panic!("Expected Run command"),
         }
@@ -142,6 +295,34 @@ mod tests {
                 assert_eq!(args.seed, None);
                 assert_eq!(args.shots, 100);
                 assert_eq!(args.workers, 2);
+                assert_eq!(args.noise_model, NoiseModelType::Depolarizing); // Default
+            }
+            Commands::Compile(_) => panic!("Expected Run command"),
+        }
+    }
+
+    #[test]
+    fn verify_cli_general_noise_model() {
+        let cmd = Cli::parse_from([
+            "pecos",
+            "run",
+            "program.json",
+            "--model",
+            "general",
+            "-p",
+            "0.01,0.02,0.03,0.04,0.05",
+            "-d",
+            "42",
+        ]);
+
+        match cmd.command {
+            Commands::Run(args) => {
+                assert_eq!(args.seed, Some(42));
+                assert_eq!(args.noise_model, NoiseModelType::General);
+                assert_eq!(
+                    args.noise_probability,
+                    Some("0.01,0.02,0.03,0.04,0.05".to_string())
+                );
             }
             Commands::Compile(_) => panic!("Expected Run command"),
         }

crates/pecos-engines/QIR_RUNTIME.md

@@ -2,14 +2,32 @@
 
 The QIR (Quantum Intermediate Representation) compiler in PECOS uses a Rust runtime library to implement quantum operations. This library is automatically built by the `build.rs` script in the `pecos-engines` crate.
 
+## Requirements
+
+To use QIR functionality, you need:
+
+- **LLVM version 14 specifically**:
+  - On Linux: Install using your package manager (e.g., `sudo apt install llvm-14`)
+  - On macOS: Install using Homebrew (`brew install llvm@14`)
+  - On Windows: Download and install LLVM 14.x from the [LLVM website](https://releases.llvm.org/download.html#14.0.0)
+
+- **Required tools**:
+  - Linux/macOS: The `llc` compiler tool must be in your PATH
+  - Windows: The `clang` compiler must be in your PATH
+
+**Note**: PECOS requires LLVM version 14.x specifically, not newer versions. LLVM 15 or later versions are not compatible with PECOS's QIR implementation.
+
+If LLVM 14 is not installed or the required tools aren't found, QIR functionality will be disabled but the rest of PECOS will continue to work normally.
+
 ## How It Works
 
 The `build.rs` script:
 
 1. Runs automatically when building the `pecos-engines` crate
-2. Checks if the QIR runtime library needs to be rebuilt
-3. Builds the library only if necessary (if source files have changed)
-4. Places the built library in both `target/debug` and `target/release` directories
+2. Checks for LLVM 14+ dependencies
+3. Checks if the QIR runtime library needs to be rebuilt
+4. Builds the library only if necessary (if source files have changed)
+5. Places the built library in both `target/debug` and `target/release` directories
 
 When the QIR compiler runs, it looks for the pre-built library in these locations. If the library is not found, the compiler will attempt to build it by running `cargo build -p pecos-engines` before raising an error.