Functions for sending experiments to IBMQ devices and converting the results to pyGSTi objects

Module Contents



dict() -> new empty dictionary



partial_trace(ordered_target_indices, input_dict)

q_list_to_ordered_target_indices(q_list, num_qubits)

pygsti.extras.ibmq.ibmqcore.partial_trace(ordered_target_indices, input_dict)
pygsti.extras.ibmq.ibmqcore.q_list_to_ordered_target_indices(q_list, num_qubits)
class pygsti.extras.ibmq.ibmqcore.IBMQExperiment(edesign, pspec, remove_duplicates=True, randomized_order=True, circuits_per_batch=75, num_shots=1024)

Bases: dict

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:

d = {} for k, v in iterable:

d[k] = v

dict(**kwargs) -> new dictionary initialized with the name=value pairs

in the keyword argument list. For example: dict(one=1, two=2)

A object that converts pyGSTi ExperimentDesigns into jobs to be submitted to IBM Q, submits these jobs to IBM Q and receives the results.


edesign: ExperimentDesign

The ExperimentDesign to be run on IBM Q. This can be a combined experiment design (e.g., a GST design combined with an RB design).

pspec: QubitProcessorSpec

A QubitProcessorSpec that represents the IBM Q device being used. This can be created using the extras.devices.create_processor_spec(). The ProcessorSpecs qubit ordering must correspond to that of the IBM device (which will be the case if you create it using that function). I.e., pspecs qubits should be labelled Q0 through Qn-1 and the labelling of the qubits should agree with IBM’s labelling.

remove_duplicates: bool, optional

If true, each distinct circuit in edesign is run only once. If false, if a circuit is repeated multiple times in edesign it is run multiple times.

randomized_order: bool, optional

Whether or not to randomize the order of the circuits in edesign before turning them into jobs to be submitted to IBM Q.

circuits_per_batch: int, optional

The circuits in edesign are divded into batches, each containing at most this many circuits. The default value of 75 is (or was) the maximal value allowed on the public IBM Q devices.

num_shots: int, optional

The number of samples from / repeats of each circuit.



An object containing jobs to be submitted to IBM Q, which can then be submitted using the methods .submit() and whose results can be grabbed from IBM Q using the method .retrieve_results(). This object has dictionary-like access for all of the objects it contains (e.g., [‘qobj’] is a list of the objects to be submitted to IBM Q).

submit(ibmq_backend, start=None, stop=None, ignore_job_limit=True, wait_time=1, wait_steps=10)

Submits the jobs to IBM Q, that implements the experiment specified by the ExperimentDesign used to create this object.

ibmq_backend: qiskit.providers.ibmq.ibmqbackend.IBMQBackend

The IBM Q backend to submit the jobs to. Should be the backend corresponding to the processor that this experiment has been designed for.

start: int, optional

Batch index to start submission (inclusive). Defaults to None, which will start submission on the first unsubmitted job. Jobs can be resubmitted by manually specifying this, i.e. start=0 will start resubmitting jobs from the beginning.

stop: int, optional

Batch index to stop submission (exclusive). Defaults to None, which will submit as many jobs as possible given the backend’s maximum job limit.

ignore_job_limit: bool, optional

If True, then stop is set to submit all remaining jobs. This is set as True to maintain backwards compatibility. Note that is more jobs are needed than the max limit, this will enter a wait loop until all jobs have been successfully submitted.

wait_time: int

Number of seconds for each waiting step.

wait_steps: int

Number of steps to take before retrying job submission.




Queries IBM Q for the status of the jobs.


Gets the results of the completed jobs from IBM Q, and processes them into a pyGSTi DataProtocol object (stored as the key ‘data’), which can then be used in pyGSTi data analysis routines (e.g., if this was a GST experiment, it can input into a GST protocol object that will analyze the data).


Writes to disk, storing both the pyGSTi DataProtocol object in pyGSTi’s standard format and saving all of the IBM Q submission information stored in this object, written into the subdirectory ‘ibmqexperiment’.


The root directory to write into. This directory will have an ‘edesign’ subdirectory, which will be created if needed and overwritten if present. If None, then the path this object was loaded from is used (if this object wasn’t loaded from disk, an error is raised).

classmethod from_dir(dirname, provider=None)

Initialize a new IBMQExperiment object from dirname.


The directory name.

provider: IBMProvider

Provider used to retrieve qjob objects from job_ids