# pennylaneai/catalyst architecture

> Architecture diagram of the GitHub repository pennylaneai/catalyst, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pennylaneai/catalyst
- Repository: https://github.com/pennylaneai/catalyst

## Overview

#### 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: [`frontend/catalyst/compiler.py`](https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/compiler.py) (Compilation orchestration), [`runtime/lib/capi/RuntimeCAPI.cpp`](https://github.com/pennylaneai/catalyst/blob/main/runtime/lib/capi/RuntimeCAPI.cpp) (QIR runtime C API), [`mlir/include/Quantum/IR/QuantumDialect.td`](https://github.com/pennylaneai/catalyst/blob/main/mlir/include/Quantum/IR/QuantumDialect.td) (Catalyst IR dialects), [`mlir/lib/Driver/CompilerDriver.cpp`](https://github.com/pennylaneai/catalyst/blob/main/mlir/lib/Driver/CompilerDriver.cpp) (Compiler driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Python frontend"]
  node_qjit["@qjit API<br/>Python API<br/>[jit.py]"]
  node_compiler_orchestrator["Compilation orchestration<br/>Python compiler<br/>[compiler.py]"]
  node_jax_trace["JAX tracing primitives<br/>tracing layer<br/>[jax_primitives.py]"]
  node_jax_tracer["JAX tracer<br/>tracing bridge<br/>[jax_tracer.py]"]
  node_compiled_functions[("Compiled function cache")]
  node_plxpr["PLXPR frontend<br/>alternate frontend<br/>[from_plxpr.py]"]
  node_qfunc_interpreter["Quantum function interpreter<br/>PLXPR lowering"]
  node_qjit_device["QJIT device<br/>device adapter<br/>[qjit_device.py]"]
  node_python_native_interface["Native compiler interface<br/>Python binding<br/>[compiler.py]"]
  node_pipeline_assembly["Pipeline assembly<br/>pipeline config<br/>[pipelines.py]"]
  node_runtime_artifacts["Runtime artifacts<br/>artifact manager"]
end

subgraph group_compiler["MLIR compiler"]
  node_compiler_driver["Compiler driver<br/>MLIR driver<br/>[CompilerDriver.cpp]"]
  node_default_pipelines["Default pipelines<br/>pipeline composition"]
  node_catalyst_dialects["Catalyst IR dialects<br/>MLIR dialects<br/>[QuantumDialect.td]"]
  node_quantum_lowering["Quantum optimization and lowering<br/>MLIR transforms"]
  node_gradient_lowering["Gradient lowering<br/>AD transforms"]
  node_llvm_qir_lowering["LLVM/QIR lowering<br/>backend lowering"]
  node_catalyst_cli["catalyst-cli<br/>native CLI<br/>[catalyst-cli.cpp]"]
end

subgraph group_execution["Runtime and execution"]
  node_runtime_capi["QIR runtime C API<br/>runtime ABI<br/>[RuntimeCAPI.cpp]"]
  node_device_backends["Device backends<br/>quantum backends<br/>[OpenQasmDevice.cpp]"]
  node_executor_dispatch["Executor dispatch<br/>heterogeneous dispatch"]
  node_transport["Transport layer<br/>coprocessor transport<br/>[TransportCAPI.cpp]"]
  node_executor_manager["Python executor manager<br/>execution manager<br/>[manager.py]"]
end

node_qjit -->|"compiles"| node_compiler_orchestrator
node_compiler_orchestrator -->|"traces"| node_jax_trace
node_jax_trace -->|"uses"| node_jax_tracer
node_compiler_orchestrator -->|"caches"| node_compiled_functions
node_qjit -.->|"alternate input path"| node_plxpr
node_plxpr -->|"interprets"| node_qfunc_interpreter
node_qfunc_interpreter -->|"preprocesses for"| node_qjit_device
node_compiler_orchestrator -->|"selects passes"| node_pipeline_assembly
node_compiler_orchestrator -->|"invokes"| node_python_native_interface
node_compiler_orchestrator -->|"prepares"| node_runtime_artifacts
node_python_native_interface -->|"submits IR"| node_compiler_driver
node_catalyst_cli -->|"drives"| node_compiler_driver
node_pipeline_assembly -->|"configures"| node_default_pipelines
node_compiler_driver -->|"runs"| node_default_pipelines
node_default_pipelines -->|"transforms"| node_catalyst_dialects
node_catalyst_dialects -->|"quantum IR"| node_quantum_lowering
node_catalyst_dialects -->|"gradient IR"| node_gradient_lowering
node_quantum_lowering -->|"lowers"| node_llvm_qir_lowering
node_gradient_lowering -->|"lowers"| node_llvm_qir_lowering
node_llvm_qir_lowering -->|"emits runtime calls"| node_runtime_capi
node_executor_dispatch -->|"dispatch calls"| node_runtime_capi
node_runtime_capi -->|"loads and executes"| node_device_backends
node_runtime_capi -->|"opens sessions"| node_transport
node_executor_manager -->|"manages targets"| node_executor_dispatch

