✨ Add buffer size support to HybridSynthesisMapper (#885)

## Description

This PR adds buffer functionality to the ZX hybrid synthesis mapper,
enabling staged operation management before mapping to hardware. The
changes introduce a bufferSize parameter and bufferedQc quantum
computation to temporarily store operations, along with support for
complete remapping and more flexible synthesis evaluation.

These are the extension which will be presented at DATE 2026

## Checklist:

- [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.
- [x] 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.
- [x] The changes are fully tested and pass the CI checks.
- [x] I have reviewed my own code changes.

Author: lsschmid

bindings/hybrid_mapper/hybrid_mapper.cpp

@@ -228,10 +228,10 @@ PYBIND11_MODULE(MQT_QMAP_MODULE_NAME, m, py::mod_gil_not_used()) {
       "Neutral Atom Mapper that can evaluate different synthesis steps "
       "to choose the best one.")
       .def(py::init<const na::NeutralAtomArchitecture&,
-                    const na::MapperParameters&>(),
+                    const na::MapperParameters&, uint32_t>(),
            "Create Hybrid Synthesis Mapper with mapper parameters.",
            py::keep_alive<1, 2>(), py::keep_alive<1, 3>(), "arch"_a,
-           "params"_a = na::MapperParameters())
+           "params"_a = na::MapperParameters(), "buffer_size"_a = 0)
       .def("set_parameters", &na::HybridSynthesisMapper::setParameters,
            "Set the parameters for the Hybrid Synthesis Mapper.", "params"_a,
            py::keep_alive<1, 2>())
@@ -267,22 +267,15 @@ PYBIND11_MODULE(MQT_QMAP_MODULE_NAME, m, py::mod_gil_not_used()) {
            "Saves the synthesized circuit with all gates but not "
            "mapped to the hardware as qasm2 to a file.",
            "filename"_a)
-      .def(
-          "append_without_mapping",
-          [](na::HybridSynthesisMapper& mapper, qc::QuantumComputation& qc) {
-            mapper.appendWithoutMapping(qc);
-          },
-          "Appends the given QuantumComputation to the synthesized "
-          "QuantumComputation without mapping it to the hardware.",
-          "qc"_a)
       .def(
           "append_with_mapping",
-          [](na::HybridSynthesisMapper& mapper, qc::QuantumComputation& qc) {
-            mapper.appendWithMapping(qc);
+          [](na::HybridSynthesisMapper& mapper, qc::QuantumComputation& qc,
+             bool completeRemap) {
+            mapper.appendWithMapping(qc, completeRemap);
           },
           "Appends the given QuantumComputation to the synthesized "
           "QuantumComputation and maps the gates to the hardware.",
-          "qc"_a)
+          "qc"_a, "complete_remap"_a = false)
       .def(
           "get_circuit_adjacency_matrix",
           [](const na::HybridSynthesisMapper& mapper) {
@@ -301,15 +294,20 @@ PYBIND11_MODULE(MQT_QMAP_MODULE_NAME, m, py::mod_gil_not_used()) {
       .def(
           "evaluate_synthesis_steps",
           [](na::HybridSynthesisMapper& mapper,
-             std::vector<qc::QuantumComputation>& qcs, bool alsoMap) {
-            return mapper.evaluateSynthesisSteps(qcs, alsoMap);
+             std::vector<qc::QuantumComputation>& qcs, bool completeRemap,
+             bool alsoMap) {
+            return mapper.evaluateSynthesisSteps(qcs, completeRemap, alsoMap);
           },
           "Evaluates the synthesis steps proposed by the ZX extraction. "
           "Returns a list of fidelities of the mapped synthesis steps.",
-          "synthesis_steps"_a, "also_map"_a = false)
-      .def("complete_remap", &na::HybridSynthesisMapper::completeRemap,
-           "Remaps the synthesized QuantumComputation to the hardware.",
-           "initial_mapping"_a = na::InitialMapping::Identity)
+          "synthesis_steps"_a, "complete_remap"_a = false, "also_map"_a = false)
+      .def(
+          "complete_remap",
+          [](na::HybridSynthesisMapper& mapper, bool includeBuffer) {
+            mapper.completeRemap(includeBuffer);
+          },
+          "Remaps the QuantumComputation to the hardware.",
+          "include_buffer"_a = true)
       .def(
           "schedule",
           [](na::HybridSynthesisMapper& mapper, const bool verbose,

include/hybridmap/HybridSynthesisMapper.hpp

@@ -17,12 +17,13 @@
 
 #include "HybridNeutralAtomMapper.hpp"
 #include "NeutralAtomArchitecture.hpp"
-#include "NeutralAtomUtils.hpp"
+#include "hybridmap/Mapping.hpp"
 #include "hybridmap/NeutralAtomDefinitions.hpp"
+#include "hybridmap/NeutralAtomScheduler.hpp"
 #include "ir/Definitions.hpp"
 #include "ir/QuantumComputation.hpp"
 
-#include <cstddef>
+#include <cstdint>
 #include <fstream>
 #include <sstream>
 #include <stdexcept>
@@ -44,103 +45,187 @@ class HybridSynthesisMapper : public NeutralAtomMapper {
   using qcs = std::vector<qc::QuantumComputation>;
 
   qc::QuantumComputation synthesizedQc;
+  qc::QuantumComputation bufferedQc;
+  uint32_t bufferSize;
+  Mapping originalMapping;
   bool initialized = false;
 
   /**
    * @brief Evaluate a single proposed synthesis step.
    * @details Effort considers swaps/shuttling and execution time estimated by
    * the mapper.
    * @param qc Proposed synthesis subcircuit.
+   * @param completeRemap If `true`, evaluate by completely remapping the whole
+   * circuit; if `false`, preserve the current mapping state.
    * @return Scalar cost/effort score for mapping qc.
    */
-  qc::fp evaluateSynthesisStep(qc::QuantumComputation& qc) const;
+  qc::fp evaluateSynthesisStep(qc::QuantumComputation& qc,
+                               bool completeRemap = false) const;
 
 public:
   // Constructors
   HybridSynthesisMapper() = delete;
   /**
-   * @brief Construct with device and optional mapper parameters.
-   * @param arch Neutral atom architecture.
-   * @param params Optional mapper configuration parameters.
+   * @brief Create a HybridSynthesisMapper configured for a neutral-atom device.
+   *
+   * @param arch Neutral-atom device architecture used for mapping and
+   * scheduling.
+   * @param params Optional mapper configuration parameters; defaults to
+   * MapperParameters().
+   * @param bufferSize Number of operations to hold in the internal buffer
+   * before flushing to the synthesized circuit (0 disables buffering).
    */
   explicit HybridSynthesisMapper(
       const NeutralAtomArchitecture& arch,
-      const MapperParameters& params = MapperParameters())
-      : NeutralAtomMapper(arch, params) {}
+      const MapperParameters& params = MapperParameters(),
+      const uint32_t bufferSize = 0)
+      : NeutralAtomMapper(arch, params), bufferSize(bufferSize) {}
 
   // Functions
 
   /**
-   * @brief Initialize synthesized and mapped circuits and mapping structures.
-   * @param nQubits Number of logical qubits to synthesize.
+   * @brief Initialize internal circuits and mapping state for a given number of
+   * logical qubits.
+   *
+   * Sets up the synthesized and buffered quantum computations, the mapped
+   * circuit storage, the logical-to-physical mapping, and records the original
+   * mapping; marks the mapper as initialized.
+   *
+   * @param nQubits Number of logical qubits to prepare.
+   * @throws std::runtime_error if `nQubits` exceeds the architecture's
+   * available positions.
    */
   void initMapping(const size_t nQubits) {
     if (nQubits > arch->getNpositions()) {
       throw std::runtime_error("Not enough qubits in architecture.");
     }
     mappedQc = qc::QuantumComputation(arch->getNpositions());
     synthesizedQc = qc::QuantumComputation(nQubits);
+    bufferedQc = qc::QuantumComputation(nQubits);
     mapping = Mapping(nQubits);
     initialized = true;
+    originalMapping = mapping;
   }
 
   /**
-   * @brief Complete a (re-)mapping of the synthesized circuit to hardware.
-   * @param initMapping Initial mapping heuristic (defaults to Identity).
+   * @brief Remap the synthesized circuit onto the stored original hardware
+   * mapping.
+   *
+   * If `includeBuffer` is true, the remap uses the combined
+   * synthesized-plus-buffered circuit returned by getSynthesizedQc(); otherwise
+   * it remaps only the internal synthesizedQc (excluding buffered operations).
+   * The result is mapped into originalMapping.
+   *
+   * @param includeBuffer When true, include buffered operations in the remap.
    */
-  void completeRemap(const InitialMapping initMapping = Identity) {
-    auto qcCopy = synthesizedQc;
-    map(qcCopy, initMapping);
+  void completeRemap(const bool includeBuffer = true) {
+    if (includeBuffer) {
+      auto copyQC = getSynthesizedQc();
+      map(copyQC, originalMapping);
+    } else {
+      auto temp = synthesizedQc;
+      map(temp, originalMapping);
+    }
+  }
+
+  /**
+   * @brief Appends buffered operations into the synthesized circuit, maps them,
+   * and schedules the mapped circuit.
+   *
+   * Appends all operations currently held in the internal buffer to the
+   * synthesized circuit, applies mapping for those appended operations, clears
+   * the buffer, and then performs the scheduling pass using the base mapper.
+   *
+   * @param verboseArg Enable verbose scheduling output when true.
+   * @param createAnimationCsv Emit scheduling animation CSV when true.
+   * @param shuttlingSpeedFactor Factor to scale shuttling durations during
+   * scheduling (1.0 = nominal speed).
+   * @return SchedulerResults Results produced by the scheduling pass (timing
+   * and placement outcomes).
+   */
+  [[nodiscard]] SchedulerResults
+  schedule(const bool verboseArg = false, const bool createAnimationCsv = false,
+           const qc::fp shuttlingSpeedFactor = 1.0) {
+    for (const auto& op : bufferedQc) {
+      synthesizedQc.emplace_back(op->clone());
+    }
+    mapAppend(bufferedQc, this->mapping);
+    bufferedQc.clear();
+    return NeutralAtomMapper::schedule(verboseArg, createAnimationCsv,
+                                       shuttlingSpeedFactor);
   }
 
   /**
-   * @brief Get the currently synthesized (unmapped) circuit.
-   * @return Synthesized QuantumComputation.
+   * @brief Return a combined view of the synthesized and buffered (unmapped)
+   * circuit.
+   *
+   * The returned QuantumComputation contains all operations from the mapper's
+   * synthesized circuit followed by any buffered operations, using the mapper's
+   * current qubit count.
+   *
+   * @return qc::QuantumComputation A new QuantumComputation with synthesized
+   * operations then buffered operations.
    */
   [[nodiscard]] qc::QuantumComputation getSynthesizedQc() const {
-    return synthesizedQc;
+    qc::QuantumComputation qc(synthesizedQc.getNqubits());
+    qc.reserve(synthesizedQc.size() + bufferedQc.size());
+    for (const auto& op : synthesizedQc) {
+      qc.emplace_back(op->clone());
+    }
+    for (const auto& op : bufferedQc) {
+      qc.emplace_back(op->clone());
+    }
+    return qc;
   }
 
   /**
-   * @brief Export synthesized circuit as OpenQASM string.
-   * @return QASM representation of the synthesized circuit.
+   * @brief Produce the OpenQASM representation of the synthesized circuit.
+   *
+   * Returns an OpenQASM string for the current synthesized circuit view,
+   * including any buffered operations not yet scheduled.
+   *
+   * @return std::string OpenQASM text describing the synthesized (and buffered)
+   * circuit.
    */
   [[nodiscard]] [[maybe_unused]] std::string getSynthesizedQcQASM() const {
     std::stringstream ss;
-    synthesizedQc.dumpOpenQASM(ss, false);
+    const auto copyQC = getSynthesizedQc();
+    copyQC.dumpOpenQASM(ss, false);
     return ss.str();
   }
 
   /**
-   * @brief Save synthesized circuit as OpenQASM to a file.
-   * @param filename Output filename.
+   * @brief Write the current synthesized circuit (including buffered
+   * operations) to a file in OpenQASM format.
+   *
+   * @param filename Path to the output file where the OpenQASM representation
+   * will be written.
    */
   [[maybe_unused]] void saveSynthesizedQc(const std::string& filename) const {
     std::ofstream ofs(filename);
-    synthesizedQc.dumpOpenQASM(ofs, false);
+    const auto copyQC = getSynthesizedQc();
+    copyQC.dumpOpenQASM(ofs, false);
     ofs.close();
   }
 
   /**
    * @brief Evaluate candidate synthesis steps and optionally map the best.
    * @param synthesisSteps Vector of candidate subcircuits.
+   * @param completeRemap If true, completely remap before evaluation.
    * @param alsoMap If true, append and map the best candidate.
    * @return List of fidelity scores for mapped steps (order matches input).
    */
   std::vector<qc::fp> evaluateSynthesisSteps(qcs& synthesisSteps,
+                                             bool completeRemap = false,
                                              bool alsoMap = false);
 
-  /**
-   * @brief Append gates without mapping (no SWAPs/shuttling inserted).
-   * @param qc Subcircuit to append as-is.
-   */
-  void appendWithoutMapping(const qc::QuantumComputation& qc);
-
   /**
    * @brief Append and map a subcircuit to hardware (may insert moves/SWAPs).
    * @param qc Subcircuit to append and map.
+   * @param completeRemap If true, completely remap before appending.
    */
-  void appendWithMapping(qc::QuantumComputation& qc);
+  void appendWithMapping(qc::QuantumComputation& qc,
+                         bool completeRemap = false);
 
   /**
    * @brief Get the current device adjacency (connectivity) matrix.

python/mqt/qmap/hybrid_mapper.pyi

@@ -99,21 +99,22 @@ class HybridNAMapper:
 
 # noinspection DuplicatedCode
 class HybridSynthesisMapper:
-    def __init__(self, arch: NeutralAtomHybridArchitecture, params: MapperParameters = ...) -> None: ...
-    def append_with_mapping(self, qc: QuantumComputation) -> None: ...
-    def append_without_mapping(self, qc: QuantumComputation) -> None: ...
-    def complete_remap(self, initial_mapping: InitialCircuitMapping = ...) -> None: ...
+    def __init__(
+        self, arch: NeutralAtomHybridArchitecture, params: MapperParameters = ..., buffer_size: typing.SupportsInt = ...
+    ) -> None: ...
+    def append_with_mapping(self, qc: QuantumComputation, complete_remap: bool = ...) -> None: ...
+    def complete_remap(self, include_buffer: bool = ...) -> None: ...
     def convert_to_aod(self) -> None: ...
     def evaluate_synthesis_steps(
-        self, synthesis_steps: list[QuantumComputation], also_map: bool = ...
+        self, synthesis_steps: list[QuantumComputation], complete_remap: bool = ..., also_map: bool = ...
     ) -> list[float]: ...
     def get_circuit_adjacency_matrix(self) -> list[list[int]]: ...
-    def get_mapped_qc_qasm(self) -> str: ...
     def get_mapped_qc_aod_qasm(self) -> str: ...
+    def get_mapped_qc_qasm(self) -> str: ...
     def get_synthesized_qc_qasm(self) -> str: ...
     def init_mapping(self, n_qubits: typing.SupportsInt) -> None: ...
-    def save_mapped_qc_qasm(self, filename: str) -> None: ...
     def save_mapped_qc_aod_qasm(self, filename: str) -> None: ...
+    def save_mapped_qc_qasm(self, filename: str) -> None: ...
     def save_synthesized_qc_qasm(self, filename: str) -> None: ...
     def schedule(
         self, verbose: bool = ..., create_animation_csv: bool = ..., shuttling_speed_factor: typing.SupportsFloat = ...