443 lines
20 KiB
Plaintext
443 lines
20 KiB
Plaintext
---
|
||
title: ExperimentService
|
||
description: API reference for qiskit.providers.ibmq.experiment.ExperimentService
|
||
in_page_toc_min_heading_level: 1
|
||
python_api_type: class
|
||
python_api_name: qiskit.providers.ibmq.experiment.ExperimentService
|
||
---
|
||
|
||
# qiskit.providers.ibmq.experiment.ExperimentService
|
||
|
||
<Class id="qiskit.providers.ibmq.experiment.ExperimentService" isDedicatedPage={true} github="https://github.com/qiskit/qiskit-ibmq-provider/tree/stable/0.13/qiskit/providers/ibmq/experiment/experimentservice.py" signature="ExperimentService(provider)" modifiers="class">
|
||
Provides experiment related services.
|
||
|
||
This class is the main interface to invoke IBM Quantum Experience experiment services, which allow you to create, delete, update, query, and retrieve experiments, experiment plots, and analysis results. The `experiment` attribute of `AccountProvider` is an instance of this class, and the main syntax for using the services is `provider.experiment.<action>`. For example:
|
||
|
||
```python
|
||
from qiskit import IBMQ
|
||
provider = IBMQ.load_account()
|
||
|
||
# Retrieve all experiments.
|
||
experiments = provider.experiment.experiments()
|
||
|
||
# Retrieve experiments with filtering.
|
||
experiment_filtered = provider.experiment.experiments(backend_name='foo')
|
||
|
||
# Retrieve a specific experiment using its ID.
|
||
experiment = provider.experiment.retrieve_experiment(EXPERIMENT_ID)
|
||
|
||
# Upload a new experiment.
|
||
from qiskit.providers.ibmq.experiment import Experiment
|
||
new_exp = Experiment(
|
||
provider=provider,
|
||
backend_name=backend_name,
|
||
experiment_type='test',
|
||
tags=['qiskit-test']
|
||
)
|
||
provider.experiment.upload_experiment(new_exp)
|
||
|
||
# Update an experiment.
|
||
new_exp.end_datetime = datetime.now()
|
||
provider.experiment.update_experiment(new_exp)
|
||
|
||
# Delete an experiment.
|
||
provider.experiment.delete_experiment(EXPERIMENT_ID)
|
||
```
|
||
|
||
Similar syntax applies to analysis results and experiment plots. Classes [`Experiment`](qiskit.providers.ibmq.experiment.Experiment "qiskit.providers.ibmq.experiment.Experiment") and [`AnalysisResult`](qiskit.providers.ibmq.experiment.AnalysisResult "qiskit.providers.ibmq.experiment.AnalysisResult") encapsulate data of an experiment and an analysis result, respectively.
|
||
|
||
IBMQBackendService constructor.
|
||
|
||
**Parameters**
|
||
|
||
**provider** (`AccountProvider`) – IBM Quantum Experience account provider.
|
||
|
||
### \_\_init\_\_
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.__init__" signature="__init__(provider)">
|
||
IBMQBackendService constructor.
|
||
|
||
**Parameters**
|
||
|
||
**provider** (`AccountProvider`) – IBM Quantum Experience account provider.
|
||
</Function>
|
||
|
||
## Methods
|
||
|
||
| | |
|
||
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
|
||
| [`__init__`](#qiskit.providers.ibmq.experiment.ExperimentService.__init__ "qiskit.providers.ibmq.experiment.ExperimentService.__init__")(provider) | IBMQBackendService constructor. |
|
||
| [`analysis_results`](#qiskit.providers.ibmq.experiment.ExperimentService.analysis_results "qiskit.providers.ibmq.experiment.ExperimentService.analysis_results")(\[limit, backend\_name, …]) | Retrieve all analysis results, with optional filtering. |
|
||
| [`backends`](#qiskit.providers.ibmq.experiment.ExperimentService.backends "qiskit.providers.ibmq.experiment.ExperimentService.backends")() | Return a list of backends. |
|
||
| [`delete_analysis_result`](#qiskit.providers.ibmq.experiment.ExperimentService.delete_analysis_result "qiskit.providers.ibmq.experiment.ExperimentService.delete_analysis_result")(result) | Delete an analysis result. |
|
||
| [`delete_experiment`](#qiskit.providers.ibmq.experiment.ExperimentService.delete_experiment "qiskit.providers.ibmq.experiment.ExperimentService.delete_experiment")(experiment) | Delete an experiment. |
|
||
| [`delete_plot`](#qiskit.providers.ibmq.experiment.ExperimentService.delete_plot "qiskit.providers.ibmq.experiment.ExperimentService.delete_plot")(experiment, plot\_name) | Delete an experiment plot. |
|
||
| [`device_components`](#qiskit.providers.ibmq.experiment.ExperimentService.device_components "qiskit.providers.ibmq.experiment.ExperimentService.device_components")(\[backend\_name]) | Return the device components. |
|
||
| [`experiments`](#qiskit.providers.ibmq.experiment.ExperimentService.experiments "qiskit.providers.ibmq.experiment.ExperimentService.experiments")(\[limit, backend\_name, type, …]) | Retrieve all experiments, with optional filtering. |
|
||
| [`retrieve_analysis_result`](#qiskit.providers.ibmq.experiment.ExperimentService.retrieve_analysis_result "qiskit.providers.ibmq.experiment.ExperimentService.retrieve_analysis_result")(result\_id) | Retrieve an analysis result. |
|
||
| [`retrieve_experiment`](#qiskit.providers.ibmq.experiment.ExperimentService.retrieve_experiment "qiskit.providers.ibmq.experiment.ExperimentService.retrieve_experiment")(experiment\_id) | Retrieve an experiment. |
|
||
| [`retrieve_plot`](#qiskit.providers.ibmq.experiment.ExperimentService.retrieve_plot "qiskit.providers.ibmq.experiment.ExperimentService.retrieve_plot")(experiment, plot\_name\[, file\_name]) | Retrieve an experiment plot. |
|
||
| [`update_analysis_result`](#qiskit.providers.ibmq.experiment.ExperimentService.update_analysis_result "qiskit.providers.ibmq.experiment.ExperimentService.update_analysis_result")(result) | Update an analysis result. |
|
||
| [`update_experiment`](#qiskit.providers.ibmq.experiment.ExperimentService.update_experiment "qiskit.providers.ibmq.experiment.ExperimentService.update_experiment")(experiment) | Update an experiment. |
|
||
| [`update_plot`](#qiskit.providers.ibmq.experiment.ExperimentService.update_plot "qiskit.providers.ibmq.experiment.ExperimentService.update_plot")(experiment, plot, plot\_name) | Update an experiment plot. |
|
||
| [`upload_analysis_result`](#qiskit.providers.ibmq.experiment.ExperimentService.upload_analysis_result "qiskit.providers.ibmq.experiment.ExperimentService.upload_analysis_result")(result) | Upload an analysis result. |
|
||
| [`upload_experiment`](#qiskit.providers.ibmq.experiment.ExperimentService.upload_experiment "qiskit.providers.ibmq.experiment.ExperimentService.upload_experiment")(experiment) | Upload a new experiment. |
|
||
| [`upload_plot`](#qiskit.providers.ibmq.experiment.ExperimentService.upload_plot "qiskit.providers.ibmq.experiment.ExperimentService.upload_plot")(experiment, plot\[, plot\_name]) | Upload an experiment plot. |
|
||
|
||
### analysis\_results
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.analysis_results" signature="analysis_results(limit=10, backend_name=None, device_components=None, experiment_id=None, result_type=None, quality=None, verified=None)">
|
||
Retrieve all analysis results, with optional filtering.
|
||
|
||
**Parameters**
|
||
|
||
* **limit** (`Optional`\[`int`]) – Number of analysis results to retrieve.
|
||
* **backend\_name** (`Optional`\[`str`]) – Backend name used for filtering.
|
||
* **device\_components** (`Optional`\[`List`\[`str`]]) – Filter by device components. An analysis result’s device components must match this list exactly for it to be included.
|
||
* **experiment\_id** (`Optional`\[`str`]) – Experiment ID used for filtering.
|
||
* **result\_type** (`Optional`\[`str`]) – Analysis result type used for filtering.
|
||
* **quality** (`Optional`\[`List`\[`Tuple`\[`str`, `Union`\[`str`, `ResultQuality`]]]]) – Quality value used for filtering. Each element in this list is a tuple of an operator and a value. The operator is one of `lt`, `le`, `gt`, `ge`, and `eq`. The value is one of the `ResultQuality` values. For example, `analysis_results(quality=[('ge', 'Bad'), ('lt', 'Good')])` will return all analysis results with a quality of `Bad` and `No Information`.
|
||
* **verified** (`Optional`\[`bool`]) – Indicates whether this result has been verified..
|
||
|
||
**Return type**
|
||
|
||
`List`\[`AnalysisResult`]
|
||
|
||
**Returns**
|
||
|
||
A list of analysis results.
|
||
|
||
**Raises**
|
||
|
||
**ValueError** – If an invalid parameter value is specified.
|
||
</Function>
|
||
|
||
### backends
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.backends" signature="backends()">
|
||
Return a list of backends.
|
||
|
||
**Return type**
|
||
|
||
`List`\[`Dict`]
|
||
|
||
**Returns**
|
||
|
||
A list of backends.
|
||
</Function>
|
||
|
||
### delete\_analysis\_result
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.delete_analysis_result" signature="delete_analysis_result(result)">
|
||
Delete an analysis result.
|
||
|
||
**Parameters**
|
||
|
||
**result** (`Union`\[`AnalysisResult`, `str`]) – The `AnalysisResult` object or the analysis result UUID.
|
||
|
||
<Admonition title="Note" type="note">
|
||
This method prompts for confirmation and requires a response before proceeding.
|
||
</Admonition>
|
||
|
||
**Return type**
|
||
|
||
`Optional`\[`AnalysisResult`]
|
||
|
||
**Returns**
|
||
|
||
The deleted analysis result.
|
||
</Function>
|
||
|
||
### delete\_experiment
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.delete_experiment" signature="delete_experiment(experiment)">
|
||
Delete an experiment.
|
||
|
||
**Parameters**
|
||
|
||
**experiment** (`Union`\[`Experiment`, `str`]) – The `Experiment` object or the experiment ID.
|
||
|
||
<Admonition title="Note" type="note">
|
||
This method prompts for confirmation and requires a response before proceeding.
|
||
</Admonition>
|
||
|
||
**Return type**
|
||
|
||
`Optional`\[`Experiment`]
|
||
|
||
**Returns**
|
||
|
||
Deleted experiment.
|
||
</Function>
|
||
|
||
### delete\_plot
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.delete_plot" signature="delete_plot(experiment, plot_name)">
|
||
Delete an experiment plot.
|
||
|
||
<Admonition title="Note" type="note">
|
||
This method prompts for confirmation and requires a response before proceeding.
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
* **experiment** (`Union`\[`Experiment`, `str`]) – The `Experiment` object or the experiment UUID.
|
||
* **plot\_name** (`str`) – Name of the plot.
|
||
|
||
**Return type**
|
||
|
||
`None`
|
||
</Function>
|
||
|
||
### device\_components
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.device_components" signature="device_components(backend_name=None)">
|
||
Return the device components.
|
||
|
||
**Parameters**
|
||
|
||
**backend\_name** (`Optional`\[`str`]) – Name of the backend whose components are to be retrieved.
|
||
|
||
**Return type**
|
||
|
||
`List`\[`DeviceComponent`]
|
||
|
||
**Returns**
|
||
|
||
A list of device components.
|
||
</Function>
|
||
|
||
### experiments
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.experiments" signature="experiments(limit=10, backend_name=None, type=None, start_datetime=None, end_datetime=None, device_components=None, tags=None, tags_operator='OR', hub=None, group=None, project=None, exclude_public=False, public_only=False, exclude_mine=False, mine_only=False)">
|
||
Retrieve all experiments, with optional filtering.
|
||
|
||
By default, results returned are as inclusive as possible. For example, if you don’t specify any filters, all experiments visible to you are returned. This includes your own experiments as well as those shared with you, from all providers you have access to (not just from the provider you used to invoke this experiment service).
|
||
|
||
**Parameters**
|
||
|
||
* **limit** (`Optional`\[`int`]) – Number of experiments to retrieve. `None` indicates no limit.
|
||
|
||
* **backend\_name** (`Optional`\[`str`]) – Backend name used for filtering.
|
||
|
||
* **type** (`Optional`\[`str`]) – Experiment type used for filtering.
|
||
|
||
* **start\_datetime** (`Optional`\[`datetime`]) – Filter by the given start timestamp, in local time. This is used to find experiments whose start date/time is after (greater than or equal to) this local timestamp.
|
||
|
||
* **end\_datetime** (`Optional`\[`datetime`]) – Filter by the given end timestamp, in local time. This is used to find experiments whose start date/time is before (less than or equal to) this local timestamp.
|
||
|
||
* **device\_components** (`Optional`\[`List`\[`str`]]) – Filter by device components. An experiment must have analysis results with device components matching the given list exactly to be included.
|
||
|
||
* **tags** (`Optional`\[`List`\[`str`]]) – Filter by tags assigned to experiments.
|
||
|
||
* **tags\_operator** (`Optional`\[`str`]) –
|
||
|
||
Logical operator to use when filtering by job tags. Valid values are “AND” and “OR”:
|
||
|
||
> * If “AND” is specified, then an experiment must have all of the tags specified in tags to be included.
|
||
> * If “OR” is specified, then an experiment only needs to have any of the tags specified in tags to be included.
|
||
|
||
* **hub** (`Optional`\[`str`]) – Filter by hub.
|
||
|
||
* **group** (`Optional`\[`str`]) – Filter by hub and group. hub must also be specified if group is.
|
||
|
||
* **project** (`Optional`\[`str`]) – Filter by hub, group, and project. hub and group must also be specified if project is.
|
||
|
||
* **exclude\_public** (`Optional`\[`bool`]) – If `True`, experiments with `share_level=public` (that is, experiments visible to all users) will not be returned. Cannot be `True` if public\_only is `True`.
|
||
|
||
* **public\_only** (`Optional`\[`bool`]) – If `True`, only experiments with `share_level=public` (that is, experiments visible to all users) will be returned. Cannot be `True` if exclude\_public is `True`.
|
||
|
||
* **exclude\_mine** (`Optional`\[`bool`]) – If `True`, experiments where I am the owner will not be returned. Cannot be `True` if mine\_only is `True`.
|
||
|
||
* **mine\_only** (`Optional`\[`bool`]) – If `True`, only experiments where I am the owner will be returned. Cannot be `True` if exclude\_mine is `True`.
|
||
|
||
**Return type**
|
||
|
||
`List`\[`Experiment`]
|
||
|
||
**Returns**
|
||
|
||
A list of experiments.
|
||
|
||
**Raises**
|
||
|
||
**ValueError** – If an invalid parameter value is specified.
|
||
</Function>
|
||
|
||
### retrieve\_analysis\_result
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.retrieve_analysis_result" signature="retrieve_analysis_result(result_id)">
|
||
Retrieve an analysis result.
|
||
|
||
**Parameters**
|
||
|
||
**result\_id** (`str`) – Analysis result UUID.
|
||
|
||
**Return type**
|
||
|
||
`AnalysisResult`
|
||
|
||
**Returns**
|
||
|
||
Retrieved analysis result.
|
||
|
||
**Raises**
|
||
|
||
* **AnalysisResultNotFoundError** – If the analysis result is not found.
|
||
* **RequestsApiError** – If an unexpected error occurred when retrieving analysis result from the server.
|
||
</Function>
|
||
|
||
### retrieve\_experiment
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.retrieve_experiment" signature="retrieve_experiment(experiment_id)">
|
||
Retrieve an experiment.
|
||
|
||
**Parameters**
|
||
|
||
**experiment\_id** (`str`) – Experiment uuid.
|
||
|
||
**Return type**
|
||
|
||
`Experiment`
|
||
|
||
**Returns**
|
||
|
||
Retrieved experiment.
|
||
|
||
**Raises**
|
||
|
||
* **ExperimentNotFoundError** – If the experiment is not found.
|
||
* **RequestsApiError** – If an unexpected error occurred when retrieving experiment from the server.
|
||
</Function>
|
||
|
||
### retrieve\_plot
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.retrieve_plot" signature="retrieve_plot(experiment, plot_name, file_name=None)">
|
||
Retrieve an experiment plot.
|
||
|
||
**Parameters**
|
||
|
||
* **experiment** (`Union`\[`Experiment`, `str`]) – The `Experiment` object or the experiment UUID.
|
||
* **plot\_name** (`str`) – Name of the plot.
|
||
* **file\_name** (`Optional`\[`str`]) – Name of the local file to save the plot to. If `None`, the content of the plot is returned instead.
|
||
|
||
**Return type**
|
||
|
||
`Union`\[`int`, `bytes`]
|
||
|
||
**Returns**
|
||
|
||
The size of the plot if file\_name is specified. Otherwise the content of the plot in bytes.
|
||
|
||
**Raises**
|
||
|
||
* **PlotNotFoundError** – If the plot is not found.
|
||
* **RequestsApiError** – If an unexpected error occurred when retrieving plot from the server.
|
||
</Function>
|
||
|
||
### update\_analysis\_result
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.update_analysis_result" signature="update_analysis_result(result)">
|
||
Update an analysis result.
|
||
|
||
**Parameters**
|
||
|
||
**result** (`AnalysisResult`) – The analysis result to update.
|
||
|
||
**Return type**
|
||
|
||
`None`
|
||
</Function>
|
||
|
||
### update\_experiment
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.update_experiment" signature="update_experiment(experiment)">
|
||
Update an experiment.
|
||
|
||
<Admonition title="Note" type="note">
|
||
Only the following experiment attributes can be updated:
|
||
|
||
> * end\_datetime
|
||
> * share\_level (visibility)
|
||
> * notes (use empty string to clear notes)
|
||
</Admonition>
|
||
|
||
**Parameters**
|
||
|
||
**experiment** (`Experiment`) – Experiment to be updated.
|
||
|
||
**Return type**
|
||
|
||
`None`
|
||
</Function>
|
||
|
||
### update\_plot
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.update_plot" signature="update_plot(experiment, plot, plot_name)">
|
||
Update an experiment plot.
|
||
|
||
**Parameters**
|
||
|
||
* **experiment** (`Union`\[`Experiment`, `str`]) – The `Experiment` object or the experiment UUID.
|
||
* **plot** (`Union`\[`str`, `bytes`]) – Name of the plot file or plot data to upload.
|
||
* **plot\_name** (`str`) – Name of the plot to update.
|
||
|
||
**Return type**
|
||
|
||
`Dict`
|
||
|
||
**Returns**
|
||
|
||
A dictionary with name and size of the uploaded plot.
|
||
</Function>
|
||
|
||
### upload\_analysis\_result
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.upload_analysis_result" signature="upload_analysis_result(result)">
|
||
Upload an analysis result.
|
||
|
||
**Parameters**
|
||
|
||
**result** (`AnalysisResult`) – The analysis result to upload.
|
||
|
||
**Return type**
|
||
|
||
`None`
|
||
</Function>
|
||
|
||
### upload\_experiment
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.upload_experiment" signature="upload_experiment(experiment)">
|
||
Upload a new experiment.
|
||
|
||
**Parameters**
|
||
|
||
**experiment** (`Experiment`) – The experiment to upload.
|
||
|
||
**Return type**
|
||
|
||
`None`
|
||
</Function>
|
||
|
||
### upload\_plot
|
||
|
||
<Function id="qiskit.providers.ibmq.experiment.ExperimentService.upload_plot" signature="upload_plot(experiment, plot, plot_name=None)">
|
||
Upload an experiment plot.
|
||
|
||
**Parameters**
|
||
|
||
* **experiment** (`Union`\[`Experiment`, `str`]) – The `Experiment` object or the experiment UUID.
|
||
* **plot** (`Union`\[`str`, `bytes`]) – Name of the plot file or plot data to upload.
|
||
* **plot\_name** (`Optional`\[`str`]) – Name of the plot. If `None`, the plot file name, if given, or a generated name is used.
|
||
|
||
**Return type**
|
||
|
||
`Dict`
|
||
|
||
**Returns**
|
||
|
||
A dictionary with name and size of the uploaded plot.
|
||
</Function>
|
||
</Class>
|
||
|