mqt-core 3.3.2__cp314-cp314t-macosx_11_0_x86_64.whl

mqt/core/include/mqt-core/zx/Rational.hpp

@@ -0,0 +1,318 @@
+/*
+ * 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
+
+#if defined(GMP)
+#include <boost/multiprecision/gmp.hpp> // IWYU pragma: keep
+using Rational = boost::multiprecision::mpq_rational;
+using BigInt = boost::multiprecision::mpz_int;
+#else
+#include <boost/multiprecision/cpp_int.hpp> // IWYU pragma: keep
+#include <boost/multiprecision/fwd.hpp>
+using Rational = boost::multiprecision::cpp_rational;
+using BigInt = boost::multiprecision::cpp_int;
+#endif
+
+#include <boost/multiprecision/rational_adaptor.hpp>
+#include <cmath>
+#include <cstdint>
+#include <cstdlib>
+#include <iostream>
+
+namespace zx {
+
+/*
+ * @brief Representation of fractions as multiples of pi
+ * @details Rationals can only have values in the half-open interval (-1,1],
+ * corresponding to the interval (-pi, pi]
+ */
+class PiRational {
+public:
+  /**
+   * @brief Default constructor initializes the rational to 0/1.
+   */
+  PiRational() = default;
+
+  /**
+   * @brief Construct a PiRational from numerator and denominator.
+   * @details The input fraction is already assumed to be in multiples of Pi.
+   * For example, the fraction 1/2 corresponds to Pi/2.
+   * @param num Numerator of the fraction.
+   * @param denom Denominator of the fraction.
+   */
+  explicit PiRational(int64_t num, int64_t denom) : frac(num, denom) {
+    modPi();
+  }
+  explicit PiRational(const BigInt& num, const BigInt& denom)
+      : frac(num, denom) {
+    modPi();
+  }
+
+  /**
+   * @brief Construct a PiRational from numerator. Denominator is assumed to
+   * be 1.
+   * @details The input numerator is already assumed to be in multiples of Pi.
+   * For example a numerator of 1 corresponds to a fraction Pi/1.
+   * @param num Numerator of the fraction.
+   */
+  explicit PiRational(int64_t num) : frac(num, 1) { modPi(); }
+
+  /**
+   * @brief Construct a PiRational from a double.
+   * @details The input double is approximated as a fraction of Pi within a
+   * tolerance of 1e-13.
+   * @param val Double value to be approximated.
+   */
+  explicit PiRational(double val);
+
+  PiRational& operator+=(const PiRational& rhs);
+  PiRational& operator+=(int64_t rhs);
+
+  PiRational& operator-=(const PiRational& rhs);
+  PiRational& operator-=(int64_t rhs);
+
+  PiRational& operator*=(const PiRational& rhs);
+  PiRational& operator*=(int64_t rhs);
+
+  PiRational& operator/=(const PiRational& rhs);
+  PiRational& operator/=(int64_t rhs);
+
+  /**
+   * @brief Check if the fraction is an integer, i.e., the denominator is 1.
+   * @return True if the fraction is an integer, false otherwise.
+   */
+  [[nodiscard]] bool isInteger() const {
+    return boost::multiprecision::denominator(frac) == 1;
+  }
+
+  /**
+   * @brief Check if the fraction is zero, i,e, the numerator is 0.
+   * @return True if the fraction is zero, false otherwise.
+   */
+  [[nodiscard]] bool isZero() const {
+    return boost::multiprecision::numerator(frac) == 0;
+  }
+
+  /**
+   * @brief Get the denominator of the fraction.
+   * @return Denominator of the fraction.
+   */
+  [[nodiscard]] BigInt getDenom() const {
+    return boost::multiprecision::denominator(frac);
+  }
+
+  /**
+   * @brief Get the numerator of the fraction.
+   * @return Numerator of the fraction.
+   */
+  [[nodiscard]] BigInt getNum() const {
+    return boost::multiprecision::numerator(frac);
+  }
+
+  /**
+   * @brief Convert the fraction to a double.
+   * @details The result is not taken mod Pi. Converting 1/1 will return an
+   * approximation of Pi.
+   * @return Double value of the fraction.
+   */
+  [[nodiscard]] double toDouble() const;
+
+  /**
+   * @brief Convert the fraction to a double mod Pi.
+   * @details The result is taken mod Pi. Converting 1/1 will return 1.0.
+   * @return Double value of the fraction.
+   */
+  [[nodiscard]] double toDoubleDivPi() const {
+    return frac.convert_to<double>();
+  }
+
+  /**
+   * @brief Check if the fraction is close to a double value within a tolerance.
+   * @details The comparison is not done mod Pi. So if the fraction is 1/1
+   * isClose(1.0, 1e-13) will return true.
+   * @param x Double value to compare to.
+   * @param tolerance Tolerance for the comparison.
+   * @return True if the fraction is close to the double value, false otherwise.
+   */
+  [[nodiscard]] bool isClose(const double x, const double tolerance) const {
+    return std::abs(toDouble() - x) < tolerance;
+  }
+
+  /**
+   * @brief Check if the fraction is close to a double value within a tolerance
+   * mod Pi.
+   * @details The comparison is done mod Pi. So if the fraction is 1/1
+   * isCloseDivPi(1.0, 1e-13) will return false, but isCloseDivPi(3.14159,
+   * 1e-14) will return true.
+   * @param x Double value to compare to.
+   * @param tolerance Tolerance for the comparison.
+   * @return True if the fraction is close to the double value divided by Pi,
+   * false otherwise.
+   */
+  [[nodiscard]] bool isCloseDivPi(const double x,
+                                  const double tolerance) const {
+    return std::abs(toDoubleDivPi() - x) < tolerance;
+  }
+
+  /**
+   * @brief Get the double value of the fraction.
+   * @details The result is not taken mod Pi. Converting 1/1 will return 1.0.
+   * @return Double value of the fraction.
+   */
+  explicit operator double() const { return this->toDouble(); }
+
+private:
+  Rational frac;
+
+  void modPi();
+
+  void setNum(const BigInt& num) {
+    boost::multiprecision::numerator(frac) = num;
+  }
+
+  void setDenom(const BigInt& denom) const {
+    boost::multiprecision::denominator(frac) = denom;
+  }
+};
+
+inline PiRational operator-(const PiRational& rhs) {
+  return PiRational(-rhs.getNum(), rhs.getDenom());
+}
+inline PiRational operator+(PiRational lhs, const PiRational& rhs) {
+  lhs += rhs;
+  return lhs;
+}
+inline PiRational operator+(PiRational lhs, const int64_t rhs) {
+  lhs += rhs;
+  return lhs;
+}
+inline PiRational operator+(const int64_t lhs, PiRational rhs) {
+  rhs += lhs;
+  return rhs;
+}
+
+inline PiRational operator-(PiRational lhs, const PiRational& rhs) {
+  lhs -= rhs;
+  return lhs;
+}
+inline PiRational operator-(PiRational lhs, const int64_t rhs) {
+  lhs -= rhs;
+  return lhs;
+}
+inline PiRational operator-(const int64_t lhs, PiRational rhs) {
+  rhs -= lhs;
+  return rhs;
+}
+
+inline PiRational operator*(PiRational lhs, const PiRational& rhs) {
+  lhs *= rhs;
+  return lhs;
+}
+inline PiRational operator*(PiRational lhs, const int64_t rhs) {
+  lhs *= rhs;
+  return lhs;
+}
+inline PiRational operator*(const int64_t lhs, PiRational rhs) {
+  rhs *= lhs;
+  return rhs;
+}
+
+inline PiRational operator/(PiRational lhs, const PiRational& rhs) {
+  lhs /= rhs;
+  return lhs;
+}
+inline PiRational operator/(PiRational lhs, const int64_t rhs) {
+  lhs /= rhs;
+  return lhs;
+}
+inline PiRational operator/(const int64_t lhs, PiRational rhs) {
+  rhs /= lhs;
+  return rhs;
+}
+
+inline bool operator<(const PiRational& lhs, const PiRational& rhs) {
+  return (lhs.getNum() * rhs.getDenom()) < (rhs.getNum() * lhs.getDenom());
+}
+
+inline bool operator<(const PiRational& lhs, const int64_t rhs) {
+  return lhs.getNum() < (rhs * lhs.getDenom());
+}
+
+inline bool operator<(const int64_t lhs, const PiRational& rhs) {
+  return (lhs * rhs.getDenom()) < rhs.getNum();
+}
+
+inline bool operator<=(const PiRational& lhs, const PiRational& rhs) {
+  return (lhs.getNum() * rhs.getDenom()) <= (rhs.getNum() * lhs.getDenom());
+}
+
+inline bool operator<=(const PiRational& lhs, const int64_t rhs) {
+  return lhs.getNum() <= (rhs * lhs.getDenom());
+}
+
+inline bool operator<=(const int64_t lhs, const PiRational& rhs) {
+  return (lhs * rhs.getDenom()) <= rhs.getNum();
+}
+
+inline bool operator>(const PiRational& lhs, const PiRational& rhs) {
+  return rhs < lhs;
+}
+
+inline bool operator>(const PiRational& lhs, const int64_t rhs) {
+  return rhs < lhs;
+}
+
+inline bool operator>(const int64_t lhs, const PiRational& rhs) {
+  return rhs < lhs;
+}
+
+inline bool operator>=(const PiRational& lhs, const PiRational& rhs) {
+  return rhs <= lhs;
+}
+
+inline bool operator>=(const PiRational& lhs, const int64_t rhs) {
+  return rhs <= lhs;
+}
+
+inline bool operator>=(const int64_t lhs, const PiRational& rhs) {
+  return rhs <= lhs;
+}
+
+inline bool operator==(const PiRational& lhs, const PiRational& rhs) {
+  return lhs.getNum() == rhs.getNum() && lhs.getDenom() == rhs.getDenom();
+}
+
+inline bool operator==(const PiRational& lhs, const int64_t rhs) {
+  return lhs.getNum() == rhs && lhs.getDenom() == 1;
+}
+
+inline bool operator==(const int64_t lhs, const PiRational& rhs) {
+  return rhs == lhs;
+}
+
+inline bool operator!=(const PiRational& lhs, const PiRational& rhs) {
+  return !(lhs == rhs);
+}
+
+inline bool operator!=(const PiRational& lhs, const int64_t rhs) {
+  return !(lhs == rhs);
+}
+
+inline bool operator!=(const int64_t lhs, const PiRational& rhs) {
+  return !(lhs == rhs);
+}
+
+inline std::ostream& operator<<(std::ostream& os, const zx::PiRational& rhs) {
+  os << rhs.getNum() << "/" << rhs.getDenom();
+  return os;
+}
+
+} // namespace zx

