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.

LocalExperimentService

class LocalExperimentService(db_dir=None)[source]

Provides local experiment database services.

This class provides a service for storing experiment data locally without connecting to a remote service. Data can be persisted to disk or kept only in memory.

Note

This class is designed for demonstration and testing purposes and will not scale well to storing many results. It stores all results in memory and writes all data out to disk at every save. It could serve as a reference for writing a more scalable system for saving experiments.

LocalExperimentService constructor.

Parameters:

db_dir (str | None) – The directory in which to place the database files. If None, results are saved in memory only and lost when the Python process ends.

Attributes

experiment_db_columns = ['experiment_id', 'parent_id', 'experiment_type', 'backend', 'tags', 'job_ids', 'share_level', 'metadata', 'figure_names', 'notes', 'hub', 'group', 'project', 'owner', 'creation_datetime', 'start_datetime', 'end_datetime', 'updated_datetime']
options

Return service options dictionary.

results_db_columns = ['result_id', 'experiment_id', 'result_type', 'result_data', 'device_components', 'quality', 'verified', 'tags', 'backend_name', 'creation_datetime', 'updated_datetime', 'chisq']

Methods

analysis_result(result_id, json_decoder=None)[source]

Retrieve a single analysis result from the database.

Parameters:

  • result_id (str) – Analysis result ID

  • json_decoder (type[JSONDecoder]) – Custom JSON decoder (unused in local service)

Returns:

Retrieved analysis result data

Raises:

ExperimentEntryNotFound – If the analysis result is not found

Return type:

DbAnalysisResultData

analysis_results(limit=None, backend_name=None, device_components=None, experiment_id=None, result_type=None, quality=None, verified=None, tags=None, created_at=None, json_decoder=None)[source]

Return a list of analysis results.

Parameters:

  • limit (int | None) – Number of analysis results to retrieve.

  • backend_name (str | None) – Name of the backend.

  • device_components (list[str] | None) – A list of device components used for filtering.

  • experiment_id (str | None) – Experiment UUID used for filtering.

  • result_type (str | None) – Analysis result type used for filtering.

  • quality (str | list[str] | None) – Quality value used for filtering.

  • verified (bool | None) – Indicates whether this result has been verified.

  • tags (list[str] | None) – Filter by tags assigned to analysis results.

  • created_at (list | None) – A list of timestamps used to filter by creation time.

  • json_decoder (type[JSONDecoder]) – Custom JSON decoder (unused in local service)

Returns:

A list of analysis results.

Raises:

ValueError – If the parameters are unsuitable for filtering

Return type:

list[DbAnalysisResultData]

backends()[source]

Return the backend list from the experiment DB.

Return type:

dict

create_analysis_results(data, blocking=True, max_workers=100, json_encoder=<class 'json.encoder.JSONEncoder'>)[source]

Create multiple analysis results (simplified without threading for local).

Parameters:

  • data (list[DbAnalysisResultData]) – List of analysis result data to save

  • blocking (bool) – Ignored for local service (always blocking)

  • max_workers (int) – Ignored for local service

  • json_encoder (type[JSONEncoder]) – Custom JSON encoder

Returns:

Status dictionary with results

create_figures(experiment_id, figure_list, blocking=True, max_workers=100)[source]

Create multiple figures (simplified without threading for local).

Parameters:

  • experiment_id (str) – ID of the experiment

  • figure_list (list[tuple]) – List of (figure, name) tuples

  • blocking (bool) – Ignored for local service

  • max_workers (int) – Ignored for local service

Returns:

Status dictionary with results

create_or_update_analysis_result(data, json_encoder=<class 'json.encoder.JSONEncoder'>, create=True, max_attempts=3)[source]

Creates or updates an analysis result.

Parameters:

  • data (DbAnalysisResultData) – The analysis result data to save

  • json_encoder (type[JSONEncoder]) – Custom JSON encoder (unused)

  • create (bool) – Whether to attempt create first

  • max_attempts (int) – Maximum number of attempts

Returns:

Analysis result ID

Return type:

str

create_or_update_experiment(data, json_encoder=<class 'json.encoder.JSONEncoder'>, create=True, max_attempts=3, **kwargs)[source]

Creates a new experiment, or updates an existing one.

Parameters:

  • data (DbExperimentData) – The experiment data to save

  • json_encoder (type[JSONEncoder]) – Custom JSON encoder (unused)

  • create (bool) – Whether to attempt create first

  • max_attempts (int) – Maximum number of attempts

  • **kwargs – Additional parameters (ignored for local service)

Returns:

Experiment ID

Return type:

str

create_or_update_figure(experiment_id, figure, figure_name=None, create=True, max_attempts=3)[source]

Creates a figure if it doesn’t exist, otherwise updates it.

Parameters:

  • experiment_id (str) – Experiment ID

  • figure (str | bytes) – Figure file name or figure data

  • figure_name (str | None) – Name of the figure

  • create (bool) – Whether to attempt create first

  • max_attempts (int) – Maximum number of attempts

Returns:

Tuple of (figure_name, size)

Return type:

tuple

delete_analysis_result(result_id)[source]

Delete an analysis result.

Parameters:

result_id (str) – Analysis result ID.

Raises:

ExperimentEntryNotFound – If the analysis result is not found

Return type:

dict

delete_experiment(experiment_id)[source]

Delete an experiment from the database.

Parameters:

experiment_id (str) – Experiment ID to delete

Raises:

ExperimentEntryNotFound – If the experiment is not found

delete_figure(experiment_id, figure_name)[source]

Delete an experiment plot.

Parameters:

  • experiment_id (str) – Experiment ID

  • figure_name (str) – Name of the figure

experiment(experiment_id, json_decoder=None)[source]

Retrieve a single experiment from the database.

Parameters:

  • experiment_id (str) – Experiment ID

  • json_decoder (type[JSONDecoder]) – Custom JSON decoder (unused in local service)

Returns:

Retrieved experiment data

Raises:

ExperimentEntryNotFound – If the experiment is not found

Return type:

DbExperimentData

experiment_has_file(experiment_id, filename)[source]

Check if an experiment has a specific file.

Parameters:

  • experiment_id (str) – Experiment ID

  • filename (str) – Name of the file to check

Returns:

True if the file exists, False otherwise

Return type:

bool

experiments()[source]

Retrieve experiment ids

Returns:

A list of experiment ids.

Return type:

list[str]

figure(experiment_id, figure_name, file_name=None)[source]

Retrieve an existing figure.

Parameters:

  • experiment_id (str) – Experiment ID

  • figure_name (str) – Name of the figure

  • file_name (str | None) – Local file to save to (if None, returns bytes)

Returns:

Size if file_name given, otherwise figure bytes

Return type:

int | bytes

file_delete(experiment_id, file_name)[source]

Delete a file from the database

file_download(experiment_id, file_name, json_decoder=<class 'json.decoder.JSONDecoder'>)[source]

Downloads a data file from the DB.

Parameters:

  • experiment_id (str) – The experiment the file belongs to

  • file_name (str) – The filename

  • json_decoder (type[JSONDecoder]) – Custom JSON decoder

Returns:

Deserialized file data

Raises:
Return type:

dict

file_upload(experiment_id, file_name, file_data, json_encoder=<class 'json.encoder.JSONEncoder'>)[source]

Uploads a data file to the DB.

Parameters:

  • experiment_id (str) – The experiment the file belongs to

  • file_name (str) – The expected filename

  • file_data (dict | str | bytes) – Dictionary or JSON string or bytes to save

  • json_encoder (type[JSONEncoder]) – Custom JSON encoder

Raises:

RuntimeError – pyyaml not available and a yaml file requested

files(experiment_id)[source]

Retrieve the file list for an experiment.

Parameters:

experiment_id (str) – Experiment ID

Returns:

{“files”: […]})

Return type:

Dictionary with file list metadata (format

save()[source]

Saves the db to disk