✨ [NA] Add New Relaxed Router (#859)

## Description

This Pull Request adds a new RelaxedIndependentSetRouter and implements
corresponding functionality to support relaxed routing within the layout
synthesizer for the zoned neutral atom compiler. It includes updates to
related classes and introduces new tests for the added functionality.

### Main Changes
- New Router Class: 
    - Added RelaxedIndependentSetRouter in layout_synthesizer.
Implements a router focusing on relaxed independent sets for routing
optimization.
- Includes documentation for methods like conflict graph creation,
movement compatibility checks, and relaxed conflict resolution.

- Compiler Updates: 
- Introduced RelaxedRoutingAwareSynthesizer and
RelaxedRoutingAwareCompiler classes using the new router.
- Refactored scheduling, analysis, and logging for better structured
debug output and timing metrics segmentation.

- Test Suite Enhancements:
    - Added test case for RelaxedRoutingAwareCompiler.
- Included corresponding JSON configuration for new routing
functionality.

## Checklist:

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

- [x] The pull request only contains commits that are focused and
relevant to this change.
- [x] I have added appropriate tests that cover the new/changed
functionality.
- [x] I have updated the documentation to reflect these changes.
- [x] 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).
- [x] The changes follow the project's style guidelines and introduce no
new warnings.
- [ ] The changes are fully tested and pass the CI checks.
- [x] I have reviewed my own code changes.

---------

Signed-off-by: Yannick Stade <[email protected]>
Co-authored-by: Copilot <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

CHANGELOG.md

@@ -11,6 +11,10 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 _If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md#unreleased)._
 
