mqt-core 3.3.2__cp314-cp314t-macosx_11_0_arm64.whl

mqt/core/include/mqt-core/na/entities/Zone.hpp

@@ -0,0 +1,95 @@
+/*
+ * Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+ * Copyright (c) 2025 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+/** @file
+ * @brief Defines a type for representing zones in NA architectures.
+ */
+
+#pragma once
+
+#include <optional>
+#include <ostream>
+#include <string>
+#include <utility>
+
+namespace na {
+
+struct Location;
+
+/// Represents a zone in the NAComputation.
+/// @details The name of the zone is used for printing the NAComputation.
+/// To maintain the uniqueness of zones, the name of the zone should be unique
+/// for this zone.
+class Zone final {
+public:
+  /// A simple struct to represent the extent of a zone.
+  struct Extent {
+    double minX = 0.0;
+    double minY = 0.0;
+    double maxX = 0.0;
+    double maxY = 0.0;
+  };
+
+private:
+  /// The identifier of the zone.
+  std::string name_;
+  /// The extent of the zone.
+  std::optional<Extent> extent_;
+
+public:
+  /// Creates a new zone with the given name.
+  /// @param name The name of the zone.
+  explicit Zone(std::string name) : name_(std::move(name)) {}
+
+  /// Creates a new zone with the given name.
+  /// @param name The name of the zone.
+  /// @param extent The extent of the zone.
+  Zone(std::string name, const Extent& extent)
+      : name_(std::move(name)), extent_(extent) {}
+
+  /// Returns the name of the zone.
+  [[nodiscard]] auto getName() const -> std::string { return name_; }
+
+  /// Returns the extent of the zone.
+  [[nodiscard]] const std::optional<Extent>& getExtent() const {
+    return extent_;
+  }
+
+  /// Sets the extent of the zone.
+  void setExtent(const Extent& extent) { extent_ = extent; }
+
+  [[nodiscard]] auto contains(const Location& location) const -> bool;
+
+  /// Prints the zone to the given output stream.
+  /// @param os The output stream to print the zone to.
+  /// @param obj The zone to print.
+  /// @return The output stream after printing the zone.
+  friend auto operator<<(std::ostream& os, const Zone& obj) -> std::ostream& {
+    return os << obj.getName();
+  }
+
+  /// Compares two zones for equality.
+  /// @param other The zone to compare with.
+  /// @return True if the zones are equal, false otherwise.
+  [[nodiscard]] auto operator==(const Zone& other) const -> bool {
+    if (this == &other) {
+      return true;
+    }
+    return name_ == other.name_;
+  }
+
+  /// Compares two zones for inequality.
+  /// @param other The zone to compare with.
+  /// @return True if the zones are not equal, false otherwise.
+  [[nodiscard]] auto operator!=(const Zone& other) const -> bool {
+    return !(*this == other);
+  }
+};
+} // namespace na

mqt/core/include/mqt-core/na/fomac/Device.hpp

