Skip to main contentIBM Quantum Documentation
You are viewing the API reference for an old version of Qiskit SDK. Switch to latest version

IBMExperimentService

IBMExperimentService(provider) GitHub(opens in a new tab)

Bases: object

Provides experiment related services.

This class is the main interface to invoke IBM Quantum experiment service, which allows you to create, delete, update, query, and retrieve experiments, experiment figures, and analysis results. The experiment attribute of AccountProvider is an instance of this class, and the main syntax for using the service is provider.experiment.<action>. For example:

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='ibmq_athens')
 
# Retrieve a specific experiment using its ID.
experiment = provider.experiment.experiment(EXPERIMENT_ID)
 
# Upload a new experiment.
new_experiment_id = provider.experiment.create_experiment(
    experiment_type="T1",
    backend_name="ibmq_athens",
    metadata={"qubits": 5}
)
 
# Update an experiment.
provider.experiment.update_experiment(
    experiment_id=EXPERIMENT_ID,
    share_level="Group"
)
 
# Delete an experiment.
provider.experiment.delete_experiment(EXPERIMENT_ID)

Similar syntax applies to analysis results and experiment figures.

IBMExperimentService constructor.

Parameters

provider (AccountProvider) – IBM Quantum Experience account provider.


Methods

analysis_result

IBMExperimentService.analysis_result(result_id, json_decoder=<class 'json.decoder.JSONDecoder'>)

Retrieve a previously stored experiment.

Parameters

  • result_id (str) – Analysis result ID.
  • json_decoder (Type[JSONDecoder]) – Custom JSON decoder to use to decode the retrieved analysis result.

Return type

Dict

Returns

Retrieved analysis result.

Raises

analysis_results

IBMExperimentService.analysis_results(limit=10, json_decoder=<class 'json.decoder.JSONDecoder'>, device_components=None, device_components_operator=None, experiment_id=None, result_type=None, result_type_operator=None, backend_name=None, quality=None, verified=None, tags=None, tags_operator='OR', sort_by=None, **filters)

Retrieve all analysis results, with optional filtering.

Parameters

  • limit (Optional[int]) – Number of analysis results to retrieve.

  • json_decoder (Type[JSONDecoder]) – Custom JSON decoder to use to decode the retrieved analysis results.

  • device_components (Optional[List[Union[str, DeviceComponent]]]) – Filter by device components.

  • device_components_operator (Optional[str]) –

    Operator used when filtering by device components. Valid values are None and “contains”:

    • If None, an analysis result’s device components must match exactly for it to be included.
    • If “contains” is specified, an analysis result’s device components must contain at least the values specified by the device_components filter.
  • experiment_id (Optional[str]) – Experiment ID used for filtering.

  • result_type (Optional[str]) – Analysis result type used for filtering.

  • result_type_operator (Optional[str]) –

    Operator used when filtering by result type. Valid values are None and “like”:

    • If None is specified, an analysis result’s type value must match exactly for it to be included.
    • If “like” is specified, an analysis result’s type value must contain the value specified by result_type. For example, result_type="foo", result_type_operator="like" will match both foo1 and 1foo.
  • backend_name (Optional[str]) – Backend name used for filtering.

  • quality (Union[List[Union[ResultQuality, str]], ResultQuality, str, None]) – Quality value used for filtering. If a list is given, analysis results whose quality value is in the list will be included.

  • verified (Optional[bool]) – Indicates whether this result has been verified..

  • tags (Optional[List[str]]) – Filter by tags assigned to analysis results. This can be used with tags_operator for granular filtering.

  • tags_operator (Optional[str]) –

    Logical operator to use when filtering by tags. Valid values are “AND” and “OR”:

    • If “AND” is specified, then an analysis result must have all of the tags specified in tags to be included.
    • If “OR” is specified, then an analysis result only needs to have any of the tags specified in tags to be included.
  • sort_by (Union[str, List[str], None]) – Specifies how the output should be sorted. This can be a single sorting option or a list of options. Each option should contain a sort key and a direction. Valid sort keys are “creation_datetime”, “device_components”, and “result_type”. Valid directions are “asc” for ascending or “desc” for descending. For example, sort_by=["result_type: asc", "creation_datetime:desc"] will return an output list that is first sorted by result type in ascending order, then by creation datetime by descending order. By default, analysis results are sorted by creation_datetime descending and result_id ascending.

  • **filters – Additional filtering keywords that are not supported and will be ignored.

