✨ Add unitary matrix to QCO dialect (#1426)

## Description

This PR implements the feature of the unitary matrix definition for
`UnitaryOpInterface` which has been removed from the original dialect
rewrite PR in favor of this follow-up.

It aims to allow access to the matrix definition of the standard gates
via a fast, stack-allocated matrix returned by the function
`getUnitaryMatrixDefinition()` in the trait.
A dynamic, heap-based matrix (size `Eigen::Dynamic`) is returned by the
`UnitaryOpInterface`. This requires a copy at the moment and further
evaluations are required if all matrices should be moved to the heap or
if there is a way to make use of the draft function
`getFastUnitaryMatrix()` which uses a template parameter, but is
currently also only accessible via a trait and thus needs a cast to the
correct type first.

The changes require the newly introduced `Eigen` library for its linear
algebra type.
For now, it uses the unsupported kronecker product feature which needs
to be discussed before merging. "Unsupported" features in Eigen are
community-contributed and are not an indication of how mature the code
is. However, the maintainers do not provide any API guarantees.

## Checklist:

<!---
This checklist serves as a reminder of a couple of things that ensure
your pull request will be merged swiftly.
-->

- [ ] The pull request only contains commits that are focused and
relevant to this change.
- [ ] I have added appropriate tests that cover the new/changed
functionality.
- [ ] I have updated the documentation to reflect these changes.
- [ ] I have added entries to the changelog for any noteworthy
additions, changes, fixes, or removals.
- [ ] I have added migration instructions to the upgrade guide (if
needed).
- [ ] The changes follow the project's style guidelines and introduce no
new warnings.
- [ ] The changes are fully tested and pass the CI checks.
- [ ] I have reviewed my own code changes.

---------

Signed-off-by: burgholzer <burgholzer@me.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: burgholzer <burgholzer@me.com>

Author: 3 people

CMakeLists.txt

@@ -63,6 +63,29 @@ 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)
+if(APPLE AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+  set(BUILD_MQT_CORE_MLIR
+      OFF
+      CACHE BOOL
+            "Disable MLIR build on macOS with GCC to avoid ABI issues between STL and libstdc++"
+            FORCE)
+  message(
+    WARNING "Disabling MLIR build on macOS with GCC to avoid ABI issues between STL and libstdc++")
+endif()
+if(APPLE AND CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang")
+  if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS "17.0.0")
+    set(BUILD_MQT_CORE_MLIR
+        OFF
+        CACHE
+          BOOL
+          "Disable MLIR build on macOS with Apple Clang < 17 due to missing complete C++20 support"
+          FORCE)
+    message(
+      WARNING
+        "Disabling MLIR build on macOS with Apple Clang < 17 due to missing complete C++20 support")
+  endif()
+endif()
 
 # try to determine the project version
 include(GetVersion)
@@ -93,29 +116,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
-      CACHE BOOL
-            "Disable MLIR build on macOS with GCC to avoid ABI issues between STL and libstdc++"
-            FORCE)
-  message(
-    WARNING "Disabling MLIR build on macOS with GCC to avoid ABI issues between STL and libstdc++")
-endif()
-if(APPLE AND CMAKE_CXX_COMPILER_ID STREQUAL "AppleClang")
-  if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS "17.0.0")
-    set(BUILD_MQT_CORE_MLIR
-        OFF
-        CACHE
-          BOOL
-          "Disable MLIR build on macOS with Apple Clang < 17 due to missing complete C++20 support"
-          FORCE)
-    message(
-      WARNING
-        "Disabling MLIR build on macOS with Apple Clang < 17 due to missing complete C++20 support")
-  endif()
-endif()
 if(BUILD_MQT_CORE_MLIR)
   include(SetupMLIR)
 endif()

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>

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

@@ -28,6 +28,62 @@ 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;
+            }
+          }
+          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 +163,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