✨ Add unitary matrix to QCO dialect

CMakeLists.txt

@@ -63,6 +63,7 @@ option(MQT_CORE_INSTALL "Generate installation instructions for MQT Core"
 option(BUILD_MQT_CORE_TESTS "Build tests for the MQT Core project" ${MQT_CORE_MASTER_PROJECT})
 option(BUILD_MQT_CORE_SHARED_LIBS "Build MQT Core libraries as shared libraries"
        ${BUILD_SHARED_LIBS})
+option(BUILD_MQT_CORE_MLIR "Build the MLIR submodule of the MQT Core project" ON)
 
 # try to determine the project version
 include(GetVersion)
@@ -93,7 +94,6 @@ endif()
 
 set(MQT_CORE_TARGET_NAME "mqt-core")
 
-option(BUILD_MQT_CORE_MLIR "Build the MLIR submodule of the MQT Core project" ON)
 if(APPLE AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
   set(BUILD_MQT_CORE_MLIR
       OFF

cmake/ExternalDependencies.cmake

@@ -22,6 +22,19 @@ if(BUILD_MQT_CORE_BINDINGS)
   find_package(nanobind CONFIG REQUIRED)
 endif()
 
+if(BUILD_MQT_CORE_MLIR)
+  set(Eigen_VERSION
+      5.0.1
+      CACHE STRING "Eigen version")
+  set(Eigen_URL
+      https://gitlab.com/libeigen/eigen/-/archive/${Eigen_VERSION}/eigen-${Eigen_VERSION}.tar.gz)
+  set(EIGEN_BUILD_TESTING
+      OFF
+      CACHE INTERNAL "Disable building Eigen tests")
+  FetchContent_Declare(Eigen URL ${Eigen_URL} FIND_PACKAGE_ARGS ${Eigen_VERSION})
+  list(APPEND FETCH_PACKAGES Eigen)
+endif()
+
 set(JSON_VERSION
     3.12.0
     CACHE STRING "nlohmann_json version")

mlir/.clang-tidy

@@ -7,3 +7,7 @@ Checks: |
   -misc-use-anonymous-namespace,
   llvm-twine-local,
   -cppcoreguidelines-pro-bounds-avoid-unchecked-container-access
+
+CheckOptions:
+  - key: misc-include-cleaner.IgnoreHeaders
+    value: "Eigen/.*;unsupported/Eigen/.*"

mlir/include/mlir/Dialect/QCO/IR/QCODialect.h

@@ -21,6 +21,7 @@
 #pragma clang diagnostic pop
 #endif
 
+#include <Eigen/Core>
 #include <mlir/Bytecode/BytecodeOpInterface.h>
 #include <mlir/Dialect/Arith/IR/Arith.h>
 #include <mlir/IR/Value.h>
@@ -49,6 +50,8 @@
 // Interfaces
 //===----------------------------------------------------------------------===//
 
+#include "mlir/Dialect/QCO/IR/QCOInterfaces.h.inc" // IWYU pragma: export
+
 namespace mlir::qco {
 
 /**
@@ -133,8 +136,6 @@ template <size_t T, size_t P> class TargetAndParameterArityTrait {
 
 } // namespace mlir::qco
 
-#include "mlir/Dialect/QCO/IR/QCOInterfaces.h.inc" // IWYU pragma: export
-
 //===----------------------------------------------------------------------===//
 // Operations
 //===----------------------------------------------------------------------===//

mlir/include/mlir/Dialect/QCO/IR/QCOInterfaces.td

@@ -28,6 +28,67 @@ def UnitaryOpInterface : OpInterface<"UnitaryOpInterface"> {
 
     let cppNamespace = "::mlir::qco";
 
+    // Generic implementation body for getUnitaryMatrix methods
+    defvar unitaryMatrixMethodBody = [{
+      auto process = [&]<typename MatrixType>(MatrixType&& m) -> bool {
+          using TargetT = std::remove_cvref_t<decltype(out)>;
+          using SourceT = std::remove_cvref_t<MatrixType>;
+
+          constexpr bool isTargetDynamic =
+              (TargetT::SizeAtCompileTime == Eigen::Dynamic);
+          constexpr bool isSourceDynamic =
+              (SourceT::SizeAtCompileTime == Eigen::Dynamic);
+
+          // Case 1: Target is Dynamic. Always accepts source.
+          if constexpr (isTargetDynamic) {
+            out = std::forward<MatrixType>(m);
+            return true;
+          }
+          // Case 2: Target is Fixed.
+          else {
+            // Case 2a: Source is Dynamic. Runtime dimension check required.
+            if constexpr (isSourceDynamic) {
+              if (m.rows() == static_cast<Eigen::Index>(TargetT::RowsAtCompileTime) &&
+                  m.cols() == static_cast<Eigen::Index>(TargetT::ColsAtCompileTime))
+                  [[likely]] {
+                out = std::forward<MatrixType>(m);
+                return true;
+              }
+            }
+            // Case 2b: Source is Fixed. Compile-time check.
+            else if constexpr (static_cast<Eigen::Index>(
+                                   SourceT::RowsAtCompileTime) ==
+                                   static_cast<Eigen::Index>(
+                                       TargetT::RowsAtCompileTime) &&
+                               static_cast<Eigen::Index>(
+                                   SourceT::ColsAtCompileTime) ==
+                                   static_cast<Eigen::Index>(
+                                       TargetT::ColsAtCompileTime)) {
+              out = std::forward<MatrixType>(m);
+              return true;
+            } else {
+              // always fail this static_assert since this compile-time branch
+              // implies incompatible matrix sizes
+              static_assert(!sizeof(TargetT) && !sizeof(SourceT),
+                "Unable to process unitary matrix into given matriy type!");
+            }
+          }
+          return false;
+        };
+
+
+      if constexpr (requires { $_op.getUnitaryMatrix().has_value(); }) {
+        if (auto&& matrix = $_op.getUnitaryMatrix()) {
+          return process(std::move(*matrix));
+        }
+        return false;
+      } else if constexpr (requires { $_op.getUnitaryMatrix(); }) {
+        return process($_op.getUnitaryMatrix());
+      } else {
+        llvm::reportFatalUsageError("Operation '" + $_op.getBaseSymbol() + "' has no unitary matrix definition!");
+      }
+    }];
+
     let methods = [
         // Qubit accessors
         InterfaceMethod<
@@ -107,7 +168,69 @@ def UnitaryOpInterface : OpInterface<"UnitaryOpInterface"> {
             "Returns the base symbol/mnemonic of the operation.",
             "StringRef", "getBaseSymbol", (ins)
         >,
+        InterfaceMethod<
+            "Populates the given 1x1 unitary matrix if possible.",
+            "bool", "getUnitaryMatrix1x1",
+            (ins "Eigen::Matrix<std::complex<double>, 1, 1>&":$out),
+            unitaryMatrixMethodBody
+        >,
+        InterfaceMethod<
+            "Populates the given 2x2 unitary matrix if possible.",
+            "bool", "getUnitaryMatrix2x2",
+            (ins "Eigen::Matrix2cd&":$out),
+            unitaryMatrixMethodBody
+        >,
+        InterfaceMethod<
+            "Populates the given 4x4 unitary matrix if possible.",
+            "bool", "getUnitaryMatrix4x4",
+            (ins "Eigen::Matrix4cd&":$out),
+            unitaryMatrixMethodBody
+        >,
+        InterfaceMethod<
+            "Populates the given dynamic unitary matrix.",
+            "bool", "getUnitaryMatrixDynamic",
+            (ins "Eigen::MatrixXcd&":$out),
+            unitaryMatrixMethodBody
+        >
     ];
+
+    let extraClassDeclaration = [{
+        template<typename MatrixType>
+        std::optional<MatrixType> getUnitaryMatrix() {
+          MatrixType out;
+          bool result = false;
+
+          // Dispatch to the appropriate fixed-size or dynamic method based on the
+          // matrix type.
+          if constexpr (MatrixType::RowsAtCompileTime == 1 &&
+                        MatrixType::ColsAtCompileTime == 1) {
+            result = this->getUnitaryMatrix1x1(out);
+          } else if constexpr (MatrixType::RowsAtCompileTime == 2 &&
+                               MatrixType::ColsAtCompileTime == 2) {
+            result = this->getUnitaryMatrix2x2(out);
+          } else if constexpr (MatrixType::RowsAtCompileTime == 4 &&
+                               MatrixType::ColsAtCompileTime == 4) {
+            result = this->getUnitaryMatrix4x4(out);
+          } else if constexpr (MatrixType::SizeAtCompileTime == Eigen::Dynamic) {
+            result = this->getUnitaryMatrixDynamic(out);
+          } else {
+            // Fallback: Try obtaining dynamic matrix and see if size matches
+            Eigen::MatrixXcd dynamicOut;
+            if (this->getUnitaryMatrixDynamic(dynamicOut)) {
+              if (dynamicOut.rows() == MatrixType::RowsAtCompileTime &&
+                  dynamicOut.cols() == MatrixType::ColsAtCompileTime) {
+                out = dynamicOut;
+                result = true;
+              }
+            }
+          }
+
+          if (result) {
+            return out;
+          }
+          return std::nullopt;
+        }
+    }];
 }
 
 #endif // QCO_INTERFACES