Module builder

Utilities for building valid HUGRs.

This module includes various tools for building HUGRs.

Depending on the type of HUGR you want to build, you may want to use one of the following builders:

• ModuleBuilder: For building a module with function declarations and definitions.
• DFGBuilder: For building a dataflow graph.
• FunctionBuilder: A DFGBuilder specialised in defining functions with a dataflow graph.
• CFGBuilder: For building a control flow graph.
• ConditionalBuilder: For building a conditional node.
• TailLoopBuilder: For building a tail-loop node.

Additionally, the CircuitBuilder provides an alternative to the DFGBuilder when working with circuits, where some inputs of operations directly correspond to some outputs and operations can be directly appended using unit indices.

Example

The following example shows how to build a simple HUGR module with two dataflow functions, one built using the DFGBuilder and the other using the CircuitBuilder.

use hugr::extension::prelude::bool_t;
use hugr::std_extensions::logic::{self, LogicOp};
use hugr::types::Signature;

let hugr = {
    let mut module_builder = ModuleBuilder::new();

    // Add a `main` function with signature `bool -> bool`.
    //
    // This block returns a handle to the built function.
    let _dfg_handle = {
        let mut dfg = module_builder.define_function(
            "main",
            Signature::new_endo(bool_t()),
        )?;

        // Get the wires from the function inputs.
        let [w] = dfg.input_wires_arr();

        // Add an operation connected to the input wire, and get the new dangling wires.
        let [w] = dfg.add_dataflow_op(LogicOp::Not, [w])?.outputs_arr();

        // Finish the function, connecting some wires to the output.
        dfg.finish_with_outputs([w])
    }?;

    // Add a similar function, using the circuit builder interface.
    let _circuit_handle = {
        let mut dfg = module_builder.define_function(
            "circuit",
            Signature::new_endo(vec![bool_t(), bool_t()]),
        )?;
        let mut circuit = dfg.as_circuit(dfg.input_wires());

        // Add multiple operations, indicating only the wire index.
        circuit.append(LogicOp::Not, [0])?.append(LogicOp::Not, [1])?;

        // Finish the circuit, and return the dataflow graph after connecting its outputs.
        let outputs = circuit.finish();
        dfg.finish_with_outputs(outputs)
    }?;

    // Finish building the HUGR, consuming the builder.
    //
    // Requires a registry with all the extensions used in the module.
    module_builder.finish_hugr()
}?;

// The built HUGR is always valid.
hugr.validate().unwrap_or_else(|e| {
    panic!("HUGR validation failed: {e}");
});

Modules

handle

Handles to nodes in HUGR used during the building phase.

Structs

BuildHandle

Handle to a dataflow node which has a known number of value outputs

CFGBuilder

Builder for a crate::ops::CFG child control flow graph.

CircuitBuilder

Builder to build regions of dataflow graphs that look like Circuits, where some inputs of operations directly correspond to some outputs.

ConditionalBuilder

Builder for a ops::Conditional node’s children.

DFGBuilder

Builder for a ops::DFG node.

DFGWrapper

Wrapper around DFGBuilder used to build other dataflow regions.

ModuleBuilder

Builder for a HUGR module.

Enums

BuildError

Error while building the HUGR.

BuilderWiringError

Error raised when wiring up a node during the build process.

CircuitBuildError

Error in CircuitBuilder

Traits

Container

Trait for HUGR container builders. Containers are nodes that are parents of sibling graphs. Implementations of this trait allow the child sibling graph to be added to the HUGR.

Dataflow

Trait for building dataflow regions of a HUGR.

DataflowHugr

Trait implemented by builders of Dataflow Hugrs

DataflowSubContainer

Trait implemented by builders of Dataflow container regions of a HUGR

HugrBuilder

Types implementing this trait can be used to build complete HUGRs (with varying root node types)

SubContainer

Types implementing this trait build a container graph region by borrowing a HUGR

Functions

endo_sig

Return a FunctionType with the same input and output types (specified).

inout_sig

Return a FunctionType with the specified input and output types.

Type Aliases

BlockBuilder

Builder for a DataflowBlock child graph.

CaseBuilder

Builder for a ops::Case child graph.

FunctionBuilder

Builder for a ops::FuncDefn node

TailLoopBuilder

Builder for a ops::TailLoop node.