qp.backline

This module contains functionality for defining and using backline in PennyLane. Backline is an open platform for compilation and low-latency execution that dynamically connects quantum workloads to heterogenous hardware devices, including GPUs, CPUs, FPGAs, and QPUs. For examples and tutorials see the Backline demo.

Warning

Backline is experimental and under heavy development. Its API may change without notice, and it is only usable through the Catalyst compiler.

Note

Backline requires a recent version of PennyLane, Catalyst, and Lightning. Check out the installation instructions and requirements.

Note that due to the wide range of system, network, and hardware configurations you can use Backline with, there are different installation requirements and steps depending on your needs.

Overview

Backline(*, controller[, coprocessors, ...])

A device for heterogeneous compilation and execution over a backline placement.

Controller(*[, name, hardware, backend, ...])

The node that controls the QPU and initiates data transfers.

Coprocessor(*[, name, hardware, backend, ...])

The node that runs a coprocessor function per received message.

Endpoint(host, port)

The address the controller dials to bring up a connection to a coprocessor.

get_transport(name)

Return the Transport registered under name.

Node(*[, name, hardware, backend, remote, ...])

A node in a backline fabric.

Placement(*, controller[, coprocessors, ...])

Declarative placement for heterogeneous execution.

Transport(name)

A named data transport.

register_transport(name)

Register a transport factory under name.

Backline provides the following abstractions for use with PennyLane and Catalyst.

  • Controller: The classical hardware Node (such as a CPU or FPGA) that controls the QPU(a quantum hardware or simulator qp.device), receives quantum measurement results, and initiates data transfers with other hardware devices (coprocessors). For example, it might perform quantum error correction (QEC) syndrome measurements on the QPU, and send these to a coprocessor for decoding.

    import pennylane as qp
    
    CPU = qp.Controller(
        hardware="cpu",
        executor_options={"host": "192.0.2.10", "port": 7810},
        init_args={"config": "dev=mlx5_0;gid=1"},
        device=qp.device("lightning.qubit", wires=1)
    )
    
  • Coprocessor: Hardware device Node (such as CPUs or GPUs) that receive information from a controller for processing. They run CoprocessingFuncion callables, potentially as a persistent kernel, such as a QEC decoder.

    GPU = qp.Coprocessor(
        coprocessor_fn="decoder",
        hardware="gpu",
        endpoint=qp.Endpoint("198.51.100.2", 7760),
        executor_options={"host": "192.0.2.11", "port": 7813},
        init_args={"config": "dev=mlx5_0;gid=3"},
    )
    
  • Backline: A representation of the complete hardware infrastructure supporting the quantum-classical program (Placement), packaged as a QNode device. The backline includes a Controller, zero or more Coprocessor nodes, and a transport method ("rdma", "memcpy", "none" for a controller with no coprocessors, or a Transport object). A backline object is given directly to a QNode in place of a traditional QNode qp.device, and orchestrates the remote executor and the RDMA network the controllers and coprocessors talk over, separate from the network used to log into remote machines.

    dev = qp.Backline(controller=CPU, coprocessors=[GPU], transport="rdma")
    
    @qp.qjit
    @qp.qnode(dev)
    def circuit(x):
        qp.RX(x, wires=0)
        return qp.expval(qp.Z(0))
    

Coprocessing functions and QEC

CoprocessorFunction(name[, lib_path, ...])

A precompiled function run on a Coprocessor to process messages received from the Controller.

decode(syndrome, *[, controller, ...])

Calls a coprocessor function available on the Backline to perform quantum error correction decoding --- providing a syndrome and recieving the corresponding correction.

css_bp_decoder(Hx, Hz, *[, postprocess, ...])

Compile a CSS code's Tanner graph into a coprocessor decode function for use with backline.

onnx_decoder(model, *[, provider, device, ...])

Create a coprocessor function that runs an ONNX model on each message, for use with backline.

triton_decoder(decoder_fns, **build_options)

Compile Triton quantum error correction decoder functions into a coprocessor function for use with backline.

When using a backline to execute a quantum program, there are multiple ways to incorporate quantum error correction (QEC) encoding and decoding.

Implicit QEC

If the qec_code argument is provided to the Backline object, e.g.,

qp.Backline(controller=CPU, coprocessors=[GPU], transport="rdma", qec_code="steane")

then the encoding is automatically applied when compiling via Catalyst as an MLIR compilation pass — the string provided must correspond to an existing Catalyst QEC encoding pass.

Here, the circuit defined in the PennyLane frontend for execution represents a logical circuit; QEC decoding will automatically be applied. The decoding function to be executed on the coprocessor can be specified in multiple ways:

  • A Triton kernel: The provided function triton_decoder() compiles a Python Triton decoder function into a shared library that can be used as a coprocessing function. Alternatively, css_bp_decoder() is a convenience function to compile a CSS Tanner graph to a belief proagation decoder using Triton.

  • An ONNX model: onnx_decoder() runs a model exported to ONNX on each message, on the CPU or on the GPU the installed onnxruntime supports, with no build step.

  • A precompiled library: CoprocessorFunction registers a precompiled library symbol and (optionally) the library path.

The coprocessor decoding function can then be provided when defining the Coprocessor.

Note

Catalyst ships with a built-in Steane GPU decoding library. This can be specified via the string coprocessor_fn="gpu_steane_launcher".

Explicit QEC

If the qec_code argument is not provided to the Backline object, then no automatic encoding or decoding will occur. It will be assumed that the circuit defined in the PennyLane frontend represents a physical circuit; encoding and decoding should be manually defined in the frontend.

To manually encode the circuit, this can be done explicitly in Python, or by manually applying an MLIR or xDSL compilation pass.

To manually decode the circuit, the decode() function can be used within the QNode to call a registered coprocessing function — providing a measured syndrome as input and returning a correction.

qdev = qp.device("lightning.qubit", wires=3)
CPU1 = qp.Controller(device=qdev)
CPU2 = qp.Coprocessor(coprocessor_fn="some_decoder")

dev = qp.Backline(controller=CPU1, coprocessors=[CPU2], transport="memcpy")

@qp.qjit(capture=True, autograph=True)
@qp.qnode(dev)
def circuit():
    # logical circuit
    ...

    # measure qubits to extract syndromes
    z_syndrome, x_syndrome = extract_syndromes()

    # manual decoding
    correction_z = qp.backline.decode(x_syndrome, decoder_id=0)

    for q in range(N):
        if correction_x[q]:
            qp.X(wires=q)

    return qp.expval(qp.Z(0))

Runtime calls

runtime_call(target, *args[, signature, ...])

Call a declared runtime symbol, in-process or on the executor it is addressed to.

runtime_declare(symbol, spec[, library])

Declare the signature of a runtime symbol so it can be called by name.

CSignature(symbol, params[, result, library])

The C signature of a runtime symbol.

CType(*values)

A C type in a CSignature.

For explicit control of runtime calls, Catalyst additionally provides functionality to call a runtime entry point directly within the qjit compiled function, by its C symbol name.

A symbol is declared with runtime_declare() and called with runtime_call() from inside a compiled program. The call can be dispatched to an executor, which invokes the symbol on the machine the runtime lives on.