mqt-core 3.2.0__cp314-cp314-win_amd64.whl

mqt/core/include/mqt-core/dd/statistics/MemoryManagerStatistics.hpp

@@ -0,0 +1,84 @@
+/*
+ * 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/Statistics.hpp"
+#include "nlohmann/json_fwd.hpp"
+
+#include <cstddef>
+
+namespace dd {
+
+/**
+ * @brief A utility class for storing statistics of a memory manager
+ */
+struct MemoryManagerStatistics final : Statistics {
+
+  /**
+   * @brief Construct a new Memory Manager Statistics object
+   * @param entrySize The size of a single entry
+   */
+  explicit MemoryManagerStatistics(const std::size_t entrySize)
+      : entrySize_(entrySize) {}
+
+  /// The size of a single entry
+  std::size_t entrySize_;
+
+  [[nodiscard]] double entryMemoryMIB() const;
+
+  /// The number of allocations performed
+  std::size_t numAllocations = 0U;
+  /// The number of allocated entries
+  std::size_t numAllocated = 0U;
+  /// The number of entries currently in use
+  std::size_t numUsed = 0U;
+  /// The number of entries currently available for reuse
+  std::size_t numAvailableForReuse = 0U;
+  /// The peak number of entries in use
+  std::size_t peakNumUsed = 0U;
+  /// The peak number of entries available for reuse
+  std::size_t peakNumAvailableForReuse = 0U;
+
+  /// Get the number of available entries from memory chunks
+  [[nodiscard]] std::size_t getNumAvailableFromChunks() const noexcept;
+
+  /// Get the total number of available entries
+  [[nodiscard]] std::size_t getTotalNumAvailable() const noexcept;
+
+  /// Get an estimate for ratio of used memory
+  [[nodiscard]] double getUsageRatio() const noexcept;
+
+  /// Get an estimate of the total allocated memory in MiB
+  [[nodiscard]] double getAllocatedMemoryMiB() const noexcept;
+
+  /// Get an estimate of the total used memory in MiB
+  [[nodiscard]] double getUsedMemoryMiB() const noexcept;
+
+  /// Get an estimate for the peak used memory in MiB
+  [[nodiscard]] double getPeakUsedMemoryMiB() const noexcept;
+
+  /// Track newly used entries (from chunks)
+  void trackUsedEntries(std::size_t numEntries = 1U) noexcept;
+
+  /// Track reused entries (from available list)
+  void trackReusedEntries(std::size_t numEntries = 1U) noexcept;
+
+  /// Track a new available entry for reuse
+  void trackReturnedEntry() noexcept;
+
+  /// Reset all statistics (except for the peak values)
+  void reset() noexcept override;
+
+  /// Get a JSON representation of the statistics
+  [[nodiscard]] nlohmann::json json() const override;
+};
+
+} // namespace dd

mqt/core/include/mqt-core/dd/statistics/PackageStatistics.hpp

@@ -0,0 +1,55 @@
+/*
+ * 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/Package.hpp"
+
+#include <iostream>
+#include <nlohmann/json_fwd.hpp>
+#include <string>
+
+namespace dd {
+
+/**
+ * @brief Computes an estimate for the memory usage of active DDs.
+ * @details The estimate is based on the number of active entries which are
+ * computed by temporarily marking all nodes reachable from the current root
+ * set and subsequently counting them in the unique tables. It accounts for the
+ * memory used by DD nodes, DD edges, and real numbers.
+ * @param package The package instance
+ * @return The estimated memory usage in MiB
+ */
+[[nodiscard]] double computeActiveMemoryMiB(Package& package);
+
+/**
+ * @brief Computes an estimate for the peak memory usage of DDs.
+ * @details The estimate is based on the peak number of used entries in the
+ * respective memory managers. It accounts for the memory used by DD nodes, DD
+ * edges, and real numbers.
+ * @param package The package instance
+ * @return The estimated memory usage in MiB
+ */
+[[nodiscard]] double computePeakMemoryMiB(const Package& package);
+
+[[nodiscard]] nlohmann::basic_json<>
+getStatistics(Package& package, bool includeIndividualTables = false);
+
+/**
+ * @brief Get some key statistics about data structures used by the DD package
+ * @return A JSON representation of the statistics
+ */
+[[nodiscard]] nlohmann::basic_json<> getDataStructureStatistics();
+
+[[nodiscard]] std::string getStatisticsString(Package& package);
+
+void printStatistics(Package& package, std::ostream& os = std::cout);
+
+} // namespace dd

