Add equivalence_library kwarg to circuit_to_{gate,inst} converters. (#4431)

Make gate registration on circuit_to_{gate,inst} conversion opt-in.

Co-authored-by: Ali Javadi-Abhari <ajavadia@users.noreply.github.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

qiskit/converters/circuit_to_gate.py

@@ -20,7 +20,7 @@ from qiskit.circuit.quantumregister import QuantumRegister, Qubit
 from qiskit.exceptions import QiskitError
 
 
-def circuit_to_gate(circuit, parameter_map=None):
+def circuit_to_gate(circuit, parameter_map=None, equivalence_library=None):
     """Build a ``Gate`` object from a ``QuantumCircuit``.
 
     The gate is anonymous (not tied to a named quantum register),
@@ -33,6 +33,8 @@ def circuit_to_gate(circuit, parameter_map=None):
            parameters in the circuit to parameters to be used in the gate.
            If None, existing circuit parameters will also parameterize the
            Gate.
+        equivalence_library (EquivalenceLibrary): Optional equivalence library
+           where the converted gate will be registered.
 
     Raises:
         QiskitError: if circuit is non-unitary or if
@@ -81,10 +83,8 @@ def circuit_to_gate(circuit, parameter_map=None):
 
     target = circuit.assign_parameters(parameter_dict, inplace=False)
 
-    # pylint: disable=cyclic-import
-    from qiskit.circuit.equivalence_library import SessionEquivalenceLibrary as sel
-    # pylint: enable=cyclic-import
-    sel.add_equivalence(gate, target)
+    if equivalence_library is not None:
+        equivalence_library.add_equivalence(gate, target)
 
     definition = target.data
 

qiskit/converters/circuit_to_instruction.py

@@ -20,7 +20,7 @@ from qiskit.circuit.quantumregister import QuantumRegister, Qubit
 from qiskit.circuit.classicalregister import ClassicalRegister
 
 
-def circuit_to_instruction(circuit, parameter_map=None):
+def circuit_to_instruction(circuit, parameter_map=None, equivalence_library=None):
     """Build an ``Instruction`` object from a ``QuantumCircuit``.
 
     The instruction is anonymous (not tied to a named quantum register),
@@ -33,6 +33,8 @@ def circuit_to_instruction(circuit, parameter_map=None):
            parameters in the circuit to parameters to be used in the instruction.
            If None, existing circuit parameters will also parameterize the
            instruction.
+        equivalence_library (EquivalenceLibrary): Optional equivalence library
+           where the converted instruction will be registered.
 
     Raises:
         QiskitError: if parameter_map is not compatible with circuit
@@ -88,10 +90,8 @@ def circuit_to_instruction(circuit, parameter_map=None):
 
     target = circuit.assign_parameters(parameter_dict, inplace=False)
 
-    # pylint: disable=cyclic-import
-    from qiskit.circuit.equivalence_library import SessionEquivalenceLibrary as sel
-    # pylint: enable=cyclic-import
-    sel.add_equivalence(instruction, target)
+    if equivalence_library is not None:
+        equivalence_library.add_equivalence(instruction, target)
 
     definition = target.data
 

releasenotes/notes/converters-equivalence-library-registration-optional-266758d497d82ce3.yaml

@@ -0,0 +1,9 @@
+---
+upgrade:
+  - |
+    The ``circuit_to_gate`` and ``circuit_to_instruction`` converters had
+    previously automatically included the generated gate or instruction in the
+    active ``SessionEquivalenceLibrary``. These converters now accept an
+    optional ``equivalence_library`` keyword argument to specify if and where
+    the converted instances should be registered. The default behavior is not
+    to register the converted instance.

test/python/circuit/test_equivalence.py

@@ -21,6 +21,7 @@ from qiskit.test import QiskitTestCase
 
 from qiskit.circuit import QuantumCircuit, Parameter, Gate
 from qiskit.circuit.exceptions import CircuitError
+from qiskit.converters import circuit_to_instruction, circuit_to_gate
 
 from qiskit.circuit import EquivalenceLibrary
 
@@ -405,15 +406,15 @@ class TestSessionEquivalenceLibrary(QiskitTestCase):
         qc_gate.h(0)
         qc_gate.cx(0, 1)
 
-        bell_gate = qc_gate.to_gate()
+        from qiskit.circuit.equivalence_library import SessionEquivalenceLibrary as sel
+        bell_gate = circuit_to_gate(qc_gate, equivalence_library=sel)
 
         qc_inst = QuantumCircuit(2)
         qc_inst.h(0)
         qc_inst.cx(0, 1)
 
-        bell_inst = qc_inst.to_instruction()
+        bell_inst = circuit_to_instruction(qc_inst, equivalence_library=sel)
 
-        from qiskit.circuit.equivalence_library import SessionEquivalenceLibrary as sel
         gate_entry = sel.get_entry(bell_gate)
         inst_entry = sel.get_entry(bell_inst)
 
@@ -429,7 +430,8 @@ class TestSessionEquivalenceLibrary(QiskitTestCase):
         qc.h(0)
         qc.cx(0, 1)
 
-        gate = qc.to_gate()
+        from qiskit.circuit.equivalence_library import SessionEquivalenceLibrary as sel
+        gate = circuit_to_gate(qc, equivalence_library=sel)
 
         decomps = gate.decompositions