# 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.
""":func:`~pennylane.backline.decode` -- the explicit per-round syndrome->correction decode.
:func:`decode` emits one transport round from inside a captured QNode: resolve the controller's
session, stage the syndrome, post the round, collect the reply.
Every step is a local :func:`~pennylane.runtime_call`, so the round runs in the controller's own
process through the transport C ABI that ``librt_transport`` exports. Session bring-up and teardown
come from the ``inject-transport-session`` pass; :func:`decode` only drives the round.
"""
from __future__ import annotations
import jax.numpy as jnp
import numpy as np
from pennylane import math
from .device import active_placement
from .placement import DEFAULT_MESSAGE_BYTES
from .runtime import runtime_call
# Native functions from TransportCAPI.h, named verbatim by a local runtime_call.
_PREFIX = "__catalyst__transport__"
_GET_SESSION = f"{_PREFIX}get_session"
_STAGE_PAYLOAD = f"{_PREFIX}stage_payload"
_POST = f"{_PREFIX}post"
_COLLECT = f"{_PREFIX}collect"
_CHECK = f"{_PREFIX}check"
_CHECK_SESSION = f"{_PREFIX}check_session"
_SIG_GET_SESSION = "(i32, str) -> ptr" # role, key
_SIG_STAGE_PAYLOAD = "(ptr, buf, u64, u32) -> i32" # session, src, bytes, decoder_id
_SIG_POST = "(ptr, u32) -> i32" # session, work_item_idx
_SIG_COLLECT = "(ptr, out, u64) -> i32" # session, reply(out), reply_bytes
_SIG_CHECK = "(i32, str)" # status, the call it came from
_SIG_CHECK_SESSION = "(ptr, str)" # session, the call it came from
# Mirrors catalyst::transport::Role.
ROLE_CONTROLLER = 0
ROLE_COPROCESSOR = 1
_DEFAULT_WORK_ITEM_IDX = 0
_PACKED_U64_BITS = 64
_PACKED_U64_BYTES = DEFAULT_MESSAGE_BYTES
def _session_key(coprocessor, coprocessors=()) -> str:
"""The key the controller's session for this round is registered under.
``inject-transport-session`` keys one controller session per coprocessor by
:attr:`~.Coprocessor.name`, falling back to ``"coprocessor.0"``; a placement with no
coprocessor is ``"controller"``. With several coprocessors that fallback would send every
unnamed one to the same session, so a name is required.
Raises:
ValueError: if the round targets an unnamed coprocessor and the placement holds more
than one, which no key can tell apart
"""
if coprocessor is None:
return "controller"
name = getattr(coprocessor, "name", None)
if name:
return name
if len(coprocessors) > 1:
raise ValueError(
f"decode: this round targets a coprocessor with no name, and the placement has "
f"{len(coprocessors)}. Pass coprocessor= to choose one directly."
)
return "coprocessor.0"
def _byte_count(array) -> int:
"""The number of bytes ``array`` occupies, from its shape and dtype.
Works for a JAX tracer as well as a plain array: both carry a static shape and dtype.
"""
shape = getattr(array, "shape", None)
dtype = getattr(array, "dtype", None)
if shape is None or dtype is None:
return int(np.asarray(array).nbytes)
count = 1
for dim in shape:
count *= int(dim)
return count * np.dtype(dtype).itemsize
def _resolve_out_bytes(placement, controller, out_bytes) -> int:
"""How many bytes the correction reply occupies.
Explicit ``out_bytes`` wins. Otherwise it is the reply size the placement commits, or with no
placement the controller's own size, or :data:`DEFAULT_MESSAGE_BYTES` when that is unset.
"""
if out_bytes is not None:
return int(out_bytes)
if placement is not None:
return int(placement.out_bytes)
size = getattr(controller, "out_bytes", None)
return DEFAULT_MESSAGE_BYTES if size is None else int(size)
def _resolve_nodes(controller, coprocessor):
"""Fill in whichever node the caller left out, from the built placement. An explicit node always wins."""
if controller is not None and coprocessor is not None:
return controller, coprocessor
placement = active_placement()
if placement is None:
raise ValueError(
"decode: the nodes are resolved from the placement of the device being traced, and "
"this trace has none. Build a placement, or pass the nodes explicitly: "
"decode(syndrome, controller=ctrl, coprocessor=coproc)."
)
if controller is None:
controller = placement.controller
if coprocessor is None:
coprocs = placement.coprocessors
if len(coprocs) != 1:
raise ValueError(
"decode: with multiple coprocessors, pass coprocessor= explicitly to choose the "
"transport session. decoder_id only selects the decoder inside that coprocessor."
)
coprocessor = coprocs[0]
return controller, coprocessor
def _validate_packed(syndrome, in_bytes, out_bytes):
"""Validate packed decode inputs and transport sizes."""
if in_bytes is not None and int(in_bytes) != _PACKED_U64_BYTES:
raise ValueError(
f"decode: bitpack=True requires in_bytes={_PACKED_U64_BYTES}, got {int(in_bytes)}"
)
if out_bytes is not None and int(out_bytes) != _PACKED_U64_BYTES:
raise ValueError(
f"decode: bitpack=True requires out_bytes={_PACKED_U64_BYTES}, got {int(out_bytes)}"
)
interface = (
math.get_interface(*syndrome)
if isinstance(syndrome, (tuple, list))
else math.get_interface(syndrome)
)
if interface == "jax":
syndrome = jnp.asarray(syndrome, dtype=jnp.uint8)
else:
syndrome = np.asarray(syndrome, dtype=np.uint8)
if syndrome.ndim != 1:
raise ValueError("decode: packed syndromes must be a 1D bit vector")
if int(syndrome.shape[0]) > _PACKED_U64_BITS:
raise ValueError(
f"decode: packed syndromes support at most {_PACKED_U64_BITS} bits, got {int(syndrome.shape[0])}"
)
return syndrome
def _pack(syndrome):
"""Pack a syndrome bit vector into 8 little-endian bytes."""
if math.get_interface(syndrome) == "jax":
xp = jnp
else:
xp = np
packed = xp.packbits(syndrome, bitorder="little")
# HACK: ``packbits`` returns the minimal byte width, but for bitpack=True transport payloads
# are always exactly 8 bytes, so pad and slice to get the right size
packed = xp.pad(packed, (0, _PACKED_U64_BYTES))[:_PACKED_U64_BITS]
return packed
def _unpack(correction):
"""Unpack 8 little-endian bytes into a 64-entry boolean bit vector."""
if math.get_interface(correction) == "jax":
xp = jnp
else:
xp = np
return math.cast(xp.unpackbits(correction, bitorder="little", count=_PACKED_U64_BITS), bool)
[docs]
def decode( # pylint: disable=too-many-arguments
syndrome,
*,
controller=None,
coprocessor=None,
out_bytes=None,
in_bytes=None,
decoder_id=0,
work_item_idx=_DEFAULT_WORK_ITEM_IDX,
bitpack=True,
library=None,
):
r"""Calls a coprocessor function available on the :class:`~.Backline` to perform quantum error correction
decoding --- providing a syndrome and recieving the corresponding correction.
``decode`` is implemented internally as a series of :func:`~pennylane.runtime_call`, with the
communication driven from the controller's own process over the session that
``inject-transport-session`` brought up from the device's placement.
.. warning::
:mod:`Backline <.backline>` is experimental and only usable through the Catalyst
compiler. :func:`decode` must be called inside a ``@qjit`` program, within a QNode executing
on a :class:`~.Backline`. Calling it in any other context will fail.
Args:
syndrome: The syndrome to send. Passed by data pointer, so its byte length comes from its
shape and dtype at compile time. With ``bitpack=True``, this must be a 1D bit vector
with at most 64 entries.
controller (Controller): The :class:`~.Controller` whose session drives the round.
coprocessor (Coprocessor | None): The :class:`~.Coprocessor` the round targets. Selects the
session key; which coprocessor serves the round is otherwise fixed by the session's
configuration.
out_bytes (int, None): The correction reply size in bytes. Defaults to the placement's
:attr:`~.Placement.out_bytes`.
in_bytes (int, None): How many bytes of ``syndrome`` to send, at most what the round was
committed to carry. Defaults to ``syndrome``'s full byte length.
decoder_id (int): Which coprocessor-side decoder handles this round.
work_item_idx (int): The committed work-item index to post.
bitpack (bool): Pack syndrome bits into 8-byte payload and unpack reply to 64-bit vector.
library (str, None): Shared library exporting the transport symbols, recorded so the
compiler links it. Defaults to ``None``, relying on ``librt_transport`` already being
loaded.
Returns:
The correction reply, as a ``uint8`` buffer of ``out_bytes`` bytes, or a 64-entry boolean
bit vector when ``bitpack=True``.
Raises:
ValueError: if the round targets an unnamed coprocessor which cannot be resolved as the
placement holds more than one coprocessor.
.. seealso:: :class:`~.Controller`, :class:`~.Coprocessor`,
:class:`~pennylane.Backline`
**Example**
.. code-block:: python
import pennylane as qp
con = qp.Controller(
device=qp.device("null.qubit", wires=2),
executor_options={"host": "192.168.3.15", "port": 7810},
)
coproc = qp.Coprocessor(
coprocessor_fn="decoder",
name="decoder-0",
hardware="gpu",
endpoint=qp.Endpoint("192.168.1.3", 18590),
)
dev = qp.Backline(controller=con, coprocessors=[coproc], transport="rdma")
@qp.qjit(capture=True)
@qp.qnode(dev)
def circuit(syndrome):
# one round: stage the syndrome, post it, wait for the correction
correction = qp.backline.decode(syndrome)
qp.cond(correction[0] == 1, qp.X)(0)
return qp.expval(qp.Z(0))
"""
controller, coprocessor = _resolve_nodes(controller, coprocessor)
placement = active_placement()
key = _session_key(coprocessor, placement.coprocessors if placement is not None else ())
if bitpack:
syndrome = _pack(_validate_packed(syndrome, in_bytes, out_bytes))
nbytes = _PACKED_U64_BYTES
reply_bytes = _PACKED_U64_BYTES
else:
nbytes = _byte_count(syndrome) if in_bytes is None else int(in_bytes)
reply_bytes = _resolve_out_bytes(placement, controller, out_bytes)
# The live controller session the setup pass registered under `key`.
session = runtime_call(
_GET_SESSION, ROLE_CONTROLLER, key, signature=_SIG_GET_SESSION, library=library
)
runtime_call(
_CHECK_SESSION, session, "get_session", signature=_SIG_CHECK_SESSION, library=library
)
# Copy `nbytes` into the outbound slot and stamp `decoder_id`, then start the round trip.
_checked(
_STAGE_PAYLOAD,
session,
syndrome,
nbytes,
decoder_id,
signature=_SIG_STAGE_PAYLOAD,
library=library,
)
# Start the round trip
_checked(_POST, session, work_item_idx, signature=_SIG_POST, library=library)
# Wait for the reply
_, correction = _checked(
_COLLECT,
session,
reply_bytes,
signature=_SIG_COLLECT,
out_bytes=reply_bytes,
library=library,
)
return _unpack(correction) if bitpack else correction
def _checked(symbol, *args, signature, library, **kwargs):
"""Call a transport function that returns a status, then stop the program if it failed."""
result = runtime_call(symbol, *args, signature=signature, library=library, **kwargs)
status = result[0] if isinstance(result, tuple) else result
runtime_call(
_CHECK, status, symbol.removeprefix(_PREFIX), signature=_SIG_CHECK, library=library
)
return result