mqt-core 3.3.2__cp314-cp314t-macosx_11_0_x86_64.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