Crate hugr 

Extensible, graph-based program representation with first-class support for linear types.

The name HUGR stands for “Hierarchical Unified Graph Representation”. It is designed primarily as an intermediate representation and interchange format for quantum and hybrid classical–quantum programs.

Both data-flow and control-flow graphs can be represented in the HUGR. Nodes in the graph may represent basic operations, or may themselves have “child” graphs, which inherit their inputs and outputs. Special “non-local” edges allow data to pass directly from a node to another node that is not a direct descendent (subject to causality constraints).

The specification can be found here.

This crate provides a Rust implementation of HUGR and the standard extensions defined in the specification.

It includes methods for:

• building HUGRs from basic operations;
• defining new extensions;
• serializing and deserializing HUGRs;
• performing local rewrites.

Example

Here we build a simple HUGR representing a boolean circuit using the [builder::DFGBuilder] as follows:

use hugr::builder::{BuildError, DFGBuilder, Dataflow, DataflowHugr, inout_sig};
use hugr::extension::prelude::{bool_t};
use hugr::envelope::EnvelopeConfig;
use hugr::hugr::Hugr;
use hugr::ops::Value;
use hugr::std_extensions::logic::LogicOp;


fn make_dfg_hugr() -> Result<Hugr, BuildError> {
    // pseudocode:
    // input x0
    // x1 == not(true)
    // x2 := not(x0)
    // x3 := or(x0,x2)
    // x4 := and(x1,x3)
    // output x4
    let mut dfg_builder = DFGBuilder::new(inout_sig(
        vec![bool_t()],
        vec![bool_t()],
    ))?;

    let [x0] = dfg_builder.input_wires_arr();
    let true_val = dfg_builder.add_load_value(Value::true_val());
    let x1 = dfg_builder.add_dataflow_op(LogicOp::Not, [true_val]).unwrap();
    let x2  = dfg_builder.add_dataflow_op(LogicOp::Not, [x0]).unwrap();
    let x3 = dfg_builder.add_dataflow_op(LogicOp::Or, [x0, x2.out_wire(0)]).unwrap();
    let x4 = dfg_builder.add_dataflow_op(LogicOp::And, x1.outputs().chain(x3.outputs())).unwrap();

    dfg_builder.finish_hugr_with_outputs(x4.outputs())
}

let h: Hugr = make_dfg_hugr().expect("build hugr");
// Serialize the hugr to obtain a printable representation
let serialized = h.store_str(EnvelopeConfig::text()).expect("serialize");
println!("{}", serialized);

Natively, HUGR does not include any quantum operations, but it is possible to define a quantum extension and then use it to build a HUGR. See the documentation in the extension module for an example of a simple quantum extension.

Modules

builder

Utilities for building valid HUGRs.

core

Definitions for the core types used in the Hugr.

envelope

Envelope format for HUGR packages.

extension

Extension framework for user-defined operations and types.

hugr

The Hugr data structure, and its basic component handles.

metadata

Type-safe metadata definition for hugr nodes.

ops

The operation types for the HUGR.

package

Bundles of hugr modules along with the extension required to load them.

std_extensions

Experiments for Extension definitions.

types

General wire types used in the compiler

utils

General utilities.

Macros

const_extension_ids

Declare ‘const’ variables holding new ExtensionIds, validating that they are well-formed as separate tests - hence, usable at the top level of a test module only. Example:

type_row

Creates a TypeRow backed by statically defined data, avoiding allocations.

Structs

Extension

A extension is a set of capabilities required to execute a graph.

Hugr

The Hugr data structure.

IncomingPort

A port in the incoming direction.

Node

A handle to a node in the HUGR.

OutgoingPort

A port in the outgoing direction.

Port

A handle to a port for a node in the HUGR.

SimpleReplacement

Specification of a simple replacement operation.

Wire

A DataFlow wire, defined by a Value-kind output port of a node

Enums

CircuitUnit

Enum for uniquely identifying the origin of linear wires in a circuit-like dataflow region.

Traits

HugrView

A trait for inspecting HUGRs. For end users we intend this to be superseded by region-specific APIs.

NodeIndex

A trait for getting the index of a node.

PortIndex

A trait for getting the undirected index of a port.

Type Aliases

Direction

The direction of a port.