✨ New Zoned Neutral Atom Compiler

.github/workflows/ci.yml

@@ -130,14 +130,18 @@ jobs:
       contents: read
       id-token: write
 
+  # to properly link python bindings, the target must be enabled and pybind11 must be installed
   cpp-linter:
     name: 🇨‌ Lint
     needs: change-detection
     if: fromJSON(needs.change-detection.outputs.run-cpp-linter)
-    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-linter.yml@v1.9
+    uses: munich-quantum-toolkit/workflows/.github/workflows/reusable-cpp-linter.yml@v1.10
     with:
       setup-z3: true
       clang-version: 20
+      setup-python: true
+      install-pkgs: "pybind11==2.13.6"
+      cmake-args: "-DBUILD_MQT_QMAP_BINDINGS=ON"
 
   # run extensive Python tests whenever this is on a PR and the PR has the `extensive-python-ci` label
   python-tests:

.gitignore

@@ -138,7 +138,7 @@ _skbuild/
 
 # Any build dirs in the tests
 test/**/build/
-/src/mqt/**/_version.py
+_version.py
 
 # Common editor files
 *~

CHANGELOG.md

@@ -7,6 +7,17 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ## [Unreleased]
 
+### Added
+
+- ✨ Add new compilers for zoned neutral atom architectures (a routing-agnostic and routing-aware compiler) ([#624]) ([**@ystade**])
+- ✨ Add a new CMake function `add_mqt_qmap_binding` to add a Python binding library ([#624]) ([**@ystade**])
+
+### Changed
+
+- ♻️ Move the C++ code for the Python bindings to the top-level `bindings` directory ([#624]) ([**@ystade**])
+- ♻️ Move all Python code (no tests) to the top-level `python` directory ([#624]) ([**@ystade**])
+- ♻️ Restructure the Python bindings for neutral atom tools into separate modules ([#624]) ([**@ystade**])
+
 ## [3.0.0] - 2025-05-08
 
 _If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md#300)._

CMakeLists.txt

@@ -17,6 +17,25 @@ project(
 # Add path for custom modules
 list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 
+# set the logging level
+set(MQT_QMAP_LOG_LEVEL
+    DEBUG
+    CACHE
+      STRING
+      "Set the active log level for spdlog (possible values: TRACE, DEBUG, INFO, WARN, ERROR, CRITICAL, OFF)"
+)
+set_property(
+  CACHE MQT_QMAP_LOG_LEVEL
+  PROPERTY STRINGS
+           TRACE
+           DEBUG
+           INFO
+           WARN
+           ERROR
+           CRITICAL
+           OFF)
+add_compile_definitions(SPDLOG_ACTIVE_LEVEL=SPDLOG_LEVEL_${MQT_QMAP_LOG_LEVEL})
+
 option(BUILD_MQT_QMAP_BINDINGS "Build the MQT QMAP Python bindings" OFF)
 if(BUILD_MQT_QMAP_BINDINGS)
   # ensure that the BINDINGS option is set
@@ -55,14 +74,24 @@ endif()
 
 option(BUILD_MQT_QMAP_TESTS "Also build tests for the MQT QMAP project" ${MQT_QMAP_MASTER_PROJECT})
 
-include(cmake/ExternalDependencies.cmake)
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
+include(ExternalDependencies)
+include(AddMQTQMAPBinding)
 
 # set the include directory for the build tree
 set(MQT_QMAP_INCLUDE_BUILD_DIR "${CMAKE_CURRENT_SOURCE_DIR}/include")
 
+# set prefix for all MQT QMAP targets
+set(MQT_QMAP_TARGET_NAME mqt-qmap)
+
 # add main library code
 add_subdirectory(src)
 
+# add bindings code if enabled
+if(BUILD_MQT_QMAP_BINDINGS)
+  add_subdirectory(bindings)
+endif()
+
 # add test code
 if(BUILD_MQT_QMAP_TESTS)
   enable_testing()

UPGRADING.md

@@ -4,6 +4,10 @@ This document describes breaking changes and how to upgrade. For a complete list
 
 ## [Unreleased]
 
+This minor release initiates the efforts to re-structure the Python bindings and make them more modular.
+Even tough this is not a breaking change, it is worth mentioning to developers of MQT QMAP that all Python code (except tests) has been moved to the top-level `python` directory.
+Furthermore, the C++ code for the Python bindings has been moved to the top-level `bindings` directory.
+
 ## [3.0.0]
 
 This major release introduces several breaking changes, including the removal of deprecated features.

src/python/CMakeLists.txt → bindings/CMakeLists.txt

@@ -25,29 +25,19 @@ list(
   ${BASEPOINT}/../../core/lib
   ${BASEPOINT}/../../core/lib64)
 
-pybind11_add_module(
+add_mqt_qmap_binding(
   pyqmap
-  # Prefer thin LTO if available
-  THIN_LTO
-  # Optimize the bindings for size
-  OPT_SIZE
-  # Source code goes here
-  bindings.cpp)
+  bindings.cpp
+  LINK_LIBS
+  MQT::QMapSCExact
+  MQT::QMapSCHeuristic
+  MQT::QMapCliffordSynthesis
+  MQT::QMapHybrid
+  MQT::NASP
+  MQT::QMapNAZoned
+  MQT::CoreQASM
+  pybind11_json)
 target_compile_definitions(pyqmap PRIVATE Z3_FOUND)
-target_link_libraries(
-  pyqmap
-  PRIVATE MQT::QMapSCExact
-          MQT::QMapSCHeuristic
-          MQT::QMapCliffordSynthesis
-          MQT::QMapHybrid
-          MQT::NASP
-          MQT::CoreQASM
-          MQT::ProjectOptions
-          MQT::ProjectWarnings
-          pybind11_json)
 
-# Install directive for scikit-build-core
-install(
-  TARGETS pyqmap
-  DESTINATION .
-  COMPONENT mqt-qmap_Python)
+# add all modules
+add_subdirectory(na)

src/python/bindings.cpp → bindings/bindings.cpp

@@ -17,12 +17,7 @@
 #include "hybridmap/NeutralAtomArchitecture.hpp"
 #include "hybridmap/NeutralAtomScheduler.hpp"
 #include "hybridmap/NeutralAtomUtils.hpp"
-#include "ir/Definitions.hpp"
 #include "ir/QuantumComputation.hpp"
-#include "ir/operations/OpType.hpp"
-#include "na/NAComputation.hpp"
-#include "na/nasp/CodeGenerator.hpp"
-#include "na/nasp/Solver.hpp"
 #include "qasm3/Importer.hpp"
 #include "sc/Architecture.hpp"
 #include "sc/Mapper.hpp"
@@ -42,22 +37,28 @@
 #include "sc/heuristic/HeuristicMapper.hpp"
 #include "sc/utils.hpp"
 
-#include <algorithm>
+#include <cstddef>
 #include <cstdint>
 #include <exception>
 #include <memory>
 #include <nlohmann/json.hpp>
 #include <plog/Severity.h>
+#include <pybind11/attr.h>
+#include <pybind11/cast.h>
+#include <pybind11/detail/common.h>
 #include <pybind11/pybind11.h>
+#include <pybind11/pytypes.h>
+// NOLINTNEXTLINE(misc-include-cleaner)
 #include <pybind11/stl.h>
-#include <pybind11_json/pybind11_json.hpp>
 #include <sstream>
 #include <stdexcept>
 #include <string>
+#include <utility>
 
 namespace py = pybind11;
 using namespace pybind11::literals;
 
+namespace {
 // c++ binding function
 std::pair<qc::QuantumComputation, MappingResults>
 map(const qc::QuantumComputation& circ, Architecture& arch,
@@ -69,15 +70,15 @@ map(const qc::QuantumComputation& circ, Architecture& arch,
     } else if (config.method == Method::Exact) {
       mapper = std::make_unique<ExactMapper>(circ, arch);
     }
-  } catch (std::exception const& e) {
+  } catch (const std::exception& e) {
     std::stringstream ss{};
     ss << "Could not construct mapper: " << e.what();
     throw std::invalid_argument(ss.str());
   }
 
   try {
     mapper->map(config);
-  } catch (std::exception const& e) {
+  } catch (const std::exception& e) {
     std::stringstream ss{};
     ss << "Error during mapping: " << e.what();
     throw std::invalid_argument(ss.str());
@@ -88,6 +89,7 @@ map(const qc::QuantumComputation& circ, Architecture& arch,
 
   return {std::move(qcMapped), results};
 }
+} // namespace
 
 PYBIND11_MODULE(pyqmap, m, py::mod_gil_not_used()) {
   m.doc() = "pybind11 for the MQT QMAP quantum circuit mapping tool";
@@ -874,164 +876,4 @@ PYBIND11_MODULE(pyqmap, m, py::mod_gil_not_used()) {
            "Returns the animation csv string")
       .def("save_animation_csv", &na::NeutralAtomMapper::saveAnimationCsv,
            "Saves the animation csv string to a file", "filename"_a);
-
-  // Neutral Atom State Preparation
-  py::class_<na::NASolver>(m, "NAStatePreparationSolver", R"(
-The neutral atom state preparation solver generates an optimal sequence of
-neutral atom operations for a given state preparation circuit.
-)")
-      .def(py::init<uint16_t, uint16_t, uint16_t, uint16_t, uint16_t, uint16_t,
-                    uint16_t, uint16_t, uint16_t, uint16_t>(),
-           "max_x"_a, "max_y"_a, "max_c"_a, "max_r"_a, "max_h_offset"_a,
-           "max_v_offset"_a, "max_h_dist"_a, "max_v_dist"_a,
-           "min_entangling_y"_a, "max_entangling_y"_a, R"(
-Create a solver instance for the neutral atom state preparation problem.
-
-The solver is based on a 2D grid abstraction of the neutral atom quantum
-computer. The 2D plane is divided into interaction sites. Each interaction site
-is denoted by abstract x- and y-coordinates. The parameter `max_x` specifies the
-maximum x-coordinate, and `max_y` specifies the maximum y-coordinate. In the
-center of an interaction site, sits an SLM trap. Around that trap there are
-several possible discrete AOD positions arranged as a grid. The specific
-position of an atom within an interaction site is determined by the x- and
-y-offset from the SLM trap, i.e., those can be positive and negative. The
-maximum absolute value of the x- and y-offset is specified by `max_h_offset` and
-`max_v_offset`, respectively. Then, the parameter `max_c` specifies the maximum
-number of AOD columns, and `max_r` specifies the maximum number of AOD rows.
-Finally, in order to interact during a Rydberg stage, atoms must be located
-within a certain distance. The maximum horizontal and vertical distance between
-two atoms is specified by `max_h_dist` and `max_v_dist`, respectively. The
-parameter `min_entangling_y` specifies the minimum y-coordinate for entangling
-operations, and `max_entangling_y` specifies the maximum y-coordinate for
-entangling operations. Hence, y-coordinates outside of this range are located in
-the storage zone.
-
-.. note::
-    The solver can only handle a single storage zone below the entangling zone,
-    i.e., in this case `min_entangling_y` must be zero and `max_entangling_y`
-    must be less than `max_y`.
-
-:param max_x: is the maximum discrete x-coordinate of the interaction sites
-:param max_y: is the maximum discrete y-coordinate of the interaction sites
-:param max_c: is the maximum number of AOD columns
-:param max_r: is the maximum number of AOD rows
-:param max_h_offset: is the maximum horizontal offset of the atoms
-:param max_v_offset: is the maximum vertical offset of the atoms
-:param max_h_dist: is the maximum horizontal distance between two atoms
-:param max_v_dist: is the maximum vertical distance between two atoms
-:param min_entangling_y: is the minimum y-coordinate for entangling operations
-:param max_entangling_y: is the maximum y-coordinate for entangling operations
-:raises ValueError: if one of the parameters is invalid, e.g., is a negative
-value
-)")
-      .def("solve", &na::NASolver::solve, "ops"_a, "num_qubits"_a,
-           "num_stages"_a, "num_transfers"_a, "mind_ops_order"_a,
-           "shield_idle_qubits"_a, R"(
-Solve the neutral atom state preparation problem.
-
-The solver generates an optimal sequence of neutral atom operations for a given
-state preparation circuit. The circuit is given as a list of operations, where
-each operation is a pair of qubits. The sequence is divided into stages. Each
-stage is either a Rydberg stage or a transfer stage. In a Rydberg stage,
-adjacent qubits in the entangling zone undergo an entangling gate. In a transfer
-stage, atoms can be stored from AOD into SLM traps and loaded from SLM traps
-into AOD. At the end of each stage, the atoms are shuttled to their next
-position. The number of stages is specified by `num_stages`. The number of
-transfers is fixed by `num_transfers` if give. If this parameter is not
-specified, then the solver will determine the optimal number of transfers. The
-parameter `mind_ops_order` specifies whether the order of the operations in the
-circuit should be preserved. The parameter `shield_idle_qubits` specifies
-whether idle qubits should be shielded from the entangling operations.
-
-.. note::
-    To retrieve the list of qubit pairs from a quantum circuit, use the function
-    :func:`get_ops_for_solver`.
-
-.. note::
-    The returned solver's result can either directly exported to the JSON format
-    by calling the method :func:`json` on the result object or the result object
-    can be passed to the function :func:`generate_code` to generate code
-    consisting of neutral atom operations.
-
-:param ops: is the list of operations in the circuit
-:param num_qubits: is the number of qubits in the circuit
-:param num_stages: is the number of stages in the sequence
-:param num_transfers: (optional) is the number of transfers in the sequence
-:param mind_ops_order: is True if the order of the operations should be
-  preserved
-:param shield_idle_qubits: is True if idle qubits should be shielded
-:returns: the result of the solver
-:raises ValueError: if one of the numeral parameters is invalid, e.g., is a
-  negative value
-)");
-
-  py::class_<na::NASolver::Result>(
-      m, "NAStatePreparationSolver.Result",
-      "Neutral Atom State Preparation Solver Result")
-      .def(py::init<>(), "Create a result object")
-      .def(
-          "json",
-          [](const na::NASolver::Result& result) { return result.json(); }, R"(
-Returns the result as a JSON string.
-
-:returns: the result as a JSON string
-)");
-
-  m.def(
-      "generate_code",
-      [](const qc::QuantumComputation& qc, const na::NASolver::Result& result,
-         const uint16_t minAtomDist, const uint16_t noInteractionRadius,
-         const uint16_t zoneDist) {
-        return na::CodeGenerator::generate(qc, result, minAtomDist,
-                                           noInteractionRadius, zoneDist)
-            .toString();
-      },
-      "qc"_a, "result"_a, "min_atom_dist"_a = 1, "no_interaction_radius"_a = 10,
-      "zone_dist"_a = 24, R"(
-Generate code for the given circuit using the solver's result. Some parameters
-of the abstraction from the 2D grid used for the solver must be provided again.
-
-:param qc: is the quantum circuit
-:param result: is the result of the solver
-:param min_atom_dist: is the minimum distance between atoms
-:param no_interaction_radius: is the radius around an atom where no other atom
-  can be placed during an entangling operation that should not interact with the
-  atom
-:param zone_dist: is the distance between zones, i.e., the minimal distance
-  between two atoms in different zones
-:raises ValueError: if one of the numeral parameters is invalid, e.g., is a
-  negative value)");
-
-  m.def(
-      "get_ops_for_solver",
-      [](const qc::QuantumComputation& qc, const std::string& operationType,
-         const uint64_t numControls, const bool quiet) {
-        auto opTypeLowerStr = operationType;
-        std::transform(opTypeLowerStr.begin(), opTypeLowerStr.end(),
-                       opTypeLowerStr.begin(),
-                       [](unsigned char c) { return std::tolower(c); });
-        return na::NASolver::getOpsForSolver(
-            qc, qc::opTypeFromString(operationType), numControls, quiet);
-      },
-      "qc"_a, "operation_type"_a = "Z", "num_operands"_a = 1, "quiet"_a = true,
-      R"(
-Extract entangling operations as list of qubit pairs from the circuit.
-
-.. warning::
-    This function can only extract qubit pairs of two-qubit operations.
-    I.e., the operands of the operation plus the controls must be equal to two.
-
-:param qc: is the quantum circuit
-:param operation_type: is the type of operation to extract, e.g., "z" for CZ
-  gates
-:param num_controls: is the number of controls the operation acts on, e.g., 1
-  for CZ gates
-:param quiet: if True, suppresses warning when the circuit contains operations
-  other than the specified operation type
-:return: list of qubit pairs
-:raises ValueError: if the circuit contains operations other than the specified
-  operation type and quiet is False
-:raises ValueError: if the operation has more than two operands including
-  controls
-)");
 }