Decomposition

bindings/na/register_zoned.cpp

@@ -371,6 +371,161 @@ void registerZoned(nb::module_& m) {
       },
       R"pb(Get the statistics of the last compilation.
 
+Returns:
+    The statistics as a dictionary)pb");
+
+  //===--------------------------------------------------------------------===//
+  // Routing-aware native gate Compiler
+  //===--------------------------------------------------------------------===//
+  nb::class_<na::zoned::RoutingAwareNativeGateCompiler>
+      routingAwareNativeGateCompiler(
+          m, "RoutingAwareNativeGateCompiler",
+          "Routing-aware native gate zoned neutral atom compiler.");
+  {
+    const na::zoned::RoutingAwareNativeGateCompiler::Config defaultConfig;
+    routingAwareNativeGateCompiler.def(
+        "__init__",
+        [](na::zoned::RoutingAwareNativeGateCompiler* self,
+           const na::zoned::Architecture& arch, const std::string& logLevel,
+           const double maxFillingFactor, const bool useWindow,
+           const size_t windowMinWidth, const double windowRatio,
+           const double windowShare,
+           const na::zoned::HeuristicPlacer::Config::Method placementMethod,
+           const float deepeningFactor, const float deepeningValue,
+           const float lookaheadFactor, const float reuseLevel,
+           const size_t maxNodes, const size_t trials,
+           const size_t queueCapacity,
+           const na::zoned::IndependentSetRouter::Config::Method routingMethod,
+           const double preferSplit, const bool warnUnsupportedGates) {
+          na::zoned::RoutingAwareNativeGateCompiler::Config config;
+          config.logLevel = spdlog::level::from_str(logLevel);
+          config.schedulerConfig.maxFillingFactor = maxFillingFactor;
+          config.layoutSynthesizerConfig.placerConfig = {
+              .useWindow = useWindow,
+              .windowMinWidth = windowMinWidth,
+              .windowRatio = windowRatio,
+              .windowShare = windowShare,
+              .method = placementMethod,
+              .deepeningFactor = deepeningFactor,
+              .deepeningValue = deepeningValue,
+              .lookaheadFactor = lookaheadFactor,
+              .reuseLevel = reuseLevel,
+              .maxNodes = maxNodes,
+              .trials = trials,
+              .queueCapacity = queueCapacity,
+          };
+          config.layoutSynthesizerConfig.routerConfig = {
+              .method = routingMethod, .preferSplit = preferSplit};
+          config.codeGeneratorConfig = {.warnUnsupportedGates =
+                                            warnUnsupportedGates};
+          new (self) na::zoned::RoutingAwareNativeGateCompiler{arch, config};
+        },
+        nb::keep_alive<1, 2>(), "arch"_a,
+        "log_level"_a = spdlog::level::to_short_c_str(defaultConfig.logLevel),
+        "max_filling_factor"_a = defaultConfig.schedulerConfig.maxFillingFactor,
+        "use_window"_a =
+            defaultConfig.layoutSynthesizerConfig.placerConfig.useWindow,
+        "window_min_width"_a =
+            defaultConfig.layoutSynthesizerConfig.placerConfig.windowMinWidth,
+        "window_ratio"_a =
+            defaultConfig.layoutSynthesizerConfig.placerConfig.windowRatio,
+        "window_share"_a =
+            defaultConfig.layoutSynthesizerConfig.placerConfig.windowShare,
+        "placement_method"_a =
+            defaultConfig.layoutSynthesizerConfig.placerConfig.method,
+        "deepening_factor"_a =
+            defaultConfig.layoutSynthesizerConfig.placerConfig.deepeningFactor,
+        "deepening_value"_a =
+            defaultConfig.layoutSynthesizerConfig.placerConfig.deepeningValue,
+        "lookahead_factor"_a =
+            defaultConfig.layoutSynthesizerConfig.placerConfig.lookaheadFactor,
+        "reuse_level"_a =
+            defaultConfig.layoutSynthesizerConfig.placerConfig.reuseLevel,
+        "max_nodes"_a =
+            defaultConfig.layoutSynthesizerConfig.placerConfig.maxNodes,
+        "trials"_a = defaultConfig.layoutSynthesizerConfig.placerConfig.trials,
+        "queue_capacity"_a =
+            defaultConfig.layoutSynthesizerConfig.placerConfig.queueCapacity,
+        "routing_method"_a =
+            defaultConfig.layoutSynthesizerConfig.routerConfig.method,
+        "prefer_split"_a =
+            defaultConfig.layoutSynthesizerConfig.routerConfig.preferSplit,
+        "warn_unsupported_gates"_a =
+            defaultConfig.codeGeneratorConfig.warnUnsupportedGates,
+        R"pb(Create a routing-aware native gate compiler for the given architecture and configurations.
+
+Args:
+    arch: The zoned neutral atom architecture
+    log_level: The log level for the compiler, possible values are "debug"/"D", "info"/"I", "warning"/"W", "error"/"E", and "critical"/"C"
+    max_filling_factor: The maximum filling factor for the entanglement zone, i.e., it sets the limit for the maximum number of entangling gates that are scheduled in parallel
+    use_window: Whether to use a window for the placer
+    window_min_width: The minimum width of the window for the placer
+    window_ratio: The ratio between the height and the width of the window
+    window_share: The share of free sites in the window in relation to the number of atoms to be moved in this step
+    placement_method: The placement method that should be used for the heuristic placer
+    deepening_factor: Controls the impact of the term in the heuristic of the A* search that resembles the standard deviation of the differences between the current and target sites of the atoms to be moved in every orientation
+    deepening_value: Is added to the sum of standard deviations before it is multiplied with the number of unplaced nodes and :attr:`deepening_factor`
+    lookahead_factor: Controls the lookahead's influence that considers the distance of atoms to their interaction partner in the next layer
+    reuse_level: The reuse level that corresponds to the estimated extra fidelity loss due to the extra trap transfers when the atom is not reused and instead moved to the storage zone and back to the entanglement zone
+    max_nodes: The maximum number of nodes that are considered in the A* search.
+        If this number is exceeded, the search is aborted and an error is raised.
+        In the current implementation, one node roughly consumes 120 Byte.
+        Hence, allowing 50,000,000 nodes results in memory consumption of about 6 GB plus the size of the rest of the data structures.
+    trials: The number of restarts during IDS.
+    queue_capacity: The maximum capacity of the priority queue used during IDS.
+    routing_method: The routing method that should be used for the independent set router
+    prefer_split: The threshold factor for group merging decisions during routing.
+    warn_unsupported_gates: Whether to warn about unsupported gates in the code generator)pb");
+  }
+
+  routingAwareNativeGateCompiler.def_static(
+      "from_json_string",
+      [](const na::zoned::Architecture& arch,
+         const std::string& json) -> na::zoned::RoutingAwareNativeGateCompiler {
+        // The correct header <nlohmann/json.hpp> is included, but clang-tidy
+        // confuses it with the wrong forward header <nlohmann/json_fwd.hpp>
+        // NOLINTNEXTLINE(misc-include-cleaner)
+        return {arch, nlohmann::json::parse(json)};
+      },
+      "arch"_a, "json"_a,
+      R"pb(Create a compiler for the given architecture and configurations from a JSON string.
+
+Args:
+    arch: The zoned neutral atom architecture
+    json: The JSON string
+
+Returns:
+    The initialized compiler
+
+Raises:
+    ValueError: If the string is not a valid JSON string)pb");
+
+  routingAwareNativeGateCompiler.def(
+      "compile",
+      [](na::zoned::RoutingAwareNativeGateCompiler& self,
+         const qc::QuantumComputation& qc) -> std::string {
+        return self.compile(qc).toString();
+      },
+      "qc"_a,
+      R"pb(Compile a quantum circuit for the zoned neutral atom architecture.
+
+Args:
+    qc: The quantum circuit
+
+Returns:
+    The compilation result as a string in the .naviz format.)pb");
+
+  routingAwareNativeGateCompiler.def(
+      "stats",
+      [](const na::zoned::RoutingAwareNativeGateCompiler& self) {
+        const auto json = nb::module_::import_("json");
+        const auto loads = json.attr("loads");
+        const nlohmann::json stats = self.getStatistics();
+        const auto dict = loads(stats.dump());
+        return nb::cast<nb::typed<nb::dict, nb::str, nb::float_>>(dict);
+      },
+      R"pb(Get the statistics of the last compilation.
+
 Returns:
     The statistics as a dictionary)pb");
 }

