Hugr¶

class hugr.hugr.base.Hugr(entrypoint_op: OpVarCov | None = None)[source]¶

Bases: Mapping[Node, NodeData], Generic[OpVarCov]

The core HUGR datastructure.

Parameters:

entrypoint_op – The operation for the entrypoint node. Defaults to a Module
root). ((which will then also be the)

Examples

>>> h = Hugr()
>>> h.entrypoint_op()
Module()
>>> h[h.entrypoint].op
Module()
>>> dfg_h = Hugr(ops.DFG([tys.Bool]))
>>> dfg_h[dfg_h.entrypoint].op
DFG(inputs=[Bool])

Methods

`add_const`	Add a constant node to the HUGR.
`add_link`	Add a link (edge) between two nodes to the HUGR,
`add_node`	Add a node to the HUGR.
`add_order_link`	Add a state order link between two nodes.
`children`	The child nodes of a given node.
`delete_link`	Delete a link (edge) between two nodes from the HUGR.
`delete_node`	Delete a node from the HUGR.
`descendants`	Iterator over all the descendants of the hugr entrypoint.
`entrypoint_op`	The operation of the root node.
`from_bytes`	Deserialize a byte string to a Hugr object.
`from_str`	Deserialize a string to a Hugr object.
`get`	D.get(k[,d]) -> D[k] if k in D, else d.
`has_link`	Check if there is a link between two ports.
`incoming_links`	Iterator over incoming links to a given node.
`incoming_order_links`	Iterator over nodes connected by an incoming state order link to a given node.
`input_neighbours`	Iterator over the input neighbours of a node.
`insert_hugr`	Insert a HUGR entrypoint and all its descendants into this HUGR.
`items`	D.items() -> a set-like object providing a view on D's items
`keys`	D.keys() -> a set-like object providing a view on D's keys
`linked_ports`	Return an iterable of In(Out)Ports linked to given Out(In)Port.
`links`	Iterator over all the links in the HUGR.
`load_json`	Deserialize a JSON string into a HUGR.
`neighbours`	Iterator over the neighbours of a node.
`nodes`	Iterator over all the nodes of the hugr and their data.
`num_in_ports`	The number of incoming ports of a node.
`num_incoming`	The number of incoming links to a node.
`num_nodes`	The number of nodes in the HUGR.
`num_out_ports`	The number of outgoing ports of a node.
`num_outgoing`	The number of outgoing links from a node.
`num_ports`	The number of ports of a node in a given direction.
`outgoing_links`	Iterator over outgoing links from a given node.
`outgoing_order_links`	Iterator over nodes connected by an outgoing state order link from a given node.
`output_neighbours`	Iterator over the output neighbours of a node.
`port_kind`	The kind of a port.
`port_type`	The type of a port, if the kind is `ValueKind`, else None.
`render_dot`	Render the HUGR to a graphviz Digraph.
`resolve_extensions`	Resolve extension types and operations in the HUGR by matching them to extensions in the registry.
`sorted_region_nodes`	Iterator over a topological ordering of all the hugr nodes.
`store_dot`	Render the HUGR to a graphviz dot file.
`to_bytes`	Serialize the HUGR into an envelope byte string.
`to_json`	Serialize the HUGR to a JSON string.
`to_model`	Export this module into the hugr model format.
`to_str`	Serialize the package to a HUGR envelope string.
`values`	D.values() -> an object providing a view on D's values

Attributes

`module_root`
`entrypoint`

add_const(value: Value, parent: ToNode | None = None, metadata: dict[str, Any] | None = None) → Node[source]¶

Add a constant node to the HUGR.

Parameters:

value – Value of the constant.
parent – Parent node of added node. Defaults to HUGR entrypoint if None.
metadata – A dictionary of metadata to associate with the node. Defaults to None.

Returns:

Handle to the added node.

Examples

>>> h = Hugr()
>>> n = h.add_const(val.TRUE)
>>> h[n].op
Const(TRUE)

add_link(src: OutPort, dst: InPort) → None[source]¶

Add a link (edge) between two nodes to the HUGR,: from an outgoing port to an incoming port.

Parameters:

src – Source port.
dst – Destination port.

Examples

>>> df = dfg.Dfg(tys.Bool)
>>> df.hugr.add_link(df.input_node.out(0), df.output_node.inp(0))
>>> list(df.hugr.linked_ports(df.input_node[0]))
[InPort(Node(6), 0)]

add_node(op: Op, parent: ToNode | None = None, num_outs: int | None = None, metadata: dict[str, Any] | None = None) → Node[source]¶

Add a node to the HUGR.

Parameters:

op – Operation of the node.
parent – Parent node of added node. Defaults to HUGR entrypoint if None.
num_outs – Number of output ports expected for this node. Defaults to None.
metadata – A dictionary of metadata to associate with the node. Defaults to None.

Returns:

Handle to the added node.

add_order_link(src: ToNode, dst: ToNode) → None[source]¶

Add a state order link between two nodes.

Parameters:

src – Source node.
dst – Destination node.

Examples

>>> df = dfg.Dfg()
>>> df.hugr.add_order_link(df.input_node, df.output_node)
>>> list(df.hugr.outgoing_order_links(df.input_node))
[Node(6)]

children(node: ToNode | None = None) → list[Node][source]¶

The child nodes of a given node.

Parameters:: node – Parent node. Defaults to the HUGR entrypoint.
Returns:: List of child nodes.

Examples

>>> h = Hugr()
>>> n = h.add_node(ops.Const(val.TRUE))
>>> h.children(h.entrypoint)
[Node(1)]

delete_link(src: OutPort, dst: InPort) → None[source]¶

Delete a link (edge) between two nodes from the HUGR.

Parameters:

src – Source port.
dst – Destination port.

delete_node(node: ToNode) → NodeData | None[source]¶

Delete a node from the HUGR.

Parameters:: node – Node to delete.
Returns:: The deleted node data, or None if the node was not found.

Examples

>>> h = Hugr()
>>> n = h.add_const(val.TRUE)
>>> deleted = h.delete_node(n)
>>> deleted.op
Const(TRUE)
>>> len(h)
1

descendants(node: ToNode | None = None) → Iterable[Node][source]¶

Iterator over all the descendants of the hugr entrypoint.

Traverses the HUGR graph in a breadth-first manner, starting from the entrypoint.

To get all the nodes in the HUGR, use nodes().

Parameters:: node – Parent node. Defaults to the HUGR entrypoint.
Returns:: List of child nodes.

entrypoint_op() → OpVarCov[source]¶

The operation of the root node.

Examples

>>> h = Hugr()
>>> h.entrypoint_op()
Module()

static from_bytes(envelope: bytes) → Hugr[source]¶

Deserialize a byte string to a Hugr object.

Some envelope formats can be read from a string. See from_str().

Parameters:: envelope – The byte string representing a Hugr envelope.
Returns:: The deserialized Hugr object.
Raises:: ValueError – If the envelope does not contain exactly one module.

static from_str(envelope: str) → Hugr[source]¶

Deserialize a string to a Hugr object.

Not all envelope formats can be read from a string. See from_bytes() for a more general method.

Parameters:: envelope – The string representing a Hugr envelope.
Returns:: The deserialized Hugr object.
Raises:: ValueError – If the envelope does not contain exactly one module.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

has_link(src: OutPort, dst: InPort) → bool[source]¶

Check if there is a link between two ports.

Parameters:

src – Source port.
dst – Destination port.

Returns:

True if there is a link, False otherwise.

Examples

>>> df = dfg.Dfg(tys.Bool)
>>> df.hugr.add_link(df.input_node.out(0), df.output_node.inp(0))
>>> df.hugr.has_link(df.input_node.out(0), df.output_node.inp(0))
True

incoming_links(node: ToNode) → Iterable[tuple[InPort, list[OutPort]]][source]¶

Iterator over incoming links to a given node.

This number includes order ports.

Parameters:: node – Node to query.
Returns:: Iterator of pairs of incoming port and the outgoing ports connected to that port.

Examples

>>> df = dfg.Dfg()
>>> df.hugr.add_link(df.input_node.out(0), df.output_node.inp(0))
>>> df.hugr.add_link(df.input_node.out(0), df.output_node.inp(1))
>>> df.hugr.add_order_link(df.input_node, df.output_node)
>>> list(df.hugr.incoming_links(df.output_node))
[(InPort(Node(6), 0), [OutPort(Node(5), 0)]), (InPort(Node(6), 1), [OutPort(Node(5), 0)]), (InPort(Node(6), -1), [OutPort(Node(5), -1)])]

incoming_order_links(node: ToNode) → Iterable[Node][source]¶

Iterator over nodes connected by an incoming state order link to a given node.

Parameters:: node – Destination node of state order link.

Examples

>>> df = dfg.Dfg()
>>> df.add_state_order(df.input_node, df.output_node)
>>> list(df.hugr.incoming_order_links(df.output_node))
[Node(5)]

input_neighbours(node: ToNode) → Iterable[Node][source]¶

Iterator over the input neighbours of a node.

Parameters:: node – Node to query.
Returns:: Iterator of nodes connected to node via incoming links. Nodes connected via multiple links will be returned multiple times.

Examples

>>> df = dfg.Dfg()
>>> df.hugr.add_link(df.input_node.out(0), df.output_node.inp(0))
>>> df.hugr.add_link(df.input_node.out(0), df.output_node.inp(1))
>>> list(df.hugr.input_neighbours(df.output_node))
[Node(5), Node(5)]

insert_hugr(hugr: Hugr, parent: ToNode | None = None) → dict[Node, Node][source]¶

Insert a HUGR entrypoint and all its descendants into this HUGR.

If the inserted HUGR entrypoint was not its module root, some nodes will be ignored.

Parameters:

hugr – HUGR to insert.
parent – Parent for root of inserted HUGR. Defaults to None.

Returns:

Mapping from node indices in inserted HUGR to their new indices in this HUGR.

Examples

>>> d = dfg.Dfg()
>>> h = Hugr()
>>> h.insert_hugr(d.hugr)
{Node(4): Node(1), Node(5): Node(2), Node(6): Node(3)}

items() → a set-like object providing a view on D's items¶

keys() → a set-like object providing a view on D's keys¶

linked_ports(port: OutPort) → Iterable[InPort][source]¶

linked_ports(port: InPort) → Iterable[OutPort]

Return an iterable of In(Out)Ports linked to given Out(In)Port.

Parameters:: port – Given port.
Returns:: Iterator over linked ports.

Examples

>>> df = dfg.Dfg(tys.Bool)
>>> df.set_outputs(df.input_node[0])
>>> list(df.hugr.linked_ports(df.input_node[0]))
[InPort(Node(6), 0)]

links() → Iterator[tuple[OutPort, InPort]][source]¶

Iterator over all the links in the HUGR.

Returns:: Iterator of pairs of outgoing port and the incoming ports.

classmethod load_json(json_str: str) → Hugr[source]¶

Deserialize a JSON string into a HUGR.

For most use cases, it is recommended to use package serialization instead. See hugr.package.Package.from_bytes().

neighbours(node: ToNode, direction: Direction | None = None) → Iterable[Node][source]¶

Iterator over the neighbours of a node.

Parameters:

node – Node to query.
direction – If given, only return neighbours in that direction.

Returns:

Iterator of nodes connected to node, ordered by direction and port offset. Nodes connected via multiple links will be returned multiple times.

Examples

>>> df = dfg.Dfg()
>>> df.hugr.add_link(df.input_node.out(0), df.output_node.inp(0))
>>> df.hugr.add_link(df.input_node.out(0), df.output_node.inp(1))
>>> list(df.hugr.neighbours(df.input_node))
[Node(6), Node(6)]
>>> list(df.hugr.neighbours(df.output_node, Direction.OUTGOING))
[]

nodes() → Iterable[tuple[Node, NodeData]][source]¶

Iterator over all the nodes of the hugr and their data.

To get the descendants of the entrypoint, use descendants().

num_in_ports(node: ToNode) → int[source]¶

The number of incoming ports of a node. See num_ports().

This value does not include order ports.

num_incoming(node: Node) → int[source]¶

The number of incoming links to a node.

Examples

>>> df = dfg.Dfg()
>>> df.hugr.add_link(df.input_node.out(0), df.output_node.inp(0))
>>> df.hugr.num_incoming(df.output_node)
1

num_nodes() → int[source]¶

The number of nodes in the HUGR.

Examples

>>> h = Hugr()
>>> n = h.add_const(val.TRUE)
>>> h.num_nodes()
2

num_out_ports(node: ToNode) → int[source]¶

The number of outgoing ports of a node. See num_ports().

This value cound does not include order ports.

num_outgoing(node: ToNode) → int[source]¶

The number of outgoing links from a node.

Examples

>>> df = dfg.Dfg()
>>> df.hugr.add_link(df.input_node.out(0), df.output_node.inp(0))
>>> df.hugr.num_outgoing(df.input_node)
1

num_ports(node: ToNode, direction: Direction) → int[source]¶

The number of ports of a node in a given direction. Not necessarily the number of connected ports - if port i is connected, then all ports 0..i are assumed to exist.

This value includes order ports.

Parameters:

node – Node to query.
direction – Direction of ports to count.

Examples

>>> from hugr.std.logic import Not
>>> h = Hugr()
>>> n1 = h.add_node(Not)
>>> n2 = h.add_node(Not)
>>> # Passing offset `2` here allocates new ports automatically
>>> h.add_link(n1.out(0), n2.inp(2))
>>> h.add_order_link(n1, n2)
>>> h.num_ports(n1, Direction.OUTGOING)
1
>>> h.num_ports(n2, Direction.INCOMING)
3

outgoing_links(node: ToNode) → Iterable[tuple[OutPort, list[InPort]]][source]¶

Iterator over outgoing links from a given node.

This number includes order ports.

Parameters:: node – Node to query.
Returns:: Iterator of pairs of outgoing port and the incoming ports connected to that port.

Examples

>>> df = dfg.Dfg()
>>> df.hugr.add_link(df.input_node.out(0), df.output_node.inp(0))
>>> df.hugr.add_link(df.input_node.out(0), df.output_node.inp(1))
>>> df.hugr.add_order_link(df.input_node, df.output_node)
>>> list(df.hugr.outgoing_links(df.input_node))
[(OutPort(Node(5), 0), [InPort(Node(6), 0), InPort(Node(6), 1)]), (OutPort(Node(5), -1), [InPort(Node(6), -1)])]

outgoing_order_links(node: ToNode) → Iterable[Node][source]¶

Iterator over nodes connected by an outgoing state order link from a given node.

Parameters:: node – Source node of state order link.

Examples

>>> df = dfg.Dfg()
>>> df.add_state_order(df.input_node, df.output_node)
>>> list(df.hugr.outgoing_order_links(df.input_node))
[Node(6)]

output_neighbours(node: ToNode) → Iterable[Node][source]¶

Iterator over the output neighbours of a node.

Parameters:: node – Node to query.
Returns:: Iterator of nodes connected to node via outgoing links. Nodes connected via multiple links will be returned multiple times.

Examples

>>> df = dfg.Dfg()
>>> df.hugr.add_link(df.input_node.out(0), df.output_node.inp(0))
>>> df.hugr.add_link(df.input_node.out(0), df.output_node.inp(1))
>>> list(df.hugr.output_neighbours(df.input_node))
[Node(6), Node(6)]

The kind of a port.

Examples

>>> df = dfg.Dfg(tys.Bool)
>>> df.hugr.port_kind(df.input_node.out(0))
ValueKind(Bool)

port_type(port: InPort | OutPort) → Type | None[source]¶

The type of a port, if the kind is ValueKind, else None.

Examples

>>> df = dfg.Dfg(tys.Bool)
>>> df.hugr.port_type(df.input_node.out(0))
Bool

render_dot(config: RenderConfig | None = None, root: Node | None = None) → gv.Digraph[source]¶

Render the HUGR to a graphviz Digraph.

Parameters:

config – Render configuration.
root – Root node defining the set of nodes to render. By default this is the module root and all nodes are rendered. If this is a container node, all nodes under it are rendered. Every incoming edge to the rendered set and outgoing edge from it is also shown, with its other endpoint labelled with its node index.

Returns:

The graphviz Digraph.

resolve_extensions(registry: ext.ExtensionRegistry) → Hugr[source]¶: Resolve extension types and operations in the HUGR by matching them to extensions in the registry.

sorted_region_nodes(parent: Node) → Iterator[Node][source]¶

Iterator over a topological ordering of all the hugr nodes.

Note that the sort is performed within a hugr region and non-local edges are ignored.

Parameters:: parent – The parent node of the region to sort.
Raises:: ValueError – If the region contains a cycle.

Examples

>>> from hugr.build.tracked_dfg import TrackedDfg
>>> from hugr.std.logic import Not
>>> dfg = TrackedDfg(tys.Bool)
>>> [b] = dfg.track_inputs()
>>> for _ in range(6):
...     _= dfg.add(Not(b));
>>> dfg.set_tracked_outputs()
>>> nodes = list(dfg.hugr)
>>> list(dfg.hugr.sorted_region_nodes(nodes[4]))
[Node(5), Node(7), Node(8), Node(9), Node(10), Node(11), Node(12), Node(6)]

store_dot(filename: str, format: str = 'svg', config: RenderConfig | None = None, root: Node | None = None) → None[source]¶

Render the HUGR to a graphviz dot file.

Parameters:

filename – The file to render to.
format – The format used for rendering (‘pdf’, ‘png’, etc.). Defaults to SVG.
config – Render configuration.
root – Root node defining the set of nodes to render. By default this is the module root and all nodes are rendered. If this is a container node, all nodes under it are rendered. Every incoming edge to the rendered set and outgoing edge from it is also shown, with its other endpoint labelled with its node index.

to_bytes(config: EnvelopeConfig | None = None) → bytes[source]¶

Serialize the HUGR into an envelope byte string.

Some envelope formats can be encoded into a string. See to_str().

to_json() → str[source]¶

Serialize the HUGR to a JSON string.

For most use cases, it is recommended to store a HUGR package instead. See hugr.package.Package.to_bytes().

to_model() → Module[source]¶: Export this module into the hugr model format.

to_str(config: EnvelopeConfig | None = None) → str[source]¶

Serialize the package to a HUGR envelope string.

Not all envelope formats can be encoded into a string. See to_bytes() for a more general method.

values() → an object providing a view on D's values¶