Show how to generate built-in transpiler stage (#1546)

Fixes #1044 .

Author: kevinsung

docs/transpile/create-a-transpiler-plugin.ipynb

@@ -58,6 +58,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# This import is needed for python versions prior to 3.10\n",
+    "from __future__ import annotations\n",
+    "\n",
     "from qiskit.transpiler import PassManager\n",
     "from qiskit.transpiler.passes import VF2Layout\n",
     "from qiskit.transpiler.passmanager_config import PassManagerConfig\n",
@@ -163,7 +166,33 @@
    "id": "d62c4edb",
    "metadata": {},
    "source": [
-    "If our example plugin were installed, then the name `my_layout` would appear in this list."
+    "If our example plugin were installed, then the name `my_layout` would appear in this list.\n",
+    "\n",
+    "If you want to use a built-in transpiler stage as the starting point for your transpiler stage plugin, you can obtain the pass manager for a built-in transpiler stage using [PassManagerStagePluginManager](/api/qiskit/qiskit.transpiler.preset_passmanagers.plugin.PassManagerStagePluginManager#passmanagerstagepluginmanager). The following code cell shows how to do this to obtain the built-in optimization stage for optimization level 3."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "f4d578d6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qiskit.transpiler.passmanager_config import PassManagerConfig\n",
+    "from qiskit.transpiler.preset_passmanagers.plugin import PassManagerStagePluginManager\n",
+    "\n",
+    "# Initialize the plugin manager\n",
+    "plugin_manager = PassManagerStagePluginManager()\n",
+    "\n",
+    "# Here we create a pass manager config to use as an example.\n",
+    "# Instead, you should use the pass manager config that you already received as input\n",
+    "# to the pass_manager method of your PassManagerStagePlugin.\n",
+    "pass_manager_config = PassManagerConfig()\n",
+    "\n",
+    "# Obtain the desired built-in transpiler stage\n",
+    "optimization = plugin_manager.get_passmanager_stage(\n",
+    "    \"optimization\", \"default\", pass_manager_config, optimization_level=3\n",
+    ")"
    ]
   },
   {
@@ -188,7 +217,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 4,
    "id": "6bc1011c-b15d-4210-973b-d9d530ece880",
    "metadata": {},
    "outputs": [],
@@ -324,17 +353,17 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 5,
    "id": "31bfaf30",
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "['aqc', 'default', 'sk']"
+       "['default', 'sk', 'aqc']"
       ]
      },
-     "execution_count": 4,
+     "execution_count": 5,
      "metadata": {},
      "output_type": "execute_result"
     }
@@ -397,7 +426,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 6,
    "id": "3c0e59d4-85b0-4157-824b-b1f6220e83ad",
    "metadata": {},
    "outputs": [],
@@ -469,17 +498,17 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 7,
    "id": "fbe1f265",
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "['ag', 'bm', 'default', 'greedy', 'layers', 'lnn']"
+       "['rb_default', 'ag', 'bm', 'default', 'greedy', 'layers', 'lnn']"
       ]
      },
-     "execution_count": 6,
+     "execution_count": 7,
      "metadata": {},
      "output_type": "execute_result"
     }