IBMExperimentService

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

• IBMExperimentEntryNotFound – If the analysis result does not exist.
• IBMQApiError – If the request to the server failed.

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.

IBMExperimentService.backends()

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

Return type

List[Dict]

Returns

A list of backends.

IBMExperimentService.create_analysis_result(experiment_id, result_data, result_type, device_components=None, tags=None, quality=ResultQuality.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.

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

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

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

Store a new figure in the database.

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

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

IBMExperimentService.delete_analysis_result(result_id)

Delete an analysis result.

Parameters

result_id (str) – Analysis result ID.

Raises

IBMQApiError – If the request to the server failed.

Return type

None

IBMExperimentService.delete_experiment(experiment_id)

Delete an experiment.

Parameters

experiment_id (str) – Experiment ID.

Raises

IBMQApiError – If the request to the server failed.

Return type

None

IBMExperimentService.delete_figure(experiment_id, figure_name)

Delete an experiment plot.

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

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.

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

• IBMExperimentEntryNotFound – If the experiment does not exist.
• IBMQApiError – If the request to the server failed.

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.

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

• IBMExperimentEntryNotFound – If the figure does not exist.
• IBMQApiError – If the request to the server failed.

IBMExperimentService.save_preferences(auto_save=None)

Stores experiment preferences on disk.

Parameters

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

Return type

None

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

• IBMExperimentEntryNotFound – If the analysis result does not exist.
• IBMQApiError – If the request to the server failed.

Return type

None

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

• IBMExperimentEntryNotFound – If the experiment does not exist.
• IBMQApiError – If the request to the server failed.

Return type

None

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

• IBMExperimentEntryNotFound – If the figure does not exist.
• IBMQApiError – If the request to the server failed.

Return saved experiment preferences.

Returns

The experiment preferences.

Return type

Dict