qiskit-documentation/docs/guides/common-parameters.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "fbce2fd6-c79e-4e90-9074-6cde8a09b517",
   "metadata": {},
   "source": [
    "# Commonly used parameters for transpilation"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6beea7ff-7407-47be-a0b7-1e7981328df5",
   "metadata": {
    "tags": [
     "version-info"
    ]
   },
   "source": [
    "<details>\n",
    "<summary><b>Package versions</b></summary>\n",
    "\n",
    "The code on this page was developed using the following requirements.\n",
    "We recommend using these versions or newer.\n",
    "\n",
    "```\n",
    "qiskit[all]~=2.0.0\n",
    "qiskit-ibm-runtime~=0.37.0\n",
    "```\n",
    "</details>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "05fb8adb-3b36-4449-b669-108d2d749ca5",
   "metadata": {},
   "source": [
    "This page describes some of the more commonly used parameters for local transpilation. These parameters are configured using arguments to [`generate_preset_pass_manager`](/docs/api/qiskit/qiskit.transpiler.generate_preset_pass_manager#qiskit.transpiler.generate_preset_pass_manager) or [`transpile`](/docs/api/qiskit/compiler#qiskit.compiler.transpile).\n",
    "\n",
    "<span id=\"approx-degree\"></span>\n",
    "## Approximation degree\n",
    "\n",
    "You can use the approximation degree to specify how closely you want the resultant circuit to match the desired (input) circuit.  This is a float in the range (0.0 - 1.0), where 0.0 is maximum approximation and 1.0 (default) is no approximation. Smaller values trade output accuracy for ease of execution (that is, fewer gates).  The default value is 1.0.\n",
    "\n",
    "In two-qubit unitary synthesis (used in initial stages of all levels and for optimization stage with optimization level 3), this value specifies the target fidelity of the output decomposition. That is, how much error is introduced when a matrix representation of a circuit is converted to discrete gates. If the approximation degree is a lower value (more approximation), the output circuit from synthesis will differ more from the input matrix, but will also likely have fewer gates (because any arbitrary two-qubit operation can be decomposed perfectly with at most three CX gates) and is easier to run.\n",
    "\n",
    "When the approximation degree is less than 1.0, circuits with one or two CX gates might be synthesized, leading to less error from the hardware, but more from the approximation. Since CX is the most expensive gate in terms of error, it might be beneficial to decrease the number of them at the cost of fidelity in synthesis (this technique was used to increase quantum volume on IBM&reg; devices: [Validating quantum computers using randomized model circuits](https://arxiv.org/abs/1811.12926)).\n",
    "\n",
    "As an example, we generate a random two-qubit `UnitaryGate` which will be synthesized in the initial stage. Setting the `approximation_degree` less than 1.0 might generate an approximate circuit. We must also specify the `basis_gates` to let the synthesis method know which gates it can use for the approximate synthesis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "e660bec2-f806-4050-955b-53a50289158e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2\n"
     ]
    }
   ],
   "source": [
    "from qiskit import QuantumCircuit, QuantumRegister\n",
    "from qiskit.circuit.library import UnitaryGate\n",
    "from qiskit.quantum_info import random_unitary\n",
    "from qiskit.transpiler import generate_preset_pass_manager\n",
    "\n",
    "UU = random_unitary(4, seed=12345)\n",
    "rand_U = UnitaryGate(UU)\n",
    "\n",
    "qubits = QuantumRegister(2, name=\"q\")\n",
    "qc = QuantumCircuit(qubits)\n",
    "qc.append(rand_U, qubits)\n",
    "pass_manager = generate_preset_pass_manager(\n",
    "    optimization_level=1,\n",
    "    approximation_degree=0.85,\n",
    "    basis_gates=[\"sx\", \"rz\", \"cx\"],\n",
    ")\n",
    "approx_qc = pass_manager.run(qc)\n",
    "print(approx_qc.count_ops()[\"cx\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6f067d6e-0157-43fc-8cb2-c86855b6bdac",
   "metadata": {},
   "source": [
    "This yields an output of `2` because the approximation requires fewer CX gates.\n",
    "\n",
    "<span id=\"seed\"></span>\n",
    "## Random number generator seed\n",
    "\n",
    "Some parts of the transpiler are stochastic, so repeated transpilation runs may return different results. To obtain a reproducible result, you can set the seed for the pseudorandom number generator using the `seed_transpiler` argument. Repeated runs using the same seed will return the same results.\n",
    "\n",
    "Example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "dbc652e8-53a4-47a9-a66e-d9c1e5ef07c9",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Image src=\"/docs/images/guides/common-parameters/extracted-outputs/dbc652e8-53a4-47a9-a66e-d9c1e5ef07c9-0.svg\" alt=\"Output of the previous code cell\" />"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "pass_manager = generate_preset_pass_manager(\n",
    "    optimization_level=1, seed_transpiler=11, basis_gates=[\"sx\", \"rz\", \"cx\"]\n",
    ")\n",
    "optimized_1 = pass_manager.run(qc)\n",
    "optimized_1.draw(\"mpl\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "20b95efa-8aa8-41ac-a037-dac2a3336879",
   "metadata": {},
   "source": [
    "<span id=\"init-layout\"></span>\n",
    "## Initial layout\n",
    "\n",
    "Before transpilation, the qubits contained in your circuit are virtual qubits that don't necessarily correspond to physical qubits on the target backend. You can specify the initial mapping of virtual qubits to physical qubits using the `initial_layout` argument. Note that the final qubit layout may differ from the initial layout because the transpiler may permute qubits using swap gates or other means.\n",
    "\n",
    "In the example below, we construct an initial layout for the [`FakeSherbrooke`](/docs/api/qiskit-ibm-runtime/fake-provider-fake-sherbrooke#fakesherbrooke) mock backend by creating a [`Layout`](/docs/api/qiskit/qiskit.transpiler.Layout) object. Our layout maps the first qubit of our circuit to qubit 5 of Sherbrooke, and it maps the second qubit of our circuit to qubit 6 of Sherbrooke. Note that physical qubits are always represented by integers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "e18c034c-eb26-4d9d-81d7-37e0eafa17c7",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Image src=\"/docs/images/guides/common-parameters/extracted-outputs/e18c034c-eb26-4d9d-81d7-37e0eafa17c7-0.svg\" alt=\"Output of the previous code cell\" />"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from qiskit_ibm_runtime.fake_provider import FakeSherbrooke\n",
    "from qiskit.transpiler import Layout\n",
    "\n",
    "backend = FakeSherbrooke()\n",
    "\n",
    "a, b = qubits\n",
    "initial_layout = Layout({a: 5, b: 6})\n",
    "\n",
    "pass_manager = generate_preset_pass_manager(\n",
    "    optimization_level=1, backend=backend, initial_layout=initial_layout\n",
    ")\n",
    "transpiled_circ = pass_manager.run(qc)\n",
    "\n",
    "transpiled_circ.draw(\"mpl\", idle_wires=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "261055f3-cb88-4651-9a98-31891a4db535",
   "metadata": {},
   "source": [
    "In addition to specifying a Layout object, you can also pass a list of integers, where the $i$-th element of the list contains the physical qubit that the $i$-th qubit should be mapped to. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "a7800d8a-7354-48e4-a55f-f902ae28c875",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Image src=\"/docs/images/guides/common-parameters/extracted-outputs/a7800d8a-7354-48e4-a55f-f902ae28c875-0.svg\" alt=\"Output of the previous code cell\" />"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "initial_layout = [5, 6]\n",
    "\n",
    "pass_manager = generate_preset_pass_manager(\n",
    "    optimization_level=1, backend=backend, initial_layout=initial_layout\n",
    ")\n",
    "transpiled_circ = pass_manager.run(qc)\n",
    "\n",
    "transpiled_circ.draw(\"mpl\", idle_wires=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d2034dd5-23e5-4473-89b8-aaf4233775c7",
   "metadata": {},
   "source": [
    "<LegacyContent>\n",
    "You can use the [`plot_error_map`](/docs/api/qiskit/qiskit.visualization.plot_error_map) function to generate a diagram of the device graph with error information and with the physical qubits labeled. You can also view similar diagrams at https://quantum.ibm.com/services/resources.\n",
    "</LegacyContent>\n",
    "<CloudContent>\n",
    "You can use the [`plot_error_map`](/docs/api/qiskit/qiskit.visualization.plot_error_map) function to generate a diagram of the device graph with error information and with the physical qubits labeled. You can also view similar diagrams on the [Compute resources](https://quantum.cloud.ibm.com/computers) page.\n",
    "</CloudContent>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "8df57c6a-1ff4-4d58-9b7e-4378452c3025",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Image src=\"/docs/images/guides/common-parameters/extracted-outputs/8df57c6a-1ff4-4d58-9b7e-4378452c3025-0.svg\" alt=\"Output of the previous code cell\" />"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from qiskit.visualization import plot_error_map\n",
    "\n",
    "plot_error_map(backend, figsize=(30, 24))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "25c05cca-b93b-4ba1-b46c-7280ec4ef8cb",
   "metadata": {},
   "source": [
    "<span id=\"xx-method\"></span>\n",
    "## Transpiler stage and plugin options\n",
    "\n",
    "These options are suffixed with `_method`. They influence how the transpiler works and are used to try and get better, different, or specific output from the transpiler.\n",
    "\n",
    "* `init_method` (str) - The plugin to use for the initialization stage.\n",
    "\n",
    "* `layout_method` (str) - The layout selection pass (`trivial`, `dense`, `sabre`). This can also be the external plugin name to use for the layout stage.\n",
    "\n",
    "* `optimization_method` (str) - The plugin to use for the optimization stage.\n",
    "\n",
    "* `routing_method` (str) - Name of routing pass (`basic`, `lookahead`, `default`, `sabre`, `none`). This can also be the external plugin name to use for the routing stage.\n",
    "\n",
    "* `scheduling_method` (str) - Name of scheduling pass. This can also be the external plugin name to use for the scheduling stage.\n",
    "  * `as_soon_as_possible`: Schedule instructions greedily: as early as possible on a qubit resource (alias: `asap`).\n",
    "  * `as_late_as_possible`: Schedule instructions late.  That is, keep qubits in the ground state when possible (alias: `alap`).\n",
    "\n",
    "* `translation_method` (str) - Name of translation pass (`unroller`, `translator`, `synthesis`). This can also be the external plugin name to use for the translation stage.\n",
    "\n",
    "* `unitary_synthesis_method` (str) - The name of the unitary synthesis method to use. By default `default` is used.\n",
    "\n",
    "<Admonition>\n",
    "  To see a list of all installed plugins for a given stage, run [`list_stage_plugins(\"stage_name\")`](https://docs.quantum.ibm.com/api/qiskit/transpiler_plugins#plugin-api). For example, if you want to see a list of all installed plugins for the routing stage, run `list_stage_plugins(routing)`.\n",
    "</Admonition>\n",
    "\n",
    "## Next steps\n",
    "\n",
    "<Admonition type=\"tip\" title=\"Recommendation\">\n",
    "    - Review the [Default options and configuration settings](defaults-and-configuration-options) topic.\n",
    "    - Learn how to [Set the optimization level.](set-optimization)\n",
    "    - Try the [Submit transpiled circuits](https://learning.quantum.ibm.com/tutorial/submit-transpiled-circuits) tutorial.\n",
    "    - Review the [Transpile API documentation.](/docs/api/qiskit/transpiler)\n",
    "\n",
    "</Admonition>"
   ]
  }
 ],
 "metadata": {
  "description": "Overview of commonly used parameters controlling quantum circuit transpilation in Qiskit.",
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3"
  },
  "title": "Commonly used parameters for transpilation"
 },
 "nbformat": 4,
 "nbformat_minor": 5
}