Return type

List[Dict]

Returns

A list of analysis results. Each analysis result is a dictionary containing the retrieved analysis result.

Raises

  • ValueError – If an invalid parameter value is specified.
  • IBMQApiError – If the request to the server failed.

backends

IBMExperimentService.backends()

Return a list of backends that can be used for experiments.

Return type

List[Dict]

Returns

A list of backends.

create_analysis_result

IBMExperimentService.create_analysis_result(experiment_id, result_data, result_type, device_components=None, tags=None, quality=<ResultQuality.UNKNOWN: 'UNKNOWN'>, verified=False, result_id=None, chisq=None, json_encoder=<class 'json.encoder.JSONEncoder'>, **kwargs)

Create a new analysis result in the database.

Parameters

  • experiment_id (str) – ID of the experiment this result is for.
  • result_data (Dict) – Result data to be stored.
  • result_type (str) – Analysis result type.
  • device_components (Union[List[Union[str, DeviceComponent]], str, DeviceComponent, None]) – Target device components, such as qubits.
  • tags (Optional[List[str]]) – Tags to be associated with the analysis result.
  • quality (Union[ResultQuality, str]) – Quality of this analysis.
  • verified (bool) – Whether the result quality has been verified.
  • result_id (Optional[str]) – Analysis result ID. It must be in the uuid4 format. One will be generated if not supplied.
  • chisq (Optional[float]) – chi^2 decimal value of the fit.
  • json_encoder (Type[JSONEncoder]) – Custom JSON encoder to use to encode the analysis result.
  • kwargs (Any) – Additional analysis result attributes that are not supported and will be ignored.

Return type

str

Returns

Analysis result ID.

Raises

  • IBMExperimentEntryExists – If the analysis result already exits.
  • IBMQApiError – If the request to the server failed.

create_experiment

IBMExperimentService.create_experiment(experiment_type, backend_name, metadata=None, experiment_id=None, parent_id=None, job_ids=None, tags=None, notes=None, share_level=None, start_datetime=None, json_encoder=<class 'json.encoder.JSONEncoder'>, **kwargs)

Create a new experiment in the database.

Parameters

  • experiment_type (str) – Experiment type.

  • backend_name (str) – Name of the backend the experiment ran on.

  • metadata (Optional[Dict]) – Experiment metadata.

  • experiment_id (Optional[str]) – Experiment ID. It must be in the uuid4 format. One will be generated if not supplied.

  • parent_id (Optional[str]) – The experiment ID of the parent experiment. The parent experiment must exist, must be on the same backend as the child, and an experiment cannot be its own parent.

  • job_ids (Optional[List[str]]) – IDs of experiment jobs.

  • tags (Optional[List[str]]) – Tags to be associated with the experiment.

  • notes (Optional[str]) – Freeform notes about the experiment.

  • share_level (Union[str, ExperimentShareLevel, None]) –

    The level at which the experiment is shared. This determines who can view the experiment (but not update it). This defaults to “private” for new experiments. Possible values include:

    • private: The experiment is only visible to its owner (default)
    • project: The experiment is shared within its project
    • group: The experiment is shared within its group
    • hub: The experiment is shared within its hub
    • public: The experiment is shared publicly regardless of provider
  • start_datetime (Union[str, datetime, None]) – Timestamp when the experiment started, in local time zone.

  • json_encoder (Type[JSONEncoder]) – Custom JSON encoder to use to encode the experiment.

  • kwargs (Any) – Additional experiment attributes that are not supported and will be ignored.

Return type

str

Returns

Experiment ID.

Raises

create_figure

IBMExperimentService.create_figure(experiment_id, figure, figure_name=None, sync_upload=True)

Store a new figure in the database.

Note

Currently only SVG figures are supported.

Parameters

  • experiment_id (str) – ID of the experiment this figure is for.
  • figure (Union[str, bytes]) – Name of the figure file or figure data to store.
  • figure_name (Optional[str]) – Name of the figure. If None, the figure file name, if given, or a generated name is used.
  • sync_upload (bool) – If True, the plot will be uploaded synchronously. Otherwise the upload will be asynchronous.

