qp.Controller

class Controller(*, name=None, hardware='cpu', backend=None, remote=False, executor_options=None, executor=None, init_args=<factory>, device=None, in_bytes=None, out_bytes=None)[source]

Bases: Node

The node that controls the QPU and initiates data transfers.

The controller runs the QNode and is the data-initiator during a decoding step: it sends syndromes to the coprocessors and receives corrections back. Pass it to Backline to build a device.

Warning

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

Keyword Arguments:
  • name (str, None) – A name identifying the controller. Defaults to None, letting the compiler derive one from the node’s role.

  • hardware (str) – The hardware the controller executes on. Defaults to "cpu"; other allowed values are "fpga". "gpu" is not accepted as a controller. The compiler combines this with the placement’s Transport to select the runtime backend.

  • backend (str, None) – The transport backend this node runs on. Defaults to None, which lets the compiler choose from the transport and hardware: cpu_verbs for "rdma" on cpu and memcpy for "memcpy". On fpga, pick the backend that matches the image on the board: hwhs (the default), hsb_hwhs or balboa_hwhs. Each coprocessor sets the matching peer= in its config: catalyst for hwhs (the default, so it can be omitted), hsb for hsb_hwhs and balboa for balboa_hwhs. Catalyst’s Backline documentation lists all backends.

  • remote (bool) – Whether the controller runs on another machine. Defaults to False.

  • executor_options (dict, None) – Options for the executor to launch for this controller. Defaults to None, which runs the node in this process. See the executor_options attribute below for every option it accepts.

  • executor (object, None) – An already-launched executor to attach. Defaults to None, in which case the compiler builds one from executor_options.

  • init_args (dict) – Backend-specific initialization arguments. Empty by default. See the init_args attribute below for the keys it accepts.

  • device (pennylane.devices.Device, None) – The PennyLane device the controller executes. Defaults to None, which builds a null.qubit.

  • in_bytes (int, None) – The size in bytes of each message the controller sends. Which sizes are supported depends on the transport backend the compiler selects for each node, and a size no available backend carries is reported when the program is compiled. Defaults to None (unset), in which case the placement sends the size the coprocessors’ functions declare (as onnx_decoder() does from its model), or else DEFAULT_MESSAGE_BYTES. See in_bytes. A size passed explicitly must match what they declare.

  • out_bytes (int, None) – The size in bytes of each reply the controller receives. Defaults to None, resolved like in_bytes (see out_bytes) and checked the same way.

See Node for the options every node shares.

See also

Coprocessor, Backline

Example

In the simplest case the controller runs in this process, on a default null.qubit:

>>> con = qp.Controller()
>>> con.device.name
'null.qubit'

Pass a device to run a real simulation, and deployment options to run it on another machine:

con = qp.Controller(
    device=qp.device("lightning.qubit", wires=4),
    name="cpu-controller",
    hardware="cpu",
    remote=True,
    executor_options={"host": "192.0.2.10", "port": 7810},
    init_args={"config": "dev=mlx5_0;gid=1"},
)

Either way, the controller is passed to Backline to build a device:

dev = qp.Backline(controller=con, transport="rdma")

backend

The name of the transport backend to run this node on, out of those in Catalyst's transport backend registry that implement the placement's transport on this node's hardware.

device

The PennyLane device the controller executes.

executor

The launched executor this node runs on.

executor_options

Options for the executor to launch for this node, passed to it as keyword arguments.

hardware

The hardware this node executes on.

in_bytes

The size in bytes of each message the controller sends, at least 1, or None (the default) when unset.

name

An optional name used to reference this node.

out_bytes

The size in bytes of each reply the controller receives, at least 1, or None (the default) when unset.

remote

Whether this node runs on another machine, so that the libraries it loads are the ones installed beside it there rather than the ones in this installation.

init_args

Backend-specific initialization arguments, forwarded to the transport backend.

backend = None

The name of the transport backend to run this node on, out of those in Catalyst’s transport backend registry that implement the placement’s transport on this node’s hardware. Defaults to None, letting the compiler pick the default one. Naming one selects a backend that is not a default, such as "fpga_verbs", or one installed by a backend package.

device = None

The PennyLane device the controller executes. Defaults to None, which builds a null.qubit over DEFAULT_WIRES wires. A controller needing more wires, or an actual simulation, should pass a device of its own.

executor = None

The launched executor this node runs on. Created automatically by the compiler from executor_options; set it directly to attach one that is already launched, in which case executor_options is ignored.

