Skip to main contentIBM Quantum Documentation

Compilation Routines

qiskit.compiler


Circuit and Pulse Compilation Functions

assemble

qiskit.compiler.assemble(experiments, backend=None, qobj_id=None, qobj_header=None, shots=None, memory=False, seed_simulator=None, qubit_lo_freq=None, meas_lo_freq=None, qubit_lo_range=None, meas_lo_range=None, schedule_los=None, meas_level=MeasLevel.CLASSIFIED, meas_return=MeasReturnType.AVERAGE, meas_map=None, memory_slot_size=100, rep_time=None, rep_delay=None, parameter_binds=None, parametric_pulses=None, init_qubits=True, **run_config) GitHub(opens in a new tab)

Assemble a list of circuits or pulse schedules into a Qobj.

This function serializes the payloads, which could be either circuits or schedules, to create Qobj “experiments”. It further annotates the experiment payload with header and configurations.

NOTE: Backend.options is not used within assemble. The required values (previously given by backend.set_options) should be manually extracted from options and supplied directly when calling.

Parameters

  • experiments (QuantumCircuit |List(opens in a new tab)[QuantumCircuit] | Schedule |List(opens in a new tab)[Schedule] | ScheduleBlock |List(opens in a new tab)[ScheduleBlock]) – Circuit(s) or pulse schedule(s) to execute

  • backend (Backend | None) – If set, some runtime options are automatically grabbed from backend.configuration() and backend.defaults(). If any other option is explicitly set (e.g., rep_time), it will override the backend’s. If any other options is set in the run_config, it will also override the backend’s.

  • qobj_id (str(opens in a new tab) | None) – String identifier to annotate the Qobj

  • qobj_header (QobjHeader |Dict(opens in a new tab) | None) – User input that will be inserted in Qobj header, and will also be copied to the corresponding Result header. Headers do not affect the run.

  • shots (int(opens in a new tab) | None) – Number of repetitions of each circuit, for sampling. Default: 1024 or max_shots from the backend configuration, whichever is smaller

  • memory (bool(opens in a new tab) | None) – If True, per-shot measurement bitstrings are returned as well (provided the backend supports it). For OpenPulse jobs, only measurement level 2 supports this option.

  • seed_simulator (int(opens in a new tab) | None) – Random seed to control sampling, for when backend is a simulator

  • qubit_lo_freq (List(opens in a new tab)[float(opens in a new tab)] | None) – List of job level qubit drive LO frequencies in Hz. Overridden by schedule_los if specified. Must have length n_qubits.

  • meas_lo_freq (List(opens in a new tab)[float(opens in a new tab)] | None) – List of measurement LO frequencies in Hz. Overridden by schedule_los if specified. Must have length n_qubits.

  • qubit_lo_range (List(opens in a new tab)[float(opens in a new tab)] | None) – List of job level drive LO ranges each of form [range_min, range_max] in Hz. Used to validate qubit_lo_freq. Must have length n_qubits.

  • meas_lo_range (List(opens in a new tab)[float(opens in a new tab)] | None) – List of job level measurement LO ranges each of form [range_min, range_max] in Hz. Used to validate meas_lo_freq. Must have length n_qubits.

  • schedule_los (List(opens in a new tab)[Dict(opens in a new tab)[PulseChannel, float(opens in a new tab)] | LoConfig] | Dict(opens in a new tab)[PulseChannel, float(opens in a new tab)] | LoConfig | None) – Experiment level (ie circuit or schedule) LO frequency configurations for qubit drive and measurement channels. These values override the job level values from default_qubit_los and default_meas_los. Frequencies are in Hz. Settable for OpenQASM 2 and pulse jobs.

  • meas_level (int(opens in a new tab) | MeasLevel) – Set the appropriate level of the measurement output for pulse experiments.

  • meas_return (str(opens in a new tab) | MeasReturnType) –

    Level of measurement data for the backend to return.

    For meas_level 0 and 1:

    • single returns information from every shot.
    • avg returns average measurement output (averaged over number of shots).
  • meas_map (List(opens in a new tab)[List(opens in a new tab)[Qubit]] | None) – List of lists, containing qubits that must be measured together.

  • memory_slot_size (int(opens in a new tab)) – Size of each memory slot if the output is Level 0.

  • rep_time (int(opens in a new tab)) – Time per program execution in seconds. Must be from the list provided by the backend (backend.configuration().rep_times). Defaults to the first entry.

  • rep_delay (float(opens in a new tab)) – Delay between programs in seconds. Only supported on certain backends (if backend.configuration().dynamic_reprate_enabled=True). If supported, rep_delay will be used instead of rep_time and must be from the range supplied by the backend (backend.configuration().rep_delay_range). Default is given by backend.configuration().default_rep_delay.

  • parameter_binds (List(opens in a new tab)[Dict(opens in a new tab)[Parameter, float(opens in a new tab)]] | None) – List of Parameter bindings over which the set of experiments will be executed. Each list element (bind) should be of the form {Parameter1: value1, Parameter2: value2, …}. All binds will be executed across all experiments; e.g., if parameter_binds is a length-n list, and there are m experiments, a total of m x n experiments will be run (one for each experiment/bind pair).

  • parametric_pulses (List(opens in a new tab)[str(opens in a new tab)] | None) –

    A list of pulse shapes which are supported internally on the backend. Example:

    ['gaussian', 'constant']
  • init_qubits (bool(opens in a new tab)) – Whether to reset the qubits to the ground state for each shot. Default: True.

  • **run_config (Dict(opens in a new tab)) – Extra arguments used to configure the run (e.g., for Aer configurable backends). Refer to the backend documentation for details on these arguments.

