New OQD end-to-end pipeline is added to Catalyst #2299

rniczh · 2025-12-15T21:13:02Z

Context:

Description of the Change:

This pipeline enables Catalyst to compile circuit for ARTIQ-based quantum device. When device_db configuration is provided, the compilation follows the ARTIQ route:

ions-decomposition: Decompose quantum operations for trapped ion systems
gates-to-pulses: Convert gate operations to pulse sequences
convert-ion-to-rtio: Convert ion operations to RTIO dialect
convert-rtio-event-to-artiq: Lower RTIO event to ARTIQ's primitives
llvm-dialect-lowering-stage: Lower to LLVM IR
emit-artiq-runtime: Generate ARTIQ runtime entry point as wrapper for ARITQ device to execute

The final stage compiles LLVM IR to an ELF binary targeting the ARTIQ device (ARM Cortex-A9). Due to current limitations where Catalyst's internal LLVM build does not include the corresponding ARM backend, the compilation will use llc to compile .ll to object file, and use ld.lld to compile to .elf

We added a compile_to_artiq helper function to the oqd module, so it can compile and link Catalyst-generated LLVM IR to ARTIQ's binary, keep OQD-specific logic out of Catalyst core.

Example:
Replace the artiq configs to your own env setting:

import os

import numpy as np
import pennylane as qml

from catalyst import qjit
from catalyst.third_party.oqd import OQDDevice, OQDDevicePipeline, compile_to_artiq

OQD_PIPELINES = OQDDevicePipeline(
    os.path.join("calibration_data", "device.toml"),
    os.path.join("calibration_data", "qubit.toml"),
    os.path.join("calibration_data", "gate.toml"),
    os.path.join("device_db", "device_db.json"),
)


def test_rx_gate():
    """Test RX gate with ARTIQ linking done in user code."""
    oqd_dev = OQDDevice(
        backend="default",
        shots=4,
        wires=1,
    )
    qml.capture.enable()

    # Compile to LLVM IR only
    @qjit(pipelines=OQD_PIPELINES, target="llvmir")
    @qml.qnode(oqd_dev)
    def circuit():
        x = np.pi / 2
        qml.RX(x, wires=0)
        return qml.counts(wires=0)

    # Compile to ARTIQ ELF
    artiq_config = {
        "kernel_ld": "/path/to/kernel.ld",
        "llc_path": "/path/to/llc",
        "lld_path": "/path/to/ld.lld",
    }

    output_elf_path = compile_to_artiq(circuit, artiq_config)
    print(f"ARTIQ ELF file generated: {output_elf_path}")

test_rx_gate()

The result will store to circuit.elf

[ARTIQ] Generated ELF: circuit.elf

And you can run it on artiq device:

artiq_run  --device-db device_db.py circuit.elf

Benefits:

Possible Drawbacks:
~~It causes the OQD specific compile stuffs steps into the original catalyst compiler driver's pipepline~~

Related GitHub Issues:
[sc-100853]

mlir/lib/Driver/CompilerDriver.cpp

github-actions · 2025-12-15T21:16:20Z

Hello. You may have forgotten to update the changelog!
Please edit doc/releases/changelog-dev.md on your branch with:

A one-to-two sentence description of the change. You may include a small working example for new features.
A link back to this PR.
Your name (or GitHub username) in the contributors section.

…d-new-oqd-pipeline

codecov · 2026-01-15T19:02:58Z

Codecov Report

❌ Patch coverage is 23.77049% with 93 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.62%. Comparing base (b3bcad1) to head (abbeb60).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
frontend/catalyst/third_party/oqd/oqd_compile.py	12.82%	68 Missing ⚠️
frontend/catalyst/jit.py	25.00%	9 Missing and 3 partials ⚠️
frontend/catalyst/third_party/oqd/oqd_device.py	57.89%	5 Missing and 3 partials ⚠️
frontend/catalyst/compiler.py	28.57%	4 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2299      +/-   ##
==========================================
- Coverage   97.31%   96.62%   -0.69%     
==========================================
  Files         107      108       +1     
  Lines       12951    13066     +115     
  Branches     1075     1100      +25     
==========================================
+ Hits        12603    12625      +22     
- Misses        288      374      +86     
- Partials       60       67       +7

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

paul0403

Thanks Hongsheng, looks really nice! I think this is the minimally intrusive way we can do it without altering too much of the base jit flow!

I left some comments but all are minor. Another thing is can you add your PR description's example as an end-to-end pytest in the frontend oqd tests? Obviously no need for execution, just check that the compiled ELF exist (maybe check a little bit of its content as well)? You may need to do things like subprocess.run("which llc", shell=True) in the test, but I think that's possible.

paul0403 · 2026-01-16T18:19:42Z

frontend/catalyst/third_party/oqd/oqd_compile.py

+    llvm_ir_path = os.path.join(str(circuit.workspace), f"{circuit_name}.ll")
+    with open(llvm_ir_path, "w", encoding="utf-8") as f:
+        f.write(llvm_ir_text)
+    print(f"LLVM IR file written to: {llvm_ir_path}")


Only print when verbose? Or should we always print?

paul0403 · 2026-01-16T18:20:51Z

frontend/catalyst/third_party/oqd/oqd_compile.py

+    print(f"LLVM IR file written to: {llvm_ir_path}")
+
+    # Link to ARTIQ's binary
+    if output_elf_name is None:


Why do we need this condition? 🤔 Is it for the user to specify a path they want themselves?

paul0403 · 2026-01-16T18:21:40Z

frontend/catalyst/third_party/oqd/oqd_compile.py

+        "-mtriple=armv7-unknown-linux-gnueabihf",
+        "-mcpu=cortex-a9",