include/na/zoned/Compiler.hpp

@@ -12,6 +12,7 @@
 
 #include "Architecture.hpp"
 #include "code_generator/CodeGenerator.hpp"
+#include "decomposer/NativeGateDecomposer.hpp"
 #include "decomposer/NoOpDecomposer.hpp"
 #include "ir/QuantumComputation.hpp"
 #include "ir/operations/Operation.hpp"
@@ -203,7 +204,7 @@ class Compiler : protected Scheduler,
     SPDLOG_DEBUG("Decomposing...");
     const auto decomposingStart = std::chrono::system_clock::now();
     const auto& decomposedSingleQubitGateLayers =
-        SELF.decompose(singleQubitGateLayers);
+        SELF.decompose(qComp.getNqubits(), singleQubitGateLayers);
     const auto decomposingEnd = std::chrono::system_clock::now();
     statistics_.decomposingTime =
         std::chrono::duration_cast<std::chrono::microseconds>(decomposingEnd -
@@ -311,4 +312,17 @@ class RoutingAwareCompiler final
   explicit RoutingAwareCompiler(const Architecture& architecture)
       : Compiler(architecture) {}
 };
+
+class RoutingAwareNativeGateCompiler final
+    : public Compiler<RoutingAwareNativeGateCompiler, ASAPScheduler,
+                      NativeGateDecomposer, VertexMatchingReuseAnalyzer,
+                      RoutingAwareSynthesizer, CodeGenerator> {
+public:
+  RoutingAwareNativeGateCompiler(const Architecture& architecture,
+                                 const Config& config)
+      : Compiler(architecture, config) {}
+
+  explicit RoutingAwareNativeGateCompiler(const Architecture& architecture)
+      : Compiler(architecture) {}
+};
 } // namespace na::zoned