mqt/core/include/mqt-core/zx/Rules.hpp

@@ -0,0 +1,132 @@
+/*
+ * 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 "ZXDefinitions.hpp"
+
+namespace zx {
+class ZXDiagram;
+
+/**
+ * @brief Check whether the spider has exactly two incident edges and a phase of
+ * 0.
+ * @param diag The diagram.
+ * @param v The vertex to check.
+ * @return True if the spider has exactly two incident edges and a phase of 0.
+ */
+
+bool checkIdSimp(const ZXDiagram& diag, Vertex v);
+
+/**
+ * @brief Remove spider from the diagram. checkIdSimp() should yield true.
+ * @details The spider is removed by connecting its incident edges.
+ */
+void removeId(ZXDiagram& diag, Vertex v);
+
+/**
+ * @brief Check whether two spiders can be fused.
+ * @details See https://arxiv.org/abs/2012.13966, page 27, rule (f).
+ * @param diag The diagram.
+ * @param v0 The first spider.
+ * @param v1 The second spider.
+ * @return True if the spiders can be fused.
+ */
+bool checkSpiderFusion(const ZXDiagram& diag, Vertex v0, Vertex v1);
+
+/**
+ * @brief Fuse two spiders. checkSpiderFusion() should yield true.
+ * @details The spiders are fused by connecting their incident edges.
+ */
+void fuseSpiders(ZXDiagram& diag, Vertex v0, Vertex v1);
+
+/**
+ * @brief Check if the local complementation rule can be applied to the given
+ * spider.
+ * @details See https://arxiv.org/abs/2012.13966, equation (102).
+ * @param diag The diagram.
+ * @param v The spider.
+ * @return True if the local complementation rule can be applied.
+ */
+bool checkLocalComp(const ZXDiagram& diag, Vertex v);
+
+/**
+ * @brief Apply the local complementation rule to the given spider.
+ * checkLocalComp() should yield true.
+ * @details See https://arxiv.org/abs/2012.13966, equation (102).
+ */
+void localComp(ZXDiagram& diag, Vertex v);
+
+/**
+ * @brief Check if the pivot rule can be applied to the given interior spiders.
+ * @details See https://arxiv.org/abs/2012.13966, equation (103).
+ * @param diag The diagram.
+ * @param v0 The first spider.
+ * @param v1 The second spider.
+ * @return True if the pivot rule can be applied.
+ */
+bool checkPivotPauli(const ZXDiagram& diag, Vertex v0, Vertex v1);
+
+/**
+ * @brief Apply the pivot rule to the given interior spiders. checkPivotPauli()
+ * should yield true.
+ * @details See https://arxiv.org/abs/2012.13966, equation (103).
+ */
+void pivotPauli(ZXDiagram& diag, Vertex v0, Vertex v1);
+
+/**
+ * @brief Check if the pivot rule can be applied. Spiders can be connected to
+ * boundaries.
+ * @param diag The diagram.
+ * @param v0 The first spider.
+ * @param v1 The second spider.
+ * @return True if the pivot rule can be applied.
+ */
+bool checkPivot(const ZXDiagram& diag, Vertex v0, Vertex v1);
+
+/**
+ * @brief Apply the pivot rule. Spiders can be connected to boundaries.
+ * checkPivot() should yield true.
+ */
+void pivot(ZXDiagram& diag, Vertex v0, Vertex v1);
+
+/**
+ * @brief Check if the gadget pivot rule can be applied. Spiders can be
+ * connected to boundaries.
+ * @details See https://arxiv.org/abs/1903.10477, page 13
+ * rule (P2) and (P3) for details.
+ * @param diag The diagram.
+ * @param v0 The first spider.
+ * @param v1 The second spider.
+ * @return True if the gadget pivot rule can be applied.
+ */
+bool checkPivotGadget(const ZXDiagram& diag, Vertex v0, Vertex v1);
+
+/**
+ * @brief Apply the gadget pivot rule. Spiders can be connected to boundaries.
+ * checkPivotGadget() should yield true.
+ * @details See https://arxiv.org/abs/1903.10477, page 13
+ * rule (P2) and (P3) for details.
+ */
+void pivotGadget(ZXDiagram& diag, Vertex v0, Vertex v1);
+
+/**
+ * @brief Check if a gadget can be fused with its connected spider and fuse if
+ * true.
+ * @details Unlike other rules, this function performs the check and
+ * modification in one step. This is for performance reasons, since the overhead
+ * for the check is significant and otherwise intermediate results would have to
+ * be computed twice. See https://arxiv.org/abs/1903.10477, page 13, rule (ID).
+ * @param diag The diagram.
+ * @param v The spider.
+ * @return True if the gadget can be fused with its connected spider.
+ */
+bool checkAndFuseGadget(ZXDiagram& diag, Vertex v);
+} // namespace zx