@@ -0,0 +1,169 @@
+/*
+ * Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+ * Copyright (c) 2025 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+#pragma once
+
+#include "fomac/FoMaC.hpp"
+#include "na/device/Generator.hpp"
+
+// NOLINTNEXTLINE(misc-include-cleaner)
+#include <nlohmann/json.hpp>
+#include <optional>
+#include <vector>
+
+namespace na {
+/**
+ * @brief Class representing the FoMaC library with neutral atom extensions.
+ * @see fomac::FoMaC
+ */
+class FoMaC : public fomac::FoMaC {
+public:
+  /**
+   * @brief Class representing a quantum device with neutral atom extensions.
+   * @see fomac::FoMaC::Device
+   * @note Since it inherits from @ref na::Device, Device objects can be
+   * converted to `nlohmann::json` objects.
+   */
+  class Device : public fomac::FoMaC::Device, na::Device {
+
+    /**
+     * @brief Initializes the name from the underlying QDMI device.
+     */
+    auto initNameFromDevice() -> void;
+
+    /**
+     * @brief Initializes the minimum atom distance from the underlying QDMI
+     * device.
+     */
+    auto initMinAtomDistanceFromDevice() -> bool;
+
+    /**
+     * @brief Initializes the number of qubits from the underlying QDMI device.
+     */
+    auto initQubitsNumFromDevice() -> void;
+
+    /**
+     * @brief Initializes the length unit from the underlying QDMI device.
+     */
+    auto initLengthUnitFromDevice() -> bool;
+
+    /**
+     * @brief Initializes the duration unit from the underlying QDMI device.
+     */
+    auto initDurationUnitFromDevice() -> bool;
+
+    /**
+     * @brief Initializes the decoherence times from the underlying QDMI device.
+     */
+    auto initDecoherenceTimesFromDevice() -> bool;
+
+    /**
+     * @brief Initializes the trap lattices from the underlying QDMI device.
+     * @details It reconstructs the entire lattice structure from the
+     * information retrieved from the QDMI device, including lattice vectors,
+     * sublattice offsets, and extent.
+     * @see na::Device::Lattice
+     */
+    auto initTrapsfromDevice() -> bool;
+
+    /**
+     * @brief Initializes the all operations from the underlying QDMI device.
+     */
+    auto initOperationsFromDevice() -> bool;
+
+    /**
+     * @brief Constructs a Device object from a fomac::FoMaC::Device object.
+     * @param device The fomac::FoMaC::Device object to wrap.
+     * @note The constructor does not initialize the additional fields of this
+     * class. For their initialization, the corresponding `init*FromDevice`
+     * methods must be called, see @ref tryCreateFromDevice.
+     */
+    explicit Device(const fomac::FoMaC::Device& device);
+
+  public:
+    /// @returns the length unit of the device.
+    [[nodiscard]] auto getLengthUnit() const -> const Unit& {
+      return lengthUnit;
+    }
+
+    /// @returns the duration unit of the device.
+    [[nodiscard]] auto getDurationUnit() const -> const Unit& {
+      return durationUnit;
+    }
+
+    /// @returns the decoherence times of the device.
+    [[nodiscard]] auto getDecoherenceTimes() const -> const DecoherenceTimes& {
+      return decoherenceTimes;
+    }
+
+    /// @returns the list of trap lattices of the device.
+    [[nodiscard]] auto getTraps() const -> const std::vector<Lattice>& {
+      return traps;
+    }
+
+    /**
+     * @brief Try to create a Device object from a fomac::FoMaC::Device object.
+     * @details This method attempts to create a Device object by initializing
+     * all necessary fields from the provided fomac::FoMaC::Device object. If
+     * any required information is missing or invalid, the method returns
+     * `std::nullopt`.
+     * @param device is the fomac::FoMaC::Device object to wrap.
+     * @return An optional containing the instantiated device if compatible,
+     * std::nullopt otherwise.
+     */
+    [[nodiscard]] static auto
+    tryCreateFromDevice(const fomac::FoMaC::Device& device)
+        -> std::optional<Device> {
+      Device d(device);
+      // The sequence of the following method calls does not matter.
+      // They are independent of each other.
+      if (!d.initMinAtomDistanceFromDevice()) {
+        return std::nullopt;
+      }
+      if (!d.initLengthUnitFromDevice()) {
+        return std::nullopt;
+      }
+      if (!d.initDurationUnitFromDevice()) {
+        return std::nullopt;
+      }
+      if (!d.initDecoherenceTimesFromDevice()) {
+        return std::nullopt;
+      }
+      if (!d.initTrapsfromDevice()) {
+        return std::nullopt;
+      }
+      if (!d.initOperationsFromDevice()) {
+        return std::nullopt;
+      }
+      d.initNameFromDevice();
+      d.initQubitsNumFromDevice();
+      return d;
+    }
+
+    // The following is the result of
+    // NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE(Device, na::Device)
+    // without any new attributes, which is the reason the macro cannot be used.
+    template <typename BasicJsonType>
+    friend void to_json(BasicJsonType& nlohmannJsonJ,
+                        const Device& nlohmannJsonT) {
+      // NOLINTNEXTLINE(misc-include-cleaner)
+      nlohmann::to_json(nlohmannJsonJ,
+                        static_cast<const na::Device&>(nlohmannJsonT));
+    }
+  };
+
+  /// @brief Deleted default constructor to prevent instantiation.
+  FoMaC() = delete;
+
+  /// @see QDMI_SESSION_PROPERTY_DEVICES
+  [[nodiscard]] static auto getDevices() -> std::vector<Device>;
+};
+
+} // namespace na

mqt/core/include/mqt-core/na/mqt_core_na_export.h

