Note

This is the documentation for the current state of the development branch of Qiskit Experiments. The documentation or APIs here can change prior to being released.

ExperimentData

class ExperimentData(experiment=None, backend=None, service=None, provider=None, parent_id=None, job_ids=None, child_data=None, verbose=True, db_data=None, start_datetime=None, **kwargs)[source]

Experiment data container class.

Note

Saving experiment data to the cloud database is currently a limited access feature. You can check whether you have access by logging into the IBM Quantum interface and seeing if you can see the database.

This class handles the following:

  1. Storing the data related to an experiment: raw data, metadata, analysis results, and figures

  2. Managing jobs and adding data from jobs automatically

  3. Saving and loading data from the database service

The field db_data is a dataclass (ExperimentDataclass) containing all the data that can be stored in the database and loaded from it, and as such is subject to strict conventions.

Other data fields can be added and used freely, but they won’t be saved to the database.

Initialize experiment data.

Parameters:

  • experiment (Optional['BaseExperiment']) – Experiment object that generated the data.

  • backend (Optional[Backend]) – Backend the experiment runs on. This overrides the backend in the experiment object.

  • service (Optional[IBMExperimentService]) – The service that stores the experiment results to the database

  • provider (Optional[Provider]) – The provider used for the experiments (can be used to automatically obtain the service)

  • parent_id (Optional[str]) – ID of the parent experiment data in the setting of a composite experiment

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

  • child_data (Optional[List[ExperimentData]]) – List of child experiment data.

  • verbose (Optional[bool]) – Whether to print messages.

  • db_data (Optional[ExperimentDataclass]) – A prepared ExperimentDataclass of the experiment info. This overrides other db parameters.

  • start_datetime (Optional[datetime]) – The time when the experiment started running. If none, defaults to the current time.

Additional info:

In order to save the experiment data to the cloud service, the class needs access to the experiment service provider. It can be obtained via three different methods, given here by priority:

  1. Passing it directly via the service parameter.

  2. Implicitly obtaining it from the provider parameter.

  3. Implicitly obtaining it from the backend parameter, using that backend’s provider.

Attributes

auto_save

Return current auto-save option.

Returns:

Whether changes will be automatically saved.

backend

Return backend.

Returns:

Backend.

backend_name

Return the backend’s name

completion_times

Returns the completion times of the jobs.

creation_datetime

Return the creation datetime of this experiment data.

Returns:

The timestamp when this experiment data was saved to the cloud service in the local timezone.

end_datetime

Return the end datetime of this experiment data.

The end datetime is the time the latest job data was added without errors; this can change as more jobs finish.

Returns:

The timestamp when the last job of this experiment finished in the local timezone.

experiment

Return the experiment for this data.

Returns:

the experiment object.

Return type:

BaseExperiment

experiment_id

Return experiment ID

Returns:

Experiment ID.

experiment_type

Return experiment type

Returns:

Experiment type.

figure_names

Return names of the figures associated with this experiment.

Returns:

Names of figures associated with this experiment.

group

Return the group of this experiment data.

Returns:

The group of this experiment data.

hgp

Returns Hub/Group/Project data as a formatted string

hub

Return the hub of this experiment data.

Returns:

The hub of this experiment data.

job_ids

Return experiment job IDs.

Returns: IDs of jobs submitted for this experiment.

metadata

Return experiment metadata.

Returns:

Experiment metadata.

notes

Return experiment notes.

Returns:

Experiment notes.

parent_id

Return parent experiment ID

Returns:

Parent ID.

project

Return the project of this experiment data.

Returns:

The project of this experiment data.

provider

Return the backend provider.

Returns:

Provider that is used to obtain backends and job data.

running_time

Return the running time of this experiment data.

The running time is the time the latest successful job started running on the remote quantum machine. This can change as more jobs finish.

service

Return the database service.

Returns:

Service that can be used to access this experiment in a database.

share_level

Return the share level for this experiment

Returns:

