mqt-core 3.3.2__cp314-cp314t-macosx_11_0_arm64.whl

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

@@ -0,0 +1,165 @@
+/*
+ * 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/RealNumber.hpp"
+#include "ir/Definitions.hpp"
+
+#include <complex>
+#include <cstddef>
+#include <functional>
+#include <iostream>
+#include <string>
+
+namespace dd {
+
+struct RealNumber;
+struct ComplexValue;
+
+/// A complex number represented by two pointers to compute table entries.
+struct Complex {
+  /// Compute table entry for the real part.
+  RealNumber* r;
+  /// Compute table entry for the imaginary part.
+  RealNumber* i;
+
+  /**
+   * @brief The static constant for the complex number zero.
+   * @return A complex number with real and imaginary part equal to zero.
+   */
+  static constexpr Complex zero() noexcept {
+    return {&constants::zero, &constants::zero};
+  }
+
+  /**
+   * @brief The static constant for the complex number one.
+   * @return A complex number with real part equal to one and imaginary part
+   * equal to zero.
+   */
+  static constexpr Complex one() noexcept {
+    return {&constants::one, &constants::zero};
+  }
+
+  /**
+   * @brief Check whether the complex number is exactly equal to zero.
+   * @returns True if the complex number is exactly equal to zero, false
+   * otherwise.
+   * @see RealNumber::exactlyZero
+   */
+  [[nodiscard]] constexpr bool exactlyZero() const noexcept {
+    return RealNumber::exactlyZero(r) && RealNumber::exactlyZero(i);
+  }
+
+  /**
+   * @brief Check whether the complex number is exactly equal to one.
+   * @returns True if the complex number is exactly equal to one, false
+   * otherwise.
+   * @see RealNumber::exactlyOne
+   * @see RealNumber::exactlyZero
+   */
+  [[nodiscard]] constexpr bool exactlyOne() const noexcept {
+    return RealNumber::exactlyOne(r) && RealNumber::exactlyZero(i);
+  }
+
+  /**
+   * @brief Check whether the complex number is approximately equal to the
+   * given complex number.
+   * @param c The complex number to compare to.
+   * @returns True if the complex number is approximately equal to the given
+   * complex number, false otherwise.
+   * @see RealNumber::approximatelyEquals
+   */
+  [[nodiscard]] bool approximatelyEquals(const Complex& c) const noexcept;
+
+  /**
+   * @brief Check whether the complex number is approximately equal to zero.
+   * @returns True if the complex number is approximately equal to zero, false
+   * otherwise.
+   * @see RealNumber::approximatelyZero
+   */
+  [[nodiscard]] bool approximatelyZero() const noexcept;
+
+  /// @brief Mark the complex number as used.
+  void mark() const noexcept;
+
+  /// @brief Unmark the complex number.
+  void unmark() const noexcept;
+
+  /**
+   * @brief Convert the complex number to a string.
+   * @param formatted Whether to apply special formatting to the numbers.
+   * @param precision The precision to use for the numbers.
+   * @returns The string representation of the complex number.
+   * @see ComplexValue::toString
+   */
+  [[nodiscard]] std::string toString(bool formatted = true,
+                                     int precision = -1) const;
+
+  /**
+   * @brief Write the complex number to a binary stream.
+   * @param os The output stream to write to.
+   * @see RealNumber::writeBinary
+   */
+  void writeBinary(std::ostream& os) const;
+
+  /**
+   * @brief Convert the Complex number to an std::complex<fp>.
+   * @returns The std::complex<fp> representation of the Complex number.
+   */
+  [[nodiscard]] explicit operator std::complex<fp>() const noexcept;
+
+  /**
+   * @brief Convert the Complex number to a ComplexValue.
+   * @returns The ComplexValue representation of the Complex number.
+   */
+  [[nodiscard]] explicit operator ComplexValue() const noexcept;
+};
+
+/**
+ * @brief Print a complex number to a stream.
+ * @param os The output stream to write to.
+ * @param c The complex number to print.
+ * @returns The output stream.
+ */
+std::ostream& operator<<(std::ostream& os, const Complex& c);
+
+ComplexValue operator*(const Complex& c1, const ComplexValue& c2);
+ComplexValue operator*(const ComplexValue& c1, const Complex& c2);
+ComplexValue operator*(const Complex& c1, const Complex& c2);
+ComplexValue operator*(const Complex& c1, fp real);
+ComplexValue operator*(fp real, const Complex& c1);
+
+ComplexValue operator/(const Complex& c1, const ComplexValue& c2);
+ComplexValue operator/(const ComplexValue& c1, const Complex& c2);
+ComplexValue operator/(const Complex& c1, const Complex& c2);
+ComplexValue operator/(const Complex& c1, fp real);
+
+} // namespace dd
+
+/// Hash function for complex numbers.
+template <> struct std::hash<dd::Complex> {
+  /**
+   * @brief Compute the hash value for a complex number.
+   * @details Reinterprets the pointers to the real and imaginary part as
+   * integers and computes the hash value for those. Afterwards, the two hash
+   * values are combined.
+   * @param c The complex number to compute the hash value for.
+   * @returns The hash value.
+   * @see dd::murmur64
+   * @see dd::combineHash
+   */
+  std::size_t operator()(dd::Complex const& c) const noexcept {
+    const auto h1 = dd::murmur64(reinterpret_cast<std::size_t>(c.r));
+    const auto h2 = dd::murmur64(reinterpret_cast<std::size_t>(c.i));
+    return qc::combineHash(h1, h2);
+  }
+};

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