mqt/core/include/mqt-core/zx/Simplify.hpp

@@ -0,0 +1,182 @@
+/*
+ * 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 "Rules.hpp"
+#include "ZXDefinitions.hpp"
+#include "ZXDiagram.hpp"
+
+#include <cstddef>
+
+namespace zx {
+
+/**
+ * @brief Simplify the diagram by applying the given rule to all vertices that
+ * match the given check.
+ * @tparam VertexCheckFun Type of the check function
+ * @tparam VertexRuleFun Type of the rule function
+ * @param diag The diagram to simplify
+ * @param check The check function that determines if a vertex should be
+ * simplified
+ * @param rule The rule function that is applied to the vertex
+ * @return The number of simplifications that were applied
+ */
+template <class VertexCheckFun, class VertexRuleFun>
+std::size_t simplifyVertices(ZXDiagram& diag, VertexCheckFun check,
+                             VertexRuleFun rule) {
+  std::size_t nSimplifications = 0;
+  bool newMatches = true;
+
+  while (newMatches) {
+    newMatches = false;
+    for (const auto& [v, _] : diag.getVertices()) {
+      if (check(diag, v)) {
+        rule(diag, v);
+        newMatches = true;
+        nSimplifications++;
+      }
+    }
+  }
+
+  return nSimplifications;
+}
+
+/**
+ * @brief Simplify the diagram by applying the given rule to all edges that
+ * match the given check.
+ * @tparam EdgeCheckFun Type of the check function
+ * @tparam EdgeRuleFun Type of the rule function
+ * @param diag The diagram to simplify
+ * @param check The check function that determines if an edge should be
+ * simplified
+ * @param rule The rule function that is applied to the edge
+ * @return The number of simplifications that were applied
+ */
+template <class EdgeCheckFun, class EdgeRuleFun>
+std::size_t simplifyEdges(ZXDiagram& diag, EdgeCheckFun check,
+                          EdgeRuleFun rule) {
+  std::size_t nSimplifications = 0;
+  bool newMatches = true;
+
+  while (newMatches) {
+    newMatches = false;
+    for (const auto& [v0, v1] : diag.getEdges()) {
+      if (diag.isDeleted(v0) || diag.isDeleted(v1) || !check(diag, v0, v1)) {
+        continue;
+      }
+      rule(diag, v0, v1);
+      newMatches = true;
+      nSimplifications++;
+    }
+  }
+
+  return nSimplifications;
+}
+
+std::size_t gadgetSimp(ZXDiagram& diag);
+
+/**
+ * @brief Apply the identity rule to the Diagram until exhaustion.
+ * @details A spider with exactly two incident edges and a phase of 0 is
+ * removed. See https://arxiv.org/abs/2012.13966 page 27, rule (id).
+ * @param diag The diagram to simplify
+ * @return The number of simplifications that were applied
+ */
+
+std::size_t idSimp(ZXDiagram& diag);
+
+/**
+ * @brief Apply the spider rule to the Diagram until exhaustion.
+ * @details Spiders of the same type connected by a regular edge can be turned
+ * into one
+ * by adding both phases and fusing all incident edges.
+ * See https://arxiv.org/abs/2012.13966 page 27, rule (f).
+ * @param diag The diagram to simplify
+ * @return The number of simplifications that were applied
+ */
+std::size_t spiderSimp(ZXDiagram& diag);
+
+/**
+ * @brief Apply the local complementation rule to the Diagram until exhaustion.
+ * @details See https://arxiv.org/abs/2012.13966 equation (102).
+ * @param diag The diagram to simplify
+ * @return The number of simplifications that were applied
+ */
+std::size_t localCompSimp(ZXDiagram& diag);
+
+/**
+ * @brief Simplify the diagram by applying the pivot rule.
+ * @details See https://arxiv.org/abs/2012.13966, equation 103 for details.
+ * Similar to the Pauli pivot rule but can be applied to vertices connectedto
+ * the boundary.
+ * @param diag The diagram to simplify.
+ * @return The number of simplifications applied.
+ */
+std::size_t pivotSimp(ZXDiagram& diag);
+
+/**
+ * Simplify the diagram by applying the pivot rule in the case that the pivot
+ * spiders have phases of Pi. See https://arxiv.org/abs/2012.13966, equation 103
+ * for details.
+ * @param diag The diagram to simplify.
+ * @return The number of simplifications applied.
+ */
+std::size_t pivotPauliSimp(ZXDiagram& diag);
+
+/**
+ * @brief Simplify all internal vertices and edges of the diagram using Clifford
+ * simplifications.
+ * @details This function applies the id, spider, local complementation,
+ * and Pauli pivot rules.
+ * @param diag The diagram to simplify.
+ * @return The number of simplifications applied.
+ */
+std::size_t interiorCliffordSimp(ZXDiagram& diag);
+
+/*
+ * @brief Simplify the diagram using Clifford simplifications.
+ * @details In addition to interior Clifford simplifications, this function also
+ * applies the regular pivot rule.
+ * @param diag The diagram to simplify.
+ * @return The number of simplifications applied.
+ */
+std::size_t cliffordSimp(ZXDiagram& diag);
+
+/**
+ * @brief Simplify the diagram by applying the pivot rule to non-Pauli spider.
+ * @details By extracting the phases into extra "gadgets", the pivot rule can be
+ * applies to non-Pauli spiders. See https://arxiv.org/abs/1903.10477, page 13
+ * rule (P2) and (P3) for details.
+ * @param diag The diagram to simplify.
+ * @return The number of simplifications applied.
+ */
+std::size_t pivotgadgetSimp(ZXDiagram& diag);
+
+/**
+ * @brief Simplify the diagram by applying Clifford simplifications and the
+ * gadget pivot rule.
+ * @details In addition to the Clifford simplification, this function also
+ * applies the pivot gadget rule.
+ * @param diag The diagram to simplify.
+ * @return The number of simplifications applied.
+ */
+std::size_t fullReduce(ZXDiagram& diag);
+
+/**
+ * @brief Apply full reduction to the diagram. Rounds phases to nearest multiple
+ * of Pi/2 during simplification.
+ * @param diag The diagram to simplify.
+ * @param tolerance The tolerance for rounding phases to multiples of Pi/2.
+ * @return The number of simplifications applied
+ */
+std::size_t fullReduceApproximate(ZXDiagram& diag, fp tolerance);
+
+} // namespace zx