Returns

A Qobj that can be run on a backend. Depending on the type of input, this will be either a QasmQobj or a PulseQobj.

Raises

QiskitError – if the input cannot be interpreted as either circuits or schedules

Return type

QasmQobj | PulseQobj

schedule

qiskit.compiler.schedule(circuits, backend=None, inst_map=None, meas_map=None, dt=None, method=None) GitHub(opens in a new tab)

Schedule a circuit to a pulse Schedule, using the backend, according to any specified methods. Supported methods are documented in qiskit.scheduler.schedule_circuit.

Parameters

Returns

A pulse Schedule that implements the input circuit

Raises

QiskitError – If inst_map and meas_map are not passed and backend is not passed

Return type

Schedule | List(opens in a new tab)[Schedule]

transpile

qiskit.compiler.transpile(circuits, backend=None, basis_gates=None, inst_map=None, coupling_map=None, backend_properties=None, initial_layout=None, layout_method=None, routing_method=None, translation_method=None, scheduling_method=None, instruction_durations=None, dt=None, approximation_degree=1.0, timing_constraints=None, seed_transpiler=None, optimization_level=None, callback=None, output_name=None, unitary_synthesis_method='default', unitary_synthesis_plugin_config=None, target=None, hls_config=None, init_method=None, optimization_method=None, ignore_backend_supplied_default_methods=False, num_processes=None) GitHub(opens in a new tab)

Transpile one or more circuits, according to some desired transpilation targets.

Transpilation is potentially done in parallel using multiprocessing when circuits is a list with > 1 QuantumCircuit object depending on the local environment and configuration.

