Struct Hugr

pub struct Hugr { /* private fields */ }

The Hugr data structure.

Implementations

impl Hugr

pub fn validate(&self) -> Result<(), ValidationError>

Check the validity of the HUGR, assuming that it has no open extension variables. TODO: Add a version of validation which allows for open extension variables (see github issue #457)

pub fn validate_no_extensions(&self) -> Result<(), ValidationError>

Check the validity of the HUGR, but don’t check consistency of extension requirements between connected nodes or between parents and children.

pub fn validate_extensions(&self) -> Result<(), ValidationError>

Validate extensions, i.e. that extension deltas from parent nodes are reflected in their children.

impl Hugr

Public API for HUGRs.

pub fn new(root_node: impl Into<OpType>) -> Self

Create a new Hugr, with a single root node.

pub fn load_json( reader: impl Read, extension_registry: &ExtensionRegistry, ) -> Result<Self, LoadHugrError>

Load a Hugr from a json reader.

Validates the Hugr against the provided extension registry, ensuring all operations are resolved.

If the feature extension_inference is enabled, we will ensure every function correctly specifies the extensions required by its contained ops.

pub fn infer_extensions(&mut self, remove: bool) -> Result<(), ExtensionError>

Infers an extension-delta for any non-function container node whose current extension_delta contains TO_BE_INFERRED. The inferred delta will be the smallest delta compatible with its children and that includes any other ExtensionIds in the current delta.

If remove is true, for such container nodes without TO_BE_INFERRED, ExtensionIds are removed from the delta if they are not used by any child node.

The non-function container nodes are: Case, CFG, Conditional, DataflowBlock, DFG, TailLoop

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.

This is distinct from runtime extension requirements computed in Hugr::infer_extensions, which are computed more granularly in each function signature by the runtime_reqs field and define the set of capabilities required by the runtime to execute each function.

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>, Root> AsRef<Hugr> for RootChecked<H, Root>

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 copy 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> Deserialize<'de> for Hugr

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

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl ExtractHugr for &Hugr

fn extract_hugr(self) -> Hugr

Extracts the view into an owned HUGR, rooted at the view’s root node and containing only the nodes and edges of the view.

impl ExtractHugr for &mut Hugr

fn extract_hugr(self) -> Hugr

Extracts the view into an owned HUGR, rooted at the view’s root node and containing only the nodes and edges of the view.

impl ExtractHugr for Hugr

fn extract_hugr(self) -> Hugr

Extracts the view into an owned HUGR, rooted at the view’s root node and containing only the nodes and edges of the view.

impl HugrInternals for Hugr

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

The underlying portgraph view type.

type Node = Node

The type of nodes in the Hugr.

fn portgraph(&self) -> Self::Portgraph<'_>

Returns a reference to the underlying portgraph.

fn base_hugr(&self) -> &Hugr

Returns the Hugr at the base of a chain of views.

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

Return the root node of this view.

fn get_pg_index(&self, node: Self::Node) -> NodeIndex

Convert a node to a portgraph node index.

fn get_node(&self, index: NodeIndex) -> Self::Node

Convert a portgraph node index to a node.

impl HugrView for Hugr

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

Returns whether the node exists.

fn node_count(&self) -> usize

Returns the number of nodes in the hugr.

fn edge_count(&self) -> usize

Returns the number of edges in the hugr.

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

Iterates over the nodes in the port graph.

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 num_ports(&self, node: Node, dir: Direction) -> usize

Number of ports in node for a given direction.

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

Return iterator over the direct children of node.

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 root(&self) -> Self::Node

Return the root node of this view.

fn root_type(&self) -> &OpType

Return the type of the HUGR root node.

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

Validates that a node is valid in the graph.

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

Validates that a node is a valid root descendant in the graph.

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

Returns the parent of a node.

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

Returns the operation type of a node.

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

Returns the metadata associated with a node.

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

Retrieve the complete metadata map for a node.

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

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_string_with_config(&self, config: RenderConfig) -> String

Return the mermaid representation of the underlying hierarchical graph.

fn dot_string(&self) -> String

where Self: Sized,

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

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 incoming ports that have Value type, along with corresponding types.

fn extensions(&self) -> &ExtensionRegistry

Returns the set of extensions used by the HUGR.

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

Check the validity of the underlying HUGR.

fn validate_no_extensions(&self) -> Result<(), ValidationError>

Check the validity of the underlying HUGR, but don’t check consistency of extension requirements between connected nodes or between parents and children.

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 RootTagged for &Hugr

type RootHandle = Node

The kind of handle that can be used to refer to the root node.

impl RootTagged for &mut Hugr

type RootHandle = Node

The kind of handle that can be used to refer to the root node.

impl RootTagged for Hugr

type RootHandle = Node

The kind of handle that can be used to refer to the root node.

impl Serialize for Hugr

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Hugr