Struct Hugr

pub struct Hugr { /* private fields */ }

The Hugr data structure.

Implementations

impl Hugr

pub fn into_region_portgraph( self, parent: Node, ) -> FlatRegion<'static, MultiPortGraph>

Consumes the HUGR and return a flat portgraph view of the region rooted at parent.

impl Hugr

Public API for HUGRs.

pub fn new() -> Self

Create a new Hugr, with a single Module operation as the root node.

pub fn new_with_entrypoint( entrypoint_op: impl Into<OpType>, ) -> Result<Self, HugrError>

Create a new Hugr, with a given entrypoint operation.

If the optype is OpType::Module, the HUGR module root will match the entrypoint node. Otherwise, the entrypoint will be a descendent of the a module initialized at the node hierarchy root. The specific HUGR created depends on the operation type.

Error

Returns HugrError::UnsupportedEntrypoint if the entrypoint operation requires additional context to be defined. This is the case for OpType::Case, OpType::DataflowBlock, and OpType::ExitBlock since they are context-specific definitions.

pub fn with_capacity( entrypoint_op: impl Into<OpType>, nodes: usize, ports: usize, ) -> Result<Self, HugrError>

Create a new Hugr, with a given entrypoint operation and preallocated capacity.

If the optype is OpType::Module, the HUGR module root will match the entrypoint node. Otherwise, the entrypoint will be a child of the a module initialized at the node hierarchy root. The specific HUGR created depends on the operation type.

Error

Returns HugrError::UnsupportedEntrypoint if the entrypoint operation requires additional context to be defined. This is the case for OpType::Case, OpType::DataflowBlock, and OpType::ExitBlock since they are context-specific definitions.

pub fn reserve(&mut self, nodes: usize, links: usize)

Reserves enough capacity to insert at least the given number of additional nodes and links.

This method does not take into account already allocated free space left after node removals, and may overallocate capacity.

pub fn load( reader: impl BufRead, extensions: Option<&ExtensionRegistry>, ) -> Result<Self, EnvelopeError>

Read a HUGR from an Envelope.

To load a HUGR, all the extensions used in its definition must be available. The Envelope may include some of the extensions, but any additional extensions must be provided in the extensions parameter. If extensions is None, the default crate::std_extensions::STD_REG is used.

pub fn load_str( envelope: impl AsRef<str>, extensions: Option<&ExtensionRegistry>, ) -> Result<Self, EnvelopeError>

Read a HUGR from an Envelope encoded in a string.

Note that not all Envelopes are valid strings. In the general case, it is recommended to use Hugr::load with a bytearray instead.

To load a HUGR, all the extensions used in its definition must be available. The Envelope may include some of the extensions, but any additional extensions must be provided in the extensions parameter. If extensions is None, the default crate::std_extensions::STD_REG is used.

pub fn store( &self, writer: impl Write, config: EnvelopeConfig, ) -> Result<(), EnvelopeError>

Store the HUGR in an Envelope.

The Envelope will not include any extension definition, and will require an adequate ExtensionRegistry to be loaded (see Hugr::load). Use Hugr::store_with_exts to include additional extensions in the Envelope.

pub fn store_with_exts( &self, writer: impl Write, config: EnvelopeConfig, extensions: &ExtensionRegistry, ) -> Result<(), EnvelopeError>

Store the HUGR in an Envelope.

The Envelope will embed the definitions of the extensions in the extensions registry. Any other extension used in the HUGR definition must be passed to Hugr::load to load back the HUGR.

pub fn store_str(&self, config: EnvelopeConfig) -> Result<String, EnvelopeError>

Store the HUGR in an Envelope encoded in a string.

Note that not all Envelopes are valid strings. In the general case, it is recommended to use Hugr::store with a bytearray instead. See EnvelopeFormat::ascii_printable.

The Envelope will not include any extension definition, and will require an adequate ExtensionRegistry to be loaded (see Hugr::load_str). Use Hugr::store_str_with_exts to include additional extensions in the Envelope.

pub fn store_str_with_exts( &self, config: EnvelopeConfig, extensions: &ExtensionRegistry, ) -> Result<String, EnvelopeError>

Store the HUGR in an Envelope encoded in a string.

Note that not all Envelopes are valid strings. In the general case, it is recommended to use Hugr::store_str with a bytearray instead. See EnvelopeFormat::ascii_printable.

The Envelope will embed the definitions of the extensions in the extensions registry. Any other extension used in the HUGR definition must be passed to Hugr::load_str to load back the HUGR.