Does this constaint the type of the host machine? i.e. does this mean an OQD script can only be run on these kinds of systems?

So the function compile_to_artiq is solely compile to ARTIQ and this is the hardware that ARTIQ employed. Well, it might be chnaged if the OQD target to different FPGA board (except the ARTIQ).

paul0403 · 2026-01-16T18:22:39Z

frontend/catalyst/third_party/oqd/oqd_compile.py

+        "-shared",
+        "--eh-frame-hdr",
+        "-m",
+        "armelf_linux_eabi",


#2299 (comment)

paul0403 · 2026-01-16T18:23:39Z

frontend/catalyst/third_party/oqd/oqd_compile.py

+    if verbose:
+        print(f"[ARTIQ] Linking ELF: {' '.join(lld_args)}")
+
+    try:


This try-except block seems identical for llc and lld. Maybe we can factor them out into a helper function? But I'm also fine with it if you leave it as is 👍

mlir/lib/RTIO/Transforms/RTIOEmitARTIQRuntime.cpp

paul0403 · 2026-01-16T18:25:42Z

mlir/lib/RTIO/Transforms/RTIOEmitARTIQRuntime.cpp

+
+  private:
+    /// Emit ARTIQ runtime wrapper for LLVM dialect kernel function
+    LogicalResult emitARTIQRuntimeForLLVMFunc(ModuleOp module, OpBuilder &builder,


module is a keyword in cpp, let's avoid it as a variable name maybe

Thanks for pointing out!

Co-authored-by: Paul <79805239+paul0403@users.noreply.github.com>

mehrdad2m

Thanks @rniczh, I did a first round of review with some minor comments. However, I would like to play around with a bit more and maybe more review on Monday.

mehrdad2m · 2026-01-16T20:15:48Z

frontend/catalyst/third_party/oqd/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Xanadu Quantum Technologies Inc.
+# Copyright 2024-2026 Xanadu Quantum Technologies Inc.


Why the copyright change? 😄

mehrdad2m · 2026-01-16T20:16:05Z

frontend/catalyst/third_party/oqd/oqd_device.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Xanadu Quantum Technologies Inc.
+# Copyright 2024-2026 Xanadu Quantum Technologies Inc.


frontend/catalyst/third_party/oqd/oqd_compile.py

mehrdad2m · 2026-01-16T20:43:08Z

frontend/catalyst/compiler.py

@@ -1,4 +1,4 @@
-# Copyright 2022-2023 Xanadu Quantum Technologies Inc.
+# Copyright 2022-2026 Xanadu Quantum Technologies Inc.


frontend/catalyst/jit.py

Co-authored-by: Mehrdad Malek <39844030+mehrdad2m@users.noreply.github.com>

New OQD end-to-end pipeline is added to Catalyst

0f95081

rniczh commented Dec 15, 2025

View reviewed changes

mlir/lib/Driver/CompilerDriver.cpp Outdated Show resolved Hide resolved

rniczh added 9 commits December 15, 2025 16:17

formatting

ac35127

update comment

8675505

inconsistent return statements

1f5a13d

update comment

cdd886e

Merge branch 'main' of github.com:PennyLaneAI/catalyst into rniczh/ad…

5d098e2

…d-new-oqd-pipeline

fix

6710592

add missing lib

4289603

Merge branch 'main' into rniczh/add-new-oqd-pipeline

3b04a9f

Update

ffa5875

rniczh requested a review from mehrdad2m January 15, 2026 18:29

rniczh added 2 commits January 15, 2026 13:34

pylint

22e3d67

add tests for EmitArtiqRuntime

14d18a5

rniczh added 10 commits January 16, 2026 10:50

move the artiq specific logic out catalyst

3eeaf4a

udpate

12f03c5

revert

345ac01

update

8bae023

revertT

a579d23

codecov

92b03af

pylint

c5dd374

Merge branch 'main' into rniczh/add-new-oqd-pipeline

0c8b3ce

date

c852319

revert redundant change

9e99d37

paul0403 reviewed Jan 16, 2026

View reviewed changes

Update mlir/lib/RTIO/Transforms/RTIOEmitARTIQRuntime.cpp

38bee24

Co-authored-by: Paul <79805239+paul0403@users.noreply.github.com>

mehrdad2m reviewed Jan 16, 2026

View reviewed changes

Update jit.py

aba4efc

Co-authored-by: Mehrdad Malek <39844030+mehrdad2m@users.noreply.github.com>

rniczh and others added 2 commits January 16, 2026 17:13

Update jit.py

fc4b5ee

Co-authored-by: Mehrdad Malek <39844030+mehrdad2m@users.noreply.github.com>

Update oqd_compile.py

abbeb60

Co-authored-by: Mehrdad Malek <39844030+mehrdad2m@users.noreply.github.com>

		@@ -1,4 +1,4 @@
		# Copyright 2024 Xanadu Quantum Technologies Inc.
		# Copyright 2024-2026 Xanadu Quantum Technologies Inc.

		@@ -1,4 +1,4 @@
		# Copyright 2022-2023 Xanadu Quantum Technologies Inc.
		# Copyright 2022-2026 Xanadu Quantum Technologies Inc.

New OQD end-to-end pipeline is added to Catalyst #2299

Are you sure you want to change the base?

New OQD end-to-end pipeline is added to Catalyst #2299

Uh oh!

Conversation

rniczh commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Dec 15, 2025

Uh oh!

codecov bot commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

paul0403 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mehrdad2m left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rniczh commented Dec 15, 2025 •

edited

Loading

codecov bot commented Jan 15, 2026 •

edited

Loading