Experiment share level.

source

Return the class name and version.

start_datetime

Return the start datetime of this experiment data.

Returns:

The timestamp when this experiment began running in the local timezone.

tags

Return tags assigned to this experiment data.

Returns:

A list of tags assigned to this experiment data.

updated_datetime

Return the update datetime of this experiment data.

Returns:

The timestamp when this experiment data was last updated in the service in the local timezone.

Methods

add_analysis_callback(callback, **kwargs)[source]

Add analysis callback for running after experiment data jobs are finished.

This method adds the callback function to a queue to be run asynchronously after completion of any running jobs, or immediately if no running jobs. If this method is called multiple times the callback functions will be executed in the order they were added.

Parameters:

  • callback (Callable) – Callback function invoked when job finishes successfully. The callback function will be called as callback(expdata, **kwargs) where expdata is this DbExperimentData object, and kwargs are any additional keyword arguments passed to this method.

  • **kwargs (Any) – Keyword arguments to be passed to the callback function.

add_analysis_results(results=None, *, name=None, value=None, quality=None, components=None, experiment=None, experiment_id=None, result_id=None, tags=None, backend=None, run_time=None, created_time=None, **extra_values)[source]

Save the analysis result.

Deprecated since version 0.6_pending: qiskit_experiments.framework.experiment_data.ExperimentData.add_analysis_results()’s argument results is pending deprecation as of qiskit-experiments 0.6. It will be marked deprecated in a future release, and then removed no earlier than 3 months after the release date. Use keyword arguments rather than creating an AnalysisResult object.

Parameters:

  • results (AnalysisResult | List[AnalysisResult] | None) – Analysis results to be saved.

  • name (str | None) – Name of the result entry.

  • value (Any | None) – Analyzed quantity.

  • quality (str | None) – Quality of the data.

  • components (List[DeviceComponent] | None) – Associated device components.

  • experiment (str | None) – String identifier of the associated experiment.

  • experiment_id (str | None) – ID of the associated experiment.

  • result_id (str | None) – ID of this analysis entry. If not set a random UUID is generated.

  • tags (List[str] | None) – List of arbitrary tags.

  • backend (str | None) – Name of associated backend.

  • run_time (datetime | None) – The date time when the experiment started to run on the device.

  • created_time (datetime | None) – The date time when this analysis is performed.

  • extra_values – Arbitrary keyword arguments for supplementary information. New dataframe columns are created in the analysis result table with added keys.

add_artifacts(artifacts, overwrite=False)[source]

Add artifacts to experiment. The artifact ID must be unique.

Parameters:

  • artifacts (ArtifactData | list[ArtifactData]) – Artifact or list of artifacts to be added.

  • overwrite (bool) – Whether to overwrite the existing artifact.

add_child_data(experiment_data)[source]

Add child experiment data to the current experiment data

add_data(data)[source]

Add experiment data.

Parameters:

data (Result | List[Result] | Dict | List[Dict]) –

Experiment data to add. Several types are accepted for convenience:

  • Result: Add data from this Result object.

  • List[Result]: Add data from the Result objects.

  • Dict: Add this data.

  • List[Dict]: Add this list of data.

Raises:

TypeError – If the input data type is invalid.

add_figures(figures, figure_names=None, overwrite=False, save_figure=None)[source]

Add the experiment figure.

Parameters:

  • figures (str | bytes | Figure | FigureData | List[str | bytes | Figure | FigureData]) – Paths of the figure files or figure data.

  • figure_names (str | List[str] | None) – Names of the figures. If None, use the figure file names, if given, or a generated name of the format experiment_type, figure index, first 5 elements of device_components, and first 8 digits of the experiment ID connected by underscores, such as T1_Q0_0123abcd.svg. If figures is a list, then figure_names must also be a list of the same length or None.

  • overwrite (bool) – Whether to overwrite the figure if one already exists with the same name. By default, overwrite is False and the figure will be renamed with an incrementing numerical suffix. For example, trying to save figure.svg when figure.svg already exists will save it as figure-1.svg, and trying to save figure-1.svg when figure-1.svg already exists will save it as figure-2.svg.

  • save_figure (bool | None) – Whether to save the figure in the database. If None, the auto-save attribute is used.