@@ -0,0 +1,150 @@
+/*
+ * 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/Complex.hpp"
+#include "dd/DDDefinitions.hpp"
+#include "dd/Edge.hpp"
+#include "dd/RealNumberUniqueTable.hpp"
+
+#include <complex>
+#include <cstddef>
+
+namespace dd {
+
+struct ComplexValue;
+
+/// A class for managing complex numbers in the DD package.
+class ComplexNumbers {
+
+public:
+  /// Default constructor.
+  explicit ComplexNumbers(RealNumberUniqueTable& table)
+      : uniqueTable(&table) {};
+  /// Default destructor.
+  ~ComplexNumbers() = default;
+
+  /**
+   * @brief Set the numerical tolerance for comparisons of floats.
+   * @param tol The new tolerance.
+   */
+  static void setTolerance(fp tol) noexcept;
+
+  /**
+   * @brief Compute the squared magnitude of a complex number.
+   * @param a The complex number.
+   * @returns The squared magnitude.
+   */
+  [[nodiscard]] static fp mag2(const Complex& a) noexcept;
+
+  /**
+   * @brief Compute the magnitude of a complex number.
+   * @param a The complex number.
+   * @returns The magnitude.
+   */
+  [[nodiscard]] static fp mag(const Complex& a) noexcept;
+
+  /**
+   * @brief Compute the argument of a complex number.
+   * @param a The complex number.
+   * @returns The argument.
+   */
+  [[nodiscard]] static fp arg(const Complex& a) noexcept;
+
+  /**
+   * @brief Compute the complex conjugate of a complex number.
+   * @param a The complex number.
+   * @returns The complex conjugate.
+   * @note Conjugation is efficiently handled by just flipping the sign of the
+   * imaginary pointer.
+   */
+  [[nodiscard]] static Complex conj(const Complex& a) noexcept;
+
+  /**
+   * @brief Compute the negation of a complex number.
+   * @param a The complex number.
+   * @returns The negation.
+   * @note Negation is efficiently handled by just flipping the sign of both
+   * pointers.
+   */
+  [[nodiscard]] static Complex neg(const Complex& a) noexcept;
+
+  /**
+   * @brief Lookup a complex value in the complex table; if not found add it.
+   * @param c The complex number.
+   * @return The found or added complex number.
+   */
+  [[nodiscard]] Complex lookup(const Complex& c);
+
+  /**
+   * @see lookup(fp r, fp i)
+   */
+  [[nodiscard]] Complex lookup(const std::complex<fp>& c);
+
+  /**
+   * @see lookup(fp r, fp i)
+   */
+  [[nodiscard]] Complex lookup(const ComplexValue& c);
+
+  /**
+   * @brief Lookup a real value in the complex table; if not found add it.
+   * @param r The real number.
+   * @return The found or added complex number with real part r and imaginary
+   * part zero.
+   */
+  [[nodiscard]] Complex lookup(fp r);
+
+  /**
+   * @brief Lookup a complex value in the complex table; if not found add it.
+   * @param r The real part.
+   * @param i The imaginary part.
+   * @return The found or added complex number.
+   * @see ComplexTable::lookup
+   */
+  [[nodiscard]] Complex lookup(fp r, fp i);
+
+  /**
+   * @brief Turn CachedEdge into Edge via lookup.
+   * @tparam Node The type of the node.
+   * @param ce The cached edge.
+   * @return The edge with looked-up weight. The zero terminal if the new weight
+   * is exactly zero.
+   */
+  template <class Node>
+  [[nodiscard]] Edge<Node> lookup(const CachedEdge<Node>& ce) {
+    auto e = Edge<Node>{ce.p, lookup(ce.w)};
+    if (e.w.exactlyZero()) {
+      e.p = Node::getTerminal();
+    }
+    return e;
+  }
+
+  /**
+   * @brief Check whether a complex number is one of the static ones.
+   * @param c The complex number.
+   * @return Whether the complex number is one of the static ones.
+   */
+  [[nodiscard]] static constexpr bool isStaticComplex(const Complex& c) {
+    return c.exactlyZero() || c.exactlyOne();
+  }
+
+  /**
+   * @brief Get the number of stored real numbers.
+   * @return The number of stored real numbers.
+   */
+  [[nodiscard]] std::size_t realCount() const noexcept;
+
+private:
+  /// A pointer to the unique table to use for calculations
+  RealNumberUniqueTable* uniqueTable;
+};
+} // namespace dd

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

