Struct SiblingSubgraph

pub struct SiblingSubgraph<N = Node> { /* private fields */ }

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

A HUGR region in which all nodes share the same parent. 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<N: HugrNode> SiblingSubgraph<N>

pub fn try_new_dataflow_subgraph<'h, H, Root>( dfg_graph: impl RootCheckable<&'h H, Root>, ) -> Result<Self, InvalidSubgraph<N>>

where H: 'h + Clone + HugrView<Node = N>, Root: ContainerHandle<N, 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. 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<N>, outgoing: OutgoingPorts<N>, hugr: &impl HugrView<Node = N>, ) -> Result<Self, InvalidSubgraph<N>>

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<H: HugrView<Node = N>>( inputs: IncomingPorts<N>, outputs: OutgoingPorts<N>, hugr: &H, checker: &TopoConvexChecker<'_, H>, ) -> Result<Self, InvalidSubgraph<N>>

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<N>>, hugr: &impl HugrView<Node = N>, ) -> Result<Self, InvalidSubgraph<N>>

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<H: HugrView<Node = N>>( nodes: impl Into<Vec<N>>, hugr: &H, checker: &TopoConvexChecker<'_, H>, ) -> Result<Self, InvalidSubgraph<N>>

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 from_node(node: N, hugr: &impl HugrView<Node = N>) -> Self

Create a subgraph containing a single node.

The subgraph signature will be given by signature of the node.

Panics

If the node has incoming or outgoing state order edges.

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

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<N>

Returns the computed IncomingPorts of the subgraph.

pub fn outgoing_ports(&self) -> &OutgoingPorts<N>

Returns the computed OutgoingPorts of the subgraph.

pub fn signature(&self, hugr: &impl HugrView<Node = N>) -> Signature

The signature of the subgraph.

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

The parent of the sibling subgraph.

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

Construct a SimpleReplacement to replace self with replacement.

replacement must be a hugr with dataflow graph 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<Node = N>, 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

pub fn set_outgoing_ports( &mut self, ports: OutgoingPorts<N>, host: &impl HugrView<Node = N>, ) -> Result<(), InvalidOutputPorts<N>>

Change the output boundary of the subgraph.

All ports of the new boundary must be contained in the old boundary, i.e. the only changes that are allowed are copying, discarding and shuffling existing ports in the output boundary.

Returns an error if the new boundary is invalid (contains ports not in the old boundary or has non-unique linear ports). In this case, self is left unchanged.

Trait Implementations

impl<N: Clone> Clone for SiblingSubgraph<N>

fn clone(&self) -> SiblingSubgraph<N>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<N: Debug> Debug for SiblingSubgraph<N>

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

Formats the value using the given formatter.

impl<'de, N> Deserialize<'de> for SiblingSubgraph<N>

where N: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<N: PartialEq> PartialEq for SiblingSubgraph<N>

fn eq(&self, other: &SiblingSubgraph<N>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<N> Serialize for SiblingSubgraph<N>

where N: Serialize,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<N: Eq> Eq for SiblingSubgraph<N>

impl<N> StructuralPartialEq for SiblingSubgraph<N>