Returns:

Figure names in SVG format.

Raises:

ValueError – If an input parameter has an invalid value.

Return type:

str | List[str]

add_jobs(jobs, timeout=None)[source]

Add experiment data.

Parameters:

  • jobs (Job | List[Job] | BasePrimitiveJob | List[BasePrimitiveJob]) – The Job or list of Jobs to add result data from.

  • timeout (float | None) – Optional, time in seconds to wait for all jobs to finish before cancelling them.

Raises:

TypeError – If the input data type is invalid.

Note

If a timeout is specified the cancel_jobs() method will be called after timing out to attempt to cancel any unfinished jobs.

If you want to wait for jobs without cancelling, use the timeout kwarg of block_for_results() instead.

add_tags_recursive(tags2add)[source]

Add tags to this experiment itself and its descendants

Parameters:

tags (tags2add - the tags that will be added to the existing)

analysis_errors()[source]

Return any errors encountered during analysis callbacks.

Return type:

str

analysis_results(index=None, refresh=False, block=True, timeout=None, columns='default', dataframe=False)[source]

Return analysis results associated with this experiment.

Caution

Retrieving analysis results by a numerical index, whether an integer or a slice, is deprecated as of 0.6 and will be removed in a future release. Use the name or ID of the result instead.

When this method is called with dataframe=True you will receive matched result entries with the index condition in the dataframe format. You can access a certain entry value by specifying its row index by either row number or short index string. For example,

results = exp_data.analysis_results("res1", dataframe=True)

print(results)

          name  experiment  components  value  quality  backend          run_time
7dd286f4  res1       MyExp    [Q0, Q1]      1     good    test1  2024-02-06 13:46
f62042a7  res1       MyExp    [Q2, Q3]      2     good    test1  2024-02-06 13:46

Getting the first result value with a row number (iloc).

value = results.iloc[0].value

Getting the first result value with a short index (loc).

value = results.loc["7dd286f4"]

See the pandas DataFrame documentation for the tips about data handling.

Deprecated since version 0.6_pending: Setting dataframe to False in analysis_results is pending deprecation as of qiskit-experiments 0.6. It will be marked deprecated in a future release, and then removed no earlier than 3 months after the release date.

Parameters:

  • index (int | slice | str | None) –

    Index of the analysis result to be returned. Several types are accepted for convenience:

    • None: Return all analysis results.

    • int: Specific index of the analysis results.

    • slice: A list slice of indexes.

    • str: ID or name of the analysis result.

  • refresh (bool) – Retrieve the latest analysis results from the server, if an experiment service is available.

  • block (bool) – If True, block for any analysis callbacks to finish running.

  • timeout (float | None) – max time in seconds to wait for analysis callbacks to finish running.

  • columns (str | list[str]) –

    Specifying a set of columns to return. You can pass a list of each column name to return, otherwise builtin column groups are available:

    • all: Return all columns, including metadata to communicate with the experiment service, such as entry IDs.

    • default: Return columns including analysis result with supplementary information about experiment.

    • minimal: Return only analysis subroutine returns.

  • dataframe (bool) – Set to True to return analysis results in the dataframe format.

Returns:

A copy of analysis results data. Updating the returned object doesn’t mutate the original dataset.

Raises:

ExperimentEntryNotFound – If the entry cannot be found.

Return type:

AnalysisResult | list[AnalysisResult] | DataFrame

analysis_status()[source]

Return the data analysis post-processing status.

Possible return values for AnalysisStatus are

  • ERROR - if any analysis callback incurred an error

  • CANCELLED - if any analysis callback is cancelled.

  • RUNNING - if any analysis callback is actively running.

  • QUEUED - if any analysis callback is queued.

  • DONE - if all analysis callbacks have successfully run.

