refactor: add HugrView::scheduling_graph, deprecate region_portgraph

hugr-core/src/hugr/internal.rs

@@ -43,6 +43,7 @@ pub trait HugrInternals {
     // needed if we want to use petgraph's algorithms on the region graph).
     // This won't be solvable until we do the big petgraph refactor -.-
     // In the meantime, just wrap the portgraph in a `FlatRegion` as needed.
+    #[deprecated(note = "Use scheduling_graph instead", since = "0.27.0")]
     fn region_portgraph(
         &self,
         parent: Self::Node,
@@ -396,6 +397,7 @@ impl Hugr {
     /// Consumes the HUGR and return a flat portgraph view of the region rooted
     /// at `parent`.
     #[inline]
+    #[deprecated(note = "Use scheduling_graph instead", since = "0.27.0")]
     pub fn into_region_portgraph(
         self,
         parent: Node,

hugr-core/src/hugr/validate.rs

@@ -128,10 +128,10 @@ impl<'a, H: HugrView> ValidationContext<'a, H> {
         &self,
         parent: H::Node,
     ) -> (Dominators<portgraph::NodeIndex>, H::RegionPortgraphNodes) {
-        let (region, node_map) = self.hugr.region_portgraph(parent);
+        let sg = self.hugr.scheduling_graph(parent);
         let entry_node = self.hugr.children(parent).next().unwrap();
-        let doms = dominators::simple_fast(&region, node_map.to_portgraph(entry_node));
-        (doms, node_map)
+        let doms = dominators::simple_fast(sg.petgraph(), sg.node_to_pg(entry_node));
+        (doms, sg.into_node_map())
     }
 
     /// Check the constraints on a single node.
@@ -422,11 +422,11 @@ impl<'a, H: HugrView> ValidationContext<'a, H> {
             return Ok(());
         }
 
-        let (region, node_map) = self.hugr.region_portgraph(parent);
-        let postorder = Topo::new(&region);
+        let sg = self.hugr.scheduling_graph(parent);
+        let postorder = Topo::new(sg.petgraph());
         let nodes_visited = postorder
-            .iter(&region)
-            .filter(|n| *n != node_map.to_portgraph(parent))
+            .iter(sg.petgraph())
+            .filter(|n| *n != sg.node_to_pg(parent))
             .count();
         let node_count = self.hugr.children(parent).count();
         if nodes_visited != node_count {

hugr-core/src/hugr/views.rs

@@ -7,10 +7,12 @@ pub mod render;
 mod rerooted;
 mod root_checked;
 pub mod sibling_subgraph;
+mod syn_edge;
 
 #[cfg(test)]
 mod tests;
 
+use ::petgraph::visit as pv;
 use serde::de::Deserialize;
 use std::borrow::Cow;
 use std::collections::HashMap;
@@ -24,23 +26,22 @@ pub use rerooted::Rerooted;
 pub use root_checked::{InvalidSignature, RootChecked, check_tag};
 pub use sibling_subgraph::SiblingSubgraph;
 
-use itertools::Itertools;
+use itertools::{Either, Itertools};
 use portgraph::render::{DotFormat, MermaidFormat};
 use portgraph::{LinkView, PortView};
 
-use super::internal::{HugrInternals, HugrMutInternals};
-use super::validate::ValidationContext;
-use super::{Hugr, HugrMut, Node, ValidationError};
 use crate::core::HugrNode;
 use crate::extension::ExtensionRegistry;
+use crate::hugr::internal::PortgraphNodeMap;
+use crate::hugr::views::syn_edge::SynEdgeWrapper;
 use crate::metadata::{Metadata, RawMetadataValue};
-use crate::ops::handle::NodeHandle;
-use crate::ops::{OpParent, OpTag, OpTrait, OpType};
-
+use crate::ops::{OpParent, OpTag, OpTrait, OpType, handle::NodeHandle};
 use crate::types::{EdgeKind, PolyFuncType, Signature, Type};
 use crate::{Direction, IncomingPort, OutgoingPort, Port};
 
-use itertools::Either;
+use super::internal::{HugrInternals, HugrMutInternals};
+use super::validate::ValidationContext;
+use super::{Hugr, HugrMut, Node, ValidationError};
 
 /// A trait for inspecting HUGRs.
 /// For end users we intend this to be superseded by region-specific APIs.
@@ -391,10 +392,7 @@ pub trait HugrView: HugrInternals {
 
     /// Return a wrapper over the view that can be used in petgraph algorithms.
     #[inline]
-    #[deprecated(
-        since = "0.26.0",
-        note = "Use hugr_core::internal::HugrInternals::region_portgraph instead."
-    )]
+    #[deprecated(since = "0.26.0", note = "Use HugrView::scheduling_graph instead.")]
     #[expect(deprecated)] // Remove at same time as PetgraphWrapper
     fn as_petgraph(&self) -> PetgraphWrapper<'_, Self>
     where
@@ -403,6 +401,22 @@ pub trait HugrView: HugrInternals {
         PetgraphWrapper { hugr: self }
     }
 
+    /// A view of a flat region, including ordering constraints from nonlocal edges,
+    /// suitable for use with petgraph algorithms.
+    fn scheduling_graph(&self, parent: Self::Node) -> SchedulingGraph<'_, Self> {
+        #[expect(deprecated)] // Inline region_portgraph here when removing
+        let (region_view, region_nodes) = self.region_portgraph(parent);
+        let graph = SynEdgeWrapper {
+            region_view,
+            syn_edges: Vec::new(),
+        };
+        SchedulingGraph {
+            graph,
+            node_map: region_nodes,
+            region_parent: parent,
+        }
+    }
+
     /// Return the mermaid representation of the underlying hierarchical graph.
     ///
     /// The hierarchy is represented using subgraphs. Edges are labelled with
@@ -552,6 +566,71 @@ impl<S: HugrNode> ExtractionResult<S> for HashMap<S, Node> {
     }
 }
 
+/// A graph of a flat region of a Hugr, including ordering constraints from nonlocal edges
+pub struct SchedulingGraph<'a, V: HugrView + ?Sized + 'a> {
+    graph: SynEdgeWrapper<portgraph::view::FlatRegion<'a, V::RegionPortgraph<'a>>>,
+    node_map: V::RegionPortgraphNodes,
+    region_parent: V::Node,
+}
+
+impl<'a, V: HugrView + 'a> SchedulingGraph<'a, V> {
+    /// Get the parent node of the region represented by this scheduling graph
+    pub fn region_parent(&self) -> V::Node {
+        self.region_parent
+    }
+
+    /// Converts a `V::Node` index in the original Hugr into
+    /// an index in [Self::petgraph]
+    ///
+    /// # Panics
+    ///
+    /// If `n` is not a child of [Self::region_parent]
+    pub fn node_to_pg(&self, n: V::Node) -> portgraph::NodeIndex {
+        self.node_map.to_portgraph(n)
+    }
+
+    /// Converts the index of a node in [Self::petgraph] to the corresponding
+    /// `V::Node` of the original Hugr.
+    ///
+    /// # Panics
+    ///
+    /// If `n` is not a node in `Self::petgraph`
+    pub fn pg_to_node(&self, n: portgraph::NodeIndex) -> V::Node {
+        self.node_map.from_portgraph(n)
+    }
+
+    /// Extracts the map between `V::Node` and the [NodeIndex] used in [Self::petgraph],
+    /// discarding the rest of `self`.
+    ///
+    /// [NodeIndex]: portgraph::NodeIndex
+    pub fn into_node_map(self) -> V::RegionPortgraphNodes {
+        self.node_map
+    }
+
+    fn portgraph_no_syn_edges(
+        self,
+    ) -> (
+        portgraph::view::FlatRegion<'a, V::RegionPortgraph<'a>>,
+        V::RegionPortgraphNodes,
+    ) {
+        // This may need to change when the SynEdgeWrapper actually has edges in it...
+        // or maybe we should keep the assert to prevent this being used any time it does.
+        assert!(self.graph.syn_edges.is_empty());
+        (self.graph.region_view, self.node_map)
+    }
+
+    /// Access to the graph, sufficient to allow [pv::Topo]
+    pub fn petgraph(
+        &self,
+    ) -> impl pv::NodeCount
+    + pv::IntoNodeIdentifiers
+    + pv::IntoEdgeReferences
+    + pv::IntoNeighborsDirected
+    + pv::Visitable<NodeId = portgraph::NodeIndex> {
+        &self.graph
+    }
+}
+
 impl HugrView for Hugr {
     #[inline]
     fn entrypoint(&self) -> Self::Node {

hugr-core/src/hugr/views/impls.rs

@@ -11,6 +11,7 @@ macro_rules! hugr_internal_methods {
     ($arg:ident, $e:expr) => {
         delegate::delegate! {
             to ({let $arg=self; $e}) {
+                #[expect(deprecated)] // Remove delegate along with region_portgraph
                 fn region_portgraph(&self, parent: Self::Node) -> (portgraph::view::FlatRegion<'_, Self::RegionPortgraph<'_>>, Self::RegionPortgraphNodes);
                 fn node_metadata_map(&self, node: Self::Node) -> &crate::hugr::NodeMetadataMap;
             }