Parameters

  • circuits (_CircuitT) – Circuit(s) to transpile

  • backend (Backend | None) – If set, the transpiler will compile the input circuit to this target device. If any other option is explicitly set (e.g., coupling_map), it will override the backend’s.

  • basis_gates (List(opens in a new tab)[str(opens in a new tab)] | None) – List of basis gate names to unroll to (e.g: ['u1', 'u2', 'u3', 'cx']). If None, do not unroll.

  • inst_map (List(opens in a new tab)[InstructionScheduleMap] | None) – Mapping of unrolled gates to pulse schedules. If this is not provided, transpiler tries to get from the backend. If any user defined calibration is found in the map and this is used in a circuit, transpiler attaches the custom gate definition to the circuit. This enables one to flexibly override the low-level instruction implementation. This feature is available iff the backend supports the pulse gate experiment.

  • coupling_map (CouplingMap |List(opens in a new tab)[List(opens in a new tab)[int(opens in a new tab)]] | None) –

    Directed coupling map (perhaps custom) to target in mapping. If the coupling map is symmetric, both directions need to be specified.

    Multiple formats are supported:

    1. CouplingMap instance
    2. List, must be given as an adjacency matrix, where each entry specifies all directed two-qubit interactions supported by backend, e.g: [[0, 1], [0, 3], [1, 2], [1, 5], [2, 5], [4, 1], [5, 3]]
  • backend_properties (BackendProperties | None) – properties returned by a backend, including information on gate errors, readout errors, qubit coherence times, etc. Find a backend that provides this information with: backend.properties()

  • initial_layout (Layout |Dict(opens in a new tab) |List(opens in a new tab) | None) –

    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 may permute qubits through swaps or other means. Multiple formats are supported:

    1. Layout instance

    2. Dict * virtual to physical:

      {qr[0]: 0,
       qr[1]: 3,
       qr[2]: 5}
      • physical to virtual:

        {0: qr[0],
         3: qr[1],
         5: qr[2]}
    3. List

      • virtual to physical:

        [0, 3, 5]  # virtual qubits are ordered (in addition to named)
      • physical to virtual:

        [qr[0], None, None, qr[1], None, qr[2]]
  • layout_method (str(opens in a new tab) | None) – Name of layout selection pass (‘trivial’, ‘dense’, ‘sabre’). This can also be the external plugin name to use for the layout stage. You can see a list of installed plugins by using list_stage_plugins() with "layout" for the stage_name argument.

  • routing_method (str(opens in a new tab) | None) – Name of routing pass (‘basic’, ‘lookahead’, ‘stochastic’, ‘sabre’, ‘none’). Note This can also be the external plugin name to use for the routing stage. You can see a list of installed plugins by using list_stage_plugins() with "routing" for the stage_name argument.

  • translation_method (str(opens in a new tab) | None) – Name of translation pass (‘unroller’, ‘translator’, ‘synthesis’) This can also be the external plugin name to use for the translation stage. You can see a list of installed plugins by using list_stage_plugins() with "translation" for the stage_name argument.

  • scheduling_method (str(opens in a new tab) | None) – Name of scheduling pass. * 'as_soon_as_possible': Schedule instructions greedily, as early as possible on a qubit resource. (alias: 'asap') * 'as_late_as_possible': Schedule instructions late, i.e. keeping qubits in the ground state when possible. (alias: 'alap') If None, no scheduling will be done. This can also be the external plugin name to use for the scheduling stage. You can see a list of installed plugins by using list_stage_plugins() with "scheduling" for the stage_name argument.

  • instruction_durations (List(opens in a new tab)[Tuple(opens in a new tab)[str(opens in a new tab), Iterable(opens in a new tab)[int(opens in a new tab)] | None, float(opens in a new tab), Iterable(opens in a new tab)[float(opens in a new tab)] | None, str(opens in a new tab)]] | List(opens in a new tab)[Tuple(opens in a new tab)[str(opens in a new tab), Iterable(opens in a new tab)[int(opens in a new tab)] | None, float(opens in a new tab), Iterable(opens in a new tab)[float(opens in a new tab)] | None]] | List(opens in a new tab)[Tuple(opens in a new tab)[str(opens in a new tab), Iterable(opens in a new tab)[int(opens in a new tab)] | None, float(opens in a new tab), str(opens in a new tab)]] | List(opens in a new tab)[Tuple(opens in a new tab)[str(opens in a new tab), Iterable(opens in a new tab)[int(opens in a new tab)] | None, float(opens in a new tab)]] | InstructionDurations | None) – Durations of instructions. Applicable only if scheduling_method is specified. The gate lengths defined in backend.properties are used as default. They are overwritten if this instruction_durations is specified. The format of instruction_durations must be as follows. The instruction_durations must be given as a list of tuples [(instruction_name, qubits, duration, unit), …]. | [(‘cx’, [0, 1], 12.3, ‘ns’), (‘u3’, [0], 4.56, ‘ns’)] | [(‘cx’, [0, 1], 1000), (‘u3’, [0], 300)] If unit is omitted, the default is ‘dt’, which is a sample time depending on backend. If the time unit is ‘dt’, the duration must be an integer.

  • dt (float(opens in a new tab) | None) – Backend sample time (resolution) in seconds. If None (default), backend.configuration().dt is used.

  • approximation_degree (float(opens in a new tab)) – heuristic dial used for circuit approximation (1.0=no approximation, 0.0=maximal approximation)

  • timing_constraints (Dict(opens in a new tab)[str(opens in a new tab), int(opens in a new tab)] | None) –

    An optional control hardware restriction on instruction time resolution. A quantum computer backend may report a set of restrictions, namely:

    • granularity: An integer value representing minimum pulse gate resolution in units of dt. A user-defined pulse gate should have duration of a multiple of this granularity value.
    • min_length: An integer value representing minimum pulse gate length in units of dt. A user-defined pulse gate should be longer than this length.
    • pulse_alignment: An integer value representing a time resolution of gate instruction starting time. Gate instruction should start at time which is a multiple of the alignment value.
    • acquire_alignment: An integer value representing a time resolution of measure instruction starting time. Measure instruction should start at time which is a multiple of the alignment value.

    This information will be provided by the backend configuration. If the backend doesn’t have any restriction on the instruction time allocation, then timing_constraints is None and no adjustment will be performed.

  • seed_transpiler (int(opens in a new tab) | None) – Sets random seed for the stochastic parts of the transpiler

  • optimization_level (int(opens in a new tab) | None) –

    How much optimization to perform on the circuits. Higher levels generate more optimized circuits, at the expense of longer transpilation time.

    • 0: no optimization
    • 1: light optimization
    • 2: heavy optimization
    • 3: even heavier optimization

    If None, level 1 will be chosen as default.

  • callback (Callable(opens in a new tab)[[BasePass, DAGCircuit, float(opens in a new tab), PropertySet, int(opens in a new tab)], Any(opens in a new tab)] | None) –

    A callback function that will be called after each pass execution. The function will be called with 5 keyword arguments, | pass_: the pass being run. | dag: the dag output of the pass. | time: the time to execute the pass. | property_set: the property set. | count: the index for the pass execution. The exact arguments passed expose the internals of the pass manager, and are subject to change as the pass manager internals change. If you intend to reuse a callback function over multiple releases, be sure to check that the arguments being passed are the same. To use the callback feature, define a function that will take in kwargs dict and access the variables. For example:

    def callback_func(**kwargs):
        pass_ = kwargs['pass_']
        dag = kwargs['dag']
        time = kwargs['time']
        property_set = kwargs['property_set']
        count = kwargs['count']
        ...
    transpile(circ, callback=callback_func)
  • output_name (str(opens in a new tab) |List(opens in a new tab)[str(opens in a new tab)] | None) – A list with strings to identify the output circuits. The length of the list should be exactly the length of the circuits parameter.

  • unitary_synthesis_method (str(opens in a new tab)) – The name of the unitary synthesis method to use. By default 'default' is used. You can see a list of installed plugins with unitary_synthesis_plugin_names().

  • unitary_synthesis_plugin_config (dict(opens in a new tab) | None) – An optional configuration dictionary that will be passed directly to the unitary synthesis plugin. By default this setting will have no effect as the default unitary synthesis method does not take custom configuration. This should only be necessary when a unitary synthesis plugin is specified with the unitary_synthesis_method argument. As this is custom for each unitary synthesis plugin refer to the plugin documentation for how to use this option.

  • target (Target | None) – A backend transpiler target. Normally this is specified as part of the backend argument, but if you have manually constructed a Target object you can specify it manually here. This will override the target from backend.

  • hls_config (HLSConfig | None) – An optional configuration class HLSConfig that will be passed directly to HighLevelSynthesis transformation pass. This configuration class allows to specify for various high-level objects the lists of synthesis algorithms and their parameters.

  • init_method (str(opens in a new tab) | None) – The plugin name to use for the init stage. By default an external plugin is not used. You can see a list of installed plugins by using list_stage_plugins() with "init" for the stage name argument.

  • optimization_method (str(opens in a new tab) | None) – 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 using list_stage_plugins() with "optimization" for the stage_name argument.

  • ignore_backend_supplied_default_methods (bool(opens in a new tab)) – If set to True any default methods specified by a backend will be ignored. Some backends specify alternative default methods to support custom compilation target-specific passes/plugins which support backend-specific compilation techniques. If you’d prefer that these defaults were not used this option is used to disable those backend-specific defaults.

  • num_processes (int(opens in a new tab) | None) – The maximum number of parallel processes to launch for this call to transpile if parallel execution is enabled. This argument overrides num_processes in the user configuration file, and the QISKIT_NUM_PROCS environment variable. If set to None the system default or local user configuration will be used.

Returns

The transpiled circuit(s).

Raises

TranspilerError – in case of bad inputs to transpiler (like conflicting parameters) or errors in passes

Return type

_CircuitT

sequence

qiskit.compiler.sequence(scheduled_circuits, backend=None, inst_map=None, meas_map=None, dt=None) GitHub(opens in a new tab)

Schedule a scheduled circuit to a pulse Schedule, using the backend.

Parameters

Returns

A pulse Schedule that implements the input circuit

Raises

QiskitError – If inst_map and meas_map are not passed and backend is not passed

Return type

Schedule | List(opens in a new tab)[Schedule]

Was this page helpful?
Report a bug or request content on GitHub.