Returns:

Then analysis status.

Return type:

AnalysisStatus

artifacts(artifact_key=None)[source]

Return specified artifact data.

Parameters:

  • artifact_key (int | str) – UID or name of the artifact. Supplying a numerical index

  • deprecated. (is)

Returns:

A list of specified artifact data.

Return type:

ArtifactData | list[ArtifactData]

block_for_results(timeout=None)[source]

Block until all pending jobs and analysis callbacks finish.

Parameters:

timeout (float | None) – Timeout in seconds for waiting for results.

Returns:

The experiment data with finished jobs and post-processing.

Return type:

ExperimentData

cancel()[source]

Attempt to cancel any running jobs and queued analysis callbacks.

Note

A running analysis callback cannot be cancelled.

Returns:

True if all jobs and analysis are successfully cancelled, otherwise false.

Return type:

bool

cancel_analysis(ids=None)[source]

Cancel any queued analysis callbacks.

Note

A currently running analysis callback cannot be cancelled.

Parameters:

ids (str | list[str] | None) – Analysis callback(s) to cancel. If None all non-finished analysis will be cancelled.

Returns:

True if the specified analysis callbacks were successfully cancelled otherwise false.

Return type:

bool

cancel_jobs(ids=None)[source]

Cancel any running jobs.

Parameters:

ids (str | list[str] | None) – Job(s) to cancel. If None all non-finished jobs will be cancelled.

Returns:

True if the specified jobs were successfully cancelled otherwise false.

Return type:

bool

child_data(index=None)[source]

Return child experiment data.

Parameters:

index (int | slice | str | None) –

Index of the child experiment data to be returned. Several types are accepted for convenience:

  • None: Return all child data.

  • int: Specific index of the child data.

  • slice: A list slice of indexes.

  • str: experiment ID of the child data.

Returns:

The requested single or list of child experiment data.

Raises:

QiskitError – If the index or ID of the child experiment data cannot be found.

Return type:

ExperimentData | List[ExperimentData]

copy(copy_results=True)[source]

Make a copy of the experiment data with a new experiment ID.

Parameters:

copy_results (bool) – If True copy the analysis results, figures, and artifacts into the returned container, along with the experiment data and metadata. If False only copy the experiment data and metadata.

Returns:

A copy of the experiment data object with the same data but different IDs.

Return type:

ExperimentData

data(index=None)[source]

Return the experiment data at the specified index.

Parameters:

index (int | slice | str | None) –

Index of the data to be returned. Several types are accepted for convenience:

  • None: Return all experiment data.

  • int: Specific index of the data.

  • slice: A list slice of data indexes.

  • str: ID of the job that produced the data.

Returns:

Experiment data.

Raises:

TypeError – If the input index has an invalid type.

Return type:

Dict | List[Dict]

delete_analysis_result(result_key)[source]

Delete the analysis result.

Parameters:

result_key (int | str) – ID or index of the analysis result to be deleted.

Returns:

Deleted analysis result IDs.

Raises:

ExperimentEntryNotFound – If analysis result not found or multiple entries are found.

Return type:

list[str]

delete_artifact(artifact_key)[source]

Delete specified artifact data.

Parameters:

artifact_key (int | str) – UID or name of the artifact. Deleting by index is deprecated.

Returns:

Deleted artifact ids.

Return type:

str | list[str]

delete_figure(figure_key)[source]

Add the experiment figure.

Parameters:

figure_key (str | int) – Name or index of the figure.

Returns:

Figure name.

Raises:

ExperimentEntryNotFound – If the figure is not found.

Return type:

str

errors()[source]

Return errors encountered during job and analysis execution.

Note

To display only job or analysis errors use the job_errors() or analysis_errors() methods.

Returns:

Experiment errors.

Return type:

str

figure(figure_key, file_name=None)[source]

Retrieve the specified experiment figure.