@@ -0,0 +1,184 @@
+/*
+ * 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 <cmath>
+#include <complex>
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+#include <iostream>
+#include <string>
+#include <utility>
+
+namespace dd {
+/// A complex number represented by two floating point values.
+struct ComplexValue {
+  /// real part
+  fp r{};
+  /// imaginary part
+  fp i{};
+
+  ComplexValue() = default;
+  // NOLINTNEXTLINE(google-explicit-constructor) We want impl. conv. from reals
+  ComplexValue(const fp real) noexcept : r{real} {}
+  explicit ComplexValue(const std::complex<fp>& c) noexcept
+      : r{c.real()}, i{c.imag()} {}
+  ComplexValue(const fp real, const fp imag) noexcept : r{real}, i{imag} {}
+
+  /**
+   * @brief Check for exact equality.
+   * @param other The other complex number to compare to.
+   * @returns True if the complex numbers are exactly equal, false otherwise.
+   */
+  [[nodiscard]] bool operator==(const ComplexValue& other) const noexcept;
+
+  /// @see operator==
+  [[nodiscard]] bool operator!=(const ComplexValue& other) const noexcept;
+
+  /**
+   * @brief Check whether the complex number is exactly equal to zero.
+   * @return True if the complex number is exactly equal to zero, false
+   * otherwise.
+   */
+  [[nodiscard]] bool exactlyZero() const noexcept { return r == 0. && i == 0.; }
+
+  /**
+   * @brief Check whether the complex number is exactly equal to one.
+   * @return True if the complex number is exactly equal to one, false
+   * otherwise.
+   */
+  [[nodiscard]] bool exactlyOne() const noexcept { return r == 1. && i == 0.; }
+
+  /**
+   * @brief Check whether the complex number is approximately equal to the
+   * given complex number.
+   * @param c The complex number to compare to.
+   * @returns True if the complex number is approximately equal to the given
+   * complex number, false otherwise.
+   * @see RealNumber::approximatelyEquals
+   */
+  [[nodiscard]] bool approximatelyEquals(const ComplexValue& c) const noexcept;
+
+  /**
+   * @brief Check whether the complex number is approximately equal to zero.
+   * @returns True if the complex number is approximately equal to zero, false
+   * otherwise.
+   * @see RealNumber::approximatelyZero
+   */
+  [[nodiscard]] bool approximatelyZero() const noexcept;
+
+  /**
+   * @brief Write a binary representation of the complex number to the given
+   * output stream.
+   * @param os The output stream to write to.
+   */
+  void writeBinary(std::ostream& os) const;
+
+  /**
+   * @brief Read a binary representation of the complex number from the given
+   * input stream.
+   * @param is The input stream to read from.
+   */
+  void readBinary(std::istream& is);
+
+  /**
+   * @brief Construct a complex number from a string.
+   * @param realStr The string representation of the real part.
+   * @param imagStr The string representation of the imaginary part.
+   */
+  void fromString(const std::string& realStr, std::string imagStr);
+
+  /**
+   * @brief Get the closest fraction to the given number.
+   * @param x The number to approximate.
+   * @param maxDenominator The maximum denominator to use.
+   * @returns The closest fraction to the given number as a pair of numerator
+   * and denominator.
+   */
+  static std::pair<std::uint64_t, std::uint64_t>
+  getLowestFraction(fp x, std::uint64_t maxDenominator = 1U << 10);
+
+  /**
+   * @brief Pretty print the given real number to the given output stream.
+   * @param os The output stream to write to.
+   * @param num The number to print.
+   * @param imaginary Whether the number is imaginary.
+   */
+  static void printFormatted(std::ostream& os, fp num, bool imaginary = false);
+
+  /**
+   * @brief Print the given complex number to the given output stream.
+   * @param real The real part of the complex number.
+   * @param imag The imaginary part of the complex number.
+   * @param formatted Whether to pretty print the number.
+   * @param precision The precision to use for printing numbers..
+   * @returns The string representation of the complex number.
+   */
+  static std::string toString(const fp& real, const fp& imag,
+                              bool formatted = true, int precision = -1);
+
+  /// Automatically convert to std::complex<fp>
+  explicit operator auto() const noexcept { return std::complex<fp>{r, i}; }
+
+  /**
+   * @brief Compute the squared magnitude of the complex number.
+   * @return The squared magnitude of the complex number.
+   */
+  [[nodiscard]] fp mag2() const noexcept { return (r * r) + (i * i); }
+
+  /**
+   * @brief Compute the magnitude of the complex number.
+   * @return The magnitude of the complex number.
+   */
+  [[nodiscard]] fp mag() const noexcept { return std::hypot(r, i); }
+
+  /// In-place addition of two complex numbers
+  ComplexValue& operator+=(const ComplexValue& rhs) noexcept;
+
+  ComplexValue& operator*=(const fp& real) noexcept;
+};
+
+ComplexValue operator+(const ComplexValue& c1, const ComplexValue& c2);
+ComplexValue operator*(const ComplexValue& c1, fp r);
+ComplexValue operator*(fp r, const ComplexValue& c1);
+ComplexValue operator*(const ComplexValue& c1, const ComplexValue& c2);
+ComplexValue operator/(const ComplexValue& c1, fp r);
+ComplexValue operator/(const ComplexValue& c1, const ComplexValue& c2);
+
+/**
+ * @brief Print a complex value to the given output stream.
+ * @param os The output stream to write to.
+ * @param c The complex value to print.
+ * @returns The output stream.
+ */
+std::ostream& operator<<(std::ostream& os, const ComplexValue& c);
+} // namespace dd
+
+/// Hash function for complex values
+template <> struct std::hash<dd::ComplexValue> {
+  /**
+   * @brief Compute the hash value for the given complex value.
+   * @details The hash value is computed by scaling the real and imaginary part
+   * by the tolerance of the complex table, rounding the result to the nearest
+   * integer and computing the hash value of the resulting pair of integers.
+   * @param c The complex value to compute the hash value for.
+   * @returns The hash value for the given complex value.
+   * @note It is rather hard to define good hash functions for floating point
+   * numbers. This hash function is not perfect, but it is fast and should
+   * provide a good distribution of hash values. Furthermore, two floating point
+   * numbers that are within the tolerance of the complex table will always
+   * produce the same hash value.
+   */
+  std::size_t operator()(dd::ComplexValue const& c) const noexcept;
+};

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