mqt/core/include/mqt-core/dd/statistics/Statistics.hpp

@@ -0,0 +1,48 @@
+/*
+ * 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 "nlohmann/json_fwd.hpp"
+
+#include <ostream>
+#include <string>
+
+namespace dd {
+
+struct Statistics {
+  Statistics() = default;
+  Statistics(const Statistics&) = default;
+  Statistics(Statistics&&) = default;
+  Statistics& operator=(const Statistics&) = default;
+  Statistics& operator=(Statistics&&) = default;
+  virtual ~Statistics() = default;
+
+  /// Reset all statistics (except for peak values)
+  virtual void reset() noexcept {};
+
+  /// Get a JSON representation of the statistics
+  [[nodiscard]] virtual nlohmann::json json() const;
+
+  /// Get a pretty-printed string representation of the statistics
+  [[nodiscard]] virtual std::string toString() const;
+
+  /**
+   * @brief Write a string representation to an output stream
+   * @param os The output stream
+   * @param stats The statistics
+   * @return The output stream
+   */
+  friend std::ostream& operator<<(std::ostream& os, const Statistics& stats) {
+    return os << stats.toString();
+  }
+};
+
+} // namespace dd

mqt/core/include/mqt-core/dd/statistics/TableStatistics.hpp

@@ -0,0 +1,79 @@
+/*
+ * 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/Statistics.hpp"
+
+#include <cstddef>
+#include <nlohmann/json_fwd.hpp>
+
+namespace dd {
+
+/// A utility class for storing statistics of a table
+struct TableStatistics : public Statistics {
+  /// The size of a single entry
+  std::size_t entrySize = 0U;
+  /// The number of buckets in the table
+  std::size_t numBuckets = 0U;
+  /// The number of entries in the table
+  std::size_t numEntries = 0U;
+  /// The peak number of entries in the table
+  std::size_t peakNumEntries = 0U;
+
+  /// The number of collisions
+  std::size_t collisions = 0U;
+  /// The number of successful lookups
+  std::size_t hits = 0U;
+  /// The number of lookups
+  std::size_t lookups = 0U;
+  /// The number of inserts
+  std::size_t inserts = 0U;
+
+  /// Track a new insert
+  void trackInsert() noexcept;
+
+  /// Reset all statistics (except for peak values)
+  void reset() noexcept override;
+
+  /**
+   * @brief Get the hit ratio of the table.
+   * @details The hit ratio is the ratio of lookups that were successful.
+   * @returns The hit ratio of the table.
+   */
+  [[nodiscard]] double hitRatio() const noexcept;
+
+  /**
+   * @brief Get the collision ratio of the table.
+   * @details A collision occurs when the hash function maps two different
+   * entries to the same bucket. The collision ratio is the ratio of lookups
+   * that resulted in a collision.
+   * @returns The collision ratio of the table.
+   */
+  [[nodiscard]] double colRatio() const noexcept;
+
+  /**
+   * @brief Get the load factor of the table.
+   * @details The load factor is the ratio of entries to buckets.
+   * @return The load factor of the table.
+   */
+  [[nodiscard]] double loadFactor() const noexcept;
+
+  /// Convert the entry size to MiB
+  [[nodiscard]] double getEntrySizeMiB() const noexcept;
+
+  /// Get the amount of memory required for the table in MiB
+  [[nodiscard]] double getMemoryMiB() const noexcept;
+
+  /// Get a JSON representation of the statistics
+  [[nodiscard]] nlohmann::json json() const override;
+};
+
+} // namespace dd

