Lower RTIO to LLVM IR

doc/releases/changelog-dev.md

@@ -99,9 +99,6 @@
     detecting when the Python compiler is being used and routing through it appropriately.
     [(#2190)](https://github.com/PennyLaneAI/catalyst/pull/2190)
 
-* RTIO dialect is added to bypass the compilation flow from OpenAPL to ARTIQ’s LLVM IR. It is introduced to bridge the gap between ION dialect and ARTIQ’s LLVM IR. The design philosophy of RTIO dialect is primarily event-based. Every operation is asynchronous; sync behaviour occurs only via `rtio.sync` or `wait operand` in event operation.
-  [(#2185)](https://github.com/PennyLaneAI/catalyst/pull/2185)
-
 * Added ``catalyst.switch``, a qjit compatible, index-switch style control flow decorator.
   [(#2171)](https://github.com/PennyLaneAI/catalyst/pull/2171)
 
@@ -366,6 +363,14 @@
 
 <h3>Internal changes ⚙️</h3>
 
+* RTIO dialect is added to bypass the compilation flow from OpenAPL to ARTIQ’s LLVM IR. It is 
+  introduced to bridge the gap between ION dialect and ARTIQ’s LLVM IR. The design philosophy 
+  of RTIO dialect is primarily event-based. Every operation is asynchronous; sync behaviour occurs 
+  only via `rtio.sync` or `wait operand` in event operation. And we now support the compiling from 
+  ION dialect to RTIO dilalect.
+  [(#2185)](https://github.com/PennyLaneAI/catalyst/pull/2185)
+  [(#2204)](https://github.com/PennyLaneAI/catalyst/pull/2204)
+
 * Integration tests for `qml.specs` have been updated to match the new output format introduced
   in PennyLane.
   [(#2255)](https://github.com/PennyLaneAI/catalyst/pull/2255)

mlir/include/Catalyst/Utils/JSONUtils.h

@@ -0,0 +1,35 @@
+// Copyright 2025 Xanadu Quantum Technologies Inc.
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include "llvm/Support/JSON.h"
+
+#include "mlir/IR/Attributes.h"
+#include "mlir/IR/BuiltinAttributes.h"
+#include "mlir/IR/MLIRContext.h"
+#include "mlir/Support/LogicalResult.h"
+
+namespace catalyst {
+
+/// Convert a JSON value to an MLIR Attribute.
+/// Handles strings, integers, floats, booleans, arrays, objects, and null.
+mlir::Attribute jsonToAttribute(mlir::MLIRContext *ctx, const llvm::json::Value &json);
+
+/// Load a JSON file and convert it to a DictionaryAttr.
+/// Returns failure if the file cannot be read or parsed, or if the root is not an object.
+mlir::FailureOr<mlir::DictionaryAttr> loadJsonFileAsDict(mlir::MLIRContext *ctx,
+                                                         llvm::StringRef filePath);
+
+} // namespace catalyst

mlir/include/Ion/IR/IonInfo.h

@@ -0,0 +1,129 @@
+// Copyright 2025 Xanadu Quantum Technologies Inc.
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include <optional>
+#include <string>
+
+#include "llvm/ADT/SmallVector.h"
+#include "llvm/ADT/StringMap.h"
+#include "llvm/ADT/StringRef.h"
+
+#include "Ion/IR/IonOps.h"
+
+namespace catalyst {
+namespace ion {
+
+/// Helper class to store and query ion information from an IonOp.
+class IonInfo {
+  public:
+    struct TransitionInfo {
+        std::string level0;
+        std::string level1;
+        double einstein_a;
+        std::string multipole;
+    };
+
+  private:
+    llvm::StringMap<double> levelEnergyMap;
+    llvm::SmallVector<TransitionInfo> transitions;
+
+  public:
+    explicit IonInfo(ion::IonOp op)
+    {
+        auto levelAttrs = op.getLevels();
+        auto transitionsAttr = op.getTransitions();
+
+        // Map from Level label to Energy value
+        for (auto levelAttr : levelAttrs) {
+            auto level = mlir::cast<LevelAttr>(levelAttr);
+            std::string label = level.getLabel().getValue().str();
+            double energy = level.getEnergy().getValueAsDouble();
+            levelEnergyMap[label] = energy;
+        }
+
+        // Store transition information
+        for (auto transitionAttr : transitionsAttr) {
+            auto transition = mlir::cast<TransitionAttr>(transitionAttr);
+            TransitionInfo info;
+            info.level0 = transition.getLevel_0().getValue().str();
+            info.level1 = transition.getLevel_1().getValue().str();
+            info.einstein_a = transition.getEinsteinA().getValueAsDouble();
+            info.multipole = transition.getMultipole().getValue().str();
+            transitions.push_back(info);
+        }
+    }
+
+    /// Get energy of a level by label
+    std::optional<double> getLevelEnergy(llvm::StringRef label) const
+    {
+        auto it = levelEnergyMap.find(label.str());
+        if (it != levelEnergyMap.end()) {
+            return it->second;
+        }
+        return std::nullopt;
+    }
+
+    /// Get level energy of a transition by index
+    template <int IndexT>
+    std::optional<double> getTransitionLevelEnergy(size_t transitionIndex) const
+    {
+        static_assert(IndexT == 0 || IndexT == 1, "IndexT must be 0 or 1");
+
+        if (transitionIndex >= transitions.size()) {
+            return std::nullopt;
+        }
+
+        const auto &transition = transitions[transitionIndex];
+        if constexpr (IndexT == 0) {
+            return getLevelEnergy(transition.level0);
+        }
+        else {
+            return getLevelEnergy(transition.level1);
+        }
+    }
+
+    /// Get energy difference of a transition (level1 energy - level0 energy)
+    std::optional<double> getTransitionEnergyDiff(size_t index) const
+    {
+        if (index >= transitions.size()) {
+            return std::nullopt;
+        }
+
+        auto energy0 = getTransitionLevelEnergy<0>(index);
+        auto energy1 = getTransitionLevelEnergy<1>(index);
+
+        if (energy0.has_value() && energy1.has_value()) {
+            return energy1.value() - energy0.value();
+        }
+
+        return std::nullopt;
+    }
+
+    /// Get number of transitions
+    size_t getNumTransitions() const { return transitions.size(); }
+
+    /// Get transition info by index
+    std::optional<TransitionInfo> getTransition(size_t index) const
+    {
+        if (index < transitions.size()) {
+            return transitions[index];
+        }
+        return std::nullopt;
+    }
+};
+
+} // namespace ion
+} // namespace catalyst

mlir/include/Ion/Transforms/Passes.td

@@ -52,4 +52,28 @@ def IonConversionPass : Pass<"convert-ion-to-llvm"> {
     ];
 }
 
+def IonToRTIOPass : Pass<"convert-ion-to-rtio", "mlir::ModuleOp"> {
+    let summary = "Convert Ion dialect operations to RTIO dialect";
+
+    let dependentDialects = [
+        "rtio::RTIODialect",
+        "arith::ArithDialect",
+        "func::FuncDialect",
+        "memref::MemRefDialect",
+        "scf::SCFDialect",
+        "quantum::QuantumDialect",
+        "ion::IonDialect",
+        "linalg::LinalgDialect",
+    ];
+
+    let options = [
+        Option<"kernelName", "kernel-name",
+               "std::string", /*default=*/"\"__kernel__\"",
+               "Name of the generated kernel function">,
+        Option<"deviceDb", "device_db",
+               "std::string", /*default=*/"\"\"",
+               "Path to the device database JSON file">,
+    ];
+}
+
 #endif // ION_PASSES

mlir/include/Ion/Transforms/Patterns.h

@@ -18,14 +18,23 @@
 #include "mlir/IR/PatternMatch.h"
 #include "mlir/Transforms/DialectConversion.h"
 
+#include "Ion/IR/IonInfo.h"
 #include "Ion/Transforms/oqd_database_managers.hpp"
 
 namespace catalyst {
 namespace ion {
-
+// Gates to pulses conversion patterns
 void populateGatesToPulsesPatterns(mlir::RewritePatternSet &, const OQDDatabaseManager &);
 void populateConversionPatterns(mlir::LLVMTypeConverter &typeConverter,
                                 mlir::RewritePatternSet &patterns);
 
+// Ion to RTIO conversion patterns
+void populateIonPulseToRTIOPatterns(mlir::TypeConverter &typeConverter,
+                                    mlir::RewritePatternSet &patterns, const IonInfo &ionInfo,
+                                    mlir::DenseMap<mlir::Value, mlir::Value> &qextractToMemrefMap);
+void populateParallelProtocolToRTIOPatterns(mlir::TypeConverter &typeConverter,
+                                            mlir::RewritePatternSet &patterns);
+void populateIonToRTIOFinalizePatterns(mlir::RewritePatternSet &patterns);
+
 } // namespace ion
 } // namespace catalyst

mlir/include/Ion/Transforms/ValueTracing.h

@@ -0,0 +1,142 @@
+// Copyright 2025 Xanadu Quantum Technologies Inc.
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma once
+
+#include <queue>
+
+#include "mlir/Dialect/SCF/IR/SCF.h"
+#include "mlir/IR/Value.h"
+
+#include "Ion/IR/IonOps.h"
+#include "Quantum/IR/QuantumOps.h"
+#include "RTIO/IR/RTIOOps.h"
+
+namespace catalyst {
+namespace ion {
+
+enum class TraceMode {
+    Qreg = 0,
+    Event = 1,
+};
+
+/// Traces a Value backward through the IR by tracing its dataflow dependencies
+/// across control flow and specific quantum operations.
+///
+/// Template Parameters:
+///   - ModeT: TraceMode enum (Qreg or Event) that controls how quantum.insert
+///            operations are handled
+///            Qreg mode: Trace to find the source qreg of the given value
+///            Event mode: Trace to find all events that contribute to the given value
+///   - CallbackT: Callable type that will be invoked for each visited value.
+///                May optionally return WalkResult for early termination.
+///
+/// Supported Operations:
+///   - scf.for
+///   - scf.if
+///   - ion.parallelprotocol
+///   - unrealized_conversion_cast
+///   - quantum.extract
+///   - quantum.insert
+template <TraceMode ModeT, typename CallbackT>
+auto traceValueWithCallback(mlir::Value value, CallbackT &&callback)
+{
+    using namespace mlir;
+    static_assert(std::is_same_v<std::invoke_result_t<CallbackT, Value>, WalkResult>,
+                  "Callback must return WalkResult");
+
+    WalkResult walkResult = WalkResult::advance();
+    std::queue<Value> worklist;
+    worklist.push(value);
+
+    while (!worklist.empty()) {
+        Value value = worklist.front();
+        worklist.pop();
+
+        if (callback(value).wasInterrupted()) {
+            walkResult = WalkResult::interrupt();
+            continue;
+        }
+
+        if (auto arg = mlir::dyn_cast<BlockArgument>(value)) {
+            Block *block = arg.getOwner();
+            Operation *parentOp = block->getParentOp();
+
+            if (auto forOp = dyn_cast<scf::ForOp>(parentOp)) {
+                unsigned argIndex = arg.getArgNumber();
+                Value iterArg = forOp.getInitArgs()[argIndex - 1];
+                worklist.push(iterArg);
+                continue;
+            }
+            else if (auto parallelProtocolOp = dyn_cast<ion::ParallelProtocolOp>(parentOp)) {
+                unsigned argIndex = arg.getArgNumber();
+                Value inQubit = parallelProtocolOp.getInQubits()[argIndex];
+                worklist.push(inQubit);
+                continue;
+            }
+            return WalkResult::interrupt();
+        }
+
+        Operation *defOp = value.getDefiningOp();
+        if (defOp == nullptr) {
+            continue;
+        }
+
+        if (auto forOp = dyn_cast<scf::ForOp>(defOp)) {
+            unsigned resultIdx = llvm::cast<OpResult>(value).getResultNumber();
+            BlockArgument iterArg = forOp.getRegionIterArg(resultIdx);
+            worklist.push(iterArg);
+        }
+        else if (auto ifOp = dyn_cast<scf::IfOp>(defOp)) {
+            unsigned resultIdx = llvm::cast<OpResult>(value).getResultNumber();
+            Value thenValue = ifOp.thenYield().getOperand(resultIdx);
+            Value elseValue = ifOp.elseYield().getOperand(resultIdx);
+            worklist.push(thenValue);
+            worklist.push(elseValue);
+        }
+        else if (auto parallelProtocolOp = dyn_cast<ion::ParallelProtocolOp>(defOp)) {
+            unsigned resultIdx = llvm::cast<OpResult>(value).getResultNumber();
+            Value inQubit = parallelProtocolOp.getInQubits()[resultIdx];
+            worklist.push(inQubit);
+        }
+        else if (auto op = dyn_cast<mlir::UnrealizedConversionCastOp>(defOp)) {
+            worklist.push(op.getInputs().front());
+        }
+        else if (auto op = dyn_cast<quantum::ExtractOp>(defOp)) {
+            worklist.push(op.getQreg());
+        }
+        else if (auto op = dyn_cast<rtio::RTIOQubitToChannelOp>(defOp)) {
+            worklist.push(op.getQubit());
+        }
+        else if (auto op = dyn_cast<quantum::InsertOp>(defOp)) {
+            Value inQreg = op.getInQreg();
+            Value qubit = op.getQubit();
+            if constexpr (ModeT == TraceMode::Qreg) {
+                worklist.push(inQreg);
+            }
+            else if constexpr (ModeT == TraceMode::Event) {
+                worklist.push(qubit);
+                // only trace qreg if it defined op is also come from insert op
+                if (llvm::isa_and_present<quantum::InsertOp>(inQreg.getDefiningOp())) {
+                    worklist.push(inQreg);
+                }
+            }
+        }
+    }
+
+    return walkResult;
+}
+
+} // namespace ion
+} // namespace catalyst

mlir/include/RTIO/CMakeLists.txt

@@ -1 +1,2 @@
 add_subdirectory(IR)
+add_subdirectory(Transforms)

mlir/include/RTIO/IR/RTIOOps.h

@@ -18,6 +18,7 @@
 #include "mlir/Bytecode/BytecodeOpInterface.h"
 #include "mlir/IR/BuiltinTypes.h"
 #include "mlir/IR/OpDefinition.h"
+#include "mlir/IR/PatternMatch.h"
 #include "mlir/Interfaces/SideEffectInterfaces.h"
 
 #define GET_ATTRDEF_CLASSES