Source code for pennylane.backline.runtime.runtime_call

# 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.

"""Calling a runtime, either as an operation on a backend or as a bare symbol."""

from __future__ import annotations

import functools

from jax._src.core import trace_state_clean

from . import operands
from .signature import CSignature, CType, declare, signature_of


def _tracing() -> bool:
    """Whether a JAX trace is open, which is where a recorded call belongs."""
    return not trace_state_clean()


@functools.lru_cache(maxsize=1)
def get_runtime_call_prim():
    """Get the primitive that backs :func:`runtime_call`, creating it on the first call."""

    # pylint: disable-next=import-outside-toplevel
    from pennylane.capture.custom_primitives import QpPrimitive

    runtime_call_prim = QpPrimitive("runtime_call")
    runtime_call_prim.multiple_results = True

    @runtime_call_prim.def_abstract_eval
    # pylint: disable-next=too-many-arguments,unused-argument
    def _(*args, signature, symbol, out_bytes, dispatch, library, local_constants):
        return operands.result_avals(signature, out_bytes)

    return runtime_call_prim


[docs] def runtime_call(target, *args, signature=None, out_bytes=0, address=None, library=None): r"""Call a declared runtime symbol, in-process or on the executor it is addressed to. A symbol is declared once with :func:`~pennylane.runtime_declare`, then called by name from inside a :func:`~pennylane.qjit` program. For a one-off call, pass its signature with ``signature=`` or pass a :class:`~pennylane.backline.runtime.CSignature` as ``target``. Passing ``address`` dispatches the call: it is recorded into the program and sent to that executor, which invokes the symbol on the machine the runtime lives on. Omitting ``address`` makes the call **local**: the symbol is invoked in the process running the compiled program, through the ordinary in-process C ABI. **Dispatched** (``address`` set): A dispatched call is run by the Catalyst executor. The `lower-runtime-dispatch` pass turns it into an ``executor.call``, which reaches ``__catalyst__executor__call_wrapper`` on the addressed machine. That calls the symbol through LLVM ORC's wrapper convention. You need to have a catalyst executor running on the addressed machine, which can be enabled from within a backline-controlled QJIT function. **Local** (``address`` is ``None``): A local call is run in the process running the compiled program. The symbol is resolved and invoked directly through its declared C ABI. Scalars are passed by value, ``ptr`` is a native pointer, and ``str`` is ``const char *``. A ``buf`` or ``out`` uses compiler-internal bufferization to obtain its data pointer. ``library`` is recorded on the compiled module so the driver links the shared library that exports the symbol. Args: target (str, CSignature): the declared symbol name, or its complete signature *args: one argument per declared parameter except ``out``, in declaration order signature (str, CSignature, None): the signature for a symbol not yet declared, using the ``"(parameter, ...) -> result"`` form or a :class:`CSignature` out_bytes (int, Sequence[int]): the compile-time size of each ``out`` buffer address (str, None): the executor to dispatch to, as ``"host:port"``. ``None`` makes the call local (in-process). library (str, None): for a local call, the shared library exporting the symbol, recorded so the driver links it. Overrides the library set at :func:`~pennylane.runtime_declare` time. Ignored for a dispatched call. Returns: The symbol's declared result. A symbol with one ``out`` parameter returns ``(result, buffer)``. With several, the buffers follow the result in the order they are declared. A local call to a ``void`` symbol returns ``None``. **Example** .. code-block:: python import pennylane as qp qp.runtime_declare("example_call_rounds", "(ptr, u32) -> u64") def program(session): # the body of a qjit program return qp.runtime_call("example_call_rounds", session, 100000, address="board:9000") A symbol that fills a buffer declares it as an ``out`` parameter. The caller does not pass one: it asks for ``out_bytes=`` and gets the filled buffer back alongside the result. .. code-block:: python qp.runtime_declare("example_call_collect", "(ptr, out, u64) -> i32") def collect(session): status, reply = qp.runtime_call( "example_call_collect", session, 64, out_bytes=64, address="board:9000", ) return reply For example, the above call to this symbol declared ``(ptr, out, u64) -> i32``: * ``session`` is the ``ptr``. * The ``out`` takes no argument. The symbol writes that buffer, so there is nothing to pass in. * ``64`` is the ``u64``: this symbol's own argument for how many bytes it may write. * ``out_bytes=64`` says how big a buffer to give it. The number shows up twice because one is what you tell the symbol and the other is what you hand it, so keep the two in step. * The call returns two results: ``status``, the ``i32`` the symbol returned, and ``reply``, which corresponds to the ``out`` buffer it filled in, as a ``uint8`` array of ``out_bytes`` bytes. A symbol can declare more than one ``out``. Give ``out_bytes`` one size per buffer, and they return in the order they are declared, for example: .. code-block:: python qp.runtime_declare("example_call_two_regions", "(ptr, out, out, u64) -> i32") def collect_both(session): status, first, second = qp.runtime_call( "example_call_two_regions", session, 96, out_bytes=(32, 64), address="board:9000", ) return first, second .. seealso:: :func:`~pennylane.runtime_declare` """ resolved = _resolve_signature(target, signature) sizes = operands.out_sizes(resolved, out_bytes) lib = library if library is not None else resolved.library return _record(resolved, args, sizes, address, lib)
def _record(signature: CSignature, args, sizes, address, library): """Record a call on a declared symbol, dispatched to an executor or invoked in-process. Either dispatching to an executor (``address`` set) or invoking in-process (``address`` is ``None``), the call becomes one ``catalyst.runtime_call`` carrying the symbol and its C signature. For a local call, it further lowers to a direct ``llvm.call`` using scalar and pointer C ABI types, with buffered arguments reduced to their data pointers. For remote calls, it becomes an ``executor.call``, which flattens the arguments into one buffer and invokes the symbol through LLVM ORC's wrapper convention. """ if not _tracing(): raise RuntimeError( f"{signature.symbol} is being called outside a compiled program. A recorded call is " f"only valid inside a qjit function." ) if address is not None and signature.result is CType.VOID and not sizes: raise TypeError( f"{signature.symbol}{signature} returns nothing, a dispatched call to it has no result." ) call_operands, local_constants = operands.operands_for( signature, args, dispatched=address is not None ) results = get_runtime_call_prim().bind( *call_operands, signature=signature, symbol=signature.symbol, out_bytes=sizes, dispatch=address, library=library, local_constants=local_constants, ) value = None if signature.result is CType.VOID else results[0][0] buffers = results[0 if signature.result is CType.VOID else 1 :] if not sizes: return value return (value, *buffers) if len(buffers) > 1 else (value, buffers[0]) def _resolve_signature(symbol, signature) -> CSignature: """Work out which signature a symbol call site means.""" if isinstance(symbol, CSignature): if signature is not None: raise ValueError("pass either a CSignature or signature=, not both") return symbol if signature is None: return signature_of(symbol) if isinstance(signature, CSignature): return signature return declare(symbol, signature)