Reno

releasenotes/notes/upgrade-pass-manager-98aa64edde67b5bb.yaml

@@ -0,0 +1,108 @@
+---
+upgrade:
+  - |
+    A pattern for the pass piepline construction was upgraded.
+    The syntactic suger shown below for instantiation of flow controller was removed.
+
+    .. code-block:: python
+
+      from qiskit.transpiler import PassManager
+
+      pm = PassManager()
+      pm.append(my_pass, condition=condition_callable, do_while=do_while_callable)
+
+    Instead of using this keyword argument pattern, you should explicitly instantiate the
+    flow controller.
+
+    .. code-block:: python
+
+      from qiskit.passmanager.flow_controllers import ConditionalController, DoWhileController
+
+      pm = PassManager()
+      pm.append(
+        ConditionalController(
+          DoWhileController(my_pass, do_while=do_while_callable),
+          condition=condition_callable,
+        )
+      )
+
+    Note that you can manage the pecking order of controllers when you want to nest them,
+    which was not possible with keyword arguments.
+    You can also build the pipeline with the constructor of the pass manager like below
+    because there is no reason to call the append method now.
+
+    .. code-block:: python
+
+      pm = PassManager(
+        ConditionalController(
+          DoWhileController(my_pass, do_while=do_while_callable),
+          condition=condition_callable,
+        )
+      )
+
+  - |
+    The append method of builtin flow controllers was removed. This includes
+
+    * :meth:`.ConditionalController.append`
+    * :meth:`.DoWhileController.append`
+    * :meth:`.FlowControllerLinear.append`
+
+    The task pipeline in a flow controller is frozen, and it must be passed
+    when the controller instance is created.
+
+  - |
+    The structure of pass list that :meth:`~qiskit.transpiler.PassManager.passes` returns
+    was updated. Previously the passes appended together was grouped in the pass list,
+    but this list is now flattened. Also nested controller is now represented by a
+    nested dictionary. For example,
+
+    .. code-block::
+      [
+        {
+          "passes": [PassA, PassB],
+          "flow_controllers": {}
+        },
+        {
+          "passes": [PassC, ConditionalController],
+          "flow_controllers": {"do_while"}
+        },
+      ]
+
+    This pass list might become
+
+    .. code-block::
+      [
+        {
+          "passes": [PassA],
+          "flow_controllers": {}
+        },
+        {
+          "passes": [PassB],
+          "flow_controllers": {}
+        },
+        {
+          "passes": [
+            PassC,
+            {
+              "passes": [PassD],
+              "flow_controllers": {"condition"},
+            }
+          ],
+          "flow_controllers": {"do_while"}
+        },
+      ]
+
+    This is just a difference in notation. Two constructions are logically the same.
+
+  - |
+    The max_iteration argument was removed from :meth:`qiskit.transpiler.PassManager.append`
+    and :meth:`qiskit.transpiler.PassManager.replace`.
+
+  - |
+    The following legacy classes were removed from the pass manager and transpiler module.
+
+    * :class:`qiskit.passmanager.flow_controllers.FlowController`
+    * :class:`qiskit.transpiler.fencedobjs.FencedObject`
+    * :class:`qiskit.transpiler.fencedobjs.FencedPropertySet`
+    * :class:`qiskit.transpiler.fencedobjs.FencedDAGCircuit`
+    * :class:`qiskit.transpiler.runningpassmanager.RunningPassManager`