pub fn resolve_extension_defs( &mut self, extensions: &ExtensionRegistry, ) -> Result<(), ExtensionResolutionError>

Given a Hugr that has been deserialized, collect all extensions used to define the HUGR while resolving all OpType::OpaqueOp operations into OpType::ExtensionOps and updating the extension pointer in all internal crate::types::CustomTypes to point to the extensions in the register.

When listing “used extensions” we only care about definitional extension requirements, i.e., the operations and types that are required to define the HUGR nodes and wire types. This is computed from the union of all extension required across the HUGR.

Updates the internal extension registry with the extensions used in the definition.

Parameters

• extensions: The extension set considered when resolving opaque operations and types. The original Hugr’s internal extension registry is ignored and replaced with the newly computed one.

Errors

• If an opaque operation cannot be resolved to an extension operation.
• If an extension operation references an extension that is missing from the registry.
• If a custom type references an extension that is missing from the registry.

impl Hugr

Internal API for HUGRs, not intended for use by users.

pub fn canonicalize_nodes(&mut self, rekey: impl FnMut(Node, Node))

Compact the nodes indices of the hugr to be contiguous, and order them as a breadth-first traversal of the hierarchy.

The rekey function is called for each moved node with the old and new indices.

After this operation, a serialization and deserialization of the Hugr is guaranteed to preserve the indices.

Trait Implementations

impl AsMut<Hugr> for Hugr

fn as_mut(&mut self) -> &mut Hugr

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<Hugr> for Hugr

fn as_ref(&self) -> &Hugr

Converts this type into a shared reference of the (usually inferred) input type.

impl<H: AsRef<Hugr>, Handle> AsRef<Hugr> for RootChecked<H, Handle>

fn as_ref(&self) -> &Hugr

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Hugr

fn clone(&self) -> Hugr

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Hugr

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

Formats the value using the given formatter.

impl Default for Hugr

fn default() -> Self

Returns the “default value” for a type.

impl<'de> DeserializeAs<'de, Hugr> for AsStringEnvelope

fn deserialize_as<D>(deserializer: D) -> Result<Hugr, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl HugrInternals for Hugr

type RegionPortgraph<'p> = &'p MultiPortGraph where Self: 'p

The portgraph graph structure returned by HugrInternals::region_portgraph.

type Node = Node

The type of nodes in the Hugr.

type RegionPortgraphNodes = DefaultPGNodeMap

A mapping between HUGR nodes and portgraph nodes in the graph returned by HugrInternals::region_portgraph.

fn region_portgraph( &self, parent: Self::Node, ) -> (FlatRegion<'_, Self::RegionPortgraph<'_>>, Self::RegionPortgraphNodes)

Returns a flat portgraph view of a region in the HUGR, and a mapping between HUGR nodes and portgraph nodes in the graph.

fn node_metadata_map(&self, node: Self::Node) -> &NodeMetadataMap

Returns a metadata entry associated with a node.

impl HugrMut for Hugr

Impl for non-wrapped Hugrs. Overwrites the recursive default-impls to directly use the hugr.

fn set_entrypoint(&mut self, root: Node)

Set entrypoint to the HUGR.

fn get_metadata_mut( &mut self, node: Self::Node, key: impl AsRef<str>, ) -> &mut NodeMetadata

Returns a metadata entry associated with a node.

fn set_metadata( &mut self, node: Self::Node, key: impl AsRef<str>, metadata: impl Into<NodeMetadata>, )

Sets a metadata value associated with a node.

fn remove_metadata(&mut self, node: Self::Node, key: impl AsRef<str>)

Remove a metadata entry associated with a node.

fn add_node_with_parent( &mut self, parent: Node, node: impl Into<OpType>, ) -> Node

Add a node to the graph with a parent in the hierarchy.

fn add_node_before( &mut self, sibling: Node, nodetype: impl Into<OpType>, ) -> Node

Add a node to the graph as the previous sibling of another node.

fn add_node_after(&mut self, sibling: Node, op: impl Into<OpType>) -> Node

Add a node to the graph as the next sibling of another node.

fn remove_node(&mut self, node: Node) -> OpType

Remove a node from the graph and return the node weight. Note that if the node has children, they are not removed; this leaves the Hugr in an invalid state. See Self::remove_subtree.

fn remove_subtree(&mut self, node: Node)

Remove a node from the graph, along with all its descendants in the hierarchy.