executor_options = None

Options for the executor to launch for this node, passed to it as keyword arguments. None (the default) requests no executor, leaving the node in this process.

Which machine, and how it is reached

  • "host" (str) - deploy the executor to this host over ssh. Requires "port", so that the address is known without having to reach the host at compile time.

  • "address" (str) - "host:port" of an executor whose lifetime is managed elsewhere. Attach to it rather than launching one.

  • "port" (int) - the port the executor binds on the target, and the local end of the ssh tunnel reaching it. Omit it for a local executor and the compiler picks a free port.

  • "user" (str) - the ssh account on the remote host. Defaults to the local username.

Naming neither "host" nor "address" runs the executor as a subprocess on this machine.

What is placed on the target

  • "workspace" (str) - the directory the executor runs in. Defaults to a generated catalyst-exec-* directory removed on teardown; one named here is left in place.

  • "deploy" (list[str]) - files and directories copied into the workspace before the executor starts. A directory contributes the files inside it, which is how a cross-built set of artifacts travels.

  • "plugins" (list[str]) - shared libraries the executor loads at startup, in order. They share one symbol namespace, so the first definition wins. The compiler appends the libraries this node implies - a coprocessor’s decode function, a controller’s device runtime - if they are not already listed.

  • "executor_bin" (str) - the command that starts the executor, for wrapping it in something like numactl.

How the process runs

  • "env" (dict[str, str]) - environment variables for the executor process.

  • "sudo" (bool) - run it as root, for a target whose devices are not world-accessible. Defaults to False.

  • "sudo_password_env" (str) - name of the environment variable holding the password to pipe to sudo -S, e.g. "MY_HOST_SUDO_PW". If unset and sudo is required, a prompt will launch for the password; unnecessary with passwordless sudo.

  • "ready_timeout" (float) - seconds to wait for the executor to report that it bound its port. Defaults to 60.0.

  • "verbose" (int) - how much the launcher logs: 0 quiet, 1 normal, 2 per-command detail.

Code generation and identity

  • "triple" (str) - the LLVM target triple to compile this node’s code for. Omit it and the executor detects it from the target’s uname, which requires reaching the host.

  • "name" (str) - the executor’s own label, used in its log filenames. Defaults to this node’s name.

Note that "port" here is the executor’s, on the channel that ships compiled code. It is unrelated to port, which is the transport’s handshake port. An unrecognized key raises.

Warning

These options are defined by the Catalyst compiler, and may not be stable.

hardware = 'cpu'

The hardware this node executes on. The compiler combines this with the placement’s Transport to select the runtime backend.

in_bytes = None

The size in bytes of each message the controller sends, at least 1, or None (the default) when unset. The size a placement sends is its in_bytes.

name = None

An optional name used to reference this node.

out_bytes = None

The size in bytes of each reply the controller receives, at least 1, or None (the default) when unset. The size a placement receives is its out_bytes.

remote = False

Whether this node runs on another machine, so that the libraries it loads are the ones installed beside it there rather than the ones in this installation. Defaults to False.

This is about the machine, not the process: it says where the node’s libraries are resolved, and executor_options independently says whether its code runs in a process of its own. The three valid combinations are:

  • remote=True with executor_options: out-of-process on another machine, reached by deploying an executor there. A remote node cannot be reached without one.

  • remote=False with executor_options: out-of-process on this machine, in an executor subprocess whose libraries still resolve from this installation.

  • remote=False with no executor_options: in-process, the default.

init_args = <dataclasses._MISSING_TYPE object>

Backend-specific initialization arguments, forwarded to the transport backend. Empty by default (never None). The keys the compiler forwards are

  • "backend_lib" (str) - explicit path to the transport backend library, taking precedence over hardware and over lib_path.

  • "config" (str) - a ;-separated key=value string configuring the backend on this machine, e.g. "dev=mlx5_0;gid=3". dev and gid select the RDMA device and GID index; the remaining keys are backend-specific (a GPU backend takes gpu=, an FPGA engine takes sq_mem=/data_mem=/reply_mem=). An RDMA coprocessor also takes peer=, the kind of controller it answers: catalyst, the default, for the controllers Catalyst ships (cpu_verbs, hwhs, fpga_verbs), hsb for hsb_hwhs, and balboa for balboa_hwhs. For more information about how to build and load the required FPGA images, please refer to the backline and backline-vpk120 repositories.

Keys outside this set are rejected when the program is compiled.