Struct SiblingSubgraph

pub struct SiblingSubgraph { /* private fields */ }

A non-empty convex subgraph of a HUGR sibling graph.

A HUGR region in which all nodes share the same parent. Unlike super::SiblingGraph, not all nodes of the sibling graph must be included. A convex subgraph is always an induced subgraph, i.e. it is defined by a set of nodes and all edges between them.

The incoming boundary (resp. outgoing boundary) is given by the input (resp. output) ports of the subgraph that are linked to nodes outside of the subgraph. The signature of the subgraph is then given by the types of the incoming and outgoing boundary ports. Given a replacement with the same signature, a SimpleReplacement can be constructed to rewrite the subgraph with the replacement.

The ordering of the nodes in the subgraph is irrelevant to define the convex subgraph, but it determines the ordering of the boundary signature.

No reference to the underlying graph is kept. Thus most of the subgraph methods expect a reference to the Hugr as an argument.

At the moment we do not support state order edges at the subgraph boundary. The boundary_port and signature methods will panic if any are found. State order edges are also unsupported in replacements in create_simple_replacement.

Implementations

impl SiblingSubgraph

pub fn try_new_dataflow_subgraph<H, Root>( dfg_graph: &H, ) -> Result<Self, InvalidSubgraph>

where H: Clone + RootTagged<RootHandle = Root>, Root: ContainerHandle<ChildrenHandle = DataflowOpID>,

A sibling subgraph from a crate::ops::OpTag::DataflowParent-rooted HUGR.

The subgraph is given by the nodes between the input and output children nodes of the root node. If you wish to create a subgraph from another root, wrap the region argument in a super::SiblingGraph.

Wires connecting the input and output nodes are ignored. Note that due to this the resulting subgraph’s signature may not match the signature of the dataflow parent.

This will return an InvalidSubgraph::EmptySubgraph error if the subgraph is empty.

pub fn try_new( incoming: IncomingPorts, outgoing: OutgoingPorts, hugr: &impl HugrView, ) -> Result<Self, InvalidSubgraph>

Create a new convex sibling subgraph from input and output boundaries.

Any sibling subgraph can be defined using two sets of boundary edges $B_I$ and $B_O$, the incoming and outgoing boundary edges respectively. Intuitively, the sibling subgraph is all the edges and nodes “between” an edge of $B_I$ and an edge of $B_O$.

Definition

More formally, the sibling subgraph of a graph $G = (V, E)$ given by sets of incoming and outgoing boundary edges $B_I, B_O \subseteq E$ is the graph given by the connected components of the graph $G’ = (V, E \ B_I \ B_O)$ that contain at least one node that is either

• the target of an incoming boundary edge, or
• the source of an outgoing boundary edge.

A subgraph is well-formed if for every edge in the HUGR

• it is in $B_I$ if and only if it has a source outside of the subgraph and a target inside of it, and
• it is in $B_O$ if and only if it has a source inside of the subgraph and a target outside of it.

Arguments

The incoming and outgoing arguments give $B_I$ and $B_O$ respectively. Incoming edges must be given by incoming ports and outgoing edges by outgoing ports. The ordering of the incoming and outgoing ports defines the signature of the subgraph.

Incoming boundary ports must be unique and partitioned by input parameter: two ports within the same set of the partition must be copyable and will result in the input being copied. Outgoing boundary ports are given in a list and can appear multiple times if they are copyable, in which case the output will be copied.

Errors

This function fails if the subgraph is not convex, if the nodes do not share a common parent or if the subgraph is empty.

pub fn try_new_with_checker( inputs: IncomingPorts, outputs: OutgoingPorts, hugr: &impl HugrView, checker: &impl ConvexChecker, ) -> Result<Self, InvalidSubgraph>

Create a new convex sibling subgraph from input and output boundaries.

Provide a ConvexChecker instance to avoid constructing one for faster convexity check. If you do not have one, use SiblingSubgraph::try_new.

Refer to SiblingSubgraph::try_new for the full documentation.

pub fn try_from_nodes( nodes: impl Into<Vec<Node>>, hugr: &impl HugrView, ) -> Result<Self, InvalidSubgraph>

Create a subgraph from a set of nodes.

The incoming boundary is given by the set of edges with a source not in nodes and a target in nodes. Conversely, the outgoing boundary is given by the set of edges with a source in nodes and a target not in nodes.

The subgraph signature will be given by the types of the incoming and outgoing edges ordered by the node order in nodes and within each node by the port order. The in- and out-arity of the signature will match the number of incoming and outgoing edges respectively. In particular, the assumption is made that no two incoming edges have the same source (no copy nodes at the input boundary).

pub fn try_from_nodes_with_checker<'c, 'h: 'c, H: HugrView>( nodes: impl Into<Vec<Node>>, hugr: &'h H, checker: &impl ConvexChecker, ) -> Result<Self, InvalidSubgraph>

Create a subgraph from a set of nodes.

Provide a ConvexChecker instance to avoid constructing one for faster convexity check. If you do not have one, use SiblingSubgraph::try_from_nodes.

Refer to SiblingSubgraph::try_from_nodes for the full documentation.

pub fn nodes(&self) -> &[Node]

An iterator over the nodes in the subgraph.

pub fn node_count(&self) -> usize

The number of nodes in the subgraph.

pub fn incoming_ports(&self) -> &IncomingPorts

Returns the computed IncomingPorts of the subgraph.

pub fn outgoing_ports(&self) -> &OutgoingPorts

Returns the computed OutgoingPorts of the subgraph.

pub fn signature(&self, hugr: &impl HugrView) -> Signature

The signature of the subgraph.

pub fn get_parent(&self, hugr: &impl HugrView) -> Node

The parent of the sibling subgraph.

pub fn create_simple_replacement( &self, hugr: &impl HugrView, replacement: Hugr, ) -> Result<SimpleReplacement, InvalidReplacement>

Construct a SimpleReplacement to replace self with replacement.

replacement must be a hugr with DFG root and its signature must match the signature of the subgraph.

May return one of the following five errors

• InvalidReplacement::InvalidDataflowGraph: the replacement graph is not a crate::ops::OpTag::DataflowParent-rooted graph,
• InvalidReplacement::InvalidSignature: the signature of the replacement DFG does not match the subgraph signature, or
• InvalidReplacement::NonConvexSubgraph: the sibling subgraph is not convex.

At the moment we do not support state order edges. If any are found in the replacement graph, this will panic.

pub fn extract_subgraph( &self, hugr: &impl HugrView, name: impl Into<String>, ) -> Hugr

Create a new Hugr containing only the subgraph.

The new Hugr will contain a FuncDefn root with the same signature as the subgraph and the specified name

Trait Implementations

impl Clone for SiblingSubgraph

fn clone(&self) -> SiblingSubgraph

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SiblingSubgraph

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.