Return type

Tuple[str, int]

Returns

A tuple of the name and size of the saved figure.

Raises

delete_analysis_result

IBMExperimentService.delete_analysis_result(result_id)

Delete an analysis result.

Parameters

result_id (str) – Analysis result ID.

Note

This method prompts for confirmation and requires a response before proceeding.

Raises

IBMQApiError – If the request to the server failed.

Return type

None

delete_experiment

IBMExperimentService.delete_experiment(experiment_id)

Delete an experiment.

Parameters

experiment_id (str) – Experiment ID.

Note

This method prompts for confirmation and requires a response before proceeding.

Raises

IBMQApiError – If the request to the server failed.

Return type

None

delete_figure

IBMExperimentService.delete_figure(experiment_id, figure_name)

Delete an experiment plot.

Note

This method prompts for confirmation and requires a response before proceeding.

Parameters

  • experiment_id (str) – Experiment ID.
  • figure_name (str) – Name of the figure.

Raises

IBMQApiError – If the request to the server failed.

Return type

None

device_components

IBMExperimentService.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

Union[Dict[str, List], List]

Returns

A list of device components if backend_name is specified. Otherwise a dictionary whose keys are backend names the values are lists of device components for the backends.

Raises

IBMQApiError – If the request to the server failed.

experiment

IBMExperimentService.experiment(experiment_id, json_decoder=<class 'json.decoder.JSONDecoder'>)

Retrieve a previously stored experiment.

Parameters

  • experiment_id (str) – Experiment ID.
  • json_decoder (Type[JSONDecoder]) – Custom JSON decoder to use to decode the retrieved experiment.

Return type

Dict

Returns

Retrieved experiment data.

Raises

experiments

