feat: PersistentHugr Walker API (#2168)

Closes #2074
Closes #2190

Author: lmondada

hugr-core/Cargo.toml

@@ -26,6 +26,9 @@ bench = false
 [[test]]
 name = "model"
 
+[[test]]
+name = "persistent_walker_example"
+
 [dependencies]
 hugr-model = { version = "0.20.0", path = "../hugr-model" }
 

hugr-core/src/hugr/persistent.rs

@@ -65,6 +65,9 @@ mod parents_view;
 mod resolver;
 mod state_space;
 mod trait_impls;
+pub mod walker;
+
+pub use walker::{PinnedWire, Walker};
 
 use std::{
     collections::{BTreeSet, HashMap, VecDeque},
@@ -75,8 +78,8 @@ use delegate::delegate;
 use derive_more::derive::From;
 use itertools::{Either, Itertools};
 use relrc::RelRc;
-use state_space::{CommitData, CommitId};
-pub use state_space::{CommitStateSpace, InvalidCommit, PatchNode};
+use state_space::CommitData;
+pub use state_space::{CommitId, CommitStateSpace, InvalidCommit, PatchNode};
 
 pub use resolver::PointerEqResolver;
 
@@ -279,6 +282,14 @@ impl PersistentHugr {
         Self { state_space }
     }
 
+    /// Create a [`PersistentHugr`] from a single commit and its ancestors.
+    // This always defines a valid `PersistentHugr` as the ancestors of a commit
+    // are guaranteed to be compatible with each other.
+    pub fn from_commit(commit: Commit) -> Self {
+        let state_space = CommitStateSpace::try_from_commits([commit]).expect("commit is valid");
+        Self { state_space }
+    }
+
     /// Create a [`PersistentHugr`] from a list of commits.
     ///
     /// `Self` will correspond to the HUGR obtained by applying the patches of
@@ -557,7 +568,7 @@ impl PersistentHugr {
             // incoming ports are of interest to us if
             //  (i) they are connected to the output of a replacement (then there will be a
             //      linked port in a parent commit), or
-            //  (ii) they are deleted by a child commit and is not the same as the out_node
+            //  (ii) they are deleted by a child commit and are not equal to the out_node
             //      (then there will be a linked port in a child commit)
             let is_linked_to_output = curr_repl_out.is_some_and(|curr_repl_out| {
                 hugr.linked_inputs(out_node.1, out_port)

hugr-core/src/hugr/persistent/state_space.rs

@@ -17,7 +17,7 @@ use crate::{
 };
 
 /// A copyable handle to a [`Commit`] vertex within a [`CommitStateSpace`]
-pub(super) type CommitId = relrc::NodeId;
+pub type CommitId = relrc::NodeId;
 
 /// A HUGR node within a commit of the commit state space
 #[derive(Copy, Clone, Ord, PartialOrd, Eq, PartialEq, Debug, Hash)]
@@ -155,14 +155,20 @@ impl CommitStateSpace {
     /// All commits in the resulting `PersistentHugr` are guaranteed to be
     /// compatible. If the selected commits would include two commits which
     /// are incompatible, a [`InvalidCommit::IncompatibleHistory`] error is
-    /// returned.
+    /// returned. If `commits` is empty, a [`InvalidCommit::NonUniqueBase`]
+    /// error is returned.
     pub fn try_extract_hugr(
         &self,
         commits: impl IntoIterator<Item = CommitId>,
     ) -> Result<PersistentHugr, InvalidCommit> {
         // Define commits as the set of all ancestors of the given commits
         let all_commit_ids = get_all_ancestors(&self.graph, commits);
 
+        if all_commit_ids.is_empty() {
+            return Err(InvalidCommit::NonUniqueBase(0));
+        }
+        debug_assert!(all_commit_ids.contains(&self.base()));
+
         // Check that all commits are compatible
         for &commit_id in &all_commit_ids {
             let selected_children = self
@@ -224,7 +230,7 @@ impl CommitStateSpace {
     }
 
     /// Get the set of nodes invalidated by `commit_id` in `parent`.
-    pub(super) fn invalidation_set(
+    pub fn invalidation_set(
         &self,
         commit_id: CommitId,
         parent: CommitId,

hugr-core/src/hugr/persistent/tests.rs

@@ -144,6 +144,68 @@ fn create_not_and_to_xor_replacement(hugr: &Hugr) -> SimpleReplacement {
     SimpleReplacement::try_new(subgraph, hugr, replacement_hugr).unwrap()
 }
 
+/// Creates a state space with 4 commits on top of the base hugr `simple_hugr`:
+///
+/// ```
+///    ┌─────────┐
+/// ───┤ (0) NOT ├─┐    ┌─────────┐
+///    └─────────┘ └────┤         │
+///    ┌─────────┐      │ (2) AND ├───
+/// ───┤ (1) NOT ├──────┤         │
+///    └─────────┘      └─────────┘
+/// ```
+///
+/// Note that for the sake of these tests, we do not care about the semantics of
+/// the rewrites. Unlike real-world use cases, the LHS and RHS here are not
+/// functionally equivalent.
+/// The state space will contain the following commits:
+///
+/// ```
+/// [commit1]
+///    ┌─────────┐                ┌─────────┐     ┌─────────┐
+/// ───┤ (0) NOT ├───    -->   ───┤ (3) NOT ├─────┤ (4) NOT ├──────
+///    └─────────┘                └─────────┘     └─────────┘
+///
+/// [commit2]
+///    ┌─────────┐
+/// ───┤ (4) NOT ├─┐    ┌─────────┐                  ┌─────────┐
+///    └─────────┘ └────┤         │             ─────┤         │
+///                     │ (2) AND ├───    -->        │ (5) XOR ├───
+/// ────────────────────┤         │             ─────┤         │
+///                     └─────────┘                  └─────────┘
+///
+/// [commit3]
+///    ┌─────────┐
+/// ───┤ (0) NOT ├─┐    ┌─────────┐                  ┌─────────┐
+///    └─────────┘ └────┤         │             ─────┤         │
+///                     │ (2) AND ├───    -->        │ (6) XOR ├───
+/// ────────────────────┤         │             ─────┤         │
+///                     └─────────┘                  └─────────┘
+///
+/// [commit4]
+///    ┌─────────┐                ┌─────────┐     ┌─────────┐
+/// ───┤ (1) NOT ├───    -->   ───┤ (7) NOT ├─────┤ (8) NOT ├──────
+///    └─────────┘                └─────────┘     └─────────┘
+/// ```
+///
+/// Viewed as a history of commits, the commits' hierarchy is as follows
+///
+/// ```
+///                                 base
+///                               /   |   \
+///                              /    |    \
+///                             /     |     \
+///                            /      |      \
+///                        commit1 commit3 commit4
+///                           |
+///                           |
+///                           |
+///                        commit2
+/// ```
+/// where
+/// - `commit1` and `commit2` are incompatible with `commit3`
+/// - `commit1` and `commit2` are disjoint with `commit4` (i.e. compatible),
+/// - `commit2` depends on `commit1`
 #[fixture]
 pub(super) fn test_state_space() -> (CommitStateSpace, [CommitId; 4]) {
     let (base_hugr, [not0_node, not1_node, _and_node]) = simple_hugr();