Parameters:

  • figure_key (str | int) – Name or index of the figure.

  • file_name (str | None) – Name of the local file to save the figure to. If None, the content of the figure is returned instead.

Returns:

The size of the figure if file_name is specified. Otherwise the content of the figure as a FigureData object.

Raises:

ExperimentEntryNotFound – If the figure cannot be found.

Return type:

int | FigureData

static get_service_from_backend(backend)[source]

Initializes the service from the backend data

static get_service_from_provider(provider)[source]

Initializes the service from the provider data

job_errors()[source]

Return any errors encountered in job execution.

Return type:

str

job_status()[source]

Return the experiment job execution status.

Possible return values for qiskit.providers.jobstatus.JobStatus are

  • ERROR - if any job incurred an error

  • CANCELLED - if any job is cancelled.

  • RUNNING - if any job is still running.

  • QUEUED - if any job is queued.

  • VALIDATING - if any job is being validated.

  • INITIALIZING - if any job is being initialized.

  • DONE - if all jobs are finished.

Note

If an experiment has status ERROR or CANCELLED there may still be pending or running jobs. In these cases it may be beneficial to call cancel_jobs() to terminate these remaining jobs.

Returns:

The job execution status.

Return type:

JobStatus

jobs()[source]

Return a list of jobs for the experiment

Return type:

List[Job]

classmethod load(experiment_id, service=None, provider=None)[source]

Load a saved experiment data from a database service.

Parameters:

  • experiment_id (str) – Experiment ID.

  • service (IBMExperimentService | None) – the database service.

  • provider (Provider | None) – an IBMProvider required for loading job data and can be used to initialize the service. When using qiskit-ibm-runtime, this is the QiskitRuntimeService and should not be confused with the experiment database service qiskit_ibm_experiment.IBMExperimentService().

Returns:

The loaded experiment data.

Raises:

ExperimentDataError – If not service nor provider were given.

Return type:

ExperimentData

remove_tags_recursive(tags2remove)[source]

Remove tags from this experiment itself and its descendants

Parameters:

tags (tags2remove - the tags that will be removed from the existing)

save(suppress_errors=True, max_workers=3, save_figures=True, save_artifacts=True, save_children=True)[source]

Save the experiment data to a database service.

Parameters:

  • suppress_errors (bool) – should the method catch exceptions (true) or pass them on, potentially aborting the experiment (false)

  • max_workers (int) – Maximum number of concurrent worker threads (default 3, maximum 10)

  • save_figures (bool) – Whether to save figures in the database or not

  • save_artifacts (bool) – Whether to save artifacts in the database

  • save_children (bool) – For composite experiments, whether to save children as well

Raises:

  • ExperimentDataSaveFailed – If no experiment database service

  • was found, or the experiment service failed to save –

Note

This saves the experiment metadata, all analysis results, and all figures. Depending on the number of figures and analysis results this operation could take a while.

To only update a previously saved experiments metadata (eg for additional tags or notes) use save_metadata().

save_metadata()[source]

Save this experiments metadata to a database service.

Note

This method does not save analysis results, figures, or artifacts. Use save() for general saving of all experiment data.

See qiskit.providers.experiment.IBMExperimentService.create_experiment() for fields that are saved.

status()[source]

Return the experiment status.

Possible return values for ExperimentStatus are

  • EMPTY - experiment data is empty

  • INITIALIZING - experiment jobs are being initialized

  • QUEUED - experiment jobs are queued

  • RUNNING - experiment jobs is actively running

  • CANCELLED - experiment jobs or analysis has been cancelled

  • POST_PROCESSING - experiment analysis is actively running

  • DONE - experiment jobs and analysis have successfully run

  • ERROR - experiment jobs or analysis incurred an error

Note

If an experiment has status ERROR there may still be pending or running jobs. In these cases it may be beneficial to call cancel_jobs() to terminate these remaining jobs.

Returns:

The experiment status.

Return type:

ExperimentStatus