mqt-core 3.1.0__cp313-cp313-win_arm64.whl

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

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

@@ -0,0 +1,139 @@
+/*
+ * 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 "ir/Definitions.hpp"
+
+#include <array>
+#include <cmath>
+#include <complex>
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <type_traits>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+namespace dd {
+/**
+ * @brief Integer type used for indexing qubits
+ * @details `std::uint16_t` can address up to 65536 qubits as [0, ..., 65535].
+ * @note If you need even more qubits, this can be increased to `std::uint32_t`.
+ * Beware of the increased memory footprint of matrix nodes.
+ */
+using Qubit = std::uint16_t;
+
+/**
+ * @brief Floating point type to use for computations
+ * @note Adjusting the precision might lead to unexpected results.
+ */
+using fp = double;
+static_assert(
+    std::is_floating_point_v<fp>,
+    "fp should be a floating point type (float, *double*, long double)");
+
+// logic radix
+static constexpr std::uint8_t RADIX = 2;
+// max no. of edges = RADIX^2
+static constexpr std::uint8_t NEDGE = RADIX * RADIX;
+
+enum class BasisStates : std::uint8_t {
+  zero,  // NOLINT(readability-identifier-naming)
+  one,   // NOLINT(readability-identifier-naming)
+  plus,  // NOLINT(readability-identifier-naming)
+  minus, // NOLINT(readability-identifier-naming)
+  right, // NOLINT(readability-identifier-naming)
+  left   // NOLINT(readability-identifier-naming)
+};
+
+static constexpr fp SQRT2_2 = static_cast<fp>(
+    0.707106781186547524400844362104849039284835937688474036588L);
+static constexpr fp PI = static_cast<fp>(
+    3.141592653589793238462643383279502884197169399375105820974L);
+static constexpr fp PI_2 = static_cast<fp>(
+    1.570796326794896619231321691639751442098584699687552910487L);
+static constexpr fp PI_4 = static_cast<fp>(
+    0.785398163397448309615660845819875721049292349843776455243L);
+
+static constexpr std::uint64_t SERIALIZATION_VERSION = 1;
+
+struct PairHash {
+  std::size_t
+  operator()(const std::pair<std::size_t, std::size_t>& p) const noexcept {
+    return qc::combineHash(p.first, p.second);
+  }
+};
+
+using CVec = std::vector<std::complex<fp>>;
+using SparseCVec = std::unordered_map<std::size_t, std::complex<fp>>;
+using SparsePVec = std::unordered_map<std::size_t, fp>;
+using SparsePVecStrKeys = std::unordered_map<std::string, fp>;
+using CMat = std::vector<CVec>;
+using SparseCMat = std::unordered_map<std::pair<std::size_t, std::size_t>,
+                                      std::complex<fp>, PairHash>;
+
+using GateMatrix = std::array<std::complex<fp>, NEDGE>;
+using TwoQubitGateMatrix =
+    std::array<std::array<std::complex<fp>, NEDGE>, NEDGE>;
+
+/**
+ * @brief Converts a decimal number to a binary string (big endian)
+ * @param value The decimal number to convert
+ * @param nbits The number of bits to use for the binary representation
+ * @return The binary representation of the decimal number
+ */
+[[nodiscard]] static inline std::string
+intToBinaryString(const std::size_t value, const std::size_t nbits) {
+  std::string binary(nbits, '0');
+  for (std::size_t j = 0; j < nbits; ++j) {
+    if ((value & (1ULL << j)) != 0U) {
+      binary[nbits - 1 - j] = '1';
+    }
+  }
+  return binary;
+}
+
+// calculates the Units in Last Place (ULP) distance of two floating point
+// numbers
+[[maybe_unused]] static std::size_t ulpDistance(fp a, fp b) {
+  // NOLINTNEXTLINE(clang-diagnostic-float-equal)
+  if (a == b) {
+    return 0;
+  }
+
+  std::size_t ulps = 1;
+  fp nextFP = std::nextafter(a, b);
+  // NOLINTNEXTLINE(clang-diagnostic-float-equal)
+  while (nextFP != b) {
+    ulps++;
+    nextFP = std::nextafter(nextFP, b);
+  }
+  return ulps;
+}
+
+/**
+ * @brief 64bit mixing hash (from MurmurHash3)
+ * @details Hash function for 64bit integers adapted from MurmurHash3
+ * @param k the number to hash
+ * @returns the hash value
+ * @see https://github.com/aappleby/smhasher/blob/master/src/MurmurHash3.cpp
+ */
+[[nodiscard]] constexpr std::size_t murmur64(std::size_t k) noexcept {
+  k ^= k >> 33;
+  k *= 0xff51afd7ed558ccdULL;
+  k ^= k >> 33;
+  k *= 0xc4ceb9fe1a85ec53ULL;
+  k ^= k >> 33;
+  return k;
+}
+
+} // namespace dd