🎨 Refactor NAComputation with concrete base classes for every operation and ouput new .naviz format (#846)

## Description

The tool [`mqt-naviz`](github.com/cda-tum/mqt-naviz) purposefully
introduces a new textual format that allows to execute operations at a
specific time stamp. The current output format of NA computation is not
really compatible even though `mqt-naviz` supports a legacy feature to
read in this old format with some caveats.

This issue triggered a wider refactoring of the `NAComputation`. Its
entire structure is refactored. Most importantly, concrete Operation
have their own class representation inheriting from some super class. At
the end, all operations inherit from the class `Op`. As part of the
refactoring, there is a straight forward way to test whether an
operation is of some particular type and then it can be casted to this
type.

## Checklist:

- [x] The pull request only contains commits that are related to it.
- [x] I have added appropriate tests and documentation.
- [x] I have made sure that all CI jobs on GitHub pass.
- [x] The pull request introduces no new warnings and follows the
project's style guidelines.

---------

Signed-off-by: burgholzer <[email protected]>
Co-authored-by: Lukas Burgholzer <[email protected]>

Author: ystade

.clang-tidy

@@ -55,7 +55,7 @@ CheckOptions:
   - key: readability-identifier-naming.MemberCase
     value: camelBack
   - key: readability-identifier-naming.MemberIgnoredRegexp
-    value: ".*ZX.*|.*SWAP.*|.*CEX.*|.*DD.*|.*EQ.*"
+    value: ".*ZX.*|.*SWAP.*|.*CEX.*|.*DD.*|.*EQ.*|.*_"
   - key: readability-identifier-naming.MethodCase
     value: camelBack
   - key: readability-identifier-naming.ParameterCase

include/mqt-core/ir/operations/CompoundOperation.hpp

@@ -55,6 +55,8 @@ class CompoundOperation final : public Operation {
 
   [[nodiscard]] bool isCustomGate() const noexcept;
 
+  [[nodiscard]] bool isGlobal(size_t nQubits) const noexcept override;
+
   void addControl(Control c) override;
 
   void clearControls() override;

include/mqt-core/ir/operations/Operation.hpp

@@ -154,6 +154,19 @@ class Operation {
 
   [[nodiscard]] virtual bool isControlled() const { return !controls.empty(); }
 
+  /**
+   * @brief Checks whether a gate is global.
+   * @details A StandardOperation is global if it acts on all qubits.
+   * A CompoundOperation is global if all its sub-operations are
+   * StandardOperations of the same type with the same parameters acting on all
+   * qubits. The latter is what a QASM line like `ry(π) q;` is translated to in
+   * MQT Core. All other operations are not global.
+   * @return True if the operation is global, false otherwise.
+   */
+  [[nodiscard]] virtual bool isGlobal(size_t /* unused */) const {
+    return false;
+  }
+
   [[nodiscard]] virtual bool actsOn(const Qubit i) const {
     for (const auto& t : targets) {
       if (t == i) {

include/mqt-core/ir/operations/StandardOperation.hpp

@@ -81,6 +81,8 @@ class StandardOperation : public Operation {
 
   [[nodiscard]] bool isStandardOperation() const override { return true; }
 
+  [[nodiscard]] bool isGlobal(size_t nQubits) const override;
+
   void addControl(const Control c) override {
     if (actsOn(c.qubit)) {
       throw QFRException("Cannot add control on qubit " +

include/mqt-core/na/NAComputation.hpp

@@ -7,96 +7,176 @@
  * Licensed under the MIT License
  */
 
+/** @file
+ * @brief Defines a class for representing neutral atom computations.
+ */
+
 #pragma once
 
-#include "NADefinitions.hpp"
-#include "operations/NAOperation.hpp"
+#include "na/entities/Atom.hpp"
+#include "na/entities/Location.hpp"
+#include "na/entities/Zone.hpp"
+#include "na/operations/Op.hpp"
 
-#include <algorithm>
 #include <cstddef>
-#include <iterator>
 #include <memory>
 #include <ostream>
 #include <string>
+#include <unordered_map>
+#include <utility>
 #include <vector>
 
 namespace na {
-class NAComputation {
+/// Represents a neutral atom computation.
+class NAComputation final {
 protected:
-  std::vector<std::shared_ptr<Point>> initialPositions;
-  std::vector<std::unique_ptr<NAOperation>> operations;
+  /// The operations in the NA computation.
+  std::vector<std::unique_ptr<Op>> operations_;
+  /// The atoms used in the NA computation.
+  std::vector<std::unique_ptr<Atom>> atoms_;
+  /// The zones used in the NA computation.
+  std::vector<std::unique_ptr<Zone>> zones_;
+  /// The initial locations of the atoms.
+  std::unordered_map<const Atom*, Location> initialLocations_;
 
 public:
-  NAComputation() = default;
-  NAComputation(NAComputation&& qc) noexcept = default;
-  NAComputation& operator=(NAComputation&& qc) noexcept = default;
-  NAComputation(const NAComputation& qc)
-      : initialPositions(qc.initialPositions) {
-    operations.reserve(qc.operations.size());
-    std::transform(qc.operations.cbegin(), qc.operations.cend(),
-                   std::back_inserter(operations),
-                   [](const auto& op) { return op->clone(); });
+  /// Returns an iterator to the beginning of the operations.
+  [[nodiscard]] auto begin() -> auto { return operations_.begin(); }
+
+  /// Returns an iterator to the beginning of the operations.
+  [[nodiscard]] auto begin() const -> auto { return operations_.begin(); }
+
+  /// Returns an iterator to the end of the operations.
+  [[nodiscard]] auto end() -> auto { return operations_.end(); }
+
+  /// Returns an iterator to the end of the operations.
+  [[nodiscard]] auto end() const -> auto { return operations_.end(); }
+
+  /// Returns the number of operations in the NAComputation.
+  [[nodiscard]] auto size() const -> std::size_t { return operations_.size(); }
+
+  /// Returns a reference to the operation at the given index.
+  /// @param i The index of the operation.
+  /// @return A reference to the operation at the given index.
+  [[nodiscard]] auto operator[](const std::size_t i) -> Op& {
+    return *operations_[i];
+  }
+
+  /// Returns a const reference to the operation at the given index.
+  /// @param i The index of the operation.
+  /// @return A const reference to the operation at the given index.
+  [[nodiscard]] auto operator[](const std::size_t i) const -> const Op& {
+    return *operations_[i];
+  }
+
+  /// Clears the operations in the NAComputation.
+  auto clear() -> void { operations_.clear(); }
+
+  /// Returns the number of atoms used in the NAComputation.
+  [[nodiscard]] auto getAtomsSize() const -> std::size_t {
+    return atoms_.size();
   }
-  NAComputation& operator=(const NAComputation& qc) {
-    if (this != &qc) {
-      initialPositions = qc.initialPositions;
-      operations.clear();
-      operations.reserve(qc.operations.size());
-      std::transform(qc.operations.cbegin(), qc.operations.cend(),
-                     std::back_inserter(operations),
-                     [](const auto& op) { return op->clone(); });
-    }
-    return *this;
+
+  /// Returns the atoms used in the NAComputation.
+  [[nodiscard]] auto getAtoms() const -> auto& { return atoms_; }
+
+  /// Returns the zones used in global operations within the NAComputation.
+  [[nodiscard]] auto getZones() const -> auto& { return zones_; }
+
+  /// Returns the initial locations of the atoms.
+  [[nodiscard]] auto getInitialLocations() const -> auto& {
+    return initialLocations_;
   }
-  virtual ~NAComputation() = default;
-  template <class T> auto emplaceBack(std::unique_ptr<T>&& op) -> void {
-    static_assert(std::is_base_of_v<NAOperation, T>,
-                  "T must be a subclass of NAOperation.");
-    operations.emplace_back(std::move(op));
+
+  /// Returns the location of the given atom after the given operation.
+  /// @param atom The atom to get the location for.
+  /// @param op The operation to get the location after.
+  /// @return The location of the atom after the operation.
+  [[nodiscard]] auto getLocationOfAtomAfterOperation(const Atom& atom,
+                                                     const Op& op) const
+      -> Location;
+
+  /// Emplaces a new atom with the given name and returns a reference to the
+  /// newly created atom.
+  /// @param name The name of the atom.
+  /// @return A reference to the newly created atom.
+  auto emplaceBackAtom(std::string name) -> const Atom& {
+    return *atoms_.emplace_back(std::make_unique<Atom>(std::move(name)));
   }
-  template <class T> auto emplaceBack(const std::unique_ptr<T>& op) -> void {
-    static_assert(std::is_base_of_v<NAOperation, T>,
-                  "T must be a subclass of NAOperation.");
-    operations.emplace_back(std::move(op));
+
+  /// Emplaces a new zone with the given name and returns a reference to the
+  /// newly created zone.
+  /// @param name The name of the zone.
+  /// @return A reference to the newly created zone.
+  auto emplaceBackZone(std::string name) -> const Zone& {
+    return *zones_.emplace_back(std::make_unique<Zone>(std::move(name)));
   }
-  template <class T, class... Args> auto emplaceBack(Args&&... args) -> void {
-    static_assert(std::is_base_of_v<NAOperation, T>,
-                  "T must be a subclass of NAOperation.");
-    operations.emplace_back(std::make_unique<T>(std::forward<Args>(args)...));
+
+  /// Emplaces a new initial location for the given atom with the given location
+  /// and returns a reference to the newly created location.
+  /// @param atom The atom to set the initial location for.
+  /// @param loc The location of the atom.
+  /// @return A reference to the newly created location.
+  auto emplaceInitialLocation(const Atom& atom, const Location& loc)
+      -> const Location& {
+    return initialLocations_.emplace(&atom, loc).first->second;
   }
-  auto clear(const bool clearInitialPositions = true) -> void {
-    operations.clear();
-    if (clearInitialPositions) {
-      initialPositions.clear();
-    }
+
+  /// Emplaces a new initial location for the given atom with the given
+  /// arguments and returns a reference to the newly created location.
+  /// @param atom The atom to set the initial location for.
+  /// @param loc The parameters for the location of the atom.
+  /// @return A reference to the newly created location.
+  template <typename... Args>
+  auto emplaceInitialLocation(const Atom& atom, Args&&... loc)
+      -> const Location& {
+    return initialLocations_
+        .emplace(&atom,
+                 Location{static_cast<double>(std::forward<Args>(loc))...})
+        .first->second;
   }
-  [[nodiscard]] auto size() const -> std::size_t { return operations.size(); }
-  [[nodiscard]] auto getInitialPositions() const
-      -> const std::vector<std::shared_ptr<Point>>& {
-    return initialPositions;
+
+  /// Emplaces a new operation of type T with the given operation and returns a
+  /// reference to the newly created operation.
+  /// @tparam T The concrete type of the operation.
+  /// @param op The operation to emplace.
+  /// @return A reference to the newly created operation.
+  template <class T> auto emplaceBack(T&& op) -> const Op& {
+    return *operations_.emplace_back(std::make_unique<T>(std::forward<T>(op)));
   }
-  auto emplaceInitialPosition(std::shared_ptr<Point> p) -> void {
-    initialPositions.emplace_back(std::move(p));
+
+  /// Emplaces a new operation of type T with the given arguments and returns a
+  /// reference to the newly created operation.
+  /// @tparam T The concrete type of the operation.
+  /// @param args The arguments for the operation.
+  /// @return A reference to the newly created operation.
+  template <class T, typename... Args>
+  auto emplaceBack(Args&&... args) -> const Op& {
+    return *operations_.emplace_back(
+        std::make_unique<T>(std::forward<Args>(args)...));
   }
+
+  /// Returns a string representation of the NAComputation.
   [[nodiscard]] auto toString() const -> std::string;
+  /// Outputs the NAComputation to the given output stream, i.e., the string
+  /// returned by toString().
+  /// @param os The output stream to print the NAComputation to.
+  /// @param qc The NAComputation to print.
+  /// @return The output stream after printing the NAComputation.
   friend auto operator<<(std::ostream& os, const NAComputation& qc)
       -> std::ostream& {
     return os << qc.toString();
   }
-  // Iterators (pass-through)
-  auto begin() noexcept { return operations.begin(); }
-  [[nodiscard]] auto begin() const noexcept { return operations.begin(); }
-  [[nodiscard]] auto cbegin() const noexcept { return operations.cbegin(); }
-  auto end() noexcept { return operations.end(); }
-  [[nodiscard]] auto end() const noexcept { return operations.end(); }
-  [[nodiscard]] auto cend() const noexcept { return operations.cend(); }
-  auto rbegin() noexcept { return operations.rbegin(); }
-  [[nodiscard]] auto rbegin() const noexcept { return operations.rbegin(); }
-  [[nodiscard]] auto crbegin() const noexcept { return operations.crbegin(); }
-  auto rend() noexcept { return operations.rend(); }
-  [[nodiscard]] auto rend() const noexcept { return operations.rend(); }
-  [[nodiscard]] auto crend() const noexcept { return operations.crend(); }
-
-  [[nodiscard]] auto validateAODConstraints() const -> bool;
+
+  /// Validates the NAComputation and checks whether all AOD constraints are
+  /// fulfilled.
+  /// Specifically,
+  /// - each atom is loaded before it is moved
+  /// - the relative order of loaded atoms is preserved
+  /// - each atom is loaded before it is stored
+  /// - each atom is stored before it is loaded (again)
+  /// @returns a pair of a Boolean indicating whether the NAComputation is valid
+  /// and a string containing the error message if the NAComputation is invalid.
+  [[nodiscard]] auto validate() const -> std::pair<bool, std::string>;
 };
 } // namespace na