mqt/core/include/mqt-core/dd/statistics/UniqueTableStatistics.hpp

@@ -0,0 +1,31 @@
+/*
+ * 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/TableStatistics.hpp"
+
+#include <cstddef>
+#include <nlohmann/json_fwd.hpp>
+
+namespace dd {
+/// \brief A class for storing statistics of a unique table
+struct UniqueTableStatistics : public TableStatistics {
+  /// The number of garbage collection runs
+  std::size_t gcRuns = 0U;
+
+  /// Reset all statistics (except for the peak values)
+  void reset() noexcept override;
+
+  /// Get a JSON representation of the statistics
+  [[nodiscard]] nlohmann::json json() const override;
+};
+
+} // namespace dd

mqt/core/include/mqt-core/ir/Definitions.hpp

@@ -0,0 +1,108 @@
+/*
+ * 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 Common definitions used throughout the library.
+ */
+
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+
+namespace qc {
+/**
+ * @brief Type alias for qubit indices.
+ * @details This type (alias) is used to represent qubit indices in the library.
+ * It has been chosen to be an unsigned 32-bit integer to allow for up to
+ * 4,294,967,295 qubits, which should be enough for most use cases.
+ */
+using Qubit = std::uint32_t;
+/**
+ * @brief Type alias for classical bit indices.
+ * @details This type (alias) is used to represent classical bit indices in the
+ * library. The choice of 64-bits is arbitrary and can be changed if necessary.
+ */
+using Bit = std::uint64_t;
+
+/// A type alias for a vector of qubits which are supposed to act as targets.
+using Targets = std::vector<Qubit>;
+
+/// Floating-point type used throughout the library
+using fp = double;
+
+/// A constant for the value of \f$\pi\f$.
+static constexpr auto PI = static_cast<fp>(
+    3.141592653589793238462643383279502884197169399375105820974L);
+/// A constant for the value of \f$\frac{\pi}{2}\f$.
+static constexpr auto PI_2 = static_cast<fp>(
+    1.570796326794896619231321691639751442098584699687552910487L);
+/// A constant for the value of \f$\frac{\pi}{4}\f$.
+static constexpr auto PI_4 = static_cast<fp>(
+    0.785398163397448309615660845819875721049292349843776455243L);
+/// A constant for the value of \f$\tau\f$.
+static constexpr auto TAU = static_cast<fp>(
+    6.283185307179586476925286766559005768394338798750211641950L);
+/// A constant for the value of \f$e\f$.
+static constexpr auto E = static_cast<fp>(
+    2.718281828459045235360287471352662497757247093699959574967L);
+
+/// Supported file formats
+enum class Format : uint8_t {
+  /**
+   * @brief OpenQASM 2.0 format
+   * @see https://arxiv.org/abs/1707.03429
+   */
+  OpenQASM2,
+  /**
+   * @brief OpenQASM 3 format
+   * @see https://openqasm.com/index.html
+   */
+  OpenQASM3
+};
+
+/**
+ * @brief Combine two 64bit hashes into one 64bit hash
+ * @details Combines two 64bit hashes into one 64bit hash based on
+ * boost::hash_combine (https://www.boost.org/LICENSE_1_0.txt)
+ * @param lhs The first hash
+ * @param rhs The second hash
+ * @returns The combined hash
+ */
+[[nodiscard]] constexpr std::size_t
+combineHash(const std::size_t lhs, const std::size_t rhs) noexcept {
+  return lhs ^ (rhs + 0x9e3779b97f4a7c15ULL + (lhs << 6) + (lhs >> 2));
+}
+
+/**
+ * @brief Extend a 64bit hash with a 64bit integer
+ * @param hash The hash to extend
+ * @param with The integer to extend the hash with
+ * @return The combined hash
+ */
+constexpr void hashCombine(std::size_t& hash, const std::size_t with) noexcept {
+  hash = combineHash(hash, with);
+}
+
+/**
+ * @brief Function used to mark unreachable code
+ * @details Uses compiler specific extensions if possible. Even if no extension
+ * is used, undefined behavior is still raised by an empty function body and the
+ * noreturn attribute.
+ */
+[[noreturn]] inline void unreachable() {
+#ifdef __GNUC__ // GCC, Clang, ICC
+  __builtin_unreachable();
+#elif defined(_MSC_VER) // MSVC
+  __assume(false);
+#endif
+}
+} // namespace qc