@@ -0,0 +1,183 @@
+/*
+ * 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 ComputeTable.hpp
+ * @brief Data structure for caching computed results of binary operations
+ */
+
+#pragma once
+
+#include "dd/Node.hpp"
+#include "dd/statistics/TableStatistics.hpp"
+#include "ir/Definitions.hpp"
+
+#include <cstddef>
+#include <functional>
+#include <iostream>
+#include <stdexcept>
+#include <vector>
+
+namespace dd {
+
+/**
+ * @brief Data structure for caching computed results of binary operations
+ * @tparam LeftOperandType type of the operation's left operand
+ * @tparam RightOperandType type of the operation's right operand
+ * @tparam ResultType type of the operation's result
+ */
+template <class LeftOperandType, class RightOperandType, class ResultType>
+class ComputeTable {
+public:
+  /// Default number of buckets for the compute table
+  static constexpr std::size_t DEFAULT_NUM_BUCKETS = 16384U;
+
+  /**
+   * Default constructor
+   * @param numBuckets Number of hash table buckets. Must be a power of two.
+   */
+  explicit ComputeTable(const size_t numBuckets = DEFAULT_NUM_BUCKETS) {
+    // numBuckets must be a power of two
+    if ((numBuckets & (numBuckets - 1)) != 0) {
+      throw std::invalid_argument("Number of buckets must be a power of two.");
+    }
+    stats.entrySize = sizeof(Entry);
+    stats.numBuckets = numBuckets;
+    valid = std::vector(numBuckets, false);
+    table = std::vector<Entry>(numBuckets);
+  }
+
+  /**
+   * @brief An entry in the compute table
+   * @details A triple consisting of the left operand, the right operand, and
+   * the result of a binary operation.
+   */
+  struct Entry {
+    LeftOperandType leftOperand;
+    RightOperandType rightOperand;
+    ResultType result;
+  };
+
+  /**
+   * @brief Compute the hash value for a given pair of operands
+   * @param leftOperand The left operand
+   * @param rightOperand The right operand
+   * @return The hash value
+   */
+  [[nodiscard]] std::size_t hash(const LeftOperandType& leftOperand,
+                                 const RightOperandType& rightOperand) const {
+    auto h1 = std::hash<LeftOperandType>{}(leftOperand);
+    if constexpr (std::is_same_v<LeftOperandType, dNode*>) {
+      if (!dNode::isTerminal(leftOperand)) {
+        h1 = qc::combineHash(
+            h1, dd::dNode::getDensityMatrixTempFlags(leftOperand->flags));
+      }
+    }
+    auto h2 = std::hash<RightOperandType>{}(rightOperand);
+    if constexpr (std::is_same_v<RightOperandType, dNode*>) {
+      if (!dNode::isTerminal(rightOperand)) {
+        h2 = qc::combineHash(
+            h2, dd::dNode::getDensityMatrixTempFlags(rightOperand->flags));
+      }
+    }
+    const auto hash = qc::combineHash(h1, h2);
+    const auto mask = stats.numBuckets - 1;
+    return hash & mask;
+  }
+
+  /// Get a reference to the underlying table
+  [[nodiscard]] const auto& getTable() const { return table; }
+
+  /// Get a reference to the statistics
+  [[nodiscard]] const auto& getStats() const noexcept { return stats; }
+
+  /**
+   * @brief Insert a new entry into the compute table
+   * @details Any existing entry for the resulting hash value will be replaced.
+   * @param leftOperand The left operand
+   * @param rightOperand The right operand
+   * @param result The result of the operation
+   */
+  void insert(const LeftOperandType& leftOperand,
+              const RightOperandType& rightOperand, const ResultType& result) {
+    const auto key = hash(leftOperand, rightOperand);
+    if (valid[key]) {
+      ++stats.collisions;
+    } else {
+      stats.trackInsert();
+      valid[key] = true;
+    }
+    table[key] = {leftOperand, rightOperand, result};
+  }
+
+  /**
+   * @brief Look up a result in the compute table
+   * @param leftOperand The left operand
+   * @param rightOperand The right operand
+   * @param useDensityMatrix Whether a density matrix is expected
+   * @return A pointer to the result if it is found, otherwise nullptr.
+   */
+  ResultType* lookup(const LeftOperandType& leftOperand,
+                     const RightOperandType& rightOperand,
+                     [[maybe_unused]] const bool useDensityMatrix = false) {
+    ResultType* result = nullptr;
+    ++stats.lookups;
+    const auto key = hash(leftOperand, rightOperand);
+    if (!valid[key]) {
+      return result;
+    }
+
+    auto& entry = table[key];
+    if (entry.leftOperand != leftOperand) {
+      return result;
+    }
+    if (entry.rightOperand != rightOperand) {
+      return result;
+    }
+
+    if constexpr (std::is_same_v<RightOperandType, dNode*> ||
+                  std::is_same_v<RightOperandType, dCachedEdge>) {
+      // Since density matrices are reduced representations of matrices, a
+      // density matrix may not be returned when a matrix is required and vice
+      // versa
+      if (!dNode::isTerminal(entry.result.p) &&
+          dNode::isDensityMatrixNode(entry.result.p->flags) !=
+              useDensityMatrix) {
+        return result;
+      }
+    }
+    ++stats.hits;
+    return &entry.result;
+  }
+
+  /**
+   * @brief Clear the compute table
+   * @details Sets all entries to invalid.
+   */
+  void clear() { valid = std::vector(stats.numBuckets, false); }
+
+  /**
+   * @brief Print the statistics of the compute table
+   * @param os The output stream to print to
+   * @return The output stream
+   */
+  std::ostream& printStatistics(std::ostream& os = std::cout) const {
+    return os << stats;
+  }
+
+private:
+  /// The actual table storing the entries
+  std::vector<Entry> table;
+  /// Dynamic bitset to mark valid entries
+  std::vector<bool> valid;
+  /// Statistics of the compute table
+  TableStatistics stats{};
+};
+} // namespace dd