✨ Expose approximate equivalence checking to Python

Author: TeWas

include/EquivalenceCheckingManager.hpp

@@ -219,10 +219,16 @@ class EquivalenceCheckingManager {
   void setTraceThreshold(double traceThreshold) {
     configuration.functionality.traceThreshold = traceThreshold;
   }
+  void setApproximateCheckingThreshold(double approximateCheckingThreshold) {
+    configuration.functionality.approximateCheckingThreshold =
+        approximateCheckingThreshold;
+  }
   void setCheckPartialEquivalence(bool checkPE) {
     configuration.functionality.checkPartialEquivalence = checkPE;
   }
-
+  void setCheckApproximateEquivalence(bool checkAE) {
+    configuration.functionality.checkApproximateEquivalence = checkAE;
+  }
   // Simulation: These setting may be changed to adjust the kinds of simulations
   // that are performed
   void setFidelityThreshold(double fidelityThreshold) {

src/Configuration.cpp

@@ -106,7 +106,11 @@ nlohmann::basic_json<> Configuration::json() const {
   if (execution.runConstructionChecker || execution.runAlternatingChecker) {
     auto& fun = config["functionality"];
     fun["trace_threshold"] = functionality.traceThreshold;
+    fun["approximate_checking_threshold"] =
+        functionality.approximateCheckingThreshold;
     fun["check_partial_equivalence"] = functionality.checkPartialEquivalence;
+    fun["check_approximate_equivalence"] =
+        functionality.checkApproximateEquivalence;
   }
 
   if (execution.runSimulationChecker) {

src/mqt/qcec/configuration.py

@@ -32,7 +32,9 @@ class ConfigurationOptions(TypedDict, total=False):
     timeout: float
     # Functionality
     trace_threshold: float
+    approximate_checking_threshold: float
     check_partial_equivalence: bool
+    check_approximate_equivalence: bool
     # Optimizations
     backpropagate_output_permutation: bool
     elide_permutations: bool

src/mqt/qcec/pyqcec.pyi

@@ -48,7 +48,9 @@ class Configuration:
 
     class Functionality:
         trace_threshold: float
+        approximate_checking_threshold: float
         check_partial_equivalence: bool
+        check_approximate_equivalence: bool
         def __init__(self) -> None: ...
 
     class Optimizations:
@@ -144,7 +146,9 @@ class EquivalenceCheckingManager:
     def set_timeout(self, timeout: float = ...) -> None: ...
     def set_tolerance(self, tolerance: float = ...) -> None: ...
     def set_trace_threshold(self, threshold: float = ...) -> None: ...
+    def set_approximate_checking_threshold(self, threshold: float = ...) -> None: ...
     def set_check_partial_equivalence(self, enable: bool = ...) -> None: ...
+    def set_check_approximate_equivalence(self, enable: bool = ...) -> None: ...
     def set_zx_checker(self, enable: bool = ...) -> None: ...
     def store_cex_input(self, enable: bool = ...) -> None: ...
     def store_cex_output(self, enable: bool = ...) -> None: ...

src/python/bindings.cpp

@@ -322,6 +322,12 @@ PYBIND11_MODULE(pyqcec, m, py::mod_gil_not_used()) {
            "Set the :attr:`trace threshold "
            "<.Configuration.Functionality.trace_threshold>` used for comparing "
            "two unitaries or functionality matrices.")
+      .def("set_approximate_checking_threshold",
+           &EquivalenceCheckingManager::setApproximateCheckingThreshold,
+           "threshold"_a = 1e-8,
+           "Set the :attr:`approximate checking threshold "
+           "<.Configuration.Functionality.approximate_checking_threshold>` "
+           "used for approximate equivalence checking.")
       .def(
           "set_check_partial_equivalence",
           &EquivalenceCheckingManager::setCheckPartialEquivalence,
@@ -331,6 +337,16 @@ PYBIND11_MODULE(pyqcec, m, py::mod_gil_not_used()) {
           "they have the same probability for each measurement outcome. "
           "If set to false, the checker will output 'not equivalent' for "
           "circuits that are partially equivalent but not totally equivalent. ")
+      .def("set_check_approximate_equivalence",
+           &EquivalenceCheckingManager::setCheckApproximateEquivalence,
+           "enable"_a = false,
+           "Set whether to check for approximate equivalence. Two circuits are "
+           "approximately equivalent if the Hilbert-Schmidt inner product "
+           "(process distance) of the two circuits is less than the "
+           "approximate_checking_threshold. "
+           "If set to false, the checker will output 'not equivalent' for "
+           "circuits that are approximately equivalent but not totally "
+           "equivalent. ")
       // Simulation
       .def("set_fidelity_threshold",
            &EquivalenceCheckingManager::setFidelityThreshold,
@@ -668,6 +684,15 @@ PYBIND11_MODULE(pyqcec, m, py::mod_gil_not_used()) {
           "Whenever any decision diagram node differs from this structure by "
           "more than the configured threshold, the circuits are concluded to "
           "be non-equivalent. Defaults to :code:`1e-8`.")
+      .def_readwrite(
+          "approximate_checking_threshold",
+          &Configuration::Functionality::approximateCheckingThreshold,
+          "To determine approximate equivalence, the Hilbert-Schmidt inner "
+          "product (or process distance) between two circuit representations "
+          "is calculated and compared against the "
+          "approximate_checking_threshold. If the process distance falls below "
+          "this threshold, the circuits are considered approximately "
+          "equivalent. Defaults to :code:`1e-8`.")
       .def_readwrite(
           "check_partial_equivalence",
           &Configuration::Functionality::checkPartialEquivalence,
@@ -679,6 +704,21 @@ PYBIND11_MODULE(pyqcec, m, py::mod_gil_not_used()) {
           "output 'not equivalent' for circuits that are partially equivalent "
           "but not totally equivalent. In particular, garbage qubits will be "
           "treated as if they were measured qubits. Defaults to "
+          ":code:`False`.")
+      .def_readwrite(
+          "check_approximate_equivalence",
+          &Configuration::Functionality::checkApproximateEquivalence,
+          "To determine approximate equivalence, the Hilbert-Schmidt inner "
+          "product (or process distance) between two circuit representations "
+          "is calculated and compared against the "
+          "approximate_checking_threshold. If the process distance falls below "
+          "this threshold, the circuits are considered approximately "
+          "equivalent.  If set to :code:`True`, a check for approximate "
+          "equivalence "
+          "will be performed. If set to :code:`False`, the checker will "
+          "output 'not equivalent' for circuits that are approximately "
+          "equivalent "
+          "but not totally equivalent. Defaults to "
           ":code:`False`.");
 
   // simulation options
@@ -752,5 +792,5 @@ PYBIND11_MODULE(pyqcec, m, py::mod_gil_not_used()) {
           "to simpler equivalence checking instances as the random "
           "instantiation. This option "
           "changes how many of those additional checks are performed.");
-}
+};
 } // namespace ec

test/python/test_approximate_equivalence.py

@@ -0,0 +1,56 @@
+"""Tests the partial equivalence checking support of QCEC."""
+
+from __future__ import annotations
+
+import pytest
+from qiskit import QuantumCircuit
+
+from mqt import qcec
+
+
+@pytest.fixture
+def original_circuit() -> QuantumCircuit:
+    """Fixture for a simple circuit."""
+    qc = QuantumCircuit(3)
+    qc.mcx([0, 1], 2)
+    return qc
+
+
+@pytest.fixture
+def alternative_circuit() -> QuantumCircuit:
+    """Fixture for an approximately equivalent version of the simple circuit."""
+    qc = QuantumCircuit(3)
+    qc.id(0)
+    qc.id(1)
+    qc.id(2)
+    return qc
+
+
+def test_configuration_pec(original_circuit: QuantumCircuit, alternative_circuit: QuantumCircuit) -> None:
+    """Test if the flag for approximate equivalence checking works."""
+    config = qcec.Configuration()
+    config.execution.run_alternating_checker = True
+    config.execution.run_construction_checker = False
+    config.execution.run_simulation_checker = False
+    config.execution.run_zx_checker = False
+    config.functionality.check_approximate_equivalence = True
+    config.functionality.approximate_checking_threshold = 0.3
+    result = qcec.verify(original_circuit, alternative_circuit, configuration=config)
+    assert result.equivalence == qcec.EquivalenceCriterion.equivalent
+
+
+def test_argument_pec(original_circuit: QuantumCircuit, alternative_circuit: QuantumCircuit) -> None:
+    """Test if the flag for approximate equivalence checking works."""
+    config = qcec.Configuration()
+    config.execution.run_alternating_checker = True
+    config.execution.run_construction_checker = False
+    config.execution.run_simulation_checker = False
+    config.execution.run_zx_checker = False
+    result = qcec.verify(
+        original_circuit,
+        alternative_circuit,
+        configuration=config,
+        check_approximate_equivalence=True,
+        approximate_checking_threshold=0.3,
+    )
+    assert result.equivalence == qcec.EquivalenceCriterion.equivalent