@@ -0,0 +1,43 @@
+
+#ifndef MQT_CORE_NA_EXPORT_H
+#define MQT_CORE_NA_EXPORT_H
+
+#ifdef MQT_CORE_NA_STATIC_DEFINE
+#  define MQT_CORE_NA_EXPORT
+#  define MQT_CORE_NA_NO_EXPORT
+#else
+#  ifndef MQT_CORE_NA_EXPORT
+#    ifdef mqt_core_na_EXPORTS
+        /* We are building this library */
+#      define MQT_CORE_NA_EXPORT __attribute__((visibility("default")))
+#    else
+        /* We are using this library */
+#      define MQT_CORE_NA_EXPORT __attribute__((visibility("default")))
+#    endif
+#  endif
+
+#  ifndef MQT_CORE_NA_NO_EXPORT
+#    define MQT_CORE_NA_NO_EXPORT __attribute__((visibility("hidden")))
+#  endif
+#endif
+
+#ifndef MQT_CORE_NA_DEPRECATED
+#  define MQT_CORE_NA_DEPRECATED __attribute__ ((__deprecated__))
+#endif
+
+#ifndef MQT_CORE_NA_DEPRECATED_EXPORT
+#  define MQT_CORE_NA_DEPRECATED_EXPORT MQT_CORE_NA_EXPORT MQT_CORE_NA_DEPRECATED
+#endif
+
+#ifndef MQT_CORE_NA_DEPRECATED_NO_EXPORT
+#  define MQT_CORE_NA_DEPRECATED_NO_EXPORT MQT_CORE_NA_NO_EXPORT MQT_CORE_NA_DEPRECATED
+#endif
+
+/* NOLINTNEXTLINE(readability-avoid-unconditional-preprocessor-if) */
+#if 0 /* DEFINE_NO_DEPRECATED */
+#  ifndef MQT_CORE_NA_NO_DEPRECATED
+#    define MQT_CORE_NA_NO_DEPRECATED
+#  endif
+#endif
+
+#endif /* MQT_CORE_NA_EXPORT_H */

mqt/core/include/mqt-core/na/operations/GlobalCZOp.hpp

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+ * Copyright (c) 2025 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+/** @file
+ * @brief Defines a class for representing global CZ operations.
+ */
+
+#pragma once
+
+#include "na/entities/Zone.hpp"
+#include "na/operations/GlobalOp.hpp"
+
+#include <utility>
+#include <vector>
+
+namespace na {
+/// Represents a global CZ operation in the NAComputation.
+class GlobalCZOp final : public GlobalOp {
+public:
+  /// Creates a new CZ operation in the given zones.
+  /// @param zones The zones the operation is applied to.
+  explicit GlobalCZOp(std::vector<const Zone*> zones)
+      : GlobalOp(std::move(zones), {}) {
+    name_ = "cz";
+  }
+
+  /// Creates a new CZ operation in the given zone.
+  /// @param zone The zone the operation is applied to.
+  explicit GlobalCZOp(const Zone& zone) : GlobalCZOp({&zone}) {}
+};
+} // namespace na

mqt/core/include/mqt-core/na/operations/GlobalOp.hpp

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+ * Copyright (c) 2025 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+/** @file
+ * @brief Defines a class for representing global operations in the
+ * NAComputation.
+ */
+
+#pragma once
+
+#include "ir/Definitions.hpp"
+#include "na/entities/Zone.hpp"
+#include "na/operations/Op.hpp"
+
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace na {
+/// Represents a global operation in the NAComputation.
+/// @details Global operations are applied to entire zones instead of to
+/// individual atoms.
+class GlobalOp : public Op {
+protected:
+  /// The name of the operation.
+  std::string name_;
+  /// The parameters of the operation.
+  std::vector<qc::fp> params_;
+  /// The zones the operation is applied to.
+  std::vector<const Zone*> zones_;
+
+  /// Creates a new global operation in the given zone with the given
+  /// parameters.
+  /// @param zones The zones the operation is applied to.
+  /// @param params The parameters of the operation.
+  GlobalOp(std::vector<const Zone*> zones, std::vector<qc::fp> params)
+      : params_(std::move(params)), zones_(std::move(zones)) {}
+
+public:
+  GlobalOp() = delete;
+
+  /// Returns the parameters of the operation.
+  [[nodiscard]] auto getParams() const -> auto& { return params_; }
+
+  /// Returns the zone the operation is applied to.
+  [[nodiscard]] auto getZones() const -> auto& { return zones_; }
+
+  /// Returns a string representation of the operation.
+  [[nodiscard]] auto toString() const -> std::string override;
+};
+} // namespace na

