mqt-core 3.3.2__cp314-cp314t-macosx_11_0_x86_64.whl

mqt/core/include/mqt-core/dd/MemoryManager.hpp

@@ -0,0 +1,193 @@
+/*
+ * 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 "dd/statistics/MemoryManagerStatistics.hpp"
+
+#include <cassert>
+#include <cstddef>
+#include <type_traits>
+#include <vector>
+
+namespace dd {
+
+// forward declarations
+struct LLBase;
+
+/**
+ * @brief A memory manager for objects of the same type that inherit from
+ * `LLBase`.
+ * @details The class manages a collection of objects. The objects are
+ * stored in contiguous chunks of memory. The manager supports reclaiming
+ * objects that are no longer in use. This is done by maintaining a linked list
+ * of available objects. When an object is no longer in use, it is added to the
+ * list. When a new object is requested, the first object from the list is
+ * returned. If the list is empty, an object from the current chunk is returned.
+ * If the current chunk is full, a new chunk is allocated. The size of chunks
+ * grows exponentially according to a growth factor.
+ * @note The main purpose of this class is to reduce the number of memory
+ * allocations and deallocations. This is achieved by allocating a large number
+ * of objects at once and reusing them. This is especially useful for objects
+ * that are frequently created and destroyed, such as decision diagram nodes,
+ * edge weights, etc.
+ */
+class MemoryManager {
+  MemoryManager(size_t entrySize, std::size_t initialAllocationSize);
+
+public:
+  // delete copy construction and assignment
+  MemoryManager(const MemoryManager&) = delete;
+  MemoryManager& operator=(const MemoryManager&) = delete;
+
+  /**
+   * @brief The number of initially allocated entries.
+   * @details The number of initially allocated entries is the number of entries
+   * that are allocated as a chunk when the manager is created. Increasing this
+   * number reduces the number of allocations, but increases the memory usage.
+   */
+  static constexpr std::size_t INITIAL_ALLOCATION_SIZE = 2048U;
+
+  /**
+   * @brief The growth factor for table entry allocation.
+   * @details The growth factor is used to determine the number of entries that
+   * are allocated when the manager runs out of entries. Per default, the number
+   * of entries is doubled. Increasing this number reduces the number of memory
+   * allocations, but increases the memory usage.
+   */
+  static constexpr double GROWTH_FACTOR = 2U;
+
+  /**
+   * @brief Construct a new MemoryManager object for objects of type T.
+   * @param initialAllocationSize The initial number of entries to allocate
+   * @tparam T The type of the entries
+   */
+  template <class T>
+  static MemoryManager
+  create(const std::size_t initialAllocationSize = INITIAL_ALLOCATION_SIZE) {
+    return {sizeof(T), initialAllocationSize};
+  }
+
+  /// default destructor
+  ~MemoryManager() = default;
+
+  /**
+   * @brief Get an entry from the manager.
+   * @details If an entry is available for reuse, it is returned. Otherwise, an
+   * entry from the pre-allocated chunks is returned. If no entry is available,
+   * a new chunk is allocated.
+   * @tparam T The type of the entry.
+   * @return A pointer to an entry.
+   */
+  template <class T> [[nodiscard]] T* get() {
+    static_assert(std::is_base_of_v<LLBase, T>,
+                  "T must be derived from LLBase");
+    assert(sizeof(T) == entrySize_ && "Cannot get entry of different size");
+
+    return static_cast<T*>(get());
+  }
+
+  /**
+   * @brief Return an entry to the manager.
+   * @details The entry is added to the list of available entries. The entry
+   * must not be used after it has been returned to the manager.
+   * @param entry A reference to an entry that is no longer in use.
+   */
+  void returnEntry(LLBase& entry) noexcept;
+
+  /**
+   * @brief Reset the manager.
+   * @details Drops all but the first chunk. If `resizeToTotal` is set to true,
+   * the first chunk is resized to the total number of entries. This increases
+   * memory locality and reduces the number of allocations when the manager is
+   * used again. However, it might also require a huge contiguous block of
+   * memory to be allocated.
+   * @param resizeToTotal If set to true, the first chunk is resized to the
+   * total number of entries.
+   */
+  void reset(bool resizeToTotal = false) noexcept;
+
+  /// Get a reference to the statistics
+  [[nodiscard]] const auto& getStats() const noexcept { return stats; }
+
+private:
+  /// Get an entry from the manager
+  [[nodiscard]] LLBase* get();
+
+  /**
+   * @brief Check whether an entry is available for reuse
+   * @return true if an entry is available for reuse, false otherwise
+   */
+  [[nodiscard]] bool entryAvailableForReuse() const noexcept;
+
+  /**
+   * @brief Get an entry from the list of available entries
+   * @return A pointer to an entry ready for reuse
+   */
+  [[nodiscard]] LLBase* getEntryFromAvailableList() noexcept;
+
+  /**
+   * @brief Check whether an entry is available in the current chunk
+   * @return true if an entry is available in the current chunk, false
+   * otherwise
+   */
+  [[nodiscard]] bool entryAvailableInChunk() const noexcept;
+
+  /// Allocate a new chunk of memory
+  void allocateNewChunk();
+
+  /**
+   * @brief Get an entry from the current chunk
+   * @return A pointer to an entry from the current chunk
+   */
+  [[nodiscard]] LLBase* getEntryFromChunk() noexcept;
+
+  /// The size of an entry in bytes (as reported by `sizeof`)
+  size_t entrySize_;
+
+  /// A chunk of memory as a vector of bytes
+  using Chunk = std::vector<std::byte>;
+
+  /**
+   * @brief A linked list of entries that are available for (re-)use
+   * @details The MemoryManager maintains a linked list of entries that are
+   * available for (re-)use. This list is implemented as a singly linked list
+   * using the `next()` method of the entries. The `available` member points to
+   * the first entry in the list. If the list is empty, `available` is
+   * `nullptr`.
+   */
+  LLBase* available;
+
+  /**
+   * @brief The storage for the entries
+   * @details The MemoryManager maintains a vector of chunks. Each chunk is a
+   * vector of entries. Entries in a chunk are allocated contiguously.
+   */
+  std::vector<Chunk> chunks;
+
+  /**
+   * @brief Iterator to the next available entry in the current chunk
+   * @details This iterator points to the next available entry in the current
+   * chunk. If the current chunk is full, it points to the end of the chunk.
+   */
+  Chunk::iterator chunkIt;
+
+  /**
+   * @brief Iterator to the end of the current chunk
+   * @details This iterator points to the end of the current chunk. It is used
+   * to determine whether the current chunk is full.
+   */
+  Chunk::iterator chunkEndIt;
+
+  /// Memory manager statistics
+  MemoryManagerStatistics stats;
+};
+
+} // namespace dd

