mqt-core 3.3.2__cp314-cp314t-macosx_11_0_x86_64.whl

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

@@ -0,0 +1,22 @@
+/*
+ * 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/Edge.hpp"
+#include "dd/Node.hpp"
+
+namespace dd {
+class Package;
+
+using VectorDD = Edge<vNode>;
+using MatrixDD = Edge<mNode>;
+using DensityMatrixDD = Edge<dNode>;
+} // namespace dd

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

@@ -0,0 +1,255 @@
+/*
+ * 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/LinkedListBase.hpp"
+#include "dd/mqt_core_dd_export.h"
+
+#include <istream>
+#include <limits>
+#include <ostream>
+
+namespace dd {
+/**
+ * @brief A struct for representing real numbers as part of the DD package.
+ * @details Consists of a floating point number (the value) and a next pointer
+ * (used for chaining entries). Numbers are marked for garbage collection via
+ * the second least significant bit of pointers referencing them.
+ * @note Due to the way the sign of the value is encoded, special care has to
+ * be taken when accessing the value. The static functions in this struct
+ * provide safe access to the value of a RealNumber* pointer.
+ */
+struct RealNumber final : LLBase {
+  /// Getter for the next object.
+  [[nodiscard]] RealNumber* next() const noexcept;
+
+  /**
+   * @brief Check whether the number points to the zero number.
+   * @param e The number to check.
+   * @returns Whether the number points to zero.
+   */
+  [[nodiscard]] static constexpr bool exactlyZero(const RealNumber* e) noexcept;
+
+  /**
+   * @brief Check whether the number points to the one number.
+   * @param e The number to check.
+   * @returns Whether the number points to one.
+   */
+  [[nodiscard]] static constexpr bool exactlyOne(const RealNumber* e) noexcept;
+
+  /**
+   * @brief Check whether the number points to the sqrt(2)/2 = 1/sqrt(2) number.
+   * @param e The number to check.
+   * @returns Whether the number points to negative one.
+   */
+  [[nodiscard]] static constexpr bool
+  exactlySqrt2over2(const RealNumber* e) noexcept;
+
+  /**
+   * @brief Get the value of the number.
+   * @param e The number to get the value for.
+   * @returns The value of the number.
+   * @note This function accounts for the sign of the number embedded in the
+   * memory address of the number.
+   */
+  [[nodiscard]] static fp val(const RealNumber* e) noexcept;
+
+  /**
+   * @brief Check whether two floating point numbers are approximately equal.
+   * @details This function checks whether two floating point numbers are
+   * approximately equal. The two numbers are considered approximately equal
+   * if the absolute difference between them is smaller than a small value
+   * (TOLERANCE). This function is used to compare floating point numbers
+   * stored in the table.
+   * @param left The first floating point number.
+   * @param right The second floating point number.
+   * @returns Whether the two floating point numbers are approximately equal.
+   */
+  [[nodiscard]] static bool approximatelyEquals(fp left, fp right) noexcept;
+
+  /**
+   * @brief Check whether two numbers are approximately equal.
+   * @details This function checks whether two numbers are approximately
+   * equal. Two numbers are considered approximately equal if they point to
+   * the same number or if the values of the numbers are approximately equal.
+   * @param left The first number.
+   * @param right The second number.
+   * @returns Whether the two numbers are approximately equal.
+   * @see approximatelyEquals(fp, fp)
+   */
+  [[nodiscard]] static bool
+  approximatelyEquals(const RealNumber* left, const RealNumber* right) noexcept;
+
+  /**
+   * @brief Check whether a floating point number is approximately zero.
+   * @param e The floating point number to check.
+   * @returns Whether the floating point number is approximately zero.
+   */
+  [[nodiscard]] static bool approximatelyZero(fp e) noexcept;
+
+  /**
+   * @brief Check whether a number is approximately zero.
+   * @param e The number to check.
+   * @returns Whether the number is approximately zero.
+   * @see approximatelyZero(fp)
+   */
+  [[nodiscard]] static bool approximatelyZero(const RealNumber* e) noexcept;
+
+  /**
+   * @brief Write a binary representation of the number to a stream.
+   * @param e The number to write.
+   * @param os The stream to write to.
+   */
+  static void writeBinary(const RealNumber* e, std::ostream& os);
+
+  /**
+   * @brief Write a binary representation of a floating point number to a
+   * @param num The number to write.
+   * @param os The stream to write to.
+   */
+  static void writeBinary(fp num, std::ostream& os);
+
+  /**
+   * @brief Read a binary representation of a number from a stream.
+   * @param num The number to read into.
+   * @param is The stream to read from.
+   */
+  static void readBinary(fp& num, std::istream& is);
+
+  /**
+   * @brief Get an aligned pointer to the number.
+   * @details Since the least significant bit of the memory address of the
+   * number is used to encode the sign of the value, the pointer to the number
+   * might not be aligned. This function returns an aligned pointer to the
+   * number.
+   * @param e The number to get the aligned pointer for.
+   * @returns An aligned pointer to the number.
+   */
+  [[nodiscard]] static RealNumber*
+  getAlignedPointer(const RealNumber* e) noexcept;
+
+  /**
+   * @brief Get a pointer to the number with a negative sign.
+   * @details Since the least significant bit of the memory address of the
+   * number is used to encode the sign of the value, this function just sets
+   * the least significant bit of the memory address of the number to 1.
+   * @param e The number to get the negative pointer for.
+   * @returns A negative pointer to the number.
+   */
+  [[nodiscard]] static RealNumber*
+  getNegativePointer(const RealNumber* e) noexcept;
+
+  /**
+   * @brief Flip the sign of the number pointer.
+   * @param e The number to flip the sign of.
+   * @returns The number with the sign flipped.
+   * @note This function does not change the sign of the value of the number.
+   * It rather changes the sign of the pointer to the number.
+   * @note We do not consider negative zero here, since it is not used in the
+   * DD package. There only exists one zero number, which is positive.
+   */
+  [[nodiscard]] static RealNumber*
+  flipPointerSign(const RealNumber* e) noexcept;
+
+  /**
+   * @brief Mark @p e for garbage collection.
+   * @details Sets the 2nd least significant bit of the next_ pointer.
+   * @param e The number to mark.
+   */
+  static void mark(RealNumber* e) noexcept;
+
+  /**
+   * @brief Unmark @p e after garbage collection.
+   * @details Unsets the 2nd least significant bit of the next_ pointer.
+   * @param e The number to unmark.
+   */
+  static void unmark(RealNumber* e) noexcept;
+
+  /**
+   * @brief Immortalize @p e.
+   * @details Sets the 3rd least significant bit of the next_ pointer.
+   * @param e The number to immortalize.
+   */
+  static void immortalize(RealNumber* e) noexcept;
+
+  /**
+   * @brief Check whether the number is flagged as negative.
+   * @param e The number to check.
+   * @returns Whether the number is negative.
+   */
+  [[nodiscard]] static bool isNegativePointer(const RealNumber* e) noexcept;
+
+  /**
+   * @brief Check whether the number is flagged as marked.
+   * @param e The number to check.
+   * @returns Whether the number is marked.
+   */
+  [[nodiscard]] static bool isMarked(const RealNumber* e) noexcept;
+
+  /**
+   * @brief Check whether the number is flagged as immortal.
+   * @param e The number to check.
+   * @returns Whether the number is immortal.
+   */
+  [[nodiscard]] static bool isImmortal(const RealNumber* e) noexcept;
+
+  /**
+   * @brief The value of the number.
+   * @details The value of the number is a floating point number. The sign of
+   * the value is encoded in the least significant bit of the memory address
+   * of the number. As a consequence, values stored here are always
+   * non-negative. The sign of the value as well as the value itself can be
+   * accessed using the static functions of this struct.
+   */
+  fp value{};
+
+  /// numerical tolerance to be used for floating point values
+  // NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
+  static inline fp eps = std::numeric_limits<dd::fp>::epsilon() * 1024;
+};
+
+static_assert(sizeof(RealNumber) == 16);
+static_assert(alignof(RealNumber) == 8);
+
+namespace constants {
+// NOLINTBEGIN(cppcoreguidelines-avoid-non-const-global-variables)
+/// The constant zero.
+MQT_CORE_DD_EXPORT extern RealNumber zero;
+/// The constant one.
+MQT_CORE_DD_EXPORT extern RealNumber one;
+/// The constant sqrt(2)/2 = 1/sqrt(2).
+MQT_CORE_DD_EXPORT extern RealNumber sqrt2over2;
+// NOLINTEND(cppcoreguidelines-avoid-non-const-global-variables)
+
+/**
+ * @brief Check whether a number is one of the static numbers.
+ * @param e The number to check.
+ * @return Whether the number is one of the static numbers.
+ */
+[[nodiscard]] constexpr bool isStaticNumber(const RealNumber* e) noexcept {
+  return RealNumber::exactlyZero(e) || RealNumber::exactlyOne(e) ||
+         RealNumber::exactlySqrt2over2(e);
+}
+} // namespace constants
+
+constexpr bool RealNumber::exactlyZero(const RealNumber* e) noexcept {
+  return e == &constants::zero;
+}
+
+constexpr bool RealNumber::exactlyOne(const RealNumber* e) noexcept {
+  return e == &constants::one;
+}
+
+constexpr bool RealNumber::exactlySqrt2over2(const RealNumber* e) noexcept {
+  return e == &constants::sqrt2over2;
+}
+} // namespace dd

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