click node_qjit "https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/jit.py"
click node_compiler_orchestrator "https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/compiler.py"
click node_jax_trace "https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/jax_primitives.py"
click node_jax_tracer "https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/jax_tracer.py"
click node_compiled_functions "https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/compiled_functions.py"
click node_plxpr "https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/from_plxpr/from_plxpr.py"
click node_qfunc_interpreter "https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/from_plxpr/qfunc_interpreter.py"
click node_qjit_device "https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/device/qjit_device.py"
click node_python_native_interface "https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/python_interface/compiler.py"
click node_pipeline_assembly "https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/pipelines.py"
click node_runtime_artifacts "https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/utils/runtime_artifacts.py"
click node_compiler_driver "https://github.com/pennylaneai/catalyst/blob/main/mlir/lib/Driver/CompilerDriver.cpp"
click node_default_pipelines "https://github.com/pennylaneai/catalyst/blob/main/mlir/lib/Driver/DefaultPipelines/DefaultPipelines.cpp"
click node_catalyst_dialects "https://github.com/pennylaneai/catalyst/blob/main/mlir/include/Quantum/IR/QuantumDialect.td"
click node_quantum_lowering "https://github.com/pennylaneai/catalyst/blob/main/mlir/lib/Quantum/Transforms/GraphDecomposition/graph_decomposition.cpp"
click node_gradient_lowering "https://github.com/pennylaneai/catalyst/blob/main/mlir/lib/Gradient/Transforms/gradient_lowering.cpp"
click node_llvm_qir_lowering "https://github.com/pennylaneai/catalyst/blob/main/mlir/lib/Catalyst/Transforms/catalyst_to_llvm.cpp"
click node_catalyst_cli "https://github.com/pennylaneai/catalyst/blob/main/mlir/tools/catalyst-cli/catalyst-cli.cpp"
click node_runtime_capi "https://github.com/pennylaneai/catalyst/blob/main/runtime/lib/capi/RuntimeCAPI.cpp"
click node_device_backends "https://github.com/pennylaneai/catalyst/blob/main/runtime/lib/backend/openqasm/OpenQasmDevice.cpp"
click node_executor_dispatch "https://github.com/pennylaneai/catalyst/blob/main/mlir/lib/Executor/Transforms/DispatchExecutorTargets.cpp"
click node_transport "https://github.com/pennylaneai/catalyst/blob/main/runtime/lib/transport/TransportCAPI.cpp"
click node_executor_manager "https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/executor/manager.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_qjit,node_compiler_orchestrator,node_jax_trace,node_jax_tracer,node_compiled_functions,node_plxpr,node_qfunc_interpreter,node_qjit_device,node_python_native_interface,node_pipeline_assembly,node_runtime_artifacts toneBlue
class node_compiler_driver,node_default_pipelines,node_catalyst_dialects,node_quantum_lowering,node_gradient_lowering,node_llvm_qir_lowering,node_catalyst_cli toneAmber
class node_runtime_capi,node_device_backends,node_executor_dispatch,node_transport,node_executor_manager toneMint
```

## Components

### Python frontend

User APIs trace and prepare hybrid programs.

- [@qjit API](https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/jit.py): Python API · Primary user compilation entry point. · `frontend/catalyst/jit.py`
- [Compilation orchestration](https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/compiler.py): Python compiler · Coordinates frontend compilation and caching. · `frontend/catalyst/compiler.py`
- [JAX tracing primitives](https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/jax_primitives.py): tracing layer · Converts PennyLane/JAX programs into compiler primitives. · `frontend/catalyst/jax_primitives.py`
- [JAX tracer](https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/jax_tracer.py): tracing bridge · `frontend/catalyst/jax_tracer.py`
- [Compiled function cache](https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/compiled_functions.py): cache · `frontend/catalyst/compiled_functions.py`
- [PLXPR frontend](https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/from_plxpr/from_plxpr.py): alternate frontend · Device-aware PennyLane program lowering path. · `frontend/catalyst/from_plxpr/from_plxpr.py`
- [Quantum function interpreter](https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/from_plxpr/qfunc_interpreter.py): PLXPR lowering · `frontend/catalyst/from_plxpr/qfunc_interpreter.py`
- [QJIT device](https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/device/qjit_device.py): device adapter · `frontend/catalyst/device/qjit_device.py`
- [Native compiler interface](https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/python_interface/compiler.py): Python binding · Invokes native compilation from Python. · `frontend/catalyst/python_interface/compiler.py`
- [Pipeline assembly](https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/pipelines.py): pipeline config · `frontend/catalyst/pipelines.py`
- [Runtime artifacts](https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/utils/runtime_artifacts.py): artifact manager · Prepares generated runtime files and environment. · `frontend/catalyst/utils/runtime_artifacts.py`

### MLIR compiler

Dialect lowering and pipeline-driven native compilation.

- [Compiler driver](https://github.com/pennylaneai/catalyst/blob/main/mlir/lib/Driver/CompilerDriver.cpp): MLIR driver · Runs configured compilation pipelines. · `mlir/lib/Driver/CompilerDriver.cpp`
- [Default pipelines](https://github.com/pennylaneai/catalyst/blob/main/mlir/lib/Driver/DefaultPipelines/DefaultPipelines.cpp): pipeline composition · `mlir/lib/Driver/DefaultPipelines/DefaultPipelines.cpp`
- [Catalyst IR dialects](https://github.com/pennylaneai/catalyst/blob/main/mlir/include/Quantum/IR/QuantumDialect.td): MLIR dialects · Quantum, QRef, and Gradient IR model program semantics. · `mlir/include/Quantum/IR/QuantumDialect.td`
- [Quantum optimization and lowering](https://github.com/pennylaneai/catalyst/blob/main/mlir/lib/Quantum/Transforms/GraphDecomposition/graph_decomposition.cpp): MLIR transforms · Decomposes, simplifies, and lowers quantum operations. · `mlir/lib/Quantum/Transforms/GraphDecomposition/graph_decomposition.cpp`
- [Gradient lowering](https://github.com/pennylaneai/catalyst/blob/main/mlir/lib/Gradient/Transforms/gradient_lowering.cpp): AD transforms · Lowers adjoint, parameter-shift, and other differentiation methods. · `mlir/lib/Gradient/Transforms/gradient_lowering.cpp`
- [LLVM/QIR lowering](https://github.com/pennylaneai/catalyst/blob/main/mlir/lib/Catalyst/Transforms/catalyst_to_llvm.cpp): backend lowering · Converts Catalyst operations to LLVM-oriented execution. · `mlir/lib/Catalyst/Transforms/catalyst_to_llvm.cpp`
- [catalyst-cli](https://github.com/pennylaneai/catalyst/blob/main/mlir/tools/catalyst-cli/catalyst-cli.cpp): native 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](https://github.com/pennylaneai/catalyst/blob/main/runtime/lib/capi/RuntimeCAPI.cpp): runtime ABI · Stable API for compiled binaries and runtime sessions. · `runtime/lib/capi/RuntimeCAPI.cpp`
- [Device backends](https://github.com/pennylaneai/catalyst/blob/main/runtime/lib/backend/openqasm/OpenQasmDevice.cpp): quantum backends · Null, OpenQASM, Braket, and OQD execution implementations. · `runtime/lib/backend/openqasm/OpenQasmDevice.cpp`
- [Executor dispatch](https://github.com/pennylaneai/catalyst/blob/main/mlir/lib/Executor/Transforms/DispatchExecutorTargets.cpp): heterogeneous dispatch · Lowers target dispatch to runtime execution. · `mlir/lib/Executor/Transforms/DispatchExecutorTargets.cpp`
- [Transport layer](https://github.com/pennylaneai/catalyst/blob/main/runtime/lib/transport/TransportCAPI.cpp): coprocessor transport · Memcpy and RDMA controller/coprocessor sessions. · `runtime/lib/transport/TransportCAPI.cpp`
- [Python executor manager](https://github.com/pennylaneai/catalyst/blob/main/frontend/catalyst/executor/manager.py): execution manager · Manages local-process and SSH execution. · `frontend/catalyst/executor/manager.py`

## Connections

- @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
