{ "cells": [ { "cell_type": "markdown", "id": "c5693a08-8ac2-4ca6-bfa9-3bf6148d257b", "metadata": {}, "source": [ "---\n", "title: Transpilation defaults and configuration options\n", "description: The default settings and configuration options for quantum circuit transpilation in the Qiskit SDK.\n", "---\n", "\n", "# Transpilation default settings and configuration options\n", "\n" ] }, { "cell_type": "markdown", "id": "051470e1-7466-4ad7-affe-6ceec583d5d5", "metadata": { "tags": [ "version-info" ] }, "source": [ "{/*\n", " DO NOT EDIT THIS CELL!!!\n", " This cell's content is generated automatically by a script. Anything you add\n", " here will be removed next time the notebook is run. To add new content, create\n", " a new cell before or after this one.\n", " */}\n", "\n", "\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.4.0\n", " qiskit-ibm-runtime~=0.46.1\n", " ```\n", " \n", "\n", "\n" ] }, { "cell_type": "markdown", "id": "a3513040-821f-4e07-9f82-98e8ba38819b", "metadata": {}, "source": [ "Abstract circuits need to be transpiled because QPUs have a limited set of basis gates and cannot execute arbitrary operations. The transpiler's function is to change arbitrary circuits so that they can run on a specified QPU. This is done by translating the circuits to the supported basis gates, and by introducing SWAP gates as needed, so that the circuit's connectivity matches that of the QPU.\n", "\n", "As explained in [Transpile with pass managers](transpile-with-pass-managers), you can create a [pass manager](/docs/api/qiskit/qiskit.transpiler.PassManager) using the [`generate_preset_pass_manager`](/docs/api/qiskit/qiskit.transpiler.generate_preset_pass_manager#qiskit.transpiler.generate_preset_pass_manager) function and pass a circuit or list of circuits to its [run](/docs/api/qiskit/qiskit.transpiler.PassManager#run) method to transpile them. You can call `generate_preset_pass_manager` passing only the optimization level and backend, choosing to use the defaults for all other options, or you can pass additional arguments to the function to fine-tune the transpilation.\n", "\n", "## Basic usage without parameters\n", "\n", "In this example, we pass a circuit and target QPU to the transpiler without specifying any further parameters.\n", "\n", "Create a circuit and view the result:\n", "\n" ] }, { "cell_type": "code", "execution_count": 1, "id": "f7070db2-2b3e-4dcd-bbc7-cac7662867b3", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 1, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from qiskit import QuantumCircuit\n", "from qiskit.circuit.library import grover_operator, DiagonalGate\n", "from qiskit_ibm_runtime.fake_provider import FakeSherbrooke\n", "\n", "# Create circuit to test transpiler on\n", "oracle = DiagonalGate([1] * 7 + [-1])\n", "qc = QuantumCircuit(3)\n", "qc.h([0, 1, 2])\n", "qc = qc.compose(grover_operator(oracle))\n", "\n", "# Add measurements to the circuit\n", "qc.measure_all()\n", "\n", "# View the circuit\n", "qc.draw(output=\"mpl\")" ] }, { "cell_type": "markdown", "id": "24622567-920c-48d9-aeba-d85a8dd34788", "metadata": {}, "source": [ "Transpile the circuit and view the result:\n", "\n" ] }, { "cell_type": "code", "execution_count": 2, "id": "27ab746b-e3d7-49a7-b40b-d1e2d9ca6088", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "\"Output" ] }, "execution_count": 2, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from qiskit.transpiler import generate_preset_pass_manager\n", "\n", "# Specify the QPU to target\n", "backend = FakeSherbrooke()\n", "\n", "# Transpile the circuit\n", "pass_manager = generate_preset_pass_manager(\n", " optimization_level=1, backend=backend\n", ")\n", "transpiled_circ = pass_manager.run(qc)\n", "\n", "# View the transpiled circuit\n", "transpiled_circ.draw(output=\"mpl\", idle_wires=False)" ] }, { "cell_type": "markdown", "id": "6c0e9d2d-511e-4948-9f48-3b7b0fe56d7a", "metadata": {}, "source": [ "## All available parameters\n", "\n", "Following are all of the available parameters for the [`generate_preset_pass_manager`](/docs/api/qiskit/qiskit.transpiler.generate_preset_pass_manager#qiskit.transpiler.generate_preset_pass_manager) function. There are two classes of arguments: those that describe the target of compilation, and those that influence how the transpiler works.\n", "\n", "All parameters except `optimization_level` are optional. For full details, see the [Transpiler API documentation](/docs/api/qiskit/transpiler#transpiler-api).\n", "\n", "* `optimization_level` (int) - How much optimization to perform on the circuits. Integer in the range (0 - 3). Higher levels generate more optimized circuits, at the expense of longer transpilation time. See [Set transpiler optimization level](set-optimization) for more details.\n", "\n", "### Parameters used to describe the compilation target:\n", "\n", "These arguments describe the target QPU for circuit execution, including information such as the coupling map of the QPU (which describes the connectivity of the qubits), the basis gates supported by the QPU, and the error rates of the gates.\n", "\n", "Many of these parameters are described in detail in [Commonly used parameters for transpilation](common-parameters).\n", "\n", "\n", " \n", " **Backend parameters** - If you specify `backend`, you don't need to specify `target` or any other backend options. Likewise, if you specify `target`, you don't need to specify `backend` or any other backend options.\n", "\n", " * `backend` (Backend) - If this is set, the transpiler compiles the input circuit to this device. If any other option is set that impacts these settings, such as `coupling_map`, it overrides the settings from `backend`.\n", " * `target` (Target) - A backend transpiler target. Normally this is specified as part of the backend argument, but if you manually constructed a Target object, you can specify it here. This overrides the target from `backend`.\n", " * `backend_properties` (BackendProperties) - Properties returned by a QPU, including information on gate errors, readout errors, qubit coherence times, and so on. Find a QPU that provides this information by running `backend.properties()`.\n", " * `timing_constraints` (Dict\\[str, int] | None) - An optional control hardware restriction on instruction time resolution. This information is provided by the QPU configuration. If the QPU doesn’t have any restriction on the instruction time allocation, `timing_constraints` is `None` and no adjustment is performed. A QPU might report a set of restrictions, namely:\n", " * `granularity`: An integer value representing the minimum pulse gate resolution in units of dt. A user-defined pulse gate should have a duration that is a multiple of this granularity value.\n", " * `min_length`: An integer value representing the minimum pulse gate length in units of dt. A user-defined pulse gate should be longer than this length.\n", " * `pulse_alignment`: An integer value representing a time resolution of gate instruction starting time. Gate instructions should start at a time that is a multiple of this value.\n", " * `acquire_alignment`: An integer value representing a time resolution of measure instruction starting time. Measure instruction should start at a time that is a multiple of this value.\n", " \n", "\n", " \n", " * `basis_gates` (List\\[str] | None) - List of basis gate names to unroll to. For example \\['u1', 'u2', 'u3', 'cx']. If `None`, do not unroll.\n", " * `coupling_map` (CouplingMap | List\\[List\\[int]]) - Directed coupling map (possibly custom) to target in mapping. If the coupling map is symmetric, both directions need to be specified. These formats are supported:\n", " * CouplingMap instance\n", " * List - must be given as an adjacency matrix, where each entry specifies all directed two-qubit interactions supported by the QPU. For example: \\[\\[0, 1], \\[0, 3], \\[1, 2], \\[1, 5], \\[2, 5], \\[4, 1], \\[5, 3]]\n", " * `inst_map` (List\\[InstructionScheduleMap] | None) - Mapping of circuit operations to pulse schedules. If `None`, the QPU's `instruction_schedule_map` is used.\n", " \n", "\n", "\n", "### Parameters used to influence how the transpiler works\n", "\n", "These parameters impact specific transpilation stages. Some of them might impact multiple stages, but have only been listed under one stage for simplicity. If you specify an argument, such as `initial_layout` for the qubits you want to use, that value overrides all the passes that could change it. In other words, the transpiler won't change anything that you manually specify. For details about specific stages, see [Transpiler stages](transpiler-stages).\n", "\n", "\n", " \n", " * `hls_config` (HLSConfig) - An optional configuration class `HLSConfig` that is passed directly to the `HighLevelSynthesis` transformation pass. This configuration class lets you specify the lists of synthesis algorithms and their parameters for various high-level objects.\n", " * `init_method` (str) - The plugin name to use for the initialization stage. By default, an external plugin is not used. You can see a list of installed plugins by running `list_stage_plugins()` with `init` for the stage name argument.\n", " * `unitary_synthesis_method` (str) - The name of the unitary synthesis method to use. By default, `default` is used. You can see a list of installed plugins by running `unitary_synthesis_plugin_names()`.\n", " * `unitary_synthesis_plugin_config` (dict) - An optional configuration dictionary that is passed directly to the unitary synthesis plugin. By default this setting has no effect because the default unitary synthesis method does not take custom configuration. Applying a custom configuration should only be necessary when a unitary synthesis plugin is specified with the `unitary_synthesis` argument. As this is custom for each unitary synthesis plugin, refer to the plugin's documentation for how to use this option.\n", " \n", "\n", " \n", " * `initial_layout` (Layout | Dict | List) - Initial position of virtual qubits on physical qubits. If this layout makes the circuit compatible with the `coupling_map` constraints, it will be used. The final layout is not guaranteed to be the same, as the transpiler might permute qubits through swaps or other means. For full details, see the [Initial layout section](common-parameters#initial-layout).\n", " * `layout_method` (str) - Name of layout selection pass (`default`, `dense`, `sabre`, and `trivial`). This can also be the external plugin name to use for the layout stage. You can see a list of installed plugins by running `list_stage_plugins()` with `layout` for the `stage_name` argument. The default value is `sabre`.\n", " \n", "\n", " \n", " * `routing_method` (str) - Name of routing pass (`basic`, `lookahead`, `default`, `sabre`, or `none`). This can also be the external plugin name to use for the routing stage. You can see a list of installed plugins by running `list_stage_plugins()` with `routing` for the `stage_name` argument. The default value is `sabre`.\n", " \n", "\n", " \n", " * `translation_method` (str) - Name of translation pass (`default`, `synthesis`, `translator`, `ibm_backend`, `ibm_dynamic_circuits`, `ibm_fractional`) This can also be the external plugin name to use for the translation stage. You can see a list of installed plugins by running `list_stage_plugins()` with `translation` for the `stage_name` argument. The default value is `translator`.\n", " \n", "\n", " \n", " * `approximation_degree` (float, in the range 0-1 | None) - Heuristic dial used for circuit approximation (1.0 = no approximation, 0.0 = maximal approximation). The default value is 1.0. Specifying `None` sets the approximation degree to the reported error rate. See the [Approximation degree section](common-parameters#approx-degree) for more details.\n", " * `optimization_method` (str) - The plugin name to use for the optimization stage. By default an external plugin is not used. You can see a list of installed plugins by running `list_stage_plugins()` with `optimization` for the `stage_name` argument.\n", " \n", "\n", " \n", " * `scheduling_method` (str) - Name of the scheduling pass. This can also be the external plugin name to use for the scheduling stage. You can see a list of installed plugins by running `list_stage_plugins()` with `scheduling` for the `stage_name` argument.\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, keeping qubits in the ground state when possible (alias: `alap`). This is the default.\n", " \n", "\n", " \n", " * `seed_transpiler` (int) - Sets random seeds for the stochastic parts of the transpiler.\n", " \n", "\n", "\n", "The following default values are used if you don't specify any of the above parameters. Refer to the method's [API reference page](../api/qiskit/transpiler_preset) for more information:\n", "\n" ] }, { "cell_type": "code", "execution_count": 3, "id": "bcaab4a6", "metadata": {}, "outputs": [ { "data": { "text/plain": [ "" ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "generate_preset_pass_manager(\n", " optimization_level=1,\n", " backend=None,\n", " target=None,\n", " basis_gates=None,\n", " coupling_map=None,\n", " initial_layout=None,\n", " layout_method=None,\n", " routing_method=None,\n", " translation_method=None,\n", " scheduling_method=None,\n", " approximation_degree=1.0,\n", " seed_transpiler=None,\n", " unitary_synthesis_method=\"default\",\n", " unitary_synthesis_plugin_config=None,\n", " hls_config=None,\n", " init_method=None,\n", " optimization_method=None,\n", ")" ] }, { "cell_type": "markdown", "id": "f1acc6e6", "metadata": {}, "source": [ "## Next steps\n", "\n", "\n", " * Learn how to [Set the optimization level](set-optimization).\n", " * Review more [Commonly used parameters](common-parameters).\n", " * Learn how to [Set the optimization level when using Qiskit Runtime](/docs/guides/runtime-options-overview).\n", " * Visit the [Transpile with pass managers](/docs/guides/transpile-with-pass-managers) topic.\n", " * For examples, see [Representing quantum computers](/docs/guides/represent-quantum-computers).\n", " * Learn [how to transpile circuits](/docs/guides/circuit-transpilation-settings) as part of the Qiskit patterns workflow using Qiskit Runtime.\n", " * Review the [Transpile API documentation](/docs/api/qiskit/transpiler).\n", "\n", "\n" ] }, { "cell_type": "markdown", "metadata": {}, "id": "a1b8767d", "source": "© IBM Corp., 2017-2026" } ], "metadata": { "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" } }, "nbformat": 4, "nbformat_minor": 5 }