Multiple magic states and factory types (#1287)

This PR
- simplifies the `Overhead` trait by requiring information about the
number of magic states per rotation (moved to implementation)
- allows to specify an index for the type of magic state (both in
`Overhead` and in `FactoryBuilder` to determine how many different magic
states are provided)
- changes the return type of `FactoryBuilder::find_factories` to return
`Vec<Cow<Factory>>` instead of `Vec<Factory>` such that implementors do
not need to copy factories in case they are already pre-computed
- adds helper structs to pass no factories or to merge two separate
factories to produce a factory builder that produces two different magic
states

Author: msoeken

resource_estimator/src/counts.rs

@@ -577,14 +577,17 @@ pub struct LayerInfo {
 }
 
 impl LayerInfo {
+    #[must_use]
     pub fn new_with_t() -> Self {
         Self { t: 1, r: 0, ccz: 0 }
     }
 
+    #[must_use]
     pub fn new_with_r() -> Self {
         Self { t: 0, r: 1, ccz: 0 }
     }
 
+    #[must_use]
     pub fn new_with_ccz() -> Self {
         Self { t: 0, r: 0, ccz: 1 }
     }

resource_estimator/src/estimates.rs

@@ -6,10 +6,13 @@ pub use error::Error;
 mod error_budget;
 pub use error_budget::ErrorBudget;
 mod factory;
-pub use factory::{DistillationRound, DistillationUnit, FactoryBuildError, RoundBasedFactory};
+pub use factory::{
+    BuilderDispatch2, DistillationRound, DistillationUnit, FactoryBuildError, FactoryDispatch2,
+    NoFactories, RoundBasedFactory,
+};
 mod physical_estimation;
 pub use physical_estimation::{
-    ErrorCorrection, Factory, FactoryBuilder, PhysicalResourceEstimation,
+    ErrorCorrection, Factory, FactoryBuilder, FactoryPart, PhysicalResourceEstimation,
     PhysicalResourceEstimationResult,
 };
 mod layout;

resource_estimator/src/estimates/error.rs

@@ -37,6 +37,13 @@ pub enum Error {
     #[error("No solution found for the provided maximum number of physical qubits.")]
     #[diagnostic(code("Qsc.Estimates.MaxPhysicalQubitsTooSmall"))]
     MaxPhysicalQubitsTooSmall,
+    /// Constraint-based search only supports one magic state type.
+    ///
+    /// ✅ This error cannot be triggered by the system, since only one magic
+    /// state type is supported.
+    #[error("Constraint-based search only supports one magic state type.")]
+    #[diagnostic(code("Qsc.Estimates.MultipleMagicStatesNotSupported"))]
+    MultipleMagicStatesNotSupported,
     /// The number of physical qubits required for a code cannot be computed.
     ///
     /// ✅ This does not contain user data and can be logged

resource_estimator/src/estimates/factory.rs

@@ -4,6 +4,14 @@ use probability::{distribution::Inverse, prelude::Binomial};
 
 use super::Factory;
 
+/// Helper structs when dispatching multiple magic states to different factories
+mod dispatch;
+pub use dispatch::{BuilderDispatch2, FactoryDispatch2};
+
+/// Helper structs for when no factories are used
+mod empty;
+pub use empty::NoFactories;
+
 pub trait DistillationUnit<P> {
     fn num_output_states(&self) -> u64;
     fn num_input_states(&self) -> u64;

resource_estimator/src/estimates/factory/dispatch.rs

@@ -0,0 +1,111 @@
+use crate::estimates::{ErrorCorrection, Factory, FactoryBuilder};
+use std::borrow::Cow;
+
+/// Implements `Factory` to combine two factories for dispatching
+///
+/// It requires that all factories define the same code parameter type.
+#[derive(Clone)]
+pub enum FactoryDispatch2<Factory1, Factory2> {
+    Factory1(Factory1),
+    Factory2(Factory2),
+}
+
+impl<Factory1: Factory, Factory2: Factory<Parameter = Factory1::Parameter>> Factory
+    for FactoryDispatch2<Factory1, Factory2>
+{
+    type Parameter = Factory1::Parameter;
+
+    fn physical_qubits(&self) -> u64 {
+        match self {
+            Self::Factory1(f) => f.physical_qubits(),
+            Self::Factory2(f) => f.physical_qubits(),
+        }
+    }
+
+    fn duration(&self) -> u64 {
+        match self {
+            Self::Factory1(f) => f.duration(),
+            Self::Factory2(f) => f.duration(),
+        }
+    }
+
+    fn num_output_states(&self) -> u64 {
+        match self {
+            Self::Factory1(f) => f.num_output_states(),
+            Self::Factory2(f) => f.num_output_states(),
+        }
+    }
+
+    fn max_code_parameter(&self) -> Option<Cow<Self::Parameter>> {
+        match self {
+            Self::Factory1(f) => f.max_code_parameter(),
+            Self::Factory2(f) => f.max_code_parameter(),
+        }
+    }
+}
+
+/// Implements `FactoryBuilder` to combine two factory builders for dispatching
+///
+/// It will use `FactoryDispatch2` as factory type for the builder.
+pub struct BuilderDispatch2<Builder1, Builder2> {
+    builder1: Builder1,
+    builder2: Builder2,
+}
+
+impl<Builder1: Default, Builder2: Default> Default for BuilderDispatch2<Builder1, Builder2> {
+    fn default() -> Self {
+        Self {
+            builder1: Builder1::default(),
+            builder2: Builder2::default(),
+        }
+    }
+}
+
+impl<E: ErrorCorrection, Builder1: FactoryBuilder<E>, Builder2: FactoryBuilder<E>> FactoryBuilder<E>
+    for BuilderDispatch2<Builder1, Builder2>
+{
+    type Factory = FactoryDispatch2<Builder1::Factory, Builder2::Factory>;
+
+    fn find_factories(
+        &self,
+        ftp: &E,
+        qubit: &std::rc::Rc<E::Qubit>,
+        magic_state_type: usize,
+        output_error_rate: f64,
+        max_code_parameter: &E::Parameter,
+    ) -> Vec<Cow<Self::Factory>> {
+        match magic_state_type {
+            0 => self
+                .builder1
+                .find_factories(
+                    ftp,
+                    qubit,
+                    magic_state_type,
+                    output_error_rate,
+                    max_code_parameter,
+                )
+                .into_iter()
+                .map(|f| Cow::Owned(FactoryDispatch2::Factory1(f.into_owned())))
+                .collect(),
+            1 => self
+                .builder2
+                .find_factories(
+                    ftp,
+                    qubit,
+                    magic_state_type,
+                    output_error_rate,
+                    max_code_parameter,
+                )
+                .into_iter()
+                .map(|f| Cow::Owned(FactoryDispatch2::Factory2(f.into_owned())))
+                .collect(),
+            _ => unreachable!("factory builder only has two magic state types"),
+        }
+    }
+
+    /// Since this builder dispatch is for two factory builders, it can support
+    /// two different magic state types.
+    fn num_magic_state_types(&self) -> usize {
+        2
+    }
+}

resource_estimator/src/estimates/factory/empty.rs

@@ -0,0 +1,59 @@
+use std::marker::PhantomData;
+
+use crate::estimates::{ErrorCorrection, Factory, FactoryBuilder};
+
+pub struct NoFactories<E> {
+    phantom: PhantomData<E>,
+}
+
+impl<E> Default for NoFactories<E> {
+    fn default() -> Self {
+        Self {
+            phantom: PhantomData,
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct NoFactory<P> {
+    phantom: PhantomData<P>,
+}
+
+impl<E: ErrorCorrection<Parameter = impl Clone>> FactoryBuilder<E> for NoFactories<E> {
+    type Factory = NoFactory<E::Parameter>;
+
+    fn find_factories(
+        &self,
+        _ftp: &E,
+        _qubit: &std::rc::Rc<<E as ErrorCorrection>::Qubit>,
+        _magic_state_type: usize,
+        _output_error_rate: f64,
+        _max_code_parameter: &<E as ErrorCorrection>::Parameter,
+    ) -> Vec<std::borrow::Cow<Self::Factory>> {
+        unreachable!()
+    }
+
+    fn num_magic_state_types(&self) -> usize {
+        0
+    }
+}
+
+impl<P: Clone> Factory for NoFactory<P> {
+    type Parameter = P;
+
+    fn physical_qubits(&self) -> u64 {
+        unreachable!()
+    }
+
+    fn duration(&self) -> u64 {
+        unreachable!()
+    }
+
+    fn num_output_states(&self) -> u64 {
+        unreachable!()
+    }
+
+    fn max_code_parameter(&self) -> Option<std::borrow::Cow<Self::Parameter>> {
+        unreachable!()
+    }
+}

resource_estimator/src/estimates/layout.rs

@@ -1,12 +1,24 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+use super::ErrorBudget;
+
+/// 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_without_padding(&self) -> u64 {
-        self.logical_qubits()
-    }
-    fn logical_depth(&self, num_magic_states_per_rotation: u64) -> u64;
-    fn num_magic_states(&self, num_magic_states_per_rotation: u64) -> u64;
-    fn num_magic_states_per_rotation(&self, eps_synthesis: f64) -> Option<u64>;
+
+    /// 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;
+
+    /// 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;
 }