How pennylaneai/catalyst works
Purpose and entry points
Catalyst is a Python JIT compiler for hybrid PennyLane quantum-classical programs, including control flow and differentiation. The principal user entry point is the @qjit frontend API in frontend/catalyst/jit.py, with compilation orchestration in frontend/catalyst/compiler.py. Native command-line compilation is exposed through mlir/tools/catalyst-cli/catalyst-cli.cpp; mlir/tools/quantum-opt/quantum-opt.cpp is the lower-level MLIR optimization tool.
Python tracing and frontend boundary
The Python package traces PennyLane/JAX programs into compiler-compatible primitives, manages compiled-function caching, and exposes Catalyst control-flow, differentiation, callback, and mitigation APIs.
• frontend/catalyst/jax_primitives.py
• frontend/catalyst/jax_tracer.py
• frontend/catalyst/compiled_functions.py
The from_plxpr subsystem is a second frontend/lowering path from PennyLane’s program representation, including device-aware preprocessing and quantum-function interpretation.
• frontend/catalyst/from_plxpr/from_plxpr.py
• frontend/catalyst/from_plxpr/qfunc_interpreter.py
• frontend/catalyst/device/qjit_device.py
Compilation orchestration and artifacts
The frontend invokes native compilation through Python bindings/interfaces, assembles pass pipelines, and manages generated runtime artifacts and execution environment. This is the boundary between Python/JAX tracing and MLIR/C++ compilation.
• frontend/catalyst/pipelines.py
• frontend/catalyst/python_interface/compiler.py
• frontend/catalyst/utils/runtime_artifacts.py
JAX integration includes custom lowering, tracing patches, CPU LAPACK custom-call support, and conversion between JAX/NumPy values and memrefs.
• frontend/catalyst/jax_extras/lowering.py
• frontend/catalyst/utils/jnp_to_memref.py
• frontend/catalyst/utils/jax_cpu_lapack_kernels/lapack_kernels.cpp
MLIR compiler core
The C++ compiler defines Catalyst-specific MLIR dialects and transformations, then drives configurable/default pipelines toward LLVM and QIR-oriented execution. The central driver and pipeline composition are:
• mlir/lib/Driver/CompilerDriver.cpp
• mlir/lib/Driver/DefaultPipelines/DefaultPipelines.cpp
• mlir/lib/Catalyst/Transforms/catalyst_to_llvm.cpp
Core IR separates quantum operations, quantum references/value semantics, gradients, executor dispatch, and domain-specific representations such as MBQC, PBC, ion traps, mitigation, and error correction.
• mlir/include/Quantum/IR/QuantumDialect.td
• mlir/include/QRef/IR/QRefDialect.td
• mlir/include/Gradient/IR/GradientDialect.td
Quantum optimization, decomposition, and differentiation
Quantum lowering includes adjoint/control expansion, gate decomposition, circuit simplification, measurement/tape splitting, and conversion to LLVM. Graph-based decomposition chooses implementations under target gate-set constraints.
• mlir/lib/Quantum/Transforms/GraphDecomposition/graph_decomposition.cpp
• mlir/lib/Quantum/Transforms/AdjointLowering/AdjointLowering.cpp
• mlir/lib/Quantum/Transforms/quantum_to_llvm.cpp
Automatic differentiation is represented and lowered in a dedicated dialect, supporting adjoint, parameter-shift, finite-difference, hybrid, JVP, and VJP methods.
• mlir/lib/Gradient/Transforms/gradient_lowering.cpp
• mlir/lib/Gradient/Transforms/GradMethods/ParameterShift.cpp
• mlir/lib/Gradient/Transforms/GradMethods/Adjoint.cpp
Runtime and device execution
Compiled binaries call a C++ QIR-oriented runtime via stable C APIs. Runtime sessions select/load device backends, manage qubits and execution contexts, and return results across the Python/native boundary.
• runtime/include/RuntimeCAPI.h
• runtime/lib/capi/RuntimeCAPI.cpp
• runtime/lib/backend/common/DynamicLibraryLoader.hpp
Included backend implementations cover null/testing execution, OpenQASM output/execution, Amazon Braket configurations, and OQD/ion-device support.
• runtime/lib/backend/null_qubit/NullQubit.cpp
• runtime/lib/backend/openqasm/OpenQasmDevice.cpp
• runtime/lib/backend/oqd/OQDDevice.cpp
Heterogeneous execution and transport
The executor dialect lowers target dispatch to LLVM/runtime calls; Python can also submit or manage execution through local processes and SSH.
• mlir/lib/Executor/Transforms/DispatchExecutorTargets.cpp
• runtime/lib/executor/ExecutorRuntime.cpp
• frontend/catalyst/executor/manager.py
A separate transport layer supports controller/coprocessor sessions over memcpy or RDMA, with CPU, GPU/HIP, and FPGA-oriented implementations. This is the principal heterogeneous execution boundary.
• runtime/lib/transport/TransportCAPI.cpp
• runtime/lib/transport/memcpy/MemcpyLink.cpp
• runtime/lib/transport/rdma/common/Context.cpp
Material dependencies/runtimes include Python, PennyLane, JAX, LLVM/MLIR, StableHLO/OpenXLA, EnzymeAD, QIR-compatible backends, and optional AWS Braket, OQD, HIP/GPU, and RDMA infrastructure.
Main entry points: compiler.py Compilation orchestration · RuntimeCAPI.cpp QIR runtime C API · QuantumDialect.td Catalyst IR dialects · CompilerDriver.cpp Compiler driver
Components 23
Python frontend
User APIs trace and prepare hybrid programs.
- @qjit API · Primary user compilation entry point.
frontend/catalyst/jit.py - Compilation orchestration · Coordinates frontend compilation and caching.
frontend/catalyst/compiler.py - JAX tracing primitives · Converts PennyLane/JAX programs into compiler primitives.
frontend/catalyst/jax_primitives.py - JAX tracer
frontend/catalyst/jax_tracer.py - Compiled function cache
frontend/catalyst/compiled_functions.py - PLXPR frontend · Device-aware PennyLane program lowering path.
frontend/catalyst/from_plxpr/from_plxpr.py - Quantum function interpreter
frontend/catalyst/from_plxpr/qfunc_interpreter.py - QJIT device
frontend/catalyst/device/qjit_device.py - Native compiler interface · Invokes native compilation from Python.
frontend/catalyst/python_interface/compiler.py - Pipeline assembly
frontend/catalyst/pipelines.py - Runtime artifacts · Prepares generated runtime files and environment.
frontend/catalyst/utils/runtime_artifacts.py
MLIR compiler
Dialect lowering and pipeline-driven native compilation.
- Compiler driver · Runs configured compilation pipelines.
mlir/lib/Driver/CompilerDriver.cpp - Default pipelines
mlir/lib/Driver/DefaultPipelines/DefaultPipelines.cpp - Catalyst IR dialects · Quantum, QRef, and Gradient IR model program semantics.
mlir/include/Quantum/IR/QuantumDialect.td - Quantum optimization and lowering · Decomposes, simplifies, and lowers quantum operations.
mlir/lib/Quantum/Transforms/GraphDecomposition/graph_decomposition.cpp - Gradient lowering · Lowers adjoint, parameter-shift, and other differentiation methods.
mlir/lib/Gradient/Transforms/gradient_lowering.cpp - LLVM/QIR lowering · Converts Catalyst operations to LLVM-oriented execution.
mlir/lib/Catalyst/Transforms/catalyst_to_llvm.cpp - catalyst-cli · Standalone native compilation entry point.
mlir/tools/catalyst-cli/catalyst-cli.cpp
Runtime and execution
Compiled code dispatches to devices and heterogeneous targets.
- QIR runtime C API · Stable API for compiled binaries and runtime sessions.
runtime/lib/capi/RuntimeCAPI.cpp - Device backends · Null, OpenQASM, Braket, and OQD execution implementations.
runtime/lib/backend/openqasm/OpenQasmDevice.cpp - Executor dispatch · Lowers target dispatch to runtime execution.
mlir/lib/Executor/Transforms/DispatchExecutorTargets.cpp - Transport layer · Memcpy and RDMA controller/coprocessor sessions.
runtime/lib/transport/TransportCAPI.cpp - Python executor manager · Manages local-process and SSH execution.
frontend/catalyst/executor/manager.py
Connections 24
- @qjit API → Compilation orchestration: compiles
- Compilation orchestration → JAX tracing primitives: traces
- JAX tracing primitives → JAX tracer: uses
- Compilation orchestration → Compiled function cache: caches
- @qjit API → PLXPR frontend: alternate input path
- PLXPR frontend → Quantum function interpreter: interprets
- Quantum function interpreter → QJIT device: preprocesses for
- Compilation orchestration → Pipeline assembly: selects passes
- Compilation orchestration → Native compiler interface: invokes
- Compilation orchestration → Runtime artifacts: prepares
- Native compiler interface → Compiler driver: submits IR
- catalyst-cli → Compiler driver: drives
- Pipeline assembly → Default pipelines: configures
- Compiler driver → Default pipelines: runs
- Default pipelines → Catalyst IR dialects: transforms
- Catalyst IR dialects → Quantum optimization and lowering: quantum IR
- Catalyst IR dialects → Gradient lowering: gradient IR
- Quantum optimization and lowering → LLVM/QIR lowering: lowers
- Gradient lowering → LLVM/QIR lowering: lowers
- LLVM/QIR lowering → QIR runtime C API: emits runtime calls
- Executor dispatch → QIR runtime C API: dispatch calls
- QIR runtime C API → Device backends: loads and executes
- QIR runtime C API → Transport layer: opens sessions
- Python executor manager → Executor dispatch: manages targets