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::{EXTENSION_ID, LOGIC_REG, 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).with_extension_delta(EXTENSION_ID),
        )?;

        // 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])
                .with_extension_delta(EXTENSION_ID),
        )?;
        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(&LOGIC_REG)
}?;

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

Re-exports

• pub use handle::BuildHandle;

Modules

• handle
  Handles to nodes in HUGR used during the building phase.

Structs

• 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. Allows appending operations by indexing a vector of input wires.
• 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) whose extension delta, when used in a non-FuncDefn container, will be inferred.
• inout_sig
  Return a FunctionType with the specified input and output types whose extension delta, when used in a non-FuncDefn container, will be inferred.

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.