mqt/core/include/mqt-core/na/operations/GlobalRYOp.hpp

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+ * Copyright (c) 2025 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+/** @file
+ * @brief Defines a class for representing global RY operations.
+ */
+
+#pragma once
+
+#include "ir/Definitions.hpp"
+#include "na/entities/Zone.hpp"
+#include "na/operations/GlobalOp.hpp"
+
+#include <utility>
+#include <vector>
+
+namespace na {
+/// Represents a global RY operation in the NAComputation.
+class GlobalRYOp final : public GlobalOp {
+public:
+  /// Creates a new RY operation in the given zones with the given angle.
+  /// @param zones The zones the operation is applied to.
+  /// @param angle The angle of the operation.
+  GlobalRYOp(std::vector<const Zone*> zones, const qc::fp angle)
+      : GlobalOp(std::move(zones), {angle}) {
+    name_ = "ry";
+  }
+
+  /// Creates a new RY operation in the given zone with the given angle.
+  /// @param zone The zone the operation is applied to.
+  /// @param angle The angle of the operation.
+  GlobalRYOp(const Zone& zone, const qc::fp angle)
+      : GlobalRYOp({&zone}, angle) {}
+};
+} // namespace na

mqt/core/include/mqt-core/na/operations/LoadOp.hpp

@@ -0,0 +1,89 @@
+/*
+ * Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+ * Copyright (c) 2025 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+/** @file
+ * @brief Defines a class for representing load operations.
+ */
+
+#pragma once
+
+#include "na/entities/Atom.hpp"
+#include "na/entities/Location.hpp"
+#include "na/operations/ShuttlingOp.hpp"
+
+#include <optional>
+#include <stdexcept>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace na {
+/// Represents a load operation in the NAComputation.
+/// @details Before an atom can be moved, it must be loaded, i.e., transferred
+/// from a static SLM to an adjustable AOD trap.
+class LoadOp final : public ShuttlingOp {
+protected:
+  /// The target locations to load the atoms to.
+  std::optional<std::vector<Location>> targetLocations_ = std::nullopt;
+
+public:
+  /// Creates a new load operation with the given atoms and target locations.
+  /// @details The target locations can be set if the loading operation contains
+  /// a certain offset.
+  /// @param atoms The atoms to load.
+  /// @param targetLocations The target locations to load the atoms to.
+  LoadOp(std::vector<const Atom*> atoms, std::vector<Location> targetLocations)
+      : ShuttlingOp(std::move(atoms)),
+        targetLocations_(std::move(targetLocations)) {
+    if (atoms_.size() != targetLocations_->size()) {
+      throw std::invalid_argument(
+          "Number of atoms and target locations must be equal.");
+    }
+  }
+
+  /// Creates a new load operation with the given atoms.
+  /// @details This constructor is used if the target locations are not set,
+  /// i.e., the load operation does not incorporate any offset.
+  /// @param atoms The atoms to load.
+  explicit LoadOp(std::vector<const Atom*> atoms)
+      : ShuttlingOp(std::move(atoms)) {}
+
+  /// Creates a new load operation with the given atom and target location.
+  /// @details The target locations can be set if the loading operation contains
+  /// a certain offset.
+  /// @param atom The atom to load.
+  /// @param targetLocation The target location to load the atom to.
+  LoadOp(const Atom& atom, const Location& targetLocation)
+      : LoadOp({&atom}, {targetLocation}) {}
+
+  /// Creates a new load operation with the given atom.
+  /// @details This constructor is used if the target locations are not set,
+  /// i.e., the load operation does not incorporate any offset.
+  /// @param atom The atom to load.
+  explicit LoadOp(const Atom& atom) : LoadOp({&atom}) {}
+
+  /// Returns whether the load operation has target locations set.
+  [[nodiscard]] auto hasTargetLocations() const -> bool override {
+    return targetLocations_.has_value();
+  }
+
+  /// Returns the target locations of the load operation.
+  [[nodiscard]] auto getTargetLocations() const
+      -> const std::vector<Location>& override {
+    if (!targetLocations_.has_value()) {
+      throw std::logic_error("Operation has no target locations set.");
+    }
+    return *targetLocations_;
+  }
+
+  /// Returns a string representation of the load operation.
+  [[nodiscard]] auto toString() const -> std::string override;
+};
+} // namespace na