mqt/core/include/mqt-core/dd/Node.hpp

@@ -0,0 +1,223 @@
+/*
+ * 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 "dd/CachedEdge.hpp"
+#include "dd/DDDefinitions.hpp"
+#include "dd/Edge.hpp"
+#include "dd/LinkedListBase.hpp"
+
+#include <array>
+#include <cassert>
+#include <cstdint>
+
+namespace dd {
+
+/**
+ * @brief Base class for all DD nodes.
+ * @details This class is used to store common information for all DD nodes.
+ * The `flags` makes the implicit padding explicit and can be used for storing
+ * node properties.
+ * Data Layout (8)|(2|2|4) = 16B.
+ */
+struct NodeBase : LLBase {
+  /// Variable index
+  Qubit v{};
+
+  /**
+   * @brief Flags for node properties
+   * @details Not required for all node types, but padding is required either
+   * way.
+   *
+   * 0b10000 = mark flag used for mark-and-sweep garbage collection,
+   *  0b1000 = marks a reduced dm node,
+   *   0b100 = marks a dm (tmp flag),
+   *    0b10 = mark first path edge (tmp flag),
+   *     0b1 = mark path is conjugated (tmp flag)
+   */
+  std::uint16_t flags = 0;
+
+  /// Mark flag used for mark-and-sweep garbage collection
+  static constexpr std::uint16_t MARK_FLAG = 0b10000U;
+
+  /// @brief Whether a node is marked as used.
+  [[nodiscard]] bool isMarked() const noexcept {
+    return (flags & MARK_FLAG) != 0U;
+  }
+
+  /// @brief Mark the node as used.
+  void mark() noexcept { flags |= MARK_FLAG; }
+
+  /// @brief Unmark the node.
+  void unmark() noexcept { flags &= static_cast<uint16_t>(~MARK_FLAG); }
+
+  /// Getter for the next object.
+  [[nodiscard]] NodeBase* next() const noexcept {
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-static-cast-downcast)
+    return static_cast<NodeBase*>(next_);
+  }
+
+  /**
+   * @brief Check if a node is terminal
+   * @details Generally, a node is terminal if it is nullptr.
+   * Some nodes (dNode) encode additional information in the least significant
+   * bits of the pointer. These bits are masked out before checking for
+   * terminal nodes.
+   * @param p The node to check
+   * @return true if the node is terminal, false otherwise.
+   */
+  [[nodiscard]] static bool isTerminal(const NodeBase* p) noexcept {
+    return (reinterpret_cast<std::uintptr_t>(p) & (~7ULL)) == 0ULL;
+  }
+  static constexpr NodeBase* getTerminal() noexcept { return nullptr; }
+};
+
+static_assert(sizeof(NodeBase) == 16);
+static_assert(alignof(NodeBase) == 8);
+
+/**
+ * @brief A vector DD node
+ * @details Data Layout (8)|(2|2|4)|(24|24) = 64B
+ */
+struct vNode final : NodeBase {       // NOLINT(readability-identifier-naming)
+  std::array<Edge<vNode>, RADIX> e{}; // edges out of this node
+
+  /// Getter for the next object
+  [[nodiscard]] vNode* next() const noexcept {
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-static-cast-downcast)
+    return static_cast<vNode*>(next_);
+  }
+  /// Getter for the terminal object
+  static constexpr vNode* getTerminal() noexcept { return nullptr; }
+};
+using vEdge = Edge<vNode>;
+using vCachedEdge = CachedEdge<vNode>;
+using VectorDD = vEdge;
+
+/**
+ * @brief A matrix DD node
+ * @details Data Layout (8)|(2|2|4)|(24|24|24|24) = 112B
+ */
+struct mNode final : NodeBase {       // NOLINT(readability-identifier-naming)
+  std::array<Edge<mNode>, NEDGE> e{}; // edges out of this node
+
+  /// Getter for the next object
+  [[nodiscard]] mNode* next() const noexcept {
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-static-cast-downcast)
+    return static_cast<mNode*>(next_);
+  }
+  /// Getter for the terminal object
+  static constexpr mNode* getTerminal() noexcept { return nullptr; }
+};
+using mEdge = Edge<mNode>;
+using mCachedEdge = CachedEdge<mNode>;
+using MatrixDD = mEdge;
+
+/**
+ * @brief A density matrix DD node
+ * @details Data Layout (8)|(2|2|4)|(24|24|24|24) = 112B
+ */
+struct dNode final : NodeBase {       // NOLINT(readability-identifier-naming)
+  std::array<Edge<dNode>, NEDGE> e{}; // edges out of this node
+
+  /// Getter for the next object
+  [[nodiscard]] dNode* next() const noexcept {
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-static-cast-downcast)
+    return static_cast<dNode*>(next_);
+  }
+  /// Getter for the terminal object
+  static constexpr dNode* getTerminal() noexcept { return nullptr; }
+
+  [[nodiscard]] [[maybe_unused]] static constexpr bool
+  tempDensityMatrixFlagsEqual(const std::uint8_t a,
+                              const std::uint8_t b) noexcept {
+    return getDensityMatrixTempFlags(a) == getDensityMatrixTempFlags(b);
+  }
+
+  [[nodiscard]] static constexpr bool
+  isConjugateTempFlagSet(const std::uintptr_t p) noexcept {
+    return (p & (1ULL << 0)) != 0U;
+  }
+  [[nodiscard]] static constexpr bool
+  isNonReduceTempFlagSet(const std::uintptr_t p) noexcept {
+    return (p & (1ULL << 1)) != 0U;
+  }
+  [[nodiscard]] static constexpr bool
+  isDensityMatrixTempFlagSet(const std::uintptr_t p) noexcept {
+    return (p & (1ULL << 2)) != 0U;
+  }
+  [[nodiscard]] static bool
+  isDensityMatrixNode(const std::uintptr_t p) noexcept {
+    return (p & (1ULL << 3)) != 0U;
+  }
+
+  [[nodiscard]] static bool isConjugateTempFlagSet(const dNode* p) noexcept {
+    return isConjugateTempFlagSet(reinterpret_cast<std::uintptr_t>(p));
+  }
+  [[nodiscard]] static bool isNonReduceTempFlagSet(const dNode* p) noexcept {
+    return isNonReduceTempFlagSet(reinterpret_cast<std::uintptr_t>(p));
+  }
+  [[nodiscard]] static bool
+  isDensityMatrixTempFlagSet(const dNode* p) noexcept {
+    return isDensityMatrixTempFlagSet(reinterpret_cast<std::uintptr_t>(p));
+  }
+  [[nodiscard]] static bool isDensityMatrixNode(const dNode* p) noexcept {
+    return isDensityMatrixNode(reinterpret_cast<std::uintptr_t>(p));
+  }
+
+  static void setConjugateTempFlagTrue(dNode*& p) noexcept {
+    p = reinterpret_cast<dNode*>(reinterpret_cast<std::uintptr_t>(p) |
+                                 (1ULL << 0));
+  }
+  static void setNonReduceTempFlagTrue(dNode*& p) noexcept {
+    p = reinterpret_cast<dNode*>(reinterpret_cast<std::uintptr_t>(p) |
+                                 (1ULL << 1));
+  }
+  static void setDensityMatTempFlagTrue(dNode*& p) noexcept {
+    p = reinterpret_cast<dNode*>(reinterpret_cast<std::uintptr_t>(p) |
+                                 (1ULL << 2));
+  }
+  static void alignDensityNode(dNode*& p) noexcept {
+    p = reinterpret_cast<dNode*>(reinterpret_cast<std::uintptr_t>(p) & (~7ULL));
+  }
+
+  [[nodiscard]] static std::uintptr_t
+  getDensityMatrixTempFlags(dNode*& p) noexcept {
+    return getDensityMatrixTempFlags(reinterpret_cast<std::uintptr_t>(p));
+  }
+  [[nodiscard]] static constexpr std::uintptr_t
+  getDensityMatrixTempFlags(const std::uintptr_t a) noexcept {
+    return a & (7ULL);
+  }
+
+  constexpr void unsetTempDensityMatrixFlags() noexcept {
+    flags = flags & static_cast<std::uint8_t>(~7U);
+  }
+
+  void setDensityMatrixNodeFlag(bool densityMatrix) noexcept;
+
+  static std::uint8_t alignDensityNodeNode(dNode*& p) noexcept;
+
+  static void getAlignedNodeRevertModificationsOnSubEdges(dNode* p) noexcept;
+
+  static void applyDmChangesToNode(dNode*& p) noexcept;
+
+  static void revertDmChangesToNode(dNode*& p) noexcept;
+};
+using dEdge = Edge<dNode>;
+using dCachedEdge = CachedEdge<dNode>;
+using DensityMatrixDD = dEdge;
+
+static inline dEdge densityFromMatrixEdge(const mEdge& e) {
+  return dEdge{reinterpret_cast<dNode*>(e.p), e.w};
+}
+
+} // namespace dd

