Simplify error handling

Author: ciaranra

Cargo.lock

@@ -21,6 +21,7 @@ keywords = ["scientific", "quantum", "QEC"]
 categories = ["science", "simulation"]
 
 [workspace.dependencies]
+thiserror = "2"
 rand = "0.9"
 rand_chacha = "0.9"
 pyo3 = { version = "0.24", features = ["extension-module"] }

Cargo.toml

@@ -1,6 +1,5 @@
 use log::debug;
 use pecos::prelude::*;
-use std::error::Error;
 use std::path::Path;
 
 /// Sets up a classical engine for the CLI based on the program type
@@ -9,15 +8,26 @@ use std::path::Path;
 pub fn setup_cli_engine(
     program_path: &Path,
     shots: Option<usize>,
-) -> Result<Box<dyn ClassicalEngine>, Box<dyn Error>> {
+) -> Result<Box<dyn ClassicalEngine>, PecosError> {
     debug!("Setting up engine for path: {}", program_path.display());
 
     // Create build directory for engine outputs
-    let build_dir = program_path.parent().unwrap().join("build");
+    let build_dir = program_path
+        .parent()
+        .ok_or_else(|| {
+            PecosError::Input(format!(
+                "Cannot determine parent directory for path: {}",
+                program_path.display()
+            ))
+        })?
+        .join("build");
     debug!("Build directory: {}", build_dir.display());
-    std::fs::create_dir_all(&build_dir)?;
+    std::fs::create_dir_all(&build_dir).map_err(PecosError::IO)?;
 
-    match detect_program_type(program_path)? {
+    // The detect_program_type function now includes proper context in errors
+    let program_type = detect_program_type(program_path)?;
+
+    match program_type {
         ProgramType::QIR => {
             debug!("Setting up QIR engine");
             let mut engine = QirEngine::new(program_path.to_path_buf());

crates/pecos-cli/src/engine_setup.rs

@@ -1,7 +1,6 @@
 use clap::{Args, Parser, Subcommand};
 use env_logger::Env;
 use pecos::prelude::*;
-use std::error::Error;
 
 mod engine_setup;
 use engine_setup::setup_cli_engine;
@@ -228,8 +227,10 @@ fn parse_general_noise_probabilities(noise_str_opt: Option<&String>) -> (f64, f6
 /// This function sets up the appropriate engines and noise models based on
 /// the command line arguments, then runs the specified program and outputs
 /// the results.
-fn run_program(args: &RunArgs) -> Result<(), Box<dyn Error>> {
+fn run_program(args: &RunArgs) -> Result<(), PecosError> {
+    // get_program_path now includes proper context in its errors
     let program_path = get_program_path(&args.program)?;
+
     let classical_engine =
         setup_cli_engine(&program_path, Some(args.shots.div_ceil(args.workers)))?;
 
@@ -295,12 +296,15 @@ fn run_program(args: &RunArgs) -> Result<(), Box<dyn Error>> {
             // Ensure parent directory exists
             if let Some(parent) = std::path::Path::new(file_path).parent() {
                 if !parent.exists() {
-                    std::fs::create_dir_all(parent)?;
+                    std::fs::create_dir_all(parent).map_err(|e| {
+                        PecosError::Resource(format!("Failed to create directory: {e}"))
+                    })?;
                 }
             }
 
             // Write results to file
-            std::fs::write(file_path, results_str)?;
+            std::fs::write(file_path, results_str)
+                .map_err(|e| PecosError::Resource(format!("Failed to write output file: {e}")))?;
             println!("Results written to {file_path}");
         }
         None => {
@@ -312,18 +316,23 @@ fn run_program(args: &RunArgs) -> Result<(), Box<dyn Error>> {
     Ok(())
 }
 
-fn main() -> Result<(), Box<dyn Error>> {
+fn main() -> Result<(), PecosError> {
     // Initialize logger with default "info" level if not specified
     env_logger::Builder::from_env(Env::default().default_filter_or("info")).init();
 
     let cli = Cli::parse();
 
     match &cli.command {
         Commands::Compile(args) => {
+            // get_program_path and detect_program_type now include proper error context
             let program_path = get_program_path(&args.program)?;
-            match detect_program_type(&program_path)? {
+
+            let program_type = detect_program_type(&program_path)?;
+
+            match program_type {
                 ProgramType::QIR => {
                     let engine = setup_cli_engine(&program_path, None)?;
+                    // The compile method should already return a properly formatted PecosError::Compilation
                     engine.compile()?;
                 }
                 ProgramType::PHIR => {

crates/pecos-cli/src/main.rs

@@ -15,6 +15,7 @@ rand.workspace = true
 rand_chacha.workspace = true
 num-traits.workspace = true
 num-complex.workspace = true
+thiserror.workspace = true
 
 [lints]
 workspace = true

crates/pecos-core/Cargo.toml

@@ -0,0 +1,73 @@
+// 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 std::error::Error;
+use std::io;
+use thiserror::Error;
+
+/// The main error type for PECOS
+#[derive(Error, Debug)]
+pub enum PecosError {
+    /// Input/output related error
+    #[error("IO error: {0}")]
+    IO(#[from] io::Error),
+
+    /// Generic error when a more specific category doesn't apply
+    #[error("{0}")]
+    Generic(String),
+
+    /// Error with context information
+    #[error("{context}: {source}")]
+    WithContext {
+        context: String,
+        #[source]
+        source: Box<dyn Error + Send + Sync>,
+    },
+
+    /// Error from an external source
+    #[error(transparent)]
+    External(#[from] Box<dyn Error + Send + Sync>),
+
+    /// Error related to invalid input parameters, arguments, or configuration
+    #[error("Input error: {0}")]
+    Input(String),
+
+    /// Error related to failures during command or operation processing
+    #[error("Processing error: {0}")]
+    Processing(String),
+
+    /// Error related to resource handling (files, libraries, etc.)
+    #[error("Resource error: {0}")]
+    Resource(String),
+
+    /// Error related to the compilation process
+    #[error("Compilation error: {0}")]
+    Compilation(String),
+
+    /// Error related to an unsupported or invalid quantum gate
+    #[error("Gate error: {0}")]
+    Gate(String),
+}
+
+impl PecosError {
+    /// Adds context to any error
+    pub fn with_context<E, S>(error: E, context: S) -> Self
+    where
+        E: Error + Send + Sync + 'static,
+        S: Into<String>,
+    {
+        Self::WithContext {
+            context: context.into(),
+            source: Box::new(error),
+        }
+    }
+}

crates/pecos-core/src/errors.rs

@@ -12,6 +12,7 @@
 
 pub mod angle;
 pub mod element;
+pub mod errors;
 pub mod gate;
 pub mod pauli;
 pub mod phase;

crates/pecos-core/src/lib.rs

@@ -10,6 +10,7 @@
 // or implied. See the License for the specific language governing permissions and limitations under
 // the License.
 
+use crate::errors::PecosError;
 use rand::RngCore;
 use rand::SeedableRng;
 use rand_chacha::ChaCha8Rng;
@@ -85,7 +86,7 @@ pub trait RngManageable {
     ///
     /// # Errors
     /// Returns an error if setting the RNG fails
-    fn set_rng(&mut self, rng: Self::Rng) -> Result<(), Box<dyn std::error::Error>>;
+    fn set_rng(&mut self, rng: Self::Rng) -> Result<(), PecosError>;
 
     /// Replace the random number generator with a new one created from a seed
     ///
@@ -108,7 +109,7 @@ pub trait RngManageable {
     /// The default implementation creates a new RNG using `SeedableRng::seed_from_u64`
     /// and sets it using `set_rng()`. Implementers typically only need to implement
     /// `set_rng()` unless they need custom seed handling.
-    fn set_seed(&mut self, seed: u64) -> Result<(), Box<dyn std::error::Error>>
+    fn set_seed(&mut self, seed: u64) -> Result<(), PecosError>
     where
         Self::Rng: SeedableRng,
     {