Allow to catch and propagate errors in all resource estimation models (#2457)

This changes return types for methods in the `Overhead` and
`FactoryBuilder` trait from `T` to `Result<T,
resource_estimator::estimates::Error>`.

No implementation of this `Overhead` and `FactoryBuilder` trait returns
an error; therefore, the behavior of RE for the default system
architecture does not change. However, when implementing the traits to
extend the resource estimator, the new signature allows more flexibility
and allows users of the implementation to see errors.

Author: msoeken

resource_estimator/src/estimates/error.rs

@@ -13,6 +13,27 @@ pub enum Error {
     #[error("Algorithm requires at least one magic state or measurement to estimate resources")]
     #[diagnostic(code("Qsc.Estimates.AlgorithmHasNoResources"))]
     AlgorithmHasNoResources,
+    /// The number of algorithmic logical qubits cannot be computed.
+    ///
+    /// ✅ This does not contain user data and can be logged
+    /// ✅ This error cannot be triggered by the system.
+    #[error("Cannot compute the number of algorithmic logical qubits: {0}")]
+    #[diagnostic(code("Qsc.Estimates.AlgorithmicLogicalQubitsComputationFailed"))]
+    AlgorithmicLogicalQubitsComputationFailed(String),
+    /// The algorithmic logical depth cannot be computed.
+    ///
+    /// ✅ This does not contain user data and can be logged
+    /// ✅ This error cannot be triggered by the system.
+    #[error("Cannot compute the algorithmic logical depth: {0}")]
+    #[diagnostic(code("Qsc.Estimates.AlgorithmicLogicalDepthComputationFailed"))]
+    AlgorithmicLogicalDepthComputationFailed(String),
+    /// The number of required magic states cannot be computed.
+    ///
+    /// ✅ This does not contain user data and can be logged
+    /// ✅ This error cannot be triggered by the system.
+    #[error("Cannot compute the required number of magic states: {0}")]
+    #[diagnostic(code("Qsc.Estimates.NumberOfMagicStatesComputationFailed"))]
+    NumberOfMagicStatesComputationFailed(String),
     /// Both constraints for maximal time and
     /// maximal number of qubits are provided
     ///
@@ -37,12 +58,12 @@ pub enum Error {
     #[error("No solution found for the provided maximum number of physical qubits.")]
     #[diagnostic(code("Qsc.Estimates.MaxPhysicalQubitsTooSmall"))]
     MaxPhysicalQubitsTooSmall,
-    /// Resource estimation configuration can never produce T states
+    /// Resource estimation failed to find factories
     ///
     /// ✅ This error cannot be triggered by the system.
-    #[error("Resource estimation configuration can never produce T states, required magic state output error rate was {0:.3e}")]
-    #[diagnostic(code("Qsc.Estimates.CannotComputeMagicStates"))]
-    CannotComputeMagicStates(f64),
+    #[error("Resource estimation failed to find factories: {0}")]
+    #[diagnostic(code("Qsc.Estimates.FactorySearchFailed"))]
+    FactorySearchFailed(String),
     /// Constraint-based search only supports one magic state type.
     ///
     /// ✅ This error cannot be triggered by the system, since only one magic

resource_estimator/src/estimates/error_correction.rs

@@ -82,13 +82,11 @@ pub trait ErrorCorrection {
         required_logical_error_rate: f64,
     ) -> Result<Self::Parameter, String> {
         for parameter in self.code_parameter_range(None) {
-            if let (Ok(probability), Ok(logical_qubits)) = (
-                self.logical_error_rate(qubit, &parameter),
-                self.logical_qubits(&parameter),
-            ) {
-                if probability / (logical_qubits as f64) <= required_logical_error_rate {
-                    return Ok(parameter);
-                }
+            let probability = self.logical_error_rate(qubit, &parameter)?;
+            let logical_qubits = self.logical_qubits(&parameter)?;
+
+            if probability / (logical_qubits as f64) <= required_logical_error_rate {
+                return Ok(parameter);
             }
         }
 
@@ -110,20 +108,17 @@ pub trait ErrorCorrection {
         let mut best: Option<(Self::Parameter, f64)> = None;
 
         for parameter in self.code_parameter_range(None) {
-            if let (Ok(probability), Ok(logical_qubits), Ok(physical_qubits)) = (
-                self.logical_error_rate(qubit, &parameter),
-                self.logical_qubits(&parameter),
-                self.physical_qubits(&parameter),
-            ) {
-                let physical_qubits_per_logical_qubits =
-                    physical_qubits as f64 / logical_qubits as f64;
-                if (probability / (logical_qubits as f64) <= required_logical_error_rate)
-                    && best
-                        .as_ref()
-                        .is_none_or(|&(_, pq)| physical_qubits_per_logical_qubits < pq)
-                {
-                    best = Some((parameter, physical_qubits_per_logical_qubits));
-                }
+            let probability = self.logical_error_rate(qubit, &parameter)?;
+            let logical_qubits = self.logical_qubits(&parameter)?;
+            let physical_qubits = self.physical_qubits(&parameter)?;
+
+            let physical_qubits_per_logical_qubits = physical_qubits as f64 / logical_qubits as f64;
+            if (probability / (logical_qubits as f64) <= required_logical_error_rate)
+                && best
+                    .as_ref()
+                    .is_none_or(|&(_, pq)| physical_qubits_per_logical_qubits < pq)
+            {
+                best = Some((parameter, physical_qubits_per_logical_qubits));
             }
         }
 
@@ -146,16 +141,14 @@ pub trait ErrorCorrection {
         let mut best: Option<(Self::Parameter, u64)> = None;
 
         for parameter in self.code_parameter_range(None) {
-            if let (Ok(probability), Ok(logical_qubits), Ok(logical_cycle_time)) = (
-                self.logical_error_rate(qubit, &parameter),
-                self.logical_qubits(&parameter),
-                self.logical_cycle_time(qubit, &parameter),
-            ) {
-                if (probability / (logical_qubits as f64) <= required_logical_error_rate)
-                    && best.as_ref().is_none_or(|&(_, t)| logical_cycle_time < t)
-                {
-                    best = Some((parameter, logical_cycle_time));
-                }
+            let probability = self.logical_error_rate(qubit, &parameter)?;
+            let logical_qubits = self.logical_qubits(&parameter)?;
+            let logical_cycle_time = self.logical_cycle_time(qubit, &parameter)?;
+
+            if (probability / (logical_qubits as f64) <= required_logical_error_rate)
+                && best.as_ref().is_none_or(|&(_, t)| logical_cycle_time < t)
+            {
+                best = Some((parameter, logical_cycle_time));
             }
         }
 

resource_estimator/src/estimates/factory.rs

@@ -33,7 +33,7 @@ where
         magic_state_type: usize,
         output_error_rate: f64,
         max_code_parameter: &E::Parameter,
-    ) -> Option<Vec<Cow<Self::Factory>>>;
+    ) -> Result<Vec<Cow<Self::Factory>>, String>;
 
     fn num_magic_state_types(&self) -> usize {
         1

resource_estimator/src/estimates/factory/dispatch.rs

@@ -76,7 +76,7 @@ impl<E: ErrorCorrection, Builder1: FactoryBuilder<E>, Builder2: FactoryBuilder<E
         magic_state_type: usize,
         output_error_rate: f64,
         max_code_parameter: &E::Parameter,
-    ) -> Option<Vec<Cow<Self::Factory>>> {
+    ) -> Result<Vec<Cow<Self::Factory>>, String> {
         match magic_state_type {
             0 => self
                 .builder1

resource_estimator/src/estimates/factory/empty.rs

@@ -32,7 +32,7 @@ impl<E: ErrorCorrection<Parameter = impl Clone>> FactoryBuilder<E> for NoFactori
         _magic_state_type: usize,
         _output_error_rate: f64,
         _max_code_parameter: &<E as ErrorCorrection>::Parameter,
-    ) -> Option<Vec<std::borrow::Cow<Self::Factory>>> {
+    ) -> Result<Vec<std::borrow::Cow<Self::Factory>>, String> {
         unreachable!()
     }
 

resource_estimator/src/estimates/factory/round_based.rs

@@ -83,7 +83,7 @@ impl<P: Clone> DistillationRound<P> {
         let mut upper = self.num_units;
         let mut lower = self.num_units / 2;
         while lower < upper {
-            self.num_units = (lower + upper) / 2;
+            self.num_units = u64::midpoint(lower, upper);
             let num_output_ts = self.compute_num_output_states(failure_probability);
             if num_output_ts >= output_states_needed_next {
                 upper = self.num_units;

resource_estimator/src/estimates/layout.rs

@@ -3,26 +3,27 @@
 
 use serde::Serialize;
 
+use super::Error;
 use super::{ErrorBudget, ErrorBudgetStrategy};
 
 /// Trait to model post-layout logical overhead
 pub trait Overhead {
     /// The number of logical qubits to execute the algorithm after mapping
     ///
     /// This number does not include qubit used to produce magic states.
-    fn logical_qubits(&self) -> u64;
+    fn logical_qubits(&self) -> Result<u64, String>;
 
     /// The number of logical unit cycles to execute the algorithm
     ///
     /// This number is a lower bound for the execution time of the algorithm,
     /// and might be extended by assuming no-ops.
-    fn logical_depth(&self, budget: &ErrorBudget) -> u64;
+    fn logical_depth(&self, budget: &ErrorBudget) -> Result<u64, String>;
 
     /// The number of magic states
     ///
     /// The index is used to indicate the type of magic states and must be
     /// supported by available factory builders in the physical estimation.
-    fn num_magic_states(&self, budget: &ErrorBudget, index: usize) -> u64;
+    fn num_magic_states(&self, budget: &ErrorBudget, index: usize) -> Result<u64, String>;
 
     /// When implemented, prunes the error budget with respect to the provided
     /// strategy
@@ -49,18 +50,23 @@ impl RealizedOverhead {
         overhead: &impl Overhead,
         budget: &ErrorBudget,
         num_magic_state_types: usize,
-    ) -> Self {
-        let logical_qubits = overhead.logical_qubits();
-        let logical_depth = overhead.logical_depth(budget);
+    ) -> Result<Self, Error> {
+        let logical_qubits = overhead
+            .logical_qubits()
+            .map_err(Error::AlgorithmicLogicalQubitsComputationFailed)?;
+        let logical_depth = overhead
+            .logical_depth(budget)
+            .map_err(Error::AlgorithmicLogicalDepthComputationFailed)?;
         let num_magic_states = (0..num_magic_state_types)
             .map(|index| overhead.num_magic_states(budget, index))
-            .collect();
+            .collect::<Result<_, _>>()
+            .map_err(Error::NumberOfMagicStatesComputationFailed)?;
 
-        Self {
+        Ok(Self {
             logical_qubits,
             logical_depth,
             num_magic_states,
-        }
+        })
     }
 
     #[must_use]
@@ -80,15 +86,15 @@ impl RealizedOverhead {
 }
 
 impl Overhead for RealizedOverhead {
-    fn logical_qubits(&self) -> u64 {
-        self.logical_qubits
+    fn logical_qubits(&self) -> Result<u64, String> {
+        Ok(self.logical_qubits)
     }
 
-    fn logical_depth(&self, _budget: &ErrorBudget) -> u64 {
-        self.logical_depth
+    fn logical_depth(&self, _budget: &ErrorBudget) -> Result<u64, String> {
+        Ok(self.logical_depth)
     }
 
-    fn num_magic_states(&self, _budget: &ErrorBudget, index: usize) -> u64 {
-        self.num_magic_states[index]
+    fn num_magic_states(&self, _budget: &ErrorBudget, index: usize) -> Result<u64, String> {
+        Ok(self.num_magic_states[index])
     }
 }