qp.backline.runtime.CType

class CType(*values)[source]

Bases: Enum

A C type in a CSignature.

Types can be specified in two ways. When constructing a CSignature directly, pass uppercase enum members such as CType.PTR and CType.U32. When declaring a symbol with runtime_declare(), write their lowercase values in a string signature:

>>> import pennylane as qp
>>> from pennylane.backline.runtime import CSignature, CType
>>> CType.U32.value
'u32'
>>> direct = CSignature("example_run", (CType.PTR, CType.U32), result=CType.I32)
>>> declared = qp.runtime_declare("example_run", "(ptr, u32) -> i32")
>>> direct == declared
True

In "(ptr, u32) -> i32", the parentheses contain the parameter types in order: ptr followed by u32. The arrow separates those parameters from the i32 result type.

The supported types are:

Enum member

String token

Use

VOID

"void"

No scalar result. It is valid only as a result type; (void) also denotes no parameters.

I1

"i1"

A Python, NumPy, or JAX boolean scalar.

I8, I16, I32, I64

"i8", "i16", "i32", "i64"

A signed integer scalar of the stated width.

U8, U16, U32, U64

"u8", "u16", "u32", "u64"

An unsigned integer scalar of the stated width.

F32, F64

"f32", "f64"

A floating-point scalar of the stated width.

PTR

"ptr"

An integer address the runtime hands out and takes back, such as a session handle.

STR

"str"

A Python string or bytes-like value known at trace time. It becomes a NUL-terminated constant in the compiled module.

BUF

"buf"

Array data for a local call. Its length is not implied; declare a separate scalar parameter when the entry point needs a byte count.

OUT

"out"

A writable buffer. The caller gives its size with out_bytes= instead of passing an argument, then receives the filled buffer alongside the result.


The special types change how arguments and results are supplied. For example:

qp.runtime_declare("example_log", "(str) -> void")
qp.runtime_declare("example_transform", "(buf, u64, out) -> i32")

@qp.qjit
def program(data):
    qp.runtime_call("example_log", "starting")
    status, output = qp.runtime_call(
        "example_transform", data, data.size, out_bytes=64
    )
    return status, output

In example_log, "starting" supplies the trace-time constant STR parameter and VOID means the call has no scalar result. In example_transform, data supplies the local BUF and data.size supplies its explicit element count. The caller passes no argument for OUT; out_bytes=64 allocates it, and the filled buffer is returned as output after the I32 status result.

Note

The 64-bit types like PTR, I64, U64, F64, and a BUF of 64-bit elements need jax_enable_x64, which Catalyst turns on when it is imported.

dtype

The numpy dtype a value of this type has in a traced program.

is_constant

Whether this type has to be a compile-time constant.

is_buffer

Whether this type is passed as an array's data pointer.

is_out

Whether the entry point writes this argument instead of reading it.

VOID

I1

I8

I16

I32

I64

U8

U16

U32

U64

F32

F64

PTR

STR

BUF

OUT

dtype

The numpy dtype a value of this type has in a traced program.

None for the types that never show up as a traced scalar (VOID, STR, BUF).

is_constant

Whether this type has to be a compile-time constant.

is_buffer

Whether this type is passed as an array’s data pointer.

is_out

Whether the entry point writes this argument instead of reading it.

VOID = 'void'
I1 = 'i1'
I8 = 'i8'
I16 = 'i16'
I32 = 'i32'
I64 = 'i64'
U8 = 'u8'
U16 = 'u16'
U32 = 'u32'
U64 = 'u64'
F32 = 'f32'
F64 = 'f64'
PTR = 'ptr'
STR = 'str'
BUF = 'buf'
OUT = 'out'