Skip to main contentIBM Quantum Documentation
You are viewing the API reference for an old version of Qiskit SDK. Switch to latest version

Executing Experiments



qiskit.execute_function.execute(experiments, backend, basis_gates=None, coupling_map=None, backend_properties=None, initial_layout=None, seed_transpiler=None, optimization_level=None, pass_manager=None, shots=None, memory=None, seed_simulator=None, default_qubit_los=None, default_meas_los=None, qubit_lo_range=None, meas_lo_range=None, schedule_los=None, meas_level=None, meas_return=None, memory_slots=None, memory_slot_size=None, rep_time=None, rep_delay=None, parameter_binds=None, schedule_circuit=False, inst_map=None, meas_map=None, scheduling_method=None, init_qubits=None, **run_config)

GitHub(opens in a new tab)

Execute a list of qiskit.circuit.QuantumCircuit or qiskit.pulse.Schedule on a backend.

The execution is asynchronous, and a handle to a job instance is returned.


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

  • backend (Backend) – Backend to execute circuits on. Transpiler options are automatically grabbed from backend.configuration() and 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)]) – List of basis gate names to unroll to. e.g: ['u1', 'u2', 'u3', 'cx']. If None, do not unroll.

  • coupling_map (CouplingMap orlist(opens in a new tab)) –

    Coupling map (perhaps custom) to target in mapping. Multiple formats are supported:

    1. CouplingMap instance
    2. list: must be given as an adjacency matrix, where each entry specifies all 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) – Properties returned by a backend, including information on gate errors, readout errors, qubit coherence times, etc. Find a backend that provides this information with:

  • initial_layout (Layout ordict(opens in a new tab) orlist(opens in a new tab)) –

    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. qiskit.transpiler.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]]
  • seed_transpiler (int(opens in a new tab)) – Sets random seed for the stochastic parts of the transpiler

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

    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.

  • pass_manager (PassManager) – The pass manager to use during transpilation. If this arg is present, auto-selection of pass manager based on the transpile options will be turned off and this pass manager will be used directly.

  • shots (int(opens in a new tab)) – Number of repetitions of each circuit, for sampling. Default: 1024

  • memory (bool(opens in a new tab)) – 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. Default: False

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

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

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

  • qubit_lo_range (Optional[List[List[float(opens in a new tab)]]]) – 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 (Optional[List[List[float(opens in a new tab)]]]) – 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)) –

    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 qasm and pulse jobs.

    If a single LO config or dict is used, the values are set at job level. If a list is used, the list must be the size of the number of experiments in the job, except in the case of a single experiment. In this case, a frequency sweep will be assumed and one experiment will be created for every list entry.

    Not every channel is required to be specified. If not specified, the backend default value will be used.

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

  • meas_return (str(opens in a new tab) or MeasReturn) – 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).

  • memory_slots (int(opens in a new tab)) – Number of classical memory slots used in this job.

  • 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 (backend.configuration().dynamic_reprate_enabled ). 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)]) – 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-nn list, and there are mm experiments, a total of m×nm \times n experiments will be run (one for each experiment/bind pair).

  • schedule_circuit (bool(opens in a new tab)) – If True, experiments will be converted to qiskit.pulse.Schedule objects prior to execution.

  • inst_map (InstructionScheduleMap) – Mapping of circuit operations to pulse schedules. If None, defaults to the instruction_schedule_map of backend.

  • meas_map (list(opens in a new tab)(list(opens in a new tab)(int(opens in a new tab)))) – List of sets of qubits that must be measured together. If None, defaults to the meas_map of backend.

  • scheduling_method (str(opens in a new tab) orlist(opens in a new tab)(str(opens in a new tab))) – Optionally specify a particular scheduling method.

  • 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. Note: for now, these keyword arguments will both be copied to the Qobj config, and passed to


returns job instance derived from Job

Return type



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


Construct a 5-qubit GHZ circuit and execute 4321 shots on a backend.

from qiskit import QuantumCircuit, execute, BasicAer
backend = BasicAer.get_backend('qasm_simulator')
qc = QuantumCircuit(5, 5)
qc.h(0), range(1, 5))
job = execute(qc, backend, shots=4321)
Was this page helpful?
Report a bug or request content on GitHub.