IBMExperimentService.experiments(limit=10, json_decoder=<class 'json.decoder.JSONDecoder'>, device_components=None, device_components_operator=None, experiment_type=None, experiment_type_operator=None, backend_name=None, tags=None, tags_operator='OR', start_datetime_after=None, start_datetime_before=None, hub=None, group=None, project=None, exclude_public=False, public_only=False, exclude_mine=False, mine_only=False, parent_id=None, sort_by=None, **filters)

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.

  • json_decoder (Type[JSONDecoder]) – Custom JSON decoder to use to decode the retrieved experiments.

  • device_components (Optional[List[Union[str, DeviceComponent]]]) – Filter by device components.

  • device_components_operator (Optional[str]) –

    Operator used when filtering by device components. Valid values are None and “contains”:

    • If None, an analysis result’s device components must match exactly for it to be included.
    • If “contains” is specified, an analysis result’s device components must contain at least the values specified by the device_components filter.
  • experiment_type (Optional[str]) – Experiment type used for filtering.

  • experiment_type_operator (Optional[str]) –

    Operator used when filtering by experiment type. Valid values are None and “like”:

    • If None is specified, an experiment’s type value must match exactly for it to be included.
    • If “like” is specified, an experiment’s type value must contain the value specified by experiment_type. For example, experiment_type="foo", experiment_type_operator="like" will match both foo1 and 1foo.
  • backend_name (Optional[str]) – Backend name used for filtering.

  • 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.
  • start_datetime_after (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.

  • start_datetime_before (Optional[datetime]) – Filter by the given start timestamp, in local time. This is used to find experiments whose start date/time is before (less than or equal to) this local timestamp.

  • 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.

  • parent_id (Optional[str]) – Filter experiments by this parent experiment ID.

  • sort_by (Union[str, List[str], None]) – Specifies how the output should be sorted. This can be a single sorting option or a list of options. Each option should contain a sort key and a direction, separated by a semicolon. Valid sort keys are “start_datetime” and “experiment_type”. Valid directions are “asc” for ascending or “desc” for descending. For example, sort_by=["experiment_type:asc", "start_datetime:desc"] will return an output list that is first sorted by experiment type in ascending order, then by start datetime by descending order. By default, experiments are sorted by start_datetime descending and experiment_id ascending.

  • **filters – Additional filtering keywords that are not supported and will be ignored.

Return type

List[Dict]

Returns

A list of experiments. Each experiment is a dictionary containing the retrieved experiment data.

Raises

  • ValueError – If an invalid parameter value is specified.
  • IBMQApiError – If the request to the server failed.

figure

IBMExperimentService.figure(experiment_id, figure_name, file_name=None)

Retrieve an existing figure.

Parameters

  • experiment_id (str) – Experiment ID.
  • figure_name (str) – Name of the figure.
  • file_name (Optional[str]) – Name of the local file to save the figure to. If None, the content of the figure is returned instead.

Return type

Union[int, bytes]

Returns

The size of the figure if file_name is specified. Otherwise the content of the figure in bytes.

Raises

save_preferences

IBMExperimentService.save_preferences(auto_save=None)

Stores experiment preferences on disk.

Note

These are preferences passed to the applications that use this service and have no effect on the service itself.

For example, if auto_save is set to True, it tells the application, such as qiskit-experiments, that you prefer changes to be automatically saved. It is up to the application to implement the preferences.

Parameters

auto_save (Optional[bool]) – Automatically save the experiment.

Return type

None

update_analysis_result

IBMExperimentService.update_analysis_result(result_id, result_data=None, tags=None, quality=None, verified=None, chisq=None, json_encoder=<class 'json.encoder.JSONEncoder'>, **kwargs)

Update an existing analysis result.

Parameters

  • result_id (str) – Analysis result ID.
  • result_data (Optional[Dict]) – Result data to be stored.
  • quality (Union[ResultQuality, str, None]) – Quality of this analysis.
  • verified (Optional[bool]) – Whether the result quality has been verified.
  • tags (Optional[List[str]]) – Tags to be associated with the analysis result.
  • chisq (Optional[float]) – chi^2 decimal value of the fit.
  • json_encoder (Type[JSONEncoder]) – Custom JSON encoder to use to encode the analysis result.
  • kwargs (Any) – Additional analysis result attributes that are not supported and will be ignored.

Raises

Return type

None

update_experiment

IBMExperimentService.update_experiment(experiment_id, metadata=None, job_ids=None, notes=None, tags=None, share_level=None, end_datetime=None, json_encoder=<class 'json.encoder.JSONEncoder'>, **kwargs)

Update an existing experiment.

Parameters

  • experiment_id (str) – Experiment ID.

  • metadata (Optional[Dict]) – Experiment metadata.

  • job_ids (Optional[List[str]]) – IDs of experiment jobs.

  • notes (Optional[str]) – Freeform notes about the experiment.

  • tags (Optional[List[str]]) – Tags to be associated with the experiment.

  • share_level (Union[str, ExperimentShareLevel, None]) –

    The level at which the experiment is shared. This determines who can view the experiment (but not update it). This defaults to “private” for new experiments. Possible values include:

    • private: The experiment is only visible to its owner (default)
    • project: The experiment is shared within its project
    • group: The experiment is shared within its group
    • hub: The experiment is shared within its hub
    • public: The experiment is shared publicly regardless of provider
  • end_datetime (Union[str, datetime, None]) – Timestamp for when the experiment ended, in local time.

  • json_encoder (Type[JSONEncoder]) – Custom JSON encoder to use to encode the experiment.

  • kwargs (Any) – Additional experiment attributes that are not supported and will be ignored.

Raises

Return type

None

update_figure

IBMExperimentService.update_figure(experiment_id, figure, figure_name, sync_upload=True)

Update an existing figure.

Parameters

  • experiment_id (str) – Experiment ID.
  • figure (Union[str, bytes]) – Name of the figure file or figure data to store.
  • figure_name (str) – Name of the figure.
  • sync_upload (bool) – If True, the plot will be uploaded synchronously. Otherwise the upload will be asynchronous.

Return type

Tuple[str, int]

Returns

A tuple of the name and size of the saved figure.

Raises


Attributes

preferences

Return saved experiment preferences.

Note

These are preferences passed to the applications that use this service and have no effect on the service itself. It is up to the application, such as qiskit-experiments to implement the preferences.

Returns

The experiment preferences.

Return type

Dict

Was this page helpful?