Access systems with your account¶

Filtering the Backends¶

You may also optionally filter the set of returned backends, by passing arguments that query the backend’s configuration, status, or properties. The filters are passed by conditions and, for more general filters, you can make advanced functions using a lambda function.

As a first example, let’s return only those backends that are real quantum devices, and that are currently operational:

provider.backends(simulator=False, operational=True)

Or, only those backends that are real devices, have more than 10 qubits, and are operational:

provider.backends(filters=lambda x: x.configuration().n_qubits >= 10
                                    and not x.configuration().simulator
                                    and x.status().operational==True)

Lastly, show the least-busy five-qubit device (in terms of the number of jobs pending in the queue):

from qiskit.providers.ibmq import least_busy

small_devices = provider.backends(filters=lambda x: x.configuration().n_qubits == 5
                                   and not x.configuration().simulator)
least_busy(small_devices)

The above filters can be combined as desired.

## Backends <a name='backends'></a>

Backends represent either a simulator or a real quantum computer, and are responsible for running quantum circuits and/or pulse schedules and returning results. They have a run method which takes in a qobj as input, the Qiskit API serialization format, and returns a BaseJob object. This object allows asynchronous running of jobs for retrieving results from a backend when the job is completed.

At a minimum, backends use the following methods, inherited from qiskit.providers.BaseBackend:

• provider(): Returns the provider of the backend.

• name(): Returns the name of the backend.

• status(): Returns the current status of the backend.

• configuration(): Returns the backend configuration.

• properties(): Returns the backend properties.

• run(QOBJ, **kwargs): Runs a qobj on the backend.

The qiskit-ibmq-provider’s implementation of BaseBackend is IBMQBackend. It accepts additional parameters to the run() method:

• job_name: Custom name to be assigned to the job.

• job_share_level: Allows sharing the job at different level.

• job_tags: Tags to be assigned to the job.

And supports additional methods:

• jobs(): Returns a list of previous jobs executed on this backend through the current provider instance.

• retrieve_job(JOB_ID): Returns a job by its job ID.

• defaults(): Gives a data structure of typical default parameters, if applicable.

• job_limit(): Returns the job limit for the backend.

• remaining_jobs_count(): Returns the number of remaining jobs that could be submitted to the backend.

• active_jobs(): Returns a list of unfinished jobs.

Refer to the IBMQBackend documentation for a complete list of methods.

Let’s load up the least-busy backend from the small_devices filtered above:

backend = least_busy(small_devices)

Some examples using the different methods:

backend.provider()

backend.name()

backend.status()

Here we see the name of the backend and the software version it is running, along with its operational status, number of jobs pending in the backends queue, and a more detailed status message.

Next we look at the backend configuration and properties:

backend.configuration()

The backend configuration provides some useful information via its attributes, such as basis_gates, coupling_map, max_experiments, max_shots, quantum_volume, and simulator.

The backend properties contain data that was measured and reported. Let’s see what kind of information is reported for qubit 0.

props = backend.properties()

def describe_qubit(qubit, properties):
    """Print a string describing some of reported properties of the given qubit."""

    # Conversion factors from standard SI units
    us = 1e6
    ns = 1e9
    GHz = 1e-9

    print("Qubit {0} has a \n"
          "  - T1 time of {1} microseconds\n"
          "  - T2 time of {2} microseconds\n"
          "  - SX gate error of {3}\n"
          "  - SX gate duration of {4} nanoseconds\n"
          "  - resonant frequency of {5} GHz".format(
              qubit,
              properties.t1(qubit) * us,
              properties.t2(qubit) * us,
              properties.gate_error('sx', qubit),
              properties.gate_length('sx', qubit) * ns,
              properties.frequency(qubit) * GHz))

describe_qubit(0, props)

To see the last five jobs run on this backend:

ran_job = None
for ran_job in backend.jobs(limit=5):
    print(str(ran_job.job_id()) + " " + str(ran_job.status()))

A job can be retrieved using the retrieve_job(JOB_ID) method:

if ran_job is not None:
    job = backend.retrieve_job(ran_job.job_id())

Retrieve jobs from a retired system¶

See a list of retired systems at this page.

To retrieve jobs from a retired system, you can use code similar to this:

from qiskit import IBMQ
IBMQ.load_account()  #If credentials have been saved already

provider = IBMQ.get_provider(<hub>, <group>, <project>)

#If you want to retrieve a list of jobs
jobs = provider.backend.jobs(backend_name=<backend_name>)

#If you want to retrieve a specific job you have the id for
job = provider.backend.retrieve_job(<job_id>)

The provider.backend.jobs() method also has more filtering options. Find the method’s documentation here.

Backend Service¶

qiskit-ibmq-provider version 0.4 (Qiskit version 0.14) introduced a new class IBMQBackendService. It provides generic backend related services for a provider without requiring a particular backend as input. The main methods it supports are:

• jobs(): Returns a list of previously submitted jobs through the current provider instance.

• retrieve_job(JOB_ID): Returns a job by its job ID.

The backend service is defined as the backends attribute of a provider. All of the backends available to this provider are also attributes of the backend service, allowing the backend names to be autocompleted:

provider.backends.ibmq_vigo

To see the last five jobs submitted through this provider, regardless of which backend they ran on:

for ran_job in provider.backends.jobs(limit=5):
    print(str(ran_job.job_id()) + " " + str(ran_job.status()))

To retrieve a particular job:

if ran_job is not None:
    job = provider.backends.retrieve_job(ran_job.job_id())

Job Manager ¶

The Job Manager is another convenience function provided by qiskit-ibmq-provider, available in version 0.4 (Qiskit version 0.14) and up. It splits experiments into multiple jobs based on backend restrictions. When the jobs are finished, it collects and presents the results in a unified view.

IBMQJobManager has the following methods:

• run(): Execute a set of circuits or pulse schedules.

• report(): Return a report on the statuses of all jobs managed by this manager.

• job_sets(): Return a list of managed job sets matching the specified filtering.

You can run multiple sets of experiments by invoking job_manager.run() multiple times, and each call will return a ManagedJobSet instance. The ManagedJobSet methods allow you to apply operations on this set of jobs as a whole and are similiar to those of the Job class:

• statuses(): Return the status of each job.

• cancel(): Cancel all jobs in this set.

• results(): Return the results of the jobs.

• error_messages(): Provide details about job failures.

• jobs(): Return a list of submitted jobs.

• report(): Return a report on current job statuses.

Now let’s see some examples. Say you want to submit a bunch of circuits to a backend:

from qiskit.providers.ibmq.managed import IBMQJobManager

sim_backend = provider.get_backend('ibmq_qasm_simulator')
circs = transpile([circuit]*20, backend=sim_backend)

# Submit them all to the backend
job_manager = IBMQJobManager()
job_set = job_manager.run(circs, backend=sim_backend, name='foo')

You can use the report() method to inquire the statuses of the jobs:

print(job_set.report())

job_set above is not very interesting, as it only contains a single job. To force multiple jobs without making this tutorial too slow, we can use the max_experiments_per_job parameter:

# Restrict 2 experiments per job.
job_set_multiple = job_manager.run(circs, backend=sim_backend, name='bar', max_experiments_per_job=2)

print(job_set_multiple.report())

As you can see, job_set_multiple contains multiple jobs. To collect the results of all jobs, you can use the results() method, which returns a ManagedResults instance. ManagedResults supports the same methods as Result, which can be used to retrieve the ouputs of individual experiments:

#results = job_set_multiple.results()
#print("This is the histogram data for experiment 1: {}".format(results.get_counts(1)))
#print("This is the histogram data for experiment 2: {}".format(results.get_counts(2)))

Similar to a job, each job set is assigned a unique ID. The job set ID along with the provider object can be used to retrieve a previously submitted job set:

job_set_id = job_set_multiple.job_set_id()
retrieved_job_set = job_manager.retrieve_job_set(job_set_id=job_set_id, provider=provider)
print(retrieved_job_set.report())

If you want to manipulate the jobs within a job set directly, you can use the jobs() method to retrive them. Note that an entry is None if that particular job could not be submitted:

#jobs = job_set_multiple.jobs()  # Get a list of all jobs in the set.
#job0 = jobs[0]
#if job0 is None:
    #print("Job0 submit failed!")