@@ -0,0 +1,217 @@
+/*
+ * 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/MemoryManager.hpp"
+#include "dd/statistics/UniqueTableStatistics.hpp"
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <iostream>
+
+namespace dd {
+
+struct RealNumber;
+
+/**
+ * @brief Immortal numbers that will never be garbage collected.
+ */
+namespace immortals {
+constexpr std::array<fp, 1> get() { return {.5}; }
+constexpr std::size_t size() { return get().size(); }
+} // namespace immortals
+
+/**
+ * @brief A unique table for real numbers.
+ * @details A hash table that stores real numbers. The hash table is implemented
+ * as an array of buckets, each of which is a linked list of entries. The hash
+ * table has a fixed number of buckets.
+ * @note: The implementation assumes that all values are non-negative and in the
+ * range [0, 1]. While numbers outside of this range can be stored, they will
+ * always be placed in the same bucket and will therefore cause collisions.
+ */
+class RealNumberUniqueTable {
+  /**
+   * @brief The number of buckets in the table.
+   * @details The number of buckets is fixed and cannot be changed after the
+   * table has been created. Increasing the number of buckets reduces the
+   * number of collisions, but increases the memory usage.
+   * @attention The number of buckets has to be one larger than a power of two.
+   * Otherwise, the hash function will not work correctly.
+   */
+  static constexpr std::size_t NBUCKET = 65537U;
+
+  /**
+   * @brief The initial garbage collection limit.
+   * @details The initial garbage collection limit is the number of entries that
+   * must be present in the table before garbage collection is triggered.
+   * Increasing this number reduces the number of garbage collections, but
+   * increases the memory usage.
+   */
+  static constexpr std::size_t INITIAL_GC_LIMIT = 65536U;
+
+public:
+  /**
+   * @brief The default constructor
+   * @param manager The memory manager to use for allocating new numbers.
+   * @param initialGCLim The initial garbage collection limit.
+   */
+  explicit RealNumberUniqueTable(MemoryManager& manager,
+                                 std::size_t initialGCLim = INITIAL_GC_LIMIT);
+
+  /**
+   * @brief The hash function for the hash table.
+   * @details The hash function for the table is a simple linear (clipped) hash
+   * function. The hash function is used to map floating point numbers to the
+   * buckets of the table.
+   * @param val The floating point number to hash. Must be non-negative.
+   * @returns The hash value of the floating point number.
+   * @note Typically, you would expect the hash to be an unsigned integer. Here,
+   * we use a signed integer because it turns out to result in fewer assembly
+   * instructions. See https://godbolt.org/z/9v4TEMfdz for a comparison.
+   */
+  static std::int64_t hash(fp val) noexcept;
+
+  /// Get a reference to the table.
+  [[nodiscard]] const auto& getTable() const noexcept { return table; }
+
+  /// Get a reference to the statistics
+  [[nodiscard]] const auto& getStats() const noexcept { return stats; }
+
+  /**
+   * @brief Lookup a number in the table
+   * @details This function is used to lookup and insert them into the table if
+   * they are not yet present. Since the table only ever stores non-negative
+   * numbers, the lookup is a three-step process. First the sign is stripped off
+   * the number and stored, then the non-negative value is looked up in the
+   * table and an aligned pointer to the respective entry is returned. Finally,
+   * If the sign of the original number was negative, the pointer is adjusted.
+   * @param val The floating point number to look up.
+   * @return A pointer to an entry corresponding to that number.
+   */
+  [[nodiscard]] RealNumber* lookup(fp val);
+
+  /**
+   * @brief Check whether the table possibly needs garbage collection.
+   * @returns Whether the number of entries in the table has reached the garbage
+   * collection limit.
+   */
+  [[nodiscard]] bool possiblyNeedsCollection() const noexcept;
+
+  /**
+   * @brief Perform garbage collection.
+   * @details This function performs garbage collection. It first checks whether
+   * garbage collection is necessary. If not, it does nothing. Otherwise, it
+   * iterates over all entries in the table and removes all numbers whose
+   * pointers are unmarked. If the force flag is set, garbage collection is
+   * performed even if it is not strictly necessary.
+   * Based on how many entries are returned to the available list, the garbage
+   * collection limit is dynamically adjusted.
+   * @param force Whether to force garbage collection.
+   * @returns The number of entries returned to the available list.
+   */
+  std::size_t garbageCollect(bool force = false) noexcept;
+
+  /**
+   * @brief Clear the table.
+   * @details This function clears the table. It iterates over all entries in
+   * the table and sets them to nullptr. It also discards the available list and
+   * all but the first chunk of the allocated chunks. Also resets all counters.
+   */
+  void clear() noexcept;
+
+  /**
+   * @brief Print the table.
+   */
+  void print() const;
+
+  /**
+   * @brief Print the bucket distribution of the table.
+   * @param os The output stream to print to.
+   * @returns The output stream.
+   */
+  std::ostream& printBucketDistribution(std::ostream& os = std::cout);
+
+  /// Count the marked entries in the table
+  [[nodiscard]] std::size_t countMarkedEntries() const noexcept;
+
+private:
+  /// Typedef for a bucket in the table.
+  using Bucket = RealNumber*;
+  /// Typedef for the table.
+  using Table = std::array<Bucket, NBUCKET>;
+
+  /**
+   * @brief The actual hash table
+   * @details The hash table is an array of buckets. Each bucket is a linked
+   * list of entries. The linked list is implemented by using the next pointer
+   * of the entries.
+   */
+  Table table{};
+  /**
+   * @brief The tail table
+   * @details The tail table is an array of pointers to the last entry in each
+   * bucket. This is used to speed up the insertion of new entries.
+   */
+  std::array<RealNumber*, NBUCKET> tailTable{};
+
+  /// A pointer to the memory manager for the numbers stored in the table.
+  MemoryManager* memoryManager{};
+
+  /// A collection of statistics
+  UniqueTableStatistics stats{};
+
+  /// The initial garbage collection limit
+  std::size_t initialGCLimit;
+  /// The current garbage collection limit
+  std::size_t gcLimit = initialGCLimit;
+
+  /**
+   * @brief Finds or inserts a value into the bucket indexed by key.
+   * @details This function either finds an entry with a value within TOLERANCE
+   * of val in the bucket indexed by key or inserts a new entry with value val
+   * into the bucket.
+   * @param key The index of the bucket to find or insert the value into.
+   * @param val The value to find or insert.
+   * @returns A pointer to the found or inserted entry.
+   */
+  RealNumber* findOrInsert(std::int64_t key, fp val);
+
+  /**
+   * @brief Inserts a value in the front of the bucket indexed by key.
+   * @param key The index of the bucket to insert the value into.
+   * @param val The value to insert.
+   * @return A pointer to the inserted entry.
+   */
+  RealNumber* insertFront(std::int64_t key, fp val);
+
+  /**
+   * @brief Inserts a value in the back of the bucket indexed by key.
+   * @param key The index of the bucket to insert the value into.
+   * @param val The value to insert.
+   * @return A pointer to the inserted entry.
+   */
+  RealNumber* insertBack(std::int64_t key, fp val);
+
+  /**
+   * @brief Lookup a non-negative number in the table.
+   * @details The table only ever stores non-negative values. Thus, any lookup
+   * must be split between actually looking up the number and adjusting for its
+   * sign. This function looks up a number in the table. If the number is not
+   * found, a new number is created and inserted into the table.
+   * @param val The floating point number to look up. Must be non-negative.
+   * @returns An aligned pointer to the entry corresponding to the number.
+   */
+  [[nodiscard]] RealNumber* lookupNonNegative(fp val);
+};
+} // namespace dd

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

