Allow any op as root (#112)

* allow any op as module root

* fix name of DFG

* new top level HugrBuilder

to allow for building non-module root HUGR
for now only adds DFG builder at root level, other containers to come

* rename to module_hugr_builder and dfg_hugr_builder

* implement empty drop for builders to force call of finish

* make finish return result uniformly

* fix comment

* check root has no edges

* don't require copy is not child of root

* use AsMut and AsRef to make builders generic over base

* clean up drop macro

* WIP owned builder specializations

* remove Drop implmentations for builders

* rename `finish()` to `finish_container()`

* finish implement owned HUGR building

for Module and DFG

* CFG HugrBuilder

* allow constants in any Container

* implement HugrBuilder for CFGBuilder

* separate further owned and borrowed builders

* owned TailLoop builder

* add owned conditional builder

* owned FunctionBuilder

* owned BlockBuilder

* owned CaseBuilder

* fix doc link

* update FuncBuilder docstring

* Apply suggestions from code review

Co-authored-by: Agustín Borgna <[email protected]>

* remove explicit lifetimes

* take some clippy pedantic suggestions

mostly docs

* clean up const + dag validation

---------

Co-authored-by: Agustín Borgna <[email protected]>

Author: ss2165

src/algorithm/nest_cfgs.rs

@@ -400,7 +400,10 @@ impl<T: Copy + Clone + PartialEq + Eq + Hash> EdgeClassifier<T> {
 #[cfg(test)]
 pub(crate) mod test {
     use super::*;
-    use crate::builder::{BuildError, CFGBuilder, Container, Dataflow, ModuleBuilder};
+    use crate::builder::{
+        BuildError, CFGBuilder, Container, Dataflow, DataflowSubContainer, HugrBuilder, HugrMutRef,
+        ModuleBuilder, SubContainer,
+    };
     use crate::ops::{
         handle::{BasicBlockID, CfgID, ConstID, NodeHandle},
         ConstValue,
@@ -430,8 +433,8 @@ pub(crate) mod test {
         //               \-> right -/             \-<--<-/
         let mut module_builder = ModuleBuilder::new();
         let main = module_builder.declare("main", Signature::new_df(vec![NAT], type_row![NAT]))?;
-        let pred_const = module_builder.constant(ConstValue::simple_predicate(0, 2))?; // Nothing here cares which
-        let const_unit = module_builder.constant(ConstValue::simple_unary_predicate())?;
+        let pred_const = module_builder.add_constant(ConstValue::simple_predicate(0, 2))?; // Nothing here cares which
+        let const_unit = module_builder.add_constant(ConstValue::simple_unary_predicate())?;
 
         let mut func_builder = module_builder.define_function(&main)?;
         let [int] = func_builder.input_wires_arr();
@@ -448,11 +451,10 @@ pub(crate) mod test {
         cfg_builder.branch(&merge, 0, &head)?;
         let exit = cfg_builder.exit_block();
         cfg_builder.branch(&tail, 0, &exit)?;
-        let cfg_id = cfg_builder.finish();
+        let cfg_id = cfg_builder.finish_sub_container()?;
 
         func_builder.finish_with_outputs(cfg_id.outputs())?;
-
-        let h = module_builder.finish()?;
+        let h = module_builder.finish_hugr()?;
 
         let (entry, exit) = (entry.node(), exit.node());
         let (split, merge, head, tail) = (split.node(), merge.node(), head.node(), tail.node());
@@ -483,8 +485,8 @@ pub(crate) mod test {
         // the conditional and the loop to indicate the boundary, so we cannot separate them.
         let mut module_builder = ModuleBuilder::new();
         let main = module_builder.declare("main", Signature::new_df(vec![NAT], type_row![NAT]))?;
-        let pred_const = module_builder.constant(ConstValue::simple_predicate(0, 2))?; // Nothing here cares which
-        let const_unit = module_builder.constant(ConstValue::simple_unary_predicate())?;
+        let pred_const = module_builder.add_constant(ConstValue::simple_predicate(0, 2))?; // Nothing here cares which
+        let const_unit = module_builder.add_constant(ConstValue::simple_unary_predicate())?;
 
         let mut func_builder = module_builder.define_function(&main)?;
         let [int] = func_builder.input_wires_arr();
@@ -499,11 +501,11 @@ pub(crate) mod test {
         cfg_builder.branch(&merge, 0, &tail)?; // trivial "loop body"
         let exit = cfg_builder.exit_block();
         cfg_builder.branch(&tail, 0, &exit)?;
-        let cfg_id = cfg_builder.finish();
+        let cfg_id = cfg_builder.finish_sub_container()?;
 
         func_builder.finish_with_outputs(cfg_id.outputs())?;
 
-        let h = module_builder.finish()?;
+        let h = module_builder.finish_hugr()?;
 
         let (entry, exit) = (entry.node(), exit.node());
         let (merge, tail) = (merge.node(), tail.node());
@@ -602,7 +604,7 @@ pub(crate) mod test {
         Ok(())
     }
 
-    fn n_identity<T: Dataflow>(
+    fn n_identity<T: DataflowSubContainer>(
         mut dataflow_builder: T,
         pred_const: &ConstID,
     ) -> Result<T::ContainerHandle, BuildError> {
@@ -611,8 +613,8 @@ pub(crate) mod test {
         dataflow_builder.finish_with_outputs([u].into_iter().chain(w))
     }
 
-    fn build_if_then_else_merge(
-        cfg: &mut CFGBuilder,
+    fn build_if_then_else_merge<T: HugrMutRef>(
+        cfg: &mut CFGBuilder<T>,
         const_pred: &ConstID,
         unit_const: &ConstID,
     ) -> Result<(BasicBlockID, BasicBlockID), BuildError> {
@@ -624,8 +626,8 @@ pub(crate) mod test {
         Ok((split, merge))
     }
 
-    fn build_then_else_merge_from_if(
-        cfg: &mut CFGBuilder,
+    fn build_then_else_merge_from_if<T: HugrMutRef>(
+        cfg: &mut CFGBuilder<T>,
         unit_const: &ConstID,
         split: BasicBlockID,
     ) -> Result<BasicBlockID, BuildError> {
@@ -649,8 +651,8 @@ pub(crate) mod test {
     }
 
     // Returns loop tail - caller must link header to tail, and provide 0th successor of tail
-    fn build_loop_from_header(
-        cfg: &mut CFGBuilder,
+    fn build_loop_from_header<T: HugrMutRef>(
+        cfg: &mut CFGBuilder<T>,
         const_pred: &ConstID,
         header: BasicBlockID,
     ) -> Result<BasicBlockID, BuildError> {
@@ -663,8 +665,8 @@ pub(crate) mod test {
     }
 
     // Result is header and tail. Caller must provide 0th successor of header (linking to tail), and 0th successor of tail.
-    fn build_loop(
-        cfg: &mut CFGBuilder,
+    fn build_loop<T: HugrMutRef>(
+        cfg: &mut CFGBuilder<T>,
         const_pred: &ConstID,
         unit_const: &ConstID,
     ) -> Result<(BasicBlockID, BasicBlockID), BuildError> {
@@ -684,8 +686,8 @@ pub(crate) mod test {
 
         let mut module_builder = ModuleBuilder::new();
         let main = module_builder.declare("main", Signature::new_df(vec![NAT], type_row![NAT]))?;
-        let pred_const = module_builder.constant(ConstValue::simple_predicate(0, 2))?; // Nothing here cares which
-        let const_unit = module_builder.constant(ConstValue::simple_unary_predicate())?;
+        let pred_const = module_builder.add_constant(ConstValue::simple_predicate(0, 2))?; // Nothing here cares which
+        let const_unit = module_builder.add_constant(ConstValue::simple_unary_predicate())?;
 
         let mut func_builder = module_builder.define_function(&main)?;
         let [int] = func_builder.input_wires_arr();
@@ -713,11 +715,11 @@ pub(crate) mod test {
         cfg_builder.branch(&entry, 0, &head)?;
         cfg_builder.branch(&tail, 0, &exit)?;
 
-        let cfg_id = cfg_builder.finish();
+        let cfg_id = cfg_builder.finish_sub_container()?;
 
         func_builder.finish_with_outputs(cfg_id.outputs())?;
 
-        let h = module_builder.finish()?;
+        let h = module_builder.finish_hugr()?;
 
         Ok((h, *cfg_id.handle(), head, tail))
     }

src/builder.rs

@@ -2,15 +2,18 @@
 //!
 use thiserror::Error;
 
-use crate::hugr::{HugrError, Node, ValidationError, Wire};
+use crate::hugr::{HugrError, HugrMut, Node, ValidationError, Wire};
 use crate::ops::handle::{BasicBlockID, CfgID, ConditionalID, DfgID, FuncID, TailLoopID};
+
 use crate::types::LinearType;
 
 pub mod handle;
 pub use handle::BuildHandle;
 
 mod build_traits;
-pub use build_traits::{Container, Dataflow};
+pub use build_traits::{
+    Container, Dataflow, DataflowHugr, DataflowSubContainer, HugrBuilder, SubContainer,
+};
 
 mod dataflow;
 pub use dataflow::{DFGBuilder, DFGWrapper, FunctionBuilder};
@@ -67,22 +70,40 @@ pub enum BuildError {
     CircuitError(#[from] circuit_builder::CircuitBuildError),
 }
 
+impl AsMut<HugrMut> for HugrMut {
+    fn as_mut(&mut self) -> &mut HugrMut {
+        self
+    }
+}
+impl AsRef<HugrMut> for HugrMut {
+    fn as_ref(&self) -> &HugrMut {
+        self
+    }
+}
+
+/// Trait allowing treating type as (im)mutable reference to [`HugrMut`]
+pub trait HugrMutRef: AsMut<HugrMut> + AsRef<HugrMut> {}
+impl HugrMutRef for HugrMut {}
+impl HugrMutRef for &mut HugrMut {}
+
 #[cfg(test)]
 mod test {
 
+    use crate::hugr::HugrMut;
     use crate::types::{ClassicType, LinearType, Signature, SimpleType};
-    use crate::{builder::ModuleBuilder, Hugr};
+    use crate::Hugr;
 
     use super::handle::BuildHandle;
-    use super::{BuildError, Container, Dataflow, FuncID, FunctionBuilder};
+    use super::{BuildError, FuncID, FunctionBuilder, ModuleBuilder};
+    use super::{DataflowSubContainer, HugrBuilder};
 
     pub(super) const NAT: SimpleType = SimpleType::Classic(ClassicType::i64());
     pub(super) const F64: SimpleType = SimpleType::Classic(ClassicType::F64);
     pub(super) const BIT: SimpleType = SimpleType::Classic(ClassicType::bit());
     pub(super) const QB: SimpleType = SimpleType::Linear(LinearType::Qubit);
 
     /// Wire up inputs of a Dataflow container to the outputs.
-    pub(super) fn n_identity<T: Dataflow>(
+    pub(super) fn n_identity<T: DataflowSubContainer>(
         dataflow_builder: T,
     ) -> Result<T::ContainerHandle, BuildError> {
         let w = dataflow_builder.input_wires();
@@ -91,13 +112,12 @@ mod test {
 
     pub(super) fn build_main(
         signature: Signature,
-        f: impl FnOnce(FunctionBuilder<true>) -> Result<BuildHandle<FuncID<true>>, BuildError>,
+        f: impl FnOnce(FunctionBuilder<&mut HugrMut>) -> Result<BuildHandle<FuncID<true>>, BuildError>,
     ) -> Result<Hugr, BuildError> {
         let mut module_builder = ModuleBuilder::new();
         let f_builder = module_builder.declare_and_def("main", signature)?;
 
         f(f_builder)?;
-
-        module_builder.finish()
+        Ok(module_builder.finish_hugr()?)
     }
 }