Add plugin pass to support non-calibrated rzz angles

qiskit_ibm_runtime/transpiler/passes/basis/fold_rzz_angle.py

@@ -28,35 +28,59 @@ class FoldRzzAngle(TransformationPass):
     """Fold Rzz gate angle into calibrated range of 0-pi/2 with
     local gate tweaks.
 
-    This pass preserves the number of Rzz gates, but it may add
-    extra single qubit gate operations.
-    These gates might be reduced by the following
-    single qubit optimization passes.
+    In the IBM Quantum ISA, the instruction Rzz(theta) has
+    valid "theta" value of [0, pi/2] and any instruction outside
+    this range becomes non-ISA operation for the quantum backend.
+    The transpiler pass discovers such non-ISA Rzz gates
+    and folds the gate angle into the calibrated range
+    with addition of single qubit gates while preserving
+    logical equivalency of the input quantum circuit.
+    Added local gates might be efficiently merged into
+    neighboring single qubit gates by the following single qubit
+    optimization passes.
+
+    This pass allows the Qiskit users to naively use the Rzz gates
+    with angle of arbitrary real numbers.
+
+    .. note::
+        This pass doesn't transform the circuit when the
+        Rzz gate angle is unbound parameter.
+        In this case, the user must assign gate angle before
+        transpile, or be responsible for choosing parameters
+        from the calibrated range of [0, pi/2].
     """
 
     def run(self, dag: DAGCircuit) -> DAGCircuit:
         # Currently control flow ops and Rzz cannot live in the same circuit.
         # Once it's supported, we need to recursively check subroutines.
         for node in dag.op_nodes():
-            if not isinstance(node.op, RZZGate) or isinstance(
-                angle := node.op.params[0], ParameterExpression
-            ):
+            if not isinstance(node.op, RZZGate):
+                continue
+            angle = node.op.params[0]
+            if isinstance(angle, ParameterExpression) or 0 <= angle <= pi / 2:
+                # Angle is unbound parameter or calibrated value.
                 continue
             wrap_angle = np.angle(np.exp(1j * angle))
-            if -pi <= wrap_angle <= -pi / 2:
+            if 0 <= wrap_angle <= pi / 2:
+                # In the first quadrant after phase wrapping.
+                # We just need to remove 2pi offset.
+                dag.substitute_node(
+                    node,
+                    RZZGate(wrap_angle),
+                    inplace=True,
+                )
+                continue
+            if pi / 2 < wrap_angle <= pi:
+                # In the second quadrant.
+                replace = _quad2(wrap_angle, node.qargs)
+            elif -pi <= wrap_angle <= -pi / 2:
+                # In the third quadrant.
                 replace = _quad3(wrap_angle, node.qargs)
             elif -pi / 2 < wrap_angle < 0:
+                # In the forth quadrant.
                 replace = _quad4(wrap_angle, node.qargs)
-            elif pi / 2 < wrap_angle <= pi:
-                replace = _quad2(wrap_angle, node.qargs)
             else:
-                if angle != wrap_angle:
-                    dag.substitute_node(
-                        node,
-                        RZZGate(wrap_angle),
-                        inplace=True,
-                    )
-                continue
+                raise RuntimeError("Unreacheable.")
             dag.substitute_node_with_dag(node, replace)
         return dag
 

test/unit/transpiler/passes/basis/test_fold_rzz_angle.py

@@ -14,6 +14,7 @@
 
 from math import pi
 from ddt import ddt, named_data
+import numpy as np
 
 from qiskit.circuit import QuantumCircuit
 from qiskit.quantum_info import Operator
@@ -61,3 +62,14 @@ def test_folding_rzz_angle_unbound(self):
         pm = PassManager([FoldRzzAngle()])
         isa = pm.run(qc)
         self.assertEqual(qc, isa)
+
+    def test_identity(self):
+        """Create identity circuit with angles with [-4pi, 4pi] and transpile."""
+        # Angle sum is zero
+        angles = pi * np.linspace(-4, 4, 17)
+        qc = QuantumCircuit(2)
+        for angle in angles:
+            qc.rzz(angle, 0, 1)
+        pm = PassManager([FoldRzzAngle()])
+        isa = pm.run(qc)
+        self.assertTrue(Operator.from_label("II").equiv(Operator.from_circuit(isa)))