@@ -0,0 +1,98 @@
+/*
+ * 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 functions for classically simulating quantum circuits.
+ */
+
+#pragma once
+
+#include "dd/Package_fwd.hpp"
+
+#include <cstddef>
+#include <map>
+#include <string>
+
+namespace qc {
+class QuantumComputation;
+}
+
+namespace dd {
+
+/**
+ * @brief Simulate a purely-quantum @ref qc::QuantumComputation on a given input
+ * state using decision diagrams.
+ *
+ * @details This method classically simulates the quantum computation @p qc on
+ * the input state @p in by sequentially applying the operations in the circuit
+ * to the initial state via decision diagram multiplication.
+ *
+ * This simple simulation method can only handle circuits that do not contain
+ * any classical control operations or measurements.
+ * Its main purpose is to construct a representation of the statevector after
+ * simulating the quantum computation for the given input state.
+ * For more elaborate simulation methods that can handle classical control and
+ * mid-circuit measurements, see @ref sample(const QuantumComputation&,
+ * std::size_t, std::size_t).
+ *
+ * @param qc The quantum computation to simulate
+ * @param in The input state to simulate. Represented as a vector DD.
+ * @param dd The DD package to use for the simulation
+ * @return A vector DD representing the output state of the simulation
+ */
+VectorDD simulate(const qc::QuantumComputation& qc, const VectorDD& in,
+                  Package& dd);
+
+/**
+ * @brief Sample from the output distribution of a quantum computation
+ *
+ * @details This method classically simulates the quantum computation @p qc
+ * starting from the all-zero state and samples @p shots times from the output
+ * distribution.
+ * The seed for the random number generator can be set using @p seed.
+ *
+ * For a circuit without mid-circuit measurements, this function will construct
+ * a representation of the final statevector similar to @ref simulate and then
+ * repeatedly sample from the resulting decision diagram, without actually
+ * collapsing the state. For a fixed number of qubits, each sample can be drawn
+ * in constant time, which is a significant of the decision diagram structure.
+ *
+ * For a circuit with mid-circuit measurements, this function will separately
+ * execute the circuit for each sample, probabilistically collapsing the state
+ * after each measurement.
+ *
+ * @param qc The quantum computation to simulate
+ * @param shots The number of shots to sample
+ * @param seed The seed for the random number generator
+ * @return A histogram of the measurement results
+ */
+std::map<std::string, std::size_t> sample(const qc::QuantumComputation& qc,
+                                          std::size_t shots = 1024U,
+                                          std::size_t seed = 0U);
+
+/**
+ * @brief Sample from the output distribution of a quantum computation
+ *
+ * @details This is a more general version of @ref sample that allows for
+ * choosing the input state to simulate as well as the DD package to use for the
+ * simulation.
+ *
+ * @param qc The quantum computation to simulate
+ * @param in The input state to simulate. Represented as a vector DD.
+ * @param dd The DD package to use for the simulation
+ * @param shots The number of shots to sample
+ * @param seed The seed for the random number generator
+ * @return A histogram of the measurement results
+ */
+std::map<std::string, std::size_t> sample(const qc::QuantumComputation& qc,
+                                          const VectorDD& in, Package& dd,
+                                          std::size_t shots,
+                                          std::size_t seed = 0U);
+} // namespace dd