Catalyst

The Catalyst Runtime is a C++ QIR (Quantum Intermediate Representation) runtime designed to execute Catalyst-compiled quantum programs. It provides an extensible architecture for backend quantum devices through the QuantumDevice public interface.

The runtime is split into two main instruction types implemented via the QuantumDevice interface:

1. Quantum Runtime (QR) instructions: Handled by methods for Qubit management, device shot noise, and quantum tape recording.
2. Quantum Instruction Set (QIS) instructions: Handled by methods for quantum operations, observables, measurements, and gradients.

A full list of supported instructions is available in RuntimeCAPI.h.

Catalyst is an MLIR-based compiler core designed for hybrid quantum-classical programs. It uses a custom quantum dialect within the MLIR framework to represent, transform, and optimize hybrid programs using a single unified representation.

Key technical characteristics include:

• Value-Semantics Representation: Quantum operations consume and produce qubit "state values". While these values are removed during lowering, they allow the dataflow of quantum operations to be represented directly in the SSA graph (similar to a DAG), enabling easier IR traversal without explicit dataflow analysis.
• Gradient Methods: Catalyst implements quantum and classical gradient methods (including parameter-shift, adjoint, and finite-difference) at the IR level. These methods support programs containing embedded classical instructions and control flow.

Catalyst provides three main types of callbacks depending on your needs:

1. debug.callback: For functions with no return values. Ideal for runtime debugging, logging, or printing.
2. pure_callback: For pure functions (no side-effects) that return values. Requires explicit type signatures and manual VJP rules for differentiation.
3. accelerate: For jax.jit compatible functions. Does not require upfront type signatures and supports automatic autodifferentiation and execution on accelerators (GPUs/TPUs).

Additionally, catalyst.debug.print is available as a convenient wrapper around the Python print function for runtime printing support.

Ahead-of-time (AOT) compilation allows you to trigger compilation at the function definition stage without providing concrete values. This is achieved by specifying the argument signature in the function definition using Python scalar types or JAX's ShapedArray. This results in faster initial execution because the function is already compiled when first called.

from jax.core import ShapedArray

@qjit  # compilation happens at definition
@qp.qnode(qp.device("lightning.qubit", wires=2))
def circuit(x: complex, z: ShapedArray(shape=(3,), dtype=jnp.float64)):
    theta = jnp.abs(x)
    qp.RY(theta, wires=0)
    qp.Rot(z[0], z[1], z[2], wires=0)
    return qp.state()

>>> circuit(0.2j, jnp.array([0.3, 0.6, 0.9]))  # calls precompiled function
Array([0.75634905-0.58210002j, 0. +0.j, 0.35962678+0.14074839j, 0. +0.j], dtype=complex128)

The behavior of catalyst.measure differs from pennylane.measure in how final measurement statistics are handled:

• pennylane.measure: Averages over all potential measurements, weighted by their likelihood.
• catalyst.measure: Post-selects on the specific outcome that was measured. This post-selected measurement changes with every execution.

Catalyst follows the MLIR design principle of avoiding boilerplate by using a two-part specification for dialects and their components:

1. Declarative Part (TableGen): Uses the Operation Definition Specification (ODS) language in .td files. These files serve as the single source of truth and automatically generate C++ header and implementation files via the build system.

   • Location: catalyst/mlir/include/<DialectName>/IR

2. C++ Part: Contains hand-written logic, transformations, storage classes, or interface method implementations that cannot be expressed in ODS.

   • Location: catalyst/mlir/lib/<DialectName>/IR

While ODS is strongly recommended for defining the structure, you can always achieve full control by working directly with the underlying C++ classes.

Catalyst provides a set of operations to manage dynamically resizable arraylists:

• catalyst.list_init: Initializes a new dynamically resizable arraylist.
• catalyst.list_push: Appends a value to the end of a list.
• catalyst.list_pop: Removes and returns the last element from a list.
• catalyst.list_load_data: Retrieves the underlying memref storing the data of the list.
• catalyst.list_dealloc: Deallocates the underlying memory of an arraylist.

// Initialize
%list = catalyst.list_init : type($list)

// Push value
// catalyst.list_push $value, $list : type($list)

// Pop value
// %result, %list = catalyst.list_pop $list : type($list) -> type($result)

// Load data as memref
// %data = catalyst.list_load_data $list : type($list) -> type($data)

// Deallocate
// catalyst.list_dealloc $list : type($list)