mqt/core/include/mqt-core/na/operations/LocalOp.hpp

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+ * Copyright (c) 2025 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+/** @file
+ * @brief Defines a class for representing local operations in the
+ * NAComputation.
+ */
+
+#pragma once
+
+#include "ir/Definitions.hpp"
+#include "na/entities/Atom.hpp"
+#include "na/operations/Op.hpp"
+
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace na {
+/// Represents a local operation in the NAComputation.
+/// @details A local operation is applied to individual atoms.
+class LocalOp : public Op {
+protected:
+  /// The name of the operation.
+  std::string name_;
+  /// The parameters of the operation.
+  std::vector<qc::fp> params_;
+  /// The atoms the operation is applied to.
+  std::vector<const Atom*> atoms_;
+
+  /// Creates a new local operation with the given atoms and parameters.
+  /// @param atoms The atoms the operation is applied to.
+  /// @param params The parameters of the operation.
+  LocalOp(std::vector<const Atom*> atoms, std::vector<qc::fp> params)
+      : params_(std::move(params)), atoms_(std::move(atoms)) {}
+
+public:
+  LocalOp() = delete;
+
+  /// Returns the atoms the operation is applied to.
+  [[nodiscard]] auto getAtoms() const -> auto& { return atoms_; }
+
+  /// Returns the parameters of the operation.
+  [[nodiscard]] auto getParams() const -> auto& { return params_; }
+
+  /// Returns a string representation of the operation.
+  [[nodiscard]] auto toString() const -> std::string override;
+};
+} // namespace na

mqt/core/include/mqt-core/na/operations/LocalRZOp.hpp

@@ -0,0 +1,42 @@
+/*
+ * Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+ * Copyright (c) 2025 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+/** @file
+ * @brief Defines a class for representing local RZ operations.
+ */
+
+#pragma once
+
+#include "ir/Definitions.hpp"
+#include "na/entities/Atom.hpp"
+#include "na/operations/LocalOp.hpp"
+
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace na {
+/// Represents a local RZ operation in the NAComputation.
+class LocalRZOp final : public LocalOp {
+public:
+  /// Creates a new RZ operation with the given atoms and angle.
+  /// @param atoms The atoms the operation is applied to.
+  /// @param angle The angle of the operation.
+  LocalRZOp(std::vector<const Atom*> atoms, const qc::fp angle)
+      : LocalOp(std::move(atoms), {angle}) {
+    name_ = "rz";
+  }
+
+  /// Creates a new RZ operation with the given atom and angle.
+  /// @param atom The atom the operation is applied to.
+  /// @param angle The angle of the operation.
+  LocalRZOp(const Atom& atom, const qc::fp angle) : LocalRZOp({&atom}, angle) {}
+};
+} // namespace na

mqt/core/include/mqt-core/na/operations/LocalUOp.hpp

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+ * Copyright (c) 2025 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+/** @file
+ * @brief Defines a class for representing local U3 operations.
+ */
+
+#pragma once
+
+#include "ir/Definitions.hpp"
+#include "na/entities/Atom.hpp"
+#include "na/operations/LocalOp.hpp"
+
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace na {
+/// Represents a local U3 operation in the NAComputation.
+class LocalUOp final : public LocalOp {
+public:
+  /// Creates a new U3 operation with the given atoms and angles.
+  /// @param atoms The atoms the operation is applied to.
+  /// @param theta The first parameter of the operation.
+  /// @param phi The second parameter of the operation.
+  /// @param lambda The third parameter of the operation.
+  LocalUOp(std::vector<const Atom*> atoms, const qc::fp theta, const qc::fp phi,
+           const qc::fp lambda)
+      : LocalOp(std::move(atoms), {theta, phi, lambda}) {
+    name_ = "u";
+  }
+
+  /// Creates a new U3 operation with the given atom and angle.
+  /// @param atom The atom the operation is applied to.
+  /// @param theta The first parameter of the operation.
+  /// @param phi The second parameter of the operation.
+  /// @param lambda The third parameter of the operation.
+  LocalUOp(const Atom& atom, const qc::fp theta, const qc::fp phi,
+           const qc::fp lambda)
+      : LocalUOp({&atom}, theta, phi, lambda) {}
+};
+} // namespace na