Experiment service migration guide#

qiskit-ibm-experiment aims to replace the experiment database service that was included as part of the deprecated qiskit-ibmq-provider package. There interface for the service in both packages is similar, with two key differences: 1. qiskit-ibm-experiment methods get and return dataclass parameters, instead receiving separate values and returning dictionaries. 2. qiskit-ibm-experiment does not automatically generate the experiment service as part of a larger provider; the experiment service needs to be manually created.

In this guide we cover those differences.

Quick start example: old usage vs new usage#

Old usage:#

This code works when the qiskit-terra and qiskit-ibmq-provider packages are installed and credentials for using IBMQ are already locally stored on the computer.

[3]:

from qiskit import IBMQ
provider = IBMQ.load_account()
service = provider.experiment
experiment_data = service.experiment(experiment_id = '5524b504-2f59-11ed-a7c7-bc97e15b08d0')
print(experiment_data['creation_datetime'])
print(experiment_data['metadata']['user'])

2022-09-08 12:35:14.997000+03:00
labuser_test

New usage:#

This code works when the qiskit-ibm-experiment package is installed and credentials for using IBMQ are already locally stored on the computer.

[4]:

from qiskit_ibm_experiment import IBMExperimentService
service = IBMExperimentService()
experiment_data = service.experiment(experiment_id = '5524b504-2f59-11ed-a7c7-bc97e15b08d0')
print(experiment_data.creation_datetime)
print(experiment_data.metadata['user'])

2022-09-08 12:35:14.997000+03:00
labuser_test

Service creation#

In qiskit-ibmq-provider, one did not create the experiment service explicitly. Rather, after loading the account, the experiment service was accessed via the experiment field.

To use the new experiment service, it needs to be explicitly created via the IBMExperimentService() constructor. It can accept the same authentication parameters used as part of qiskit-ibmq-provider. e.g. passing a token or a url. In most cases it is best to perform once

from qiskit_ibm_experiment import IBMExperimentService
IBMExperimentService.save_account(name='my_config', token='MY_API_TOKEN')

Allowing the token to be retrieved automatically when creating a service.

Method usage#

The interface for the class remains almost the same. The main change is the return value of experiment, experiments, analysis_result and analysis_results.

All the following methods are used exactly in the same way: * backends * create_analysis_result * create_experiment * create_figure * delete_analysis_result * delete_experiment * delete_figure * device_components * figure * save_preferences * update_analysis_result * update_experiment

The return values of experiment and analysis_result was changed from Dict to ExperimentData and AnalysisResultData. The result types of experiments and analysis_results is now a list of the corresponding data type.

Note: A planned future change involves analysis_results returning a pandas dataframe by default; this is not yet implemented.

As seen in the above usage example, the return value change means that instead of doing, e.g.

(Old style)

print(experiment_data['metadata']['user'])

(New Style)

print(experiment_data.metadata['user'])

(the metadata value remains a dictionary, even though the experiment data was changed to ExperimentData class)