# Copyright 2026 Xanadu Quantum Technologies Inc.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Placement types and node constructors for backline heterogeneous compilation and execution."""
from collections.abc import Sequence
from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Literal, get_args
from pennylane.devices.device_constructor import device as _make_device
from .functions import CoprocessorFunction
from .transports import Transport, get_transport
if TYPE_CHECKING:
from pennylane.devices import Device
# Wires given to the ``null.qubit`` device a :class:`~.Controller` falls back to.
DEFAULT_WIRES = 32
DEFAULT_MESSAGE_BYTES = 8
"""The default size, in bytes, of a controller's messages in each direction."""
Hardware = Literal["cpu", "gpu", "fpga"]
"""Hardware on which a backline node executes."""
_SUPPORTED_HARDWARE = frozenset(get_args(Hardware))
[docs]
@dataclass(frozen=True)
class Endpoint:
"""The address the controller dials to bring up a connection to a coprocessor.
The coprocessor listens on :attr:`port`; the controller connects to :attr:`host`\\ ``:``\\
:attr:`port`. Some transports, such as ``"rdma"``, require an endpoint on every coprocessor;
others, such as ``"memcpy"``, do not use a network endpoint. For a coprocessor co-located with
the controller on a transport that does require one, use localhost (``"127.0.0.1"``).
Args:
host (str): The address the controller connects to, e.g. ``"192.0.2.11"`` or
``"127.0.0.1"``.
port (int): The port the coprocessor listens on for the out-of-band connection handshake.
This is the handshake channel that exchanges the information needed to set up the data
path.
.. seealso:: :class:`~.Coprocessor`
**Example**
>>> ep = qp.Endpoint("127.0.0.1", 7760)
>>> (ep.host, ep.port)
('127.0.0.1', 7760)
"""
host: str
"""The address the controller connects to, e.g. ``"192.0.2.11"`` or ``"127.0.0.1"``."""
port: int
"""The port the coprocessor listens on for the out-of-band connection handshake. This is the
handshake channel that exchanges the information needed to set up the data path."""
def __post_init__(self):
if not isinstance(self.host, str):
raise TypeError(f"host must be a str, got {type(self.host).__name__}: {self.host!r}")
if not self.host:
raise ValueError("host must be a non-empty str")
if not isinstance(self.port, int):
raise TypeError(f"port must be an int, got {type(self.port).__name__}: {self.port!r}")
if not 1 <= self.port <= 65535:
raise ValueError(f"port must be in 1..65535, got {self.port}")
[docs]
@dataclass(frozen=True, kw_only=True)
class Node:
"""A node in a backline fabric.
Base class for :class:`~.Controller` and :class:`~.Coprocessor`. It carries the node's name and
hardware, how its code is deployed, and any backend-specific initialization arguments. Nodes
are assembled into a device with :class:`~pennylane.Backline`.
.. warning::
:mod:`Backline <.backline>` is experimental and only usable through the Catalyst
compiler.
Keyword Args:
name (str, None): A name identifying this node. Defaults to ``None``, letting the compiler
derive one from the node's role.
hardware (str): The hardware this node executes on. Defaults to ``"cpu"``; other allowed values are
``gpu`` and ``fpga`. The compiler
combines this with the placement's :class:`~.Transport` to select the runtime backend.
backend (str, None): The name of the transport backend to run this node on. Defaults to
``None``, letting the compiler pick the default backend for the transport and hardware.
remote (bool): Whether this node runs on another machine. Defaults to ``False``.
executor_options (dict, None): Options for the executor to launch for this node.
Defaults to ``None``, which runs the node in this process. See the
:attr:`~.Node.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 :attr:`executor_options`.
init_args (dict): Backend-specific initialization arguments. Empty by default. See the
:attr:`~.Node.init_args` attribute below for the keys it accepts.
.. seealso:: :class:`~.Controller`, :class:`~.Coprocessor`, :class:`~pennylane.Backline`
"""
name: str | None = None
"""An optional name used to reference this node."""
hardware: Hardware = "cpu"
"""The hardware this node executes on. The compiler combines this with the placement's
:class:`~.Transport` to select the runtime backend."""
backend: str | None = 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."""
remote: bool = 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
:attr:`executor_options` independently says whether its code runs in a process of its own. The
three valid combinations are:
* ``remote=True`` with :attr:`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 :attr:`executor_options`: out-of-process on this machine, in an executor
subprocess whose libraries still resolve from this installation.
* ``remote=False`` with no :attr:`executor_options`: in-process, the default.
"""
executor_options: dict | None = 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 :attr:`name`.
Note that ``"port"`` here is the executor's, on the channel that ships compiled code. It is
unrelated to :attr:`~.Endpoint.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.
"""
executor: object | None = None
"""The launched executor this node runs on. Created automatically by the compiler from
:attr:`executor_options`; set it directly to attach one that is already launched, in which case
:attr:`executor_options` is ignored."""
init_args: dict = field(default_factory=dict)
"""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 :attr:`hardware` and over :attr:`~.CoprocessorFunction.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 <https://github.com/PennyLaneAI/backline>`__ and
`backline-vpk120 <https://github.com/PennyLaneAI/backline-vpk120>`__ repositories.
Keys outside this set are rejected when the program is compiled.
"""
def __post_init__(self):
if self.hardware not in _SUPPORTED_HARDWARE:
raise ValueError(
f"hardware must be one of {sorted(_SUPPORTED_HARDWARE)}, got {self.hardware!r}"
)
[docs]
@dataclass(frozen=True, kw_only=True)
class Controller(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 :class:`coprocessors <.Coprocessor>` and receives corrections back. Pass it to
:class:`~pennylane.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 Args:
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 :class:`~.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
<https://docs.pennylane.ai/projects/catalyst/en/latest/dev/backline.html>`__ 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
:attr:`~.Node.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 :attr:`executor_options`.
init_args (dict): Backend-specific initialization arguments. Empty by default. See the
:attr:`~.Node.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 :func:`~.onnx_decoder` does from its model), or
else :data:`DEFAULT_MESSAGE_BYTES`. See :attr:`~.Placement.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 :attr:`~.Placement.out_bytes`) and
checked the same way.
See :class:`~.Node` for the options every node shares.
.. seealso:: :class:`~.Coprocessor`, :class:`~pennylane.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:
.. code-block:: python
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 :class:`~pennylane.Backline` to build a device:
.. code-block:: python
dev = qp.Backline(controller=con, transport="rdma")
"""
device: "Device | None" = None
"""The PennyLane device the controller executes. Defaults to ``None``, which builds a
``null.qubit`` over :data:`DEFAULT_WIRES` wires. A controller needing more wires, or an actual
simulation, should pass a device of its own."""
in_bytes: int | None = field(default=None, repr=False)
"""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 :attr:`~.Placement.in_bytes`."""
out_bytes: int | None = field(default=None, repr=False)
"""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 :attr:`~.Placement.out_bytes`."""
def __post_init__(self):
super().__post_init__()
for name in ("in_bytes", "out_bytes"):
value = getattr(self, name)
if value is None:
continue
if isinstance(value, bool) or not isinstance(value, int):
raise TypeError(f"{name} must be an int, got {type(value).__name__}")
if value < 1:
raise ValueError(f"{name} must be at least 1, got {value}")
if self.device is None:
object.__setattr__(self, "device", _make_device("null.qubit", wires=DEFAULT_WIRES))
[docs]
@dataclass(frozen=True, kw_only=True)
class Coprocessor(Node):
"""The node that runs a coprocessor function per received message.
A coprocessor receives messages from the :class:`controller <.Controller>` (e.g., syndromes).
The :attr:`coprocessor_fn` is used to process the message, and sends the result back (e.g.,
corrections). Depending on the connection type, a :attr:`coprocessor_fn` may be a persistent
kernel. Pass coprocessors to :class:`~pennylane.Backline` to build a device.
The coprocessor owns the connection :attr:`endpoint`: it listens on :attr:`Endpoint.port`, and
the controller dials :attr:`Endpoint.host`\\ ``:``\\ :attr:`Endpoint.port` to bring the
connection up.
.. warning::
:mod:`Backline <.backline>` is experimental and only usable through the Catalyst
compiler.
Keyword Args:
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 coprocessing function executes on. Defaults to ``"cpu"``; other allowed values are
``gpu``. ``fpga`` is not currently accepted for a coprocessor. The compiler
combines this with the placement's :class:`~.Transport` to select the runtime backend.
backend (str, None): The name of the transport backend to run this node on. Defaults to
``None``, letting the compiler pick the default backend for the transport and hardware.
remote (bool): Whether the coprocessor runs on another machine. Defaults to ``False``.
coprocessor_fn (str, CoprocessorFunction): The function that processes each received
message. A string is wrapped in a :class:`~.CoprocessorFunction` naming that symbol, so
reading the attribute back always gives a :class:`~.CoprocessorFunction`.
endpoint (Endpoint, None): The address the controller dials to reach this coprocessor.
Some transports, such as ``"rdma"``, require it; others, such as ``"memcpy"``, do not
use a network endpoint and may leave it unset.
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
:attr:`~.Node.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 :attr:`executor_options`.
init_args (dict): Backend-specific initialization arguments. Empty by default. See the
:attr:`~.Node.init_args` attribute below for the keys it accepts.
See :class:`~.Node` for the options every node shares.
.. seealso:: :class:`~.Controller`, :class:`~.CoprocessorFunction`, :class:`~.Endpoint`,
:class:`~pennylane.Backline`
**Example**
A coprocessor co-located with the controller needs only a function (and, for ``"rdma"``, a
loopback endpoint):
>>> coproc = qp.Coprocessor(coprocessor_fn="decoder", endpoint=qp.Endpoint("127.0.0.1", 7760))
>>> coproc.coprocessor_fn.name
'decoder'
A remote GPU decoder names its endpoint, its hardware, and how to deploy to it:
.. code-block:: python
coproc = qp.Coprocessor(
name="gpu-decoder",
coprocessor_fn="decoder",
hardware="gpu",
endpoint=qp.Endpoint("198.51.100.2", 7760),
remote=True,
executor_options={"host": "192.0.2.11", "port": 7813},
init_args={"config": "dev=mlx5_0;gid=3;gpu=0"},
)
Note that :attr:`Endpoint.host` and ``executor_options["host"]`` are two addresses for the
*same* machine: the first is the interface the transport's data path uses, the second is how
the compiler reaches it to deploy code.
Coprocessors are passed to :class:`~pennylane.Backline` as a sequence:
.. code-block:: python
dev = qp.Backline(controller=qp.Controller(), coprocessors=[coproc], transport="rdma")
"""
coprocessor_fn: str | CoprocessorFunction
"""The function for processing each received message. Accepts a
:class:`~.CoprocessorFunction`, or a string naming the symbol, which is wrapped in one on
construction - so this attribute always reads back as a :class:`~.CoprocessorFunction`. The
symbol itself is resolved later, by the runtime."""
endpoint: Endpoint | None = None
"""The address the controller dials to reach this coprocessor. Some transports, such as
``"rdma"``, require it; others, such as ``"memcpy"``, do not use a network endpoint and may
leave it unset."""
def __post_init__(self):
super().__post_init__()
if isinstance(self.coprocessor_fn, str):
object.__setattr__(self, "coprocessor_fn", CoprocessorFunction(self.coprocessor_fn))
[docs]
@dataclass(frozen=True, kw_only=True)
class Placement:
"""Declarative placement for heterogeneous execution.
Contains a :class:`controller <.Controller>` node, any :class:`coprocessor <.Coprocessor>`
nodes, and the :class:`transport <.Transport>` that carries data between them. Rather than
constructing this directly, use :class:`~pennylane.Backline` to assemble a controller,
coprocessors, and transport into a device; the resulting placement is available as
:attr:`~pennylane.Backline.placement`.
.. warning::
:mod:`Backline <.backline>` is experimental and only usable through the Catalyst
compiler.
Keyword Args:
controller (Controller): The :class:`~.Controller` running the QNode.
coprocessors (Sequence[Coprocessor]): The
:class:`coprocessing accelerators <.Coprocessor>`. Defaults to ``()``.
transport (str | Transport): Which transport carries data between nodes, as a
:class:`~.Transport` or its registry name (e.g. ``"rdma"``). A name is resolved on
construction, so this reads back as a :class:`~.Transport`. ``"none"`` places the
controller alone and cannot be used with coprocessors.
qec_code (str | None): The quantum error-correcting code the circuit is encoded for.
Defaults to ``None``, which leaves the circuit unencoded.
.. seealso:: :class:`~.Controller`, :class:`~.Coprocessor`, :class:`~.Transport`,
:class:`~pennylane.Backline`
**Example**
A placement is built for you by :class:`~pennylane.Backline` and read back off the device:
>>> con = qp.Controller(name="cpu-controller")
>>> coproc = qp.Coprocessor(coprocessor_fn="decoder", endpoint=qp.Endpoint("127.0.0.1", 7760))
>>> dev = qp.Backline(controller=con, coprocessors=[coproc], transport="rdma")
>>> dev.placement.transport
Transport(name='rdma')
>>> dev.placement.controller.name
'cpu-controller'
>>> len(dev.placement.coprocessors)
1
:attr:`coprocessors` accepts any sequence and is normalized to a tuple, and :attr:`transport`
accepts either a registry name or a :class:`~.Transport`:
>>> isinstance(dev.placement.coprocessors, tuple)
True
"""
controller: Controller
"""The :class:`~.Controller` running the QNode."""
coprocessors: Sequence["Coprocessor"] = ()
"""The :class:`coprocessing accelerators <.Coprocessor>`. Any sequence is accepted, and is
stored as a tuple."""
transport: str | Transport
"""Which transport carries data between nodes. Accepts a :class:`~.Transport`, or its registry
name (e.g. ``"rdma"``), which is resolved with :func:`~.get_transport` on construction - so
this attribute always reads back as a :class:`~.Transport`. The transport itself is implemented
in the compiled runtime."""
qec_code: str | None = None
"""The quantum error-correcting code for logical qubit encoding, e.g. ``"steane"``. Naming it
here lets the compiler encode the circuit, and no separate lowering step is needed. Defaults to
``None``, which leaves the circuit unencoded."""
in_bytes: int = field(init=False, repr=False)
"""The size in bytes of each message the controller sends to every coprocessor: the
controller's :attr:`~.Controller.in_bytes` when set, else the size its coprocessors' functions
declare (:attr:`~.CoprocessorFunction.message_bytes`), else :data:`DEFAULT_MESSAGE_BYTES`."""
out_bytes: int = field(init=False, repr=False)
"""The size in bytes of each reply the controller receives, resolved like :attr:`in_bytes`."""
def __post_init__(self):
if not isinstance(self.coprocessors, tuple):
object.__setattr__(self, "coprocessors", tuple(self.coprocessors))
if isinstance(self.transport, str):
object.__setattr__(self, "transport", get_transport(self.transport))
self._resolve_message_sizes()
if self.transport.name == "none" and self.coprocessors:
raise ValueError('Cannot use transport="none" with coprocessors')
if self.transport.name == "rdma":
for coprocessor in self.coprocessors:
# TODO: how should we handle when these fields are provided for `memcpy`
if coprocessor.endpoint is None:
raise ValueError(
"transport='rdma' requires every coprocessor to set endpoint; "
"memcpy does not require it"
)
def _resolve_message_sizes(self):
"""Set :attr:`in_bytes` and :attr:`out_bytes` from the controller's sizes and those its
coprocessors' functions declare. Raise if the functions declare different sizes, or one
differs from a size the controller sets."""
declared = []
for index, coprocessor in enumerate(self.coprocessors):
sizes = coprocessor.coprocessor_fn.message_bytes
if sizes is not None:
label = repr(coprocessor.name) if coprocessor.name else f"coprocessor {index}"
declared.append((label, sizes))
if len({sizes for _, sizes in declared}) > 1:
listed = ", ".join(f"{label} expects {i} B in, {o} B out" for label, (i, o) in declared)
raise ValueError(
f"the coprocessors' functions expect different message sizes ({listed}), but the "
f"controller sends one size to every coprocessor"
)
label, expected = declared[0] if declared else (None, (None, None))
for name, size in zip(("in_bytes", "out_bytes"), expected):
given = getattr(self.controller, name)
if given is not None and size is not None and given != size:
raise ValueError(
f"the controller's {name}={given} does not match the {size} B the function of "
f"{label} expects. Leave {name} unset to take it from the function"
)
resolved = given if given is not None else size
object.__setattr__(self, name, DEFAULT_MESSAGE_BYTES if resolved is None else resolved)