+### Added
+
+- ✨ Add relaxed routing method to the zoned neutral atom compiler ([#859]) ([**@ystade**])
+
 ### Changed
 
 - 👷 Stop testing on `ubuntu-22.04` and `ubuntu-22.04-arm` runners ([#874]) ([**@denialhaag**])
@@ -169,6 +173,7 @@ _📚 Refer to the [GitHub Release Notes] for previous changelogs._
 <!-- PR links -->
 
 [#874]: https://github.com/munich-quantum-toolkit/qmap/pull/874
+[#859]: https://github.com/munich-quantum-toolkit/qmap/pull/859
 [#848]: https://github.com/munich-quantum-toolkit/qmap/pull/848
 [#847]: https://github.com/munich-quantum-toolkit/qmap/pull/847
 [#832]: https://github.com/munich-quantum-toolkit/qmap/pull/832

bindings/na/zoned/zoned.cpp

@@ -15,6 +15,7 @@
 #include "na/zoned/layout_synthesizer/PlaceAndRouteSynthesizer.hpp"
 #include "na/zoned/layout_synthesizer/placer/AStarPlacer.hpp"
 #include "na/zoned/layout_synthesizer/placer/VertexMatchingPlacer.hpp"
+#include "na/zoned/layout_synthesizer/router/IndependentSetRouter.hpp"
 
 #include <cstddef>
 // The header <nlohmann/json.hpp> is used, but clang-tidy confuses it with the
@@ -24,6 +25,7 @@
 #include <pybind11/attr.h>
 #include <pybind11/cast.h>
 #include <pybind11/detail/common.h>
+#include <pybind11/native_enum.h>
 #include <pybind11/pybind11.h>
 // NOLINTNEXTLINE(misc-include-cleaner)
 #include <pybind11_json/pybind11_json.hpp>
@@ -51,6 +53,17 @@ PYBIND11_MODULE(MQT_QMAP_MODULE_NAME, m, py::mod_gil_not_used()) {
                      return self.exportNAVizMachine();
                    });
 
+  //===--------------------------------------------------------------------===//
+  // Routing Method Enum
+  //===--------------------------------------------------------------------===//
+  py::native_enum<na::zoned::IndependentSetRouter::Config::Method>(
+      m, "RoutingMethod", "enum.Enum")
+      .value("strict", na::zoned::IndependentSetRouter::Config::Method::STRICT)
+      .value("relaxed",
+             na::zoned::IndependentSetRouter::Config::Method::RELAXED)
+      .export_values()
+      .finalize();
+
   //===--------------------------------------------------------------------===//
   // Routing-agnostic Compiler
   //===--------------------------------------------------------------------===//
@@ -63,7 +76,9 @@ PYBIND11_MODULE(MQT_QMAP_MODULE_NAME, m, py::mod_gil_not_used()) {
                     const std::string& logLevel, const double maxFillingFactor,
                     const bool useWindow, const size_t windowSize,
                     const bool dynamicPlacement,
-                    const bool warnUnsupportedGates)
+                    const na::zoned::IndependentSetRouter::Config::Method
+                        routingMethod,
+                    const double preferSplit, const bool warnUnsupportedGates)
                      -> na::zoned::RoutingAgnosticCompiler {
           na::zoned::RoutingAgnosticCompiler::Config config;
           config.logLevel = spdlog::level::from_str(logLevel);
@@ -72,6 +87,8 @@ PYBIND11_MODULE(MQT_QMAP_MODULE_NAME, m, py::mod_gil_not_used()) {
               .useWindow = useWindow,
               .windowSize = windowSize,
               .dynamicPlacement = dynamicPlacement};
+          config.layoutSynthesizerConfig.routerConfig = {
+              .method = routingMethod, .preferSplit = preferSplit};
           config.codeGeneratorConfig = {.warnUnsupportedGates =
                                             warnUnsupportedGates};
           return {arch, config};
@@ -85,6 +102,10 @@ PYBIND11_MODULE(MQT_QMAP_MODULE_NAME, m, py::mod_gil_not_used()) {
             defaultConfig.layoutSynthesizerConfig.placerConfig.windowSize,
         "dynamic_placement"_a =
             defaultConfig.layoutSynthesizerConfig.placerConfig.dynamicPlacement,
+        "routing_method"_a =
+            defaultConfig.layoutSynthesizerConfig.routerConfig.method,
+        "prefer_split"_a =
+            defaultConfig.layoutSynthesizerConfig.routerConfig.preferSplit,
         "warn_unsupported_gates"_a =
             defaultConfig.codeGeneratorConfig.warnUnsupportedGates);
   }
@@ -125,7 +146,10 @@ PYBIND11_MODULE(MQT_QMAP_MODULE_NAME, m, py::mod_gil_not_used()) {
                     const double windowRatio, const double windowShare,
                     const float deepeningFactor, const float deepeningValue,
                     const float lookaheadFactor, const float reuseLevel,
-                    const size_t maxNodes, const bool warnUnsupportedGates)
+                    const size_t maxNodes,
+                    const na::zoned::IndependentSetRouter::Config::Method
+                        routingMethod,
+                    const double preferSplit, const bool warnUnsupportedGates)
                      -> na::zoned::RoutingAwareCompiler {
           na::zoned::RoutingAwareCompiler::Config config;
           config.logLevel = spdlog::level::from_str(logLevel);
@@ -139,7 +163,10 @@ PYBIND11_MODULE(MQT_QMAP_MODULE_NAME, m, py::mod_gil_not_used()) {
               .deepeningValue = deepeningValue,
               .lookaheadFactor = lookaheadFactor,
               .reuseLevel = reuseLevel,
-              .maxNodes = maxNodes};
+              .maxNodes = maxNodes,
+          };
+          config.layoutSynthesizerConfig.routerConfig = {
+              .method = routingMethod, .preferSplit = preferSplit};
           config.codeGeneratorConfig = {.warnUnsupportedGates =
                                             warnUnsupportedGates};
           return {arch, config};
@@ -165,6 +192,10 @@ PYBIND11_MODULE(MQT_QMAP_MODULE_NAME, m, py::mod_gil_not_used()) {
             defaultConfig.layoutSynthesizerConfig.placerConfig.reuseLevel,
         "max_nodes"_a =
             defaultConfig.layoutSynthesizerConfig.placerConfig.maxNodes,
+        "routing_method"_a =
+            defaultConfig.layoutSynthesizerConfig.routerConfig.method,
+        "prefer_split"_a =
+            defaultConfig.layoutSynthesizerConfig.routerConfig.preferSplit,
         "warn_unsupported_gates"_a =
             defaultConfig.codeGeneratorConfig.warnUnsupportedGates);
   }

include/na/zoned/Compiler.hpp

@@ -159,23 +159,14 @@ class Compiler : protected Scheduler,
     }
 #endif // SPDLOG_ACTIVE_LEVEL <= SPDLOG_LEVEL_DEBUG
 
-    const auto& schedulingStart = std::chrono::system_clock::now();
     // CodeQL was not very happy about the structural binding here, hence I
     // removed it.
+    SPDLOG_DEBUG("Scheduling...");
+    const auto schedulingStart = std::chrono::system_clock::now();
     const auto& schedule = SELF.schedule(qComp);
+    const auto schedulingEnd = std::chrono::system_clock::now();
     const auto& singleQubitGateLayers = schedule.first;
     const auto& twoQubitGateLayers = schedule.second;
-    const auto& schedulingEnd = std::chrono::system_clock::now();
-    const auto& reuseQubits = SELF.analyzeReuse(twoQubitGateLayers);
-    const auto& reuseAnalysisEnd = std::chrono::system_clock::now();
-    const auto& [placement, routing] = LayoutSynthesizer::synthesize(
-        qComp.getNqubits(), twoQubitGateLayers, reuseQubits);
-    const auto& layoutSynthesisEnd = std::chrono::system_clock::now();
-    NAComputation code =
-        SELF.generate(singleQubitGateLayers, placement, routing);
-    const auto& codeGenerationEnd = std::chrono::system_clock::now();
-    assert(code.validate().first);
-
     statistics_.schedulingTime =
         std::chrono::duration_cast<std::chrono::microseconds>(schedulingEnd -
                                                               schedulingStart)
@@ -203,25 +194,44 @@ class Compiler : protected Scheduler,
           avg, max);
     }
 #endif // SPDLOG_ACTIVE_LEVEL <= SPDLOG_LEVEL_DEBUG
+
+    SPDLOG_DEBUG("Analyzing reuse...");
+    const auto reuseAnalysisStart = std::chrono::system_clock::now();
+    const auto& reuseQubits = SELF.analyzeReuse(twoQubitGateLayers);
+    const auto reuseAnalysisEnd = std::chrono::system_clock::now();
     statistics_.reuseAnalysisTime =
-        std::chrono::duration_cast<std::chrono::microseconds>(reuseAnalysisEnd -
-                                                              schedulingEnd)
+        std::chrono::duration_cast<std::chrono::microseconds>(
+            reuseAnalysisEnd - reuseAnalysisStart)
             .count();
     SPDLOG_INFO("Time for reuse analysis: {}us", statistics_.reuseAnalysisTime);
+
+    SPDLOG_DEBUG("Synthesizing layout...");
+    const auto layoutSynthesisStart = std::chrono::system_clock::now();
+    const auto& [placement, routing] = LayoutSynthesizer::synthesize(
+        qComp.getNqubits(), twoQubitGateLayers, reuseQubits);
+    const auto layoutSynthesisEnd = std::chrono::system_clock::now();
     statistics_.layoutSynthesisTime =
         std::chrono::duration_cast<std::chrono::microseconds>(
-            layoutSynthesisEnd - reuseAnalysisEnd)
+            layoutSynthesisEnd - layoutSynthesisStart)
             .count();
     statistics_.layoutSynthesizerStatistics =
         SELF.getLayoutSynthesisStatistics();
     SPDLOG_INFO("Time for layout synthesis: {}us",
                 statistics_.layoutSynthesisTime);
+
+    SPDLOG_DEBUG("Generating code...");
+    const auto codeGenerationStart = std::chrono::system_clock::now();
+    NAComputation code =
+        SELF.generate(singleQubitGateLayers, placement, routing);
+    const auto codeGenerationEnd = std::chrono::system_clock::now();
+    assert(code.validate().first);
     statistics_.codeGenerationTime =
         std::chrono::duration_cast<std::chrono::microseconds>(
-            codeGenerationEnd - layoutSynthesisEnd)
+            codeGenerationEnd - codeGenerationStart)
             .count();
     SPDLOG_INFO("Time for code generation: {}us",
                 statistics_.codeGenerationTime);
