qp.runtime_call

runtime_call(target, *args, signature=None, out_bytes=0, address=None, library=None)[source]

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

A symbol is declared once with runtime_declare(), then called by name from inside a qjit() program. For a one-off call, pass its signature with signature= or pass a 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.

Parameters:
  • 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 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 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

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.

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:

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