fn connect( &mut self, src: Node, src_port: impl Into<OutgoingPort>, dst: Node, dst_port: impl Into<IncomingPort>, )

Connect two nodes at the given ports.

fn disconnect(&mut self, node: Node, port: impl Into<Port>)

Disconnects all edges from the given port.

fn add_other_edge( &mut self, src: Node, dst: Node, ) -> (OutgoingPort, IncomingPort)

Adds a non-dataflow edge between two nodes. The kind is given by the operation’s OpTrait::other_input or OpTrait::other_output.

fn insert_hugr( &mut self, root: Self::Node, other: Hugr, ) -> InsertionResult<Node, Self::Node>

Insert another hugr into this one, under a given parent node.

fn insert_from_view<H: HugrView>( &mut self, root: Self::Node, other: &H, ) -> InsertionResult<H::Node, Self::Node>

Copy another hugr into this one, under a given parent node.

fn insert_subgraph<H: HugrView>( &mut self, root: Self::Node, other: &H, subgraph: &SiblingSubgraph<H::Node>, ) -> HashMap<H::Node, Self::Node>

Copy a subgraph from another hugr into this one, under a given parent node.

fn copy_descendants( &mut self, root: Self::Node, new_parent: Self::Node, subst: Option<Substitution<'_>>, ) -> BTreeMap<Self::Node, Self::Node>

Copies the strict descendants of root to under the new_parent, optionally applying a Substitution to the OpTypes of the copied nodes.

fn use_extension(&mut self, extension: impl Into<Arc<Extension>>)

Registers a new extension in the set used by the hugr, keeping the one most recent one if the extension already exists.

fn use_extensions<Reg>(&mut self, registry: impl IntoIterator<Item = Reg>)

where ExtensionRegistry: Extend<Reg>,

Extend the set of extensions used by the hugr with the extensions in the registry.

fn with_entrypoint_mut(&mut self, entrypoint: Self::Node) -> Rerooted<&mut Self>

where Self: Sized,

Returns a mutable view of the HUGR with a different entrypoint.

fn apply_patch<R, E>( &mut self, rw: impl Patch<Self, Outcome = R, Error = E>, ) -> Result<R, E>

where Self: Sized,

Applies a patch to the graph.

impl HugrMutInternals for Hugr

Impl for non-wrapped Hugrs. Overwrites the recursive default-impls to directly use the hugr.

fn set_module_root(&mut self, root: Node)

Set the node at the root of the HUGR hierarchy.

fn set_num_ports(&mut self, node: Node, incoming: usize, outgoing: usize)

Set the number of ports on a node. This may invalidate the node’s PortIndex.

fn add_ports( &mut self, node: Node, direction: Direction, amount: isize, ) -> Range<usize>

Alter the number of ports on a node and returns a range with the new port offsets, if any. This may invalidate the node’s PortIndex.

fn insert_ports( &mut self, node: Node, direction: Direction, index: usize, amount: usize, ) -> Range<usize>

Insert amount new ports for a node, starting at index. The direction parameter specifies whether to add ports to the incoming or outgoing list. Links from this node are preserved, even when ports are renumbered by the insertion.

fn set_parent(&mut self, node: Node, parent: Node)

Sets the parent of a node.

fn move_after_sibling(&mut self, node: Node, after: Node)

Move a node in the hierarchy to be the subsequent sibling of another node.

fn move_before_sibling(&mut self, node: Node, before: Node)

Move a node in the hierarchy to be the prior sibling of another node.

fn replace_op(&mut self, node: Node, op: impl Into<OpType>) -> OpType

Replace the OpType at node and return the old OpType. In general this invalidates the ports, which may need to be resized to match the OpType signature.

fn optype_mut(&mut self, node: Node) -> &mut OpType

Gets a mutable reference to the optype.

fn node_metadata_map_mut(&mut self, node: Self::Node) -> &mut NodeMetadataMap

Returns a metadata entry associated with a node.

fn extensions_mut(&mut self) -> &mut ExtensionRegistry

Returns a mutable reference to the extension registry for this HUGR.

impl HugrView for Hugr

fn entrypoint(&self) -> Self::Node

The distinguished node from where operations are applied, commonly defining a region of interest.

fn module_root(&self) -> Self::Node

A pointer to the module region defined at the root of the HUGR.

fn contains_node(&self, node: Self::Node) -> bool

Returns true if the node exists in the HUGR.

fn get_parent(&self, node: Self::Node) -> Option<Self::Node>

Returns the parent of a node.

fn get_optype(&self, node: Node) -> &OpType

Returns the operation type of a node.

fn num_nodes(&self) -> usize

Returns the number of nodes in the HUGR.

fn num_edges(&self) -> usize

Returns the number of edges in the HUGR.

fn num_ports(&self, node: Self::Node, dir: Direction) -> usize

Number of ports in node for a given direction.

fn nodes(&self) -> impl Iterator<Item = Node> + Clone

Iterates over the all the nodes in the HUGR.

fn node_ports( &self, node: Node, dir: Direction, ) -> impl Iterator<Item = Port> + Clone

Iterator over ports of node in a given direction.

fn all_node_ports(&self, node: Node) -> impl Iterator<Item = Port> + Clone

Iterator over both the input and output ports of node.

fn linked_ports( &self, node: Node, port: impl Into<Port>, ) -> impl Iterator<Item = (Node, Port)> + Clone

Iterator over the nodes and ports connected to a port.

fn node_connections( &self, node: Node, other: Node, ) -> impl Iterator<Item = [Port; 2]> + Clone

Iterator the links between two nodes.

fn children( &self, node: Self::Node, ) -> impl DoubleEndedIterator<Item = Self::Node> + Clone

Returns an iterator over the direct children of node.

fn descendants( &self, node: Self::Node, ) -> impl Iterator<Item = Self::Node> + Clone

Returns an iterator over all the descendants of a node, including the node itself.

fn neighbours( &self, node: Node, dir: Direction, ) -> impl Iterator<Item = Node> + Clone

Iterates over neighbour nodes in the given direction. May contain duplicates if the graph has multiple links between nodes.

fn all_neighbours(&self, node: Node) -> impl Iterator<Item = Node> + Clone

Iterates over the input and output neighbours of the node in sequence.

fn mermaid_string_with_config(&self, config: RenderConfig) -> String

👎Deprecated: Use mermaid_format instead

Return the mermaid representation of the underlying hierarchical graph.

fn mermaid_string_with_formatter( &self, formatter: MermaidFormatter<'_, Self>, ) -> String

Return the mermaid representation of the underlying hierarchical graph according to the provided MermaidFormatter formatting options.

fn dot_string(&self) -> String

where Self: Sized,

Return the graphviz representation of the underlying graph and hierarchy side by side.

fn extensions(&self) -> &ExtensionRegistry

Returns the set of extensions used by the HUGR.

fn extract_hugr( &self, target: Node, ) -> (Hugr, impl ExtractionResult<Node> + 'static)

Extracts a HUGR containing the parent node and all its descendants.

fn entrypoint_optype(&self) -> &OpType

Returns the operation type of the entrypoint node.

fn entrypoint_tag(&self) -> OpTag

An operation tag that is guaranteed to represent the HugrView::entrypoint node operation.

fn with_entrypoint(&self, entrypoint: Self::Node) -> Rerooted<&Self>

where Self: Sized,

Returns a non-mutable view of the HUGR with a different entrypoint.

fn get_metadata( &self, node: Self::Node, key: impl AsRef<str>, ) -> Option<&NodeMetadata>

Returns the metadata associated with a node.

fn num_inputs(&self, node: Self::Node) -> usize

Number of inputs to a node. Shorthand for num_ports(node, Direction::Incoming).

fn num_outputs(&self, node: Self::Node) -> usize

Number of outputs from a node. Shorthand for num_ports(node, Direction::Outgoing).

fn node_outputs( &self, node: Self::Node, ) -> impl Iterator<Item = OutgoingPort> + Clone

Iterator over output ports of node. Like node_ports(node, Direction::Outgoing) but preserves knowledge that the ports are OutgoingPorts.

fn node_inputs( &self, node: Self::Node, ) -> impl Iterator<Item = IncomingPort> + Clone

Iterator over inputs ports of node. Like node_ports(node, Direction::Incoming) but preserves knowledge that the ports are IncomingPorts.

fn all_linked_ports( &self, node: Self::Node, dir: Direction, ) -> Either<impl Iterator<Item = (Self::Node, OutgoingPort)>, impl Iterator<Item = (Self::Node, IncomingPort)>>

Iterator over all the nodes and ports connected to a node in a given direction.

fn all_linked_outputs( &self, node: Self::Node, ) -> impl Iterator<Item = (Self::Node, OutgoingPort)>

Iterator over all the nodes and ports connected to a node’s inputs.

fn all_linked_inputs( &self, node: Self::Node, ) -> impl Iterator<Item = (Self::Node, IncomingPort)>

Iterator over all the nodes and ports connected to a node’s outputs.

fn single_linked_port( &self, node: Self::Node, port: impl Into<Port>, ) -> Option<(Self::Node, Port)>

If there is exactly one port connected to this port, return it and its node.

fn single_linked_output( &self, node: Self::Node, port: impl Into<IncomingPort>, ) -> Option<(Self::Node, OutgoingPort)>

If there is exactly one OutgoingPort connected to this IncomingPort, return it and its node.

fn single_linked_input( &self, node: Self::Node, port: impl Into<OutgoingPort>, ) -> Option<(Self::Node, IncomingPort)>

If there is exactly one IncomingPort connected to this OutgoingPort, return it and its node.

fn linked_outputs( &self, node: Self::Node, port: impl Into<IncomingPort>, ) -> impl Iterator<Item = (Self::Node, OutgoingPort)>

Iterator over the nodes and output ports connected to a given input port. Like linked_ports but preserves knowledge that the linked ports are OutgoingPorts.

fn linked_inputs( &self, node: Self::Node, port: impl Into<OutgoingPort>, ) -> impl Iterator<Item = (Self::Node, IncomingPort)>

Iterator over the nodes and input ports connected to a given output port Like linked_ports but preserves knowledge that the linked ports are IncomingPorts.

fn is_linked(&self, node: Self::Node, port: impl Into<Port>) -> bool

Returns whether a port is connected.

fn entry_descendants(&self) -> impl Iterator<Item = Self::Node> + Clone

Returns an iterator over all the descendants of the hugr entrypoint, including the node itself.

fn first_child(&self, node: Self::Node) -> Option<Self::Node>

Returns the first child of the specified node (if it is a parent). Useful because x.children().next() leaves x borrowed.

fn input_neighbours( &self, node: Self::Node, ) -> impl Iterator<Item = Self::Node> + Clone

Iterates over the input neighbours of the node. Shorthand for neighbours(node, Direction::Incoming).

fn output_neighbours( &self, node: Self::Node, ) -> impl Iterator<Item = Self::Node> + Clone

Iterates over the output neighbours of the node. Shorthand for neighbours(node, Direction::Outgoing).

fn get_io(&self, node: Self::Node) -> Option<[Self::Node; 2]>

Get the input and output child nodes of a dataflow parent. If the node isn’t a dataflow parent, then return None

fn inner_function_type(&self) -> Option<Cow<'_, Signature>>

Returns the function type defined by this dataflow HUGR.

fn poly_func_type(&self) -> Option<PolyFuncType>

Returns the function type defined by this HUGR, i.e. Some iff the root is a FuncDecl or FuncDefn.

fn as_petgraph(&self) -> PetgraphWrapper<'_, Self>

where Self: Sized,

Return a wrapper over the view that can be used in petgraph algorithms.

fn mermaid_string(&self) -> String

Return the mermaid representation of the underlying hierarchical graph.

fn mermaid_format(&self) -> MermaidFormatter<'_, Self>

Construct a mermaid representation of the underlying hierarchical graph.

fn static_source(&self, node: Self::Node) -> Option<Self::Node>

If a node has a static input, return the source node.

fn static_targets( &self, node: Self::Node, ) -> Option<impl Iterator<Item = (Self::Node, IncomingPort)>>

If a node has a static output, return the targets.

fn signature(&self, node: Self::Node) -> Option<Cow<'_, Signature>>

Get the “signature” (incoming and outgoing types) of a node, non-Value kind ports will be missing.

fn value_types( &self, node: Self::Node, dir: Direction, ) -> impl Iterator<Item = (Port, Type)>

Iterator over all outgoing ports that have Value type, along with corresponding types.

fn in_value_types( &self, node: Self::Node, ) -> impl Iterator<Item = (IncomingPort, Type)>

Iterator over all incoming ports that have Value type, along with corresponding types.

fn out_value_types( &self, node: Self::Node, ) -> impl Iterator<Item = (OutgoingPort, Type)>

Iterator over all outgoing ports that have Value type, along with corresponding types.

fn validate(&self) -> Result<(), ValidationError<Self::Node>>

where Self: Sized,

Check the validity of the underlying HUGR.

impl PartialEq for Hugr

fn eq(&self, other: &Hugr) -> 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 SerializeAs<Hugr> for AsStringEnvelope

fn serialize_as<S>(source: &Hugr, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Hugr