include/na/zoned/decomposer/DecomposerBase.hpp

@@ -24,12 +24,14 @@ class DecomposerBase {
   virtual ~DecomposerBase() = default;
   /**
    * This function defines the interface of the decomposer.
+   * @param nQubits is the number of qubits in the quantum computation.
    * @param singleQubitGateLayers are the layers of single-qubit gates that are
    * meant to be first decomposed into the native gate set.
    * @return the new single-qubit gate layers
    */
-  [[nodiscard]] virtual auto decompose(
-      const std::vector<SingleQubitGateRefLayer>& singleQubitGateLayers) const
+  [[nodiscard]] virtual auto
+  decompose(size_t nQubits,
+            const std::vector<SingleQubitGateRefLayer>& singleQubitGateLayers)
       -> std::vector<SingleQubitGateLayer> = 0;
 };
 } // namespace na::zoned

include/na/zoned/decomposer/NativeGateDecomposer.hpp

@@ -0,0 +1,133 @@
+/*
+ * Copyright (c) 2023 - 2026 Chair for Design Automation, TUM
+ * Copyright (c) 2025 - 2026 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+#pragma once
+
+#include "DecomposerBase.hpp"
+#include "ir/operations/StandardOperation.hpp"
+#include "na/zoned/Types.hpp"
+
+#include <vector>
+
+namespace na::zoned {
+
+class NativeGateDecomposer : public DecomposerBase {
+  /**
+   * A minimal struct to store the parameters of a U3 gate along with the qubit
+   * it acts on.
+   */
+  struct StructU3 {
+    std::array<qc::fp, 3> angles;
+    qc::Qubit qubit;
+  };
+  /**
+   * A quaternion is represented by an array of four `qc::fp` values `{q0, q1,
+   * q2, q3}` denoting the components of the quaternion.
+   */
+  using Quaternion = std::array<qc::fp, 4>;
+  size_t nQubits_ = 0;
+
+  /// Tolerance for floating-point comparisons, scaled to account for
+  /// accumulated rounding errors in quaternion arithmetic (~10 bits margin).
+  constexpr static qc::fp epsilon =
+      std::numeric_limits<qc::fp>::epsilon() * 1024;
+
+public:
+  /// The configuration of the NativeGateDecomposer
+  struct Config {
+    template <typename BasicJsonType>
+    friend void to_json(BasicJsonType& /* unused */,
+                        const Config& /* unused */) {}
+    template <typename BasicJsonType>
+    friend void from_json(const BasicJsonType& /* unused */,
+                          Config& /* unused */) {}
+  };
+
+private:
+  /**
+   * @brief Takes a vector of SingleQubitGateLayers and, for each layer,
+   * transforms all gates into U3 gates represented by `StructU3` objects.
+   * @details It combines all gates acting on the same qubit into a single U3
+   * gate.
+   * @param layers is a std::vector of SingleQubitGateLayers of a scheduled
+   * circuit.
+   * @returns a vector of vectors of StructU3 objects representing the single
+   * qubit gate layers.
+   */
+  [[nodiscard]] auto
+  transformToU3(const std::vector<SingleQubitGateRefLayer>& layers) const
+      -> std::vector<std::vector<StructU3>>;
+
+public:
+  /// Create a new NativeGateDecomposer.
+  NativeGateDecomposer(const Architecture& /* unused */,
+                       const Config& /* unused */) {}
+
+  /**
+   * @brief Converts commonly used single qubit gates into their Quaternion
+   * representation.
+   * @details A single qubit gate R_v(phi) with rotation axis v=(v0,v1,v2)
+   * and rotation angle phi can be represented as a quaternion:
+   * @code quaternion(R_v(phi)) = (cos(phi/2) * I, v0 * sin(phi/2) * X, v1 *
+   * sin(phi/2) * Y, v2 * sin(phi/2) * Z)@endcode with X, Y, Z Pauli Matrices.
+   * @param op a reference_wrapper to the operation to be converted
+   * @returns a quaternion.
+   */
+  static auto
+  convertGateToQuaternion(std::reference_wrapper<const qc::Operation> op)
+      -> Quaternion;
+  /**
+   * @brief Merges the quaternions representing two gates as in a matrix
+   * multiplication of the gates.
+   * @param q1 the first quaternion to be combined.
+   * @param q2 the second quaternion to be combined.
+   * @returns an quaternion.
+   */
+  static auto combineQuaternions(const Quaternion& q1, const Quaternion& q2)
+      -> Quaternion;
+  /**
+   * @brief Calculates the values of the U3-gate parameters theta, phi, and
+   * lambda.
+   * @param quat is a quaternion representing a single qubit gate.
+   * @returns an array of three `qc::fp` values `{theta, phi, lambda}` giving
+   * the U3 gate angles.
+   */
+  static auto getU3AnglesFromQuaternion(const Quaternion& quat)
+      -> std::array<qc::fp, 3>;
+
+  /**
+   * @brief Calculates the largest value of the U3-gate parameter theta from a
+   * vector of operations.
+   * @param layer is a vector of U3 parameters.
+   * @returns the maximal value of theta in the given layer.
+   */
+  static auto calcThetaMax(const std::vector<StructU3>& layer) -> qc::fp;
+
+  /**
+   * @brief Takes a vector of `qc::fp` representing the U3-gate angles of a
+   * single-qubit gate and the maximal value of theta for the single qubit gate
+   * layer and calculates the transversal decomposition angles as in Nottingham
+   * et. al. 2024.
+   * @param angles is a `std::array` of `qc::fp` representing (theta, phi,
+   * lambda).
+   * @param theta_max the maximal theta value of the single-qubit gate layer.
+   * @returns an array of `qc::fp` values giving the angles (chi, gamma_minus,
+   * gamma_plus).
+   */
+  auto static getDecompositionAngles(const std::array<qc::fp, 3>& angles,
+                                     qc::fp theta_max) -> std::array<qc::fp, 3>;
+
+  [[nodiscard]] auto
+  decompose(size_t nQubits,
+            const std::vector<SingleQubitGateRefLayer>& singleQubitGateLayers)
+      -> std::vector<SingleQubitGateLayer> override;
+};
+
+} // namespace na::zoned

