Executing Experiments

execute(experiments, backend, basis_gates=None, coupling_map=None, backend_properties=None, initial_layout=None, seed_transpiler=None, optimization_level=None, pass_manager=None, qobj_id=None, qobj_header=None, shots=1024, memory=False, max_credits=10, seed_simulator=None, default_qubit_los=None, default_meas_los=None, schedule_los=None, meas_level=MeasLevel.CLASSIFIED, meas_return=MeasReturnType.AVERAGE, memory_slots=None, memory_slot_size=100, rep_time=None, parameter_binds=None, schedule_circuit=False, inst_map=None, meas_map=None, scheduling_method=None, **run_config)

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.

Parameters

• experiments (QuantumCircuit or list[QuantumCircuit] or Schedule or list[Schedule]) – Circuit(s) or pulse schedule(s) to execute

• backend (BaseBackend) – Backend to execute circuits on. Transpiler options are automatically grabbed from backend.configuration() and backend.properties(). If any other option is explicitly set (e.g. coupling_map), it will override the backend’s.

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

• coupling_map (CouplingMap or list) –

  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: backend.properties()

• initial_layout (Layout or dict or 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 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) – Sets random seed for the stochastic parts of the transpiler

• optimization_level (int) – How much optimization to perform on the circuits. Higher levels generate more optimized circuits, at the expense of longer transpilation time. #. No optimization #. Light optimization #. Heavy optimization #. Highest 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.

• qobj_id (str) – String identifier to annotate the Qobj

• qobj_header (QobjHeader or dict) – User input that will be inserted in Qobj header, and will also be copied to the corresponding qiskit.result.Result header. Headers do not affect the run.

• shots (int) – Number of repetitions of each circuit, for sampling. Default: 1024

• memory (bool) – 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

• max_credits (int) – Maximum credits to spend on job. Default: 10

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

• default_qubit_los (list) – List of default qubit LO frequencies in Hz

• default_meas_los (list) – List of default meas LO frequencies in Hz

• schedule_los (None or list or dict or LoConfig) –

  Experiment LO configurations, if specified the list is in the format:

  list[Union[Dict[PulseChannel, float], LoConfig]] or
       Union[Dict[PulseChannel, float], LoConfig]

• meas_level (int or MeasLevel) – Set the appropriate level of the measurement output for pulse experiments.

• meas_return (str 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) – Number of classical memory slots used in this job.

• memory_slot_size (int) – Size of each memory slot if the output is Level 0.

• rep_time (int) – repetition time of the experiment in μs. The delay between experiments will be rep_time. Must be from the list provided by the device.

• parameter_binds (list[dict]) – 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).

• schedule_circuit (bool) – 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(list(int))) – List of sets of qubits that must be measured together. If None, defaults to the meas_map of backend.

• scheduling_method (str or list(str)) – Optionally specify a particular scheduling method.

• run_config (dict) – 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 backend.run()

Returns

returns job instance derived from BaseJob

Return type

BaseJob

Raises

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

Example

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)
qc.cx(0, range(1, 5))
qc.measure_all()
 
job = execute(qc, backend, shots=4321)