feat!: Add Hugr entrypoints (#2147)

Adds the concept of "entrypoint" to the HUGRs, detaching the "main node
of interest" from the hierarchy root.

Now hugrs will **always** have a `Module` at their root (appropriately
called `HugrView::module_root`), and any manipulation is mostly focused
around the entrypoint instead.

Closes #2029 
Closes #2010

before:
```mermaid
graph LR

subgraph 0 ["(0) DFG"]

direction LR

1["(1) Input"]

2["(2) Output"]

3["(3) test.quantum.CX"]

4["(4) test.quantum.CX"]

1--"0:0<br>qubit"-->3

1--"1:1<br>qubit"-->3

3--"0:1<br>qubit"-->4

3--"1:0<br>qubit"-->4

3-."2:2".->4

4--"0:0<br>qubit"-->2

4--"1:1<br>qubit"-->2

end
```
after:
```mermaid
graph LR

subgraph 0 ["(0) Module"]

direction LR

subgraph 1 ["(1) FuncDefn: #quot;main#quot;"]

direction LR

2["(2) Input"]

3["(3) Output"]

subgraph 4 ["(4) [**DFG**]"]

direction LR

style 4 stroke:#832561,stroke-width:3px

5["(5) Input"]

6["(6) Output"]

7["(7) test.quantum.CX"]

8["(8) test.quantum.CX"]

5--"0:0<br>qubit"-->7

5--"1:1<br>qubit"-->7

7--"0:1<br>qubit"-->8

7--"1:0<br>qubit"-->8

7-."2:2".->8

8--"0:0<br>qubit"-->6

8--"1:1<br>qubit"-->6

end

2--"0:0<br>qubit"-->4

2--"1:1<br>qubit"-->4

4--"0:0<br>qubit"-->3

4--"1:1<br>qubit"-->3

end

end
```

# How does this affect...

### ...HugrView?

`::root` has been split into `module_root` and `entrypoint`. In general,
you'll want to use the latter (as described in the docs).
`nodes()` is still defined, but now there's also `descendants(node)` and
`entry_descendants()`, which should be preferred.
### ...builders?

The change should be transparent for hugr building operations. When you
start an specific builder or call `Hugr::new(op)` we add additional
nodes as necessary so that the new entrypoint is correctly defined
inside a module;
- If `op` is a module, we just leave it at the top.
- If `op` can be defined in a module, we put it below the root.
- If `op` is a dataflow operation, we define a "main" function with the
same signature and put it there.
- More exotic operations are not allowed, you'll need to build the
container yourself and change the entrypoint afterwards.

### ...SiblingGraph, SiblingMut, and DescendantsGraph?

The structs are no more. Instead, `HugrView` has two new methods:
- `with_entrypoint(&self, Node) -> Rerooted<&Self>`
- `with_entrypoint_mut(&mut self, Node) -> Rerooted<&mut Self>`
The new wrapper implements `HugrMut`, so it can be used transparently.

The main benefit of this is that `Rerooted` still contains all the nodes
that are not descendants from the entrypoint. So external edges are
still well-defined, and rewrite operations may still put look at the
root module and define things there if needed.

### ...serialization?

The hugr json now has an `entrypoint` field. If missing, we assume it's
the root.
For backwards compatibility, if the serialized root is not a module we
will transparently wrap it as described before so older jsons will
continue working without modifications.

hugr-module encoding is left as a TODO 
### ...packages and envelopes?

Now every HUGR can be put in a package without modifications!
Ideally we'll now be able to remove the hugr <-> json methods and only
use envelopes. (That's a TODO).
### ...mermaid/dot renders?

The entrypoint node is now highlighted in purple, and its title shown in
bold between brackets. See the example above.
### ...passes?

Things should work as normal. New passes should look at the entrypoint
and its descendants when looking for things to rewrite, instead of the
whole hugr.

# TODOs not in this PR:

- [ ] Python support. #2148
- [ ] `hugr-module` support #2156
- [ ] Deprecate/remove hugr json methods, always use envelopes instead.
#2159
- [ ] Update the spec.

BREAKING CHANGE: `Hugr`s now have an entrypoint node.
BREAKING CHANGE: Removed `SiblingGraph` / `SiblingMut` /
`DescendantsGraph`

---------

Co-authored-by: Seyon Sivarajah <[email protected]>

Author: aborgna-q

Cargo.lock

@@ -48,7 +48,7 @@ fn test_package(#[default(bool_t())] id_type: Type) -> Package {
     df.finish_with_outputs([i]).unwrap();
     let hugr = module.hugr().clone(); // unvalidated
 
-    Package::new(vec![hugr]).unwrap()
+    Package::new(vec![hugr])
 }
 
 #[fixture]
@@ -121,7 +121,7 @@ fn test_mermaid_invalid(bad_hugr_string: String, mut cmd: Command) {
     cmd.write_stdin(bad_hugr_string);
     cmd.assert()
         .failure()
-        .stderr(contains("has an unconnected port"));
+        .stderr(contains("Error loading hugr"));
 }
 
 #[rstest]
@@ -133,7 +133,7 @@ fn test_bad_hugr(bad_hugr_string: String, mut val_cmd: Command) {
     val_cmd
         .assert()
         .failure()
-        .stderr(contains("Node(1)").and(contains("unconnected port")));
+        .stderr(contains("Error loading hugr"));
 }
 
 #[rstest]

hugr-cli/tests/validate.rs

@@ -31,7 +31,12 @@ hugr-model = { version = "0.19.1", path = "../hugr-model" }
 
 cgmath = { workspace = true, features = ["serde"] }
 delegate = { workspace = true }
-derive_more = { workspace = true, features = ["display", "error", "from"] }
+derive_more = { workspace = true, features = [
+    "display",
+    "error",
+    "from",
+    "into",
+] }
 downcast-rs = { workspace = true }
 enum_dispatch = { workspace = true }
 fxhash.workspace = true

hugr-core/Cargo.toml

@@ -151,6 +151,10 @@ pub enum BuildError {
     /// CFG can only have one entry.
     #[error("CFG entry node already built for CFG node: {0}.")]
     EntryBuiltError(Node),
+    /// We don't allow creating `BasicBlockBuilder<Hugr>`s when the sum-rows
+    /// are not homogeneous. Use a CFGBuilder and create a valid graph instead.
+    #[error("Cannot initialize hugr for a BasicBlockBuilder with complex sum-rows. Use a CFGBuilder instead.")]
+    BasicBlockTooComplex,
     /// Node was expected to have a certain type but was found to not.
     #[error("Node with index {node} does not have type {op_desc} as expected.")]
     #[allow(missing_docs)]
@@ -164,6 +168,13 @@ pub enum BuildError {
     #[error("Error building Conditional node: {0}.")]
     ConditionalError(#[from] conditional::ConditionalBuildError),
 
+    /// Node not found in Hugr
+    #[error("{node} not found in the Hugr")]
+    NodeNotFound {
+        /// Missing node
+        node: Node,
+    },
+
     /// Wire not found in Hugr
     #[error("Wire not found in Hugr: {0}.")]
     WireNotFound(Wire),
@@ -303,31 +314,32 @@ pub(crate) mod test {
     #[fixture]
     pub(crate) fn simple_package() -> Package {
         let hugr = simple_module_hugr();
-        Package::new([hugr]).unwrap()
+        Package::new([hugr])
     }
 
     #[fixture]
     pub(crate) fn multi_module_package() -> Package {
         let hugr0 = simple_module_hugr();
         let hugr1 = simple_module_hugr();
-        Package::new([hugr0, hugr1]).unwrap()
+        Package::new([hugr0, hugr1])
     }
 
     /// A helper method which creates a DFG rooted hugr with Input and Output node
     /// only (no wires), given a function type with extension delta.
     // TODO consider taking two type rows and using TO_BE_INFERRED
     pub(crate) fn closed_dfg_root_hugr(signature: Signature) -> Hugr {
-        let mut hugr = Hugr::new(ops::DFG {
+        let mut hugr = Hugr::new_with_entrypoint(ops::DFG {
             signature: signature.clone(),
-        });
+        })
+        .unwrap();
         hugr.add_node_with_parent(
-            hugr.root(),
+            hugr.entrypoint(),
             ops::Input {
                 types: signature.input,
             },
         );
         hugr.add_node_with_parent(
-            hugr.root(),
+            hugr.entrypoint(),
             ops::Output {
                 types: signature.output,
             },

hugr-core/src/builder.rs

@@ -94,7 +94,7 @@ pub trait Container {
         name: impl Into<String>,
         signature: impl Into<PolyFuncType>,
     ) -> Result<FunctionBuilder<&mut Hugr>, BuildError> {
-        let signature = signature.into();
+        let signature: PolyFuncType = signature.into();
         let body = signature.body().clone();
         let f_node = self.add_child_node(ops::FuncDefn {
             name: name.into(),
@@ -228,9 +228,9 @@ pub trait Dataflow: Container {
         hugr: Hugr,
         input_wires: impl IntoIterator<Item = Wire>,
     ) -> Result<BuildHandle<DataflowOpID>, BuildError> {
-        let optype = hugr.get_optype(hugr.root()).clone();
+        let optype = hugr.get_optype(hugr.entrypoint()).clone();
         let num_outputs = optype.value_output_count();
-        let node = self.add_hugr(hugr).new_root;
+        let node = self.add_hugr(hugr).inserted_entrypoint;
 
         wire_up_inputs(input_wires, node, self)
             .map_err(|error| BuildError::OperationWiring { op: optype, error })?;
@@ -250,8 +250,8 @@ pub trait Dataflow: Container {
         hugr: &impl HugrView,
         input_wires: impl IntoIterator<Item = Wire>,
     ) -> Result<BuildHandle<DataflowOpID>, BuildError> {
-        let node = self.add_hugr_view(hugr).new_root;
-        let optype = hugr.get_optype(hugr.root()).clone();
+        let node = self.add_hugr_view(hugr).inserted_entrypoint;
+        let optype = hugr.get_optype(hugr.entrypoint()).clone();
         let num_outputs = optype.value_output_count();
 
         wire_up_inputs(input_wires, node, self)
@@ -284,6 +284,7 @@ pub trait Dataflow: Container {
     /// # Panics
     ///
     /// Panics if the number of input Wires does not match the size of the array.
+    #[track_caller]
     fn input_wires_arr<const N: usize>(&self) -> [Wire; N] {
         collect_array(self.input_wires())
     }
@@ -676,7 +677,7 @@ fn add_node_with_wires<T: Dataflow + ?Sized>(
     nodetype: impl Into<OpType>,
     inputs: impl IntoIterator<Item = Wire>,
 ) -> Result<(Node, usize), BuildError> {
-    let op = nodetype.into();
+    let op: OpType = nodetype.into();
     let num_outputs = op.value_output_count();
     let op_node = data_builder.add_child_node(op.clone());
 

hugr-core/src/builder/build_traits.rs

@@ -148,8 +148,8 @@ impl CFGBuilder<Hugr> {
             signature: signature.clone(),
         };
 
-        let base = Hugr::new(cfg_op);
-        let cfg_node = base.root();
+        let base = Hugr::new_with_entrypoint(cfg_op).expect("CFG entrypoints be valid");
+        let cfg_node = base.entrypoint();
         CFGBuilder::create(base, cfg_node, signature.input, signature.output)
     }
 }
@@ -224,7 +224,7 @@ impl<B: AsMut<Hugr> + AsRef<Hugr>> CFGBuilder<B> {
             self.hugr_mut().add_node_with_parent(parent, op)
         };
 
-        BlockBuilder::create(self.hugr_mut(), block_n)
+        BlockBuilder::create_with_io(self.hugr_mut(), block_n)
     }
 
     /// Return a builder for a non-entry [`DataflowBlock`] child graph with
@@ -314,7 +314,29 @@ impl<B: AsMut<Hugr> + AsRef<Hugr>> BlockBuilder<B> {
     ) -> Result<(), BuildError> {
         Dataflow::set_outputs(self, [branch_wire].into_iter().chain(outputs))
     }
+
+    /// Create a new BlockBuilder.
+    ///
+    /// See [`BlockBuilder::create_with_io`] if you need to initialize the input
+    /// and output nodes.
+    ///
+    /// # Parameters
+    /// - `base`: The base HUGR to build on.
+    /// - `block_n`: The block we are building.
     fn create(base: B, block_n: Node) -> Result<Self, BuildError> {
+        let db = DFGBuilder::create(base, block_n)?;
+        Ok(BlockBuilder::from_dfg_builder(db))
+    }
+
+    /// Create a new BlockBuilder, initializing the input and output nodes.
+    ///
+    /// See [`BlockBuilder::create`] if you don't need to initialize the input
+    /// and output nodes.
+    ///
+    /// # Parameters
+    /// - `base`: The base HUGR to build on.
+    /// - `block_n`: The block we are building.
+    fn create_with_io(base: B, block_n: Node) -> Result<Self, BuildError> {
         let block_op = base
             .as_ref()
             .get_optype(block_n)
@@ -348,15 +370,28 @@ impl BlockBuilder<Hugr> {
     ) -> Result<Self, BuildError> {
         let inputs = inputs.into();
         let sum_rows: Vec<_> = sum_rows.into_iter().collect();
-        let other_outputs = other_outputs.into();
-        let op = DataflowBlock {
-            inputs: inputs.clone(),
-            other_outputs: other_outputs.clone(),
-            sum_rows,
-        };
-
-        let base = Hugr::new(op);
-        let root = base.root();
+        let other_outputs: TypeRow = other_outputs.into();
+        let num_out_branches = sum_rows.len();
+
+        // We only support blocks where all the possible `sum_rows` branches have the same types,
+        // as that lets us branch it directly to an exit node.
+        if let Some(row) = sum_rows.first() {
+            if sum_rows.iter().skip(1).any(|r2| row != r2) {
+                return Err(BuildError::BasicBlockTooComplex);
+            }
+        }
+        let cfg_outputs = sum_rows.first().cloned().unwrap_or_default();
+        let cfg_outputs = cfg_outputs.extend(other_outputs.as_slice());
+
+        let mut cfg = CFGBuilder::new(Signature::new(inputs, cfg_outputs))?;
+        let block = cfg.entry_builder(sum_rows, other_outputs)?;
+        let block = block.finish_sub_container()?;
+        for i in 0..num_out_branches {
+            cfg.branch(&block, i, &cfg.exit_block())?;
+        }
+        let mut base = std::mem::take(cfg.hugr_mut());
+        let root = block.node();
+        base.set_entrypoint(root);
         Self::create(base, root)
     }
 
@@ -375,7 +410,7 @@ impl BlockBuilder<Hugr> {
 pub(crate) mod test {
     use crate::builder::{DataflowSubContainer, ModuleBuilder};
 
-    use crate::extension::prelude::usize_t;
+    use crate::extension::prelude::{bool_t, usize_t};
     use crate::hugr::validate::InterGraphEdgeError;
     use crate::hugr::ValidationError;
     use crate::type_row;
@@ -417,6 +452,29 @@ pub(crate) mod test {
         Ok(())
     }
 
+    #[test]
+    fn basic_cfg_block() -> Result<(), BuildError> {
+        assert_eq!(
+            BlockBuilder::new(
+                vec![],
+                [vec![usize_t()].into(), vec![bool_t()].into()],
+                vec![]
+            ),
+            Err(BuildError::BasicBlockTooComplex)
+        );
+
+        let sum_rows: Vec<TypeRow> = vec![vec![usize_t()].into(), vec![usize_t()].into()];
+        let mut block_builder =
+            BlockBuilder::new(vec![usize_t()], sum_rows.clone(), vec![usize_t()])?;
+        let [inp] = block_builder.input_wires_arr();
+        let branch = block_builder.make_sum(0, sum_rows, [inp])?;
+        let hugr = block_builder.finish_hugr_with_outputs(branch, [inp])?;
+
+        hugr.validate().unwrap();
+
+        Ok(())
+    }
+
     pub(crate) fn build_basic_cfg<T: AsMut<Hugr> + AsRef<Hugr>>(
         cfg_builder: &mut CFGBuilder<T>,
     ) -> Result<(), BuildError> {

hugr-core/src/builder/cfg.rs

@@ -1,8 +1,8 @@
 use crate::hugr::views::HugrView;
 use crate::types::{Signature, TypeRow};
 
-use crate::ops;
-use crate::ops::handle::CaseID;
+use crate::ops::handle::{CaseID, NodeHandle};
+use crate::ops::{self};
 
 use super::build_traits::SubContainer;
 use super::handle::BuildHandle;
@@ -153,7 +153,7 @@ impl ConditionalBuilder<Hugr> {
     ) -> Result<Self, BuildError> {
         let sum_rows: Vec<_> = sum_rows.into_iter().collect();
         let other_inputs = other_inputs.into();
-        let outputs = outputs.into();
+        let outputs: TypeRow = outputs.into();
 
         let n_out_wires = outputs.len();
         let n_cases = sum_rows.len();
@@ -163,8 +163,8 @@ impl ConditionalBuilder<Hugr> {
             other_inputs,
             outputs,
         };
-        let base = Hugr::new(op);
-        let conditional_node = base.root();
+        let base = Hugr::new_with_entrypoint(op).expect("Conditional entrypoint should be valid");
+        let conditional_node = base.entrypoint();
 
         Ok(ConditionalBuilder {
             base,
@@ -178,13 +178,15 @@ impl ConditionalBuilder<Hugr> {
 impl CaseBuilder<Hugr> {
     /// Initialize a Case rooted HUGR
     pub fn new(signature: Signature) -> Result<Self, BuildError> {
-        let op = ops::Case {
-            signature: signature.clone(),
-        };
-        let base = Hugr::new(op);
-        let root = base.root();
-        let dfg_builder = DFGBuilder::create_with_io(base, root, signature)?;
-
+        // Start by building a conditional with a single case
+        let mut conditional =
+            ConditionalBuilder::new([signature.input.clone()], vec![], signature.output.clone())?;
+        let case = conditional.case_builder(0)?.finish_sub_container()?.node();
+
+        // Extract the half-finished hugr, and wrap it in an owned case builder
+        let mut base = std::mem::take(conditional.hugr_mut());
+        base.set_entrypoint(case);
+        let dfg_builder = DFGBuilder::create(base, case)?;
         Ok(CaseBuilder::from_dfg_builder(dfg_builder))
     }
 }
@@ -203,6 +205,14 @@ mod test {
 
     use super::*;
 
+    #[test]
+    fn basic_conditional_case() -> Result<(), BuildError> {
+        let case_b = CaseBuilder::new(Signature::new_endo(vec![usize_t(), usize_t()]))?;
+        let [in0, in1] = case_b.input_wires_arr();
+        case_b.finish_with_outputs([in0, in1])?;
+        Ok(())
+    }
+
     #[test]
     fn basic_conditional() -> Result<(), BuildError> {
         let mut conditional_b =