mqt/core/include/mqt-core/dd/NoiseFunctionality.hpp

@@ -0,0 +1,144 @@
+/*
+ * 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 "dd/DDDefinitions.hpp"
+#include "dd/Node.hpp"
+#include "dd/Package.hpp"
+#include "ir/Definitions.hpp"
+#include "ir/operations/OpType.hpp"
+#include "ir/operations/Operation.hpp"
+
+#include <array>
+#include <cassert>
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <random>
+#include <set>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace dd {
+
+using NrEdges = std::tuple_size<decltype(dNode::e)>;
+using ArrayOfEdges = std::array<dCachedEdge, NrEdges::value>;
+
+// noise operations available for deterministic noise aware quantum circuit
+// simulation
+enum NoiseOperations : std::uint8_t {
+  AmplitudeDamping,
+  PhaseFlip,
+  Depolarization,
+  Identity
+};
+
+void sanityCheckOfNoiseProbabilities(double noiseProbability,
+                                     double amplitudeDampingProb,
+                                     double multiQubitGateFactor);
+
+class StochasticNoiseFunctionality {
+public:
+  StochasticNoiseFunctionality(Package& dd, std::size_t nq,
+                               double gateNoiseProbability,
+                               double amplitudeDampingProb,
+                               double multiQubitGateFactor,
+                               const std::string& cNoiseEffects);
+
+  ~StochasticNoiseFunctionality() { package->decRef(identityDD); }
+
+protected:
+  Package* package;
+  std::size_t nQubits;
+  std::uniform_real_distribution<fp> dist;
+
+  double noiseProbability;
+  double noiseProbabilityMulti;
+  fp sqrtAmplitudeDampingProbability;
+  fp oneMinusSqrtAmplitudeDampingProbability;
+  fp sqrtAmplitudeDampingProbabilityMulti;
+  fp oneMinusSqrtAmplitudeDampingProbabilityMulti;
+  GateMatrix ampDampingTrue{};
+  GateMatrix ampDampingTrueMulti{};
+  GateMatrix ampDampingFalse{};
+  GateMatrix ampDampingFalseMulti{};
+  std::vector<NoiseOperations> noiseEffects;
+  mEdge identityDD;
+
+  [[nodiscard]] std::size_t getNumberOfQubits() const { return nQubits; }
+  [[nodiscard]] double getNoiseProbability(bool multiQubitNoiseFlag) const;
+
+  [[nodiscard]] static qc::OpType
+  getAmplitudeDampingOperationType(bool multiQubitNoiseFlag,
+                                   bool amplitudeDampingFlag);
+
+  [[nodiscard]] GateMatrix
+  getAmplitudeDampingOperationMatrix(bool multiQubitNoiseFlag,
+                                     bool amplitudeDampingFlag) const;
+
+public:
+  void applyNoiseOperation(const std::set<qc::Qubit>& targets, mEdge operation,
+                           vEdge& state, std::mt19937_64& generator);
+
+protected:
+  [[nodiscard]] mEdge stackOperation(const mEdge& operation, qc::Qubit target,
+                                     qc::OpType noiseOperation,
+                                     const GateMatrix& matrix) const;
+
+  mEdge generateNoiseOperation(mEdge operation, qc::Qubit target,
+                               std::mt19937_64& generator,
+                               bool amplitudeDamping, bool multiQubitOperation);
+
+  [[nodiscard]] qc::OpType returnNoiseOperation(NoiseOperations noiseOperation,
+                                                double prob,
+                                                bool multiQubitNoiseFlag) const;
+};
+
+class DeterministicNoiseFunctionality {
+public:
+  DeterministicNoiseFunctionality(Package& dd, std::size_t nq,
+                                  double noiseProbabilitySingleQubit,
+                                  double noiseProbabilityMultiQubit,
+                                  double ampDampProbSingleQubit,
+                                  double ampDampProbMultiQubit,
+                                  const std::string& cNoiseEffects);
+
+protected:
+  Package* package;
+  std::size_t nQubits;
+
+  double noiseProbSingleQubit;
+  double noiseProbMultiQubit;
+  double ampDampingProbSingleQubit;
+  double ampDampingProbMultiQubit;
+
+  std::vector<NoiseOperations> noiseEffects;
+
+  [[nodiscard]] std::size_t getNumberOfQubits() const { return nQubits; }
+
+public:
+  void applyNoiseEffects(dEdge& originalEdge,
+                         const std::unique_ptr<qc::Operation>& qcOperation);
+
+private:
+  dCachedEdge applyNoiseEffects(dEdge& originalEdge,
+                                const std::set<qc::Qubit>& usedQubits,
+                                bool firstPathEdge, Qubit level);
+
+  static void applyPhaseFlipToEdges(ArrayOfEdges& e, double probability);
+
+  void applyAmplitudeDampingToEdges(ArrayOfEdges& e, double probability) const;
+
+  void applyDepolarisationToEdges(ArrayOfEdges& e, double probability) const;
+};
+
+} // namespace dd