🚸♻️ improved verify functions (#117)

- `verify` function refactored from C++ binding function to Python function in analogy to `verify_compilation_flow`
- allow to pass keyword arguments to `verify` functions instead of configuration object

Author: burgholzer

Diff for: mqt/qcec/__init__.py

@@ -10,8 +10,8 @@
     EquivalenceCheckingManager,
     EquivalenceCriterion,
     StateType,
-    verify,
 )
+from mqt.qcec.verify import verify
 from mqt.qcec.verify_compilation_flow import verify_compilation
 
 __all__ = [

Diff for: mqt/qcec/bindings.cpp

@@ -149,14 +149,6 @@ static std::unique_ptr<EquivalenceCheckingManager> createManagerFromOptions(
   return createManagerFromConfiguration(circ1, circ2, configuration);
 }
 
-static ec::EquivalenceCheckingManager::Results
-verify(const py::object& circ1, const py::object& circ2,
-       const Configuration& configuration = Configuration()) {
-  const auto ecm = createManagerFromConfiguration(circ1, circ2, configuration);
-  ecm->run();
-  return ecm->getResults();
-}
-
 PYBIND11_MODULE(pyqcec, m) {
   m.doc() = "Python interface for the MQT QCEC quantum circuit equivalence "
             "checking tool";
@@ -731,14 +723,6 @@ PYBIND11_MODULE(pyqcec, m) {
           "exponentially, this is only recommended for a small number of "
           "qubits and defaults to :code:`False`.");
 
-  m.def("verify", &verify, "circ1"_a, "circ2"_a,
-        "config"_a = ec::Configuration{},
-        "Convenience function for verifying the equivalence of two circuits. "
-        "Wraps creating an instance of :class:`EquivalenceCheckingManager "
-        "<.EquivalenceCheckingManager>`, calling "
-        ":meth:`EquivalenceCheckingManager.run` and calling "
-        ":meth:`EquivalenceCheckingManager.get_result`.");
-
 #ifdef VERSION_INFO
   m.attr("__version__") = MACRO_STRINGIFY(VERSION_INFO);
 #else

Diff for: mqt/qcec/verify.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any
+
+from mqt.qcec import Configuration, EquivalenceCheckingManager
+from qiskit import QuantumCircuit
+
+
+def verify(
+    circ1: QuantumCircuit | str, circ2: QuantumCircuit | str, configuration: Configuration | None = None, **kwargs: Any
+) -> EquivalenceCheckingManager.Results:
+    """
+    Verify that ``circ1`` and ``circ2`` are equivalent.
+    Wraps creating an instance of :class:`EquivalenceCheckingManager <.EquivalenceCheckingManager>`,
+    calling :meth:`EquivalenceCheckingManager.run`,
+    and calling :meth:`EquivalenceCheckingManager.get_result`.
+    If ``configuration`` is not ``None``, it is used to configure the ``EquivalenceCheckingManager``.
+    """
+
+    if kwargs:
+        # create the equivalence checker from keyword arguments
+        ecm = EquivalenceCheckingManager(circ1, circ2, **kwargs)
+    else:
+        if configuration is None:
+            configuration = Configuration()
+
+        # create the equivalence checker from configuration
+        ecm = EquivalenceCheckingManager(circ1, circ2, configuration)
+
+    # execute the check
+    ecm.run()
+
+    # obtain the result
+    return ecm.get_results()

Diff for: mqt/qcec/verify_compilation_flow.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import sys
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING or sys.version_info < (3, 9, 0):
     import importlib_resources as resources
@@ -19,17 +19,22 @@ def verify_compilation(
     optimization_level: int = 1,
     ancilla_mode: AncillaMode = AncillaMode.NO_ANCILLA,
     configuration: Configuration | None = None,
+    **kwargs: Any,
 ) -> EquivalenceCheckingManager.Results:
     """
     Verify that the ``compiled_circuit`` (compiled with a certain ``optimization_level`` amd ``ancilla_mode``) is equivalent to the ``original_circuit``.
     If ``configuration`` is not ``None``, it is used to configure the ``EquivalenceCheckingManager``.
     """
 
-    if configuration is None:
-        configuration = Configuration()
+    if kwargs:
+        # create the equivalence checker from keyword arguments
+        ecm = EquivalenceCheckingManager(original_circuit, compiled_circuit, **kwargs)
+    else:
+        if configuration is None:
+            configuration = Configuration()
 
-    # create the equivalence checker
-    ecm = EquivalenceCheckingManager(original_circuit, compiled_circuit, configuration)
+        # create the equivalence checker from configuration
+        ecm = EquivalenceCheckingManager(original_circuit, compiled_circuit, configuration)
 
     # use the gate_cost scheme for the verification
     ecm.set_application_scheme("gate_cost")

Diff for: test/python/test_verify.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import pytest
+from mqt import qcec
+from qiskit import QuantumCircuit
+
+
+@pytest.fixture
+def original_circuit() -> QuantumCircuit:
+    qc = QuantumCircuit(3)
+    qc.h(0)
+    qc.cx(0, 1)
+    qc.cx(0, 2)
+    qc.measure_all()
+    return qc
+
+
+@pytest.fixture
+def alternative_circuit() -> QuantumCircuit:
+    qc = QuantumCircuit(3, 3)
+    qc.h(0)
+    qc.cx(0, 1)
+    qc.swap(0, 1)
+    qc.cx(1, 2)
+    qc.measure(0, 1)
+    qc.measure(1, 0)
+    qc.measure(2, 2)
+    return qc
+
+
+def test_verify(original_circuit: QuantumCircuit, alternative_circuit: QuantumCircuit) -> None:
+    """
+    Test the verification of two equivalent circuits.
+    """
+    result = qcec.verify(original_circuit, alternative_circuit)
+    assert result.equivalence == qcec.EquivalenceCriterion.equivalent

Diff for: test/python/test_verify_compilation.py

@@ -6,14 +6,6 @@
 from qiskit.providers.fake_provider import FakeAthens
 
 
-def get_circuits(qc: QuantumCircuit, optimization_level: int = 1) -> tuple[QuantumCircuit, QuantumCircuit]:
-    """
-    Compile the circuit ``qc`` to the 5-qubit IBMQ Athens architecture.
-    """
-    qc_comp = transpile(qc, backend=FakeAthens(), optimization_level=optimization_level)
-    return qc, qc_comp
-
-
 @pytest.fixture
 def original_circuit() -> QuantumCircuit:
     qc = QuantumCircuit(3)