include/na/zoned/decomposer/NoOpDecomposer.hpp

@@ -27,17 +27,10 @@ class NoOpDecomposer : public DecomposerBase {
 public:
   /// The configuration of the NoOpDecomposer
   struct Config {
-    template <
-        typename BasicJsonType,
-        nlohmann::detail::enable_if_t<
-            nlohmann::detail::is_basic_json<BasicJsonType>::value, int> = 0>
+    template <typename BasicJsonType>
     friend void to_json(BasicJsonType& /* unused */,
                         const Config& /* unused */) {}
-
-    template <
-        typename BasicJsonType,
-        nlohmann::detail::enable_if_t<
-            nlohmann::detail::is_basic_json<BasicJsonType>::value, int> = 0>
+    template <typename BasicJsonType>
     friend void from_json(const BasicJsonType& /* unused */,
                           Config& /* unused */) {}
   };
@@ -48,8 +41,9 @@ class NoOpDecomposer : public DecomposerBase {
   NoOpDecomposer(const Architecture& /* unused */, const Config& /* unused */) {
   }
 
-  [[nodiscard]] auto decompose(
-      const std::vector<SingleQubitGateRefLayer>& singleQubitGateLayers) const
+  [[nodiscard]] auto
+  decompose(size_t nQubits,
+            const std::vector<SingleQubitGateRefLayer>& singleQubitGateLayers)
       -> std::vector<SingleQubitGateLayer> override;
 };
 } // namespace na::zoned