+
     statistics_.totalTime =
         std::chrono::duration_cast<std::chrono::microseconds>(
             codeGenerationEnd - schedulingStart)
@@ -254,7 +264,7 @@ class RoutingAgnosticCompiler final
   RoutingAgnosticCompiler(const Architecture& architecture,
                           const Config& config)
       : Compiler(architecture, config) {}
-  RoutingAgnosticCompiler(const Architecture& architecture)
+  explicit RoutingAgnosticCompiler(const Architecture& architecture)
       : Compiler(architecture) {}
 };
 
@@ -275,7 +285,7 @@ class RoutingAwareCompiler final
 public:
   RoutingAwareCompiler(const Architecture& architecture, const Config& config)
       : Compiler(architecture, config) {}
-  RoutingAwareCompiler(const Architecture& architecture)
+  explicit RoutingAwareCompiler(const Architecture& architecture)
       : Compiler(architecture) {}
 };
 } // namespace na::zoned

include/na/zoned/layout_synthesizer/PlaceAndRouteSynthesizer.hpp

@@ -97,9 +97,11 @@ class PlaceAndRouteSynthesizer : public LayoutSynthesizerBase,
       : PlaceAndRouteSynthesizer(architecture, Config{}) {}
 
 public:
-  [[nodiscard]] auto synthesize(
-      size_t nQubits, const std::vector<TwoQubitGateLayer>& twoQubitGateLayers,
-      const std::vector<std::unordered_set<qc::Qubit>>& reuseQubits) -> Layout {
+  [[nodiscard]] auto
+  synthesize(size_t nQubits,
+             const std::vector<TwoQubitGateLayer>& twoQubitGateLayers,
+             const std::vector<std::unordered_set<qc::Qubit>>& reuseQubits)
+      -> Layout override {
     const auto& placementStart = std::chrono::system_clock::now();
     const auto& placement =
         SELF.place(nQubits, twoQubitGateLayers, reuseQubits);

include/na/zoned/layout_synthesizer/placer/AStarPlacer.hpp

@@ -303,7 +303,7 @@ class AStarPlacer : public PlacerBase {
   place(size_t nQubits,
         const std::vector<TwoQubitGateLayer>& twoQubitGateLayers,
         const std::vector<std::unordered_set<qc::Qubit>>& reuseQubits)
-      -> std::vector<Placement>;
+      -> std::vector<Placement> override;
 
 private:
   /**

include/na/zoned/layout_synthesizer/placer/VertexMatchingPlacer.hpp

@@ -99,7 +99,7 @@ class VertexMatchingPlacer : public PlacerBase {
   place(size_t nQubits,
         const std::vector<TwoQubitGateLayer>& twoQubitGateLayers,
         const std::vector<std::unordered_set<qc::Qubit>>& reuseQubits)
-      -> std::vector<Placement>;
+      -> std::vector<Placement> override;
 
 private:
   /// Generate qubit initial layout