mqt/core/include/mqt-core/ir/Permutation.hpp

@@ -0,0 +1,213 @@
+/*
+ * 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 "Definitions.hpp"
+#include "operations/Control.hpp"
+
+#include <cstddef>
+#include <functional>
+#include <initializer_list>
+#include <map>
+#include <utility>
+
+namespace qc {
+class Permutation {
+  std::map<Qubit, Qubit> permutation;
+
+public:
+  [[nodiscard]] auto apply(const Controls& controls) const -> Controls;
+  [[nodiscard]] auto apply(const Targets& targets) const -> Targets;
+  [[nodiscard]] auto apply(Qubit qubit) const -> Qubit;
+  [[nodiscard]] auto maxKey() const -> Qubit;
+  [[nodiscard]] auto maxValue() const -> Qubit;
+
+  /// Constructors
+  Permutation() = default;
+  template <class InputIt>
+  Permutation(InputIt first, InputIt last) : permutation(first, last) {}
+  Permutation(const std::initializer_list<std::pair<const Qubit, Qubit>> init)
+      : permutation(init) {}
+
+  /// Returns an iterator to the beginning
+  [[nodiscard]] auto begin() noexcept -> decltype(permutation)::iterator {
+    return permutation.begin();
+  }
+  [[nodiscard]] auto begin() const noexcept
+      -> decltype(permutation)::const_iterator {
+    return permutation.begin();
+  }
+  [[nodiscard]] auto cbegin() const noexcept -> auto {
+    return permutation.cbegin();
+  }
+
+  /// Returns an iterator to the end
+  [[nodiscard]] auto end() noexcept -> decltype(permutation)::iterator {
+    return permutation.end();
+  }
+  [[nodiscard]] auto end() const noexcept
+      -> decltype(permutation)::const_iterator {
+    return permutation.end();
+  }
+  [[nodiscard]] auto cend() const noexcept -> auto {
+    return permutation.cend();
+  }
+
+  /// Returns a reverse iterator to the beginning
+  [[nodiscard]] auto rbegin() noexcept
+      -> decltype(permutation)::reverse_iterator {
+    return permutation.rbegin();
+  }
+  [[nodiscard]] auto rbegin() const noexcept
+      -> decltype(permutation)::const_reverse_iterator {
+    return permutation.rbegin();
+  }
+  [[nodiscard]] auto crbegin() const noexcept -> auto {
+    return permutation.crbegin();
+  }
+
+  /// Returns a reverse iterator to the end
+  [[nodiscard]] auto rend() noexcept
+      -> decltype(permutation)::reverse_iterator {
+    return permutation.rend();
+  }
+  [[nodiscard]] auto rend() const noexcept
+      -> decltype(permutation)::const_reverse_iterator {
+    return permutation.rend();
+  }
+  [[nodiscard]] auto crend() const noexcept -> auto {
+    return permutation.crend();
+  }
+
+  /// Checks whether the permutation is empty
+  [[nodiscard]] auto empty() const -> bool { return permutation.empty(); }
+
+  /// Returns the number of elements
+  [[nodiscard]] auto size() const -> std::size_t { return permutation.size(); }
+
+  /// Clears the permutation
+  void clear() { permutation.clear(); }
+
+  /// Finds element with specific key
+  [[nodiscard]] auto find(const Qubit qubit)
+      -> decltype(permutation.find(qubit)) {
+    return permutation.find(qubit);
+  }
+  [[nodiscard]] auto find(const Qubit qubit) const
+      -> decltype(permutation.find(qubit)) {
+    return permutation.find(qubit);
+  }
+
+  /// Returns the number of elements with specific key
+  [[nodiscard]] auto count(const Qubit qubit) const -> std::size_t {
+    return permutation.count(qubit);
+  }
+
+  /// Access specified element with bounds checking
+  [[nodiscard]] auto at(const Qubit qubit) const -> Qubit {
+    return permutation.at(qubit);
+  }
+
+  /// Access specified element with bounds checking
+  [[nodiscard]] auto at(const Qubit qubit) -> Qubit& {
+    return permutation.at(qubit);
+  }
+
+  /// Access or insert specified element
+  [[nodiscard]] auto operator[](const Qubit qubit) -> Qubit& {
+    return permutation[qubit];
+  }
+
+  /// Inserts elements or nodes
+  auto insert(const std::pair<const Qubit, Qubit>& value) -> auto {
+    return permutation.insert(value);
+  }
+  template <class InputIt> auto insert(InputIt first, InputIt last) -> void {
+    permutation.insert(first, last);
+  }
+  auto insert(const std::initializer_list<std::pair<const Qubit, Qubit>> init)
+      -> void {
+    permutation.insert(init);
+  }
+
+  /// Constructs element in-place
+  template <class... Args> auto emplace(Args&&... args) -> auto {
+    return permutation.emplace(std::forward<Args>(args)...);
+  }
+
+  // NOLINTBEGIN(readability-identifier-naming)
+
+  /// Inserts in-place if the key does not exist, does nothing otherwise
+  template <class... Args>
+  auto try_emplace(const Qubit key, Args&&... args) -> auto {
+    return permutation.try_emplace(key, std::forward<Args>(args)...);
+  }
+
+  /// Inserts an element or assigns to the current element if the key already
+  /// exists
+  auto insert_or_assign(const Qubit key, const Qubit value) -> auto {
+    return permutation.insert_or_assign(key, value);
+  }
+
+  // NOLINTEND(readability-identifier-naming)
+
+  /// Erases elements
+  auto erase(const Qubit qubit) -> std::size_t {
+    return permutation.erase(qubit);
+  }
+  auto erase(const decltype(permutation)::const_iterator pos)
+      -> decltype(permutation)::iterator {
+    return permutation.erase(pos);
+  }
+  auto erase(const decltype(permutation)::const_iterator first,
+             const decltype(permutation)::const_iterator last)
+      -> decltype(permutation)::iterator {
+    return permutation.erase(first, last);
+  }
+
+  /// Swaps the contents
+  void swap(Permutation& other) noexcept {
+    permutation.swap(other.permutation);
+  }
+
+  /// Lexicographically compares the values in the map
+  [[nodiscard]] auto operator<(const Permutation& other) const -> bool {
+    return permutation < other.permutation;
+  }
+  [[nodiscard]] auto operator<=(const Permutation& other) const -> bool {
+    return permutation <= other.permutation;
+  }
+  [[nodiscard]] auto operator>(const Permutation& other) const -> bool {
+    return permutation > other.permutation;
+  }
+  [[nodiscard]] auto operator>=(const Permutation& other) const -> bool {
+    return permutation >= other.permutation;
+  }
+  [[nodiscard]] auto operator==(const Permutation& other) const -> bool {
+    return permutation == other.permutation;
+  }
+  [[nodiscard]] auto operator!=(const Permutation& other) const -> bool {
+    return permutation != other.permutation;
+  }
+};
+} // namespace qc
+
+// define hash function for Permutation
+template <> struct std::hash<qc::Permutation> {
+  std::size_t operator()(const qc::Permutation& p) const noexcept {
+    std::size_t seed = 0;
+    for (const auto& [k, v] : p) {
+      qc::hashCombine(seed, k);
+      qc::hashCombine(seed, v);
+    }
+    return seed;
+  }
+};