Local Storage

from mpqp.local_storage import *

The local_storage module is responsible for handling the storage of results and jobs data locally on the user’s device using a SQLite database. The functions defined here are for the most part callable directly on the Result, BatchResult and Job classes.

Functions provided here are decomposed in two broad categories:

• the ones used to interact with MPQP objects by the end user, presented in sections Saving, Loading and Deleting,

• the ones used to interact more closely with the database, aimed more at internal use, presented in sections The Setup and Querying.

Saving

Provides functions to insert Job and Result into the local database.

insert_jobs(jobs)

Insert a job in the database.

Method corresponding: save().

Parameters:

jobs (TypeAliasForwardRef('Job') | list[TypeAliasForwardRef('Job')]) – The job(s) to be inserted.

Returns:

The ID of the newly inserted job.

Return type:

list[int]

Example

>>> job = Job(JobType.STATE_VECTOR, QCircuit(2), IBMDevice.AER_SIMULATOR)
>>> insert_jobs(job)
[17]

insert_results(result, reuse_similar_job=True)

Insert a result or batch result into the database.

Methods corresponding: Result.save and BatchResult.save.

Parameters:

• result (TypeAliasForwardRef('Result') | TypeAliasForwardRef('BatchResult') | list[TypeAliasForwardRef('Result')]) – The result(s) to be inserted.

• reuse_similar_job (bool) – If True, checks for an existing job in the database and reuses its ID to avoid duplicates.

Returns:

List of IDs of the inserted result(s).

Return type:

list[int]

Example

>>> result = Result(Job(JobType.STATE_VECTOR, QCircuit(2), IBMDevice.AER_SIMULATOR), StateVector([1, 0, 0, 0]))
>>> insert_results(result)
[21]

Loading

This module provides utility functions retrieving jobs and results from local storage. In the process, they are converted to MPQP objects (Job and Result).

get_all_jobs()

Retrieve all jobs from the local storage and convert them into Job.

Method of the class corresponding: load_all().

Returns:

All locally stored jobs.

Return type:

list[TypeAliasForwardRef(‘Job’)]

Example

>>> for job in get_all_jobs():
...     print(job)
Job(JobType.SAMPLE, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR)
Job(JobType.SAMPLE, QCircuit(...), IBMDevice.AER_SIMULATOR)
Job(JobType.SAMPLE, QCircuit(...), AWSDevice.BRAKET_LOCAL_SIMULATOR)
Job(JobType.SAMPLE, QCircuit(...), ATOSDevice.MYQLM_CLINALG)
Job(JobType.SAMPLE, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR)
Job(JobType.SAMPLE, QCircuit(...), IBMDevice.AER_SIMULATOR)
Job(JobType.SAMPLE, QCircuit(...), AWSDevice.BRAKET_LOCAL_SIMULATOR)
Job(JobType.SAMPLE, QCircuit(...), ATOSDevice.MYQLM_CLINALG)
Job(JobType.STATE_VECTOR, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR)
Job(JobType.STATE_VECTOR, QCircuit(...), IBMDevice.AER_SIMULATOR)
Job(JobType.STATE_VECTOR, QCircuit(...), AWSDevice.BRAKET_LOCAL_SIMULATOR)
Job(JobType.STATE_VECTOR, QCircuit(...), ATOSDevice.MYQLM_CLINALG)
Job(JobType.STATE_VECTOR, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR)
Job(JobType.STATE_VECTOR, QCircuit(...), IBMDevice.AER_SIMULATOR)
Job(JobType.STATE_VECTOR, QCircuit(...), AWSDevice.BRAKET_LOCAL_SIMULATOR)
Job(JobType.STATE_VECTOR, QCircuit(...), ATOSDevice.MYQLM_CLINALG)

get_all_results()

Retrieve all results from the local storage and convert them into Result.

Method of the class corresponding: load_all().

Returns:

All locally stored results.

Return type:

list[TypeAliasForwardRef(‘Result’)]

Example

>>> for result in get_all_results():
...     print(repr(result))
Result(Job(JobType.SAMPLE, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR), [Sample(...), Sample(...)], None, 1024)
Result(Job(JobType.SAMPLE, QCircuit(...), IBMDevice.AER_SIMULATOR), [Sample(...), Sample(...)], None, 1024)
Result(Job(JobType.SAMPLE, QCircuit(...), AWSDevice.BRAKET_LOCAL_SIMULATOR), [Sample(...), Sample(...)], None, 1024)
Result(Job(JobType.SAMPLE, QCircuit(...), ATOSDevice.MYQLM_CLINALG), [Sample(...), Sample(...)], ..., 1024)
Result(Job(JobType.SAMPLE, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR), [Sample(...), Sample(...)], None, 1024)
Result(Job(JobType.SAMPLE, QCircuit(...), IBMDevice.AER_SIMULATOR), [Sample(...), Sample(...)], None, 1024)
Result(Job(JobType.SAMPLE, QCircuit(...), AWSDevice.BRAKET_LOCAL_SIMULATOR), [Sample(...), Sample(...)], None, 1024)
Result(Job(JobType.SAMPLE, QCircuit(...), ATOSDevice.MYQLM_CLINALG), [Sample(...), Sample(...)], ..., 1024)
Result(Job(JobType.SAMPLE, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR), [Sample(...), Sample(...)], None, 1024)
Result(Job(JobType.SAMPLE, QCircuit(...), IBMDevice.AER_SIMULATOR), [Sample(...), Sample(...)], None, 1024)
Result(Job(JobType.SAMPLE, QCircuit(...), AWSDevice.BRAKET_LOCAL_SIMULATOR), [Sample(...), Sample(...)], None, 1024)
Result(Job(JobType.SAMPLE, QCircuit(...), ATOSDevice.MYQLM_CLINALG), [Sample(...), Sample(...)], ..., 1024)
Result(Job(JobType.STATE_VECTOR, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR), StateVector([1, 0, 0, 0]), 0, 0)
Result(Job(JobType.STATE_VECTOR, QCircuit(...), IBMDevice.AER_SIMULATOR), StateVector([1, 0, 0, 0]), 0, 0)
Result(Job(JobType.STATE_VECTOR, QCircuit(...), AWSDevice.BRAKET_LOCAL_SIMULATOR), StateVector([1, 0, 0, 0]), 0, 0)
Result(Job(JobType.STATE_VECTOR, QCircuit(...), ATOSDevice.MYQLM_CLINALG), StateVector([1, 0, 0, 0]), 0, 0)
Result(Job(JobType.STATE_VECTOR, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR), StateVector([1, 0, 0, 0]), 0, 0)
Result(Job(JobType.STATE_VECTOR, QCircuit(...), IBMDevice.AER_SIMULATOR), StateVector([1, 0, 0, 0]), 0, 0)
Result(Job(JobType.STATE_VECTOR, QCircuit(...), AWSDevice.BRAKET_LOCAL_SIMULATOR), StateVector([1, 0, 0, 0]), 0, 0)
Result(Job(JobType.STATE_VECTOR, QCircuit(...), ATOSDevice.MYQLM_CLINALG), StateVector([1, 0, 0, 0]), 0, 0)

get_jobs_with_id(job_id)

Retrieve jobs with the given ID(s).

Method of the class corresponding: load_by_local_id().

Parameters:

job_id (int | list[int]) – ID(s) to search for.

Returns:

Job(s) corresponding to the id(s).

Return type:

list[TypeAliasForwardRef(‘Job’)]

Example

>>> jobs = get_jobs_with_id([1, 2, 3])
>>> for job in jobs:
...     print(job)
Job(JobType.SAMPLE, QCircuit([...], label="H CX BM"), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR)
Job(JobType.SAMPLE, QCircuit([...], label="H CX BM"), IBMDevice.AER_SIMULATOR)
Job(JobType.SAMPLE, QCircuit([...], label="H CX BM"), AWSDevice.BRAKET_LOCAL_SIMULATOR)

get_jobs_with_job(job)

Retrieve job(s) matching the given job(s) attributes from the database

• job type,

• circuit,

• device,

• measure.

Method of the class corresponding: load_similar().

Parameters:

job (TypeAliasForwardRef('Job') | list[TypeAliasForwardRef('Job')]) – Job(s) to search for.

Returns:

Matching job(s) corresponding to the job(s) attributes

Return type:

list[TypeAliasForwardRef(‘Job’)]

Example

>>> job = Job(JobType.STATE_VECTOR, QCircuit([], nb_qubits=2, label="circuit 1"), IBMDevice.AER_SIMULATOR)
>>> print(get_jobs_with_job(job))
[Job(JobType.STATE_VECTOR, QCircuit(...), IBMDevice.AER_SIMULATOR)]

get_jobs_with_result(result)

Retrieve job(s) associated with the given result(s) attributes from the database:

• data,

• error,

• shots.

Parameters:

result (TypeAliasForwardRef('Result') | list[TypeAliasForwardRef('Result')] | TypeAliasForwardRef('BatchResult')) – Result(s) to find associated jobs for.

Returns:

Matching job(s) corresponding to the result(s) attribute and job attribute of the result(s).

Return type:

list[TypeAliasForwardRef(‘Job’)]

Example

>>> result = Result(
...     Job(JobType.STATE_VECTOR, QCircuit([], nb_qubits=2, label="circuit 1"), IBMDevice.AER_SIMULATOR),
...     StateVector([1, 0, 0, 0]),
...     0,
...     0,
... )
>>> for job in get_jobs_with_result(result):
...     print(repr(job))
Job(JobType.STATE_VECTOR, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR)
Job(JobType.STATE_VECTOR, QCircuit(...), IBMDevice.AER_SIMULATOR)
Job(JobType.STATE_VECTOR, QCircuit(...), AWSDevice.BRAKET_LOCAL_SIMULATOR)
Job(JobType.STATE_VECTOR, QCircuit(...), ATOSDevice.MYQLM_CLINALG)
Job(JobType.STATE_VECTOR, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR)
Job(JobType.STATE_VECTOR, QCircuit(...), IBMDevice.AER_SIMULATOR)
Job(JobType.STATE_VECTOR, QCircuit(...), AWSDevice.BRAKET_LOCAL_SIMULATOR)
Job(JobType.STATE_VECTOR, QCircuit(...), ATOSDevice.MYQLM_CLINALG)

get_results_with_id(result_id)

Retrieve results with the given ID(s).

Method of the class corresponding: load_by_local_id().

Parameters:

result_id (int | list[int]) – ID(s) to search for.

Returns:

Matching result(s) corresponding to the id(s).

Return type:

list[TypeAliasForwardRef(‘Result’)]

Example

>>> for result in get_results_with_id(1):
...     print(repr(result))
Result(Job(JobType.SAMPLE, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR), [Sample(...), Sample(...)], None, 1024)
>>> for result in get_results_with_id([2, 3]):
...     print(repr(result))
Result(Job(JobType.SAMPLE, QCircuit(...), IBMDevice.AER_SIMULATOR), [Sample(...), Sample(...)], None, 1024)
Result(Job(JobType.SAMPLE, QCircuit(...), AWSDevice.BRAKET_LOCAL_SIMULATOR), [Sample(...), Sample(...)], None, 1024)

get_results_with_job_id(job_id)

Retrieve results associated with the given job ID(s).

Method of the class corresponding: load_by_local_job_id().

Parameters:

job_id (int | list[int]) – ID(s) to search for.

Returns:

Results corresponding to the job id(s).

Return type:

list[TypeAliasForwardRef(‘Result’)]

Example

>>> results = get_results_with_job_id(1)
>>> for result in results:
...     print(repr(result))
Result(Job(JobType.SAMPLE, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR), [Sample(...), Sample(...)], None, 1024)
Result(Job(JobType.SAMPLE, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR), [Sample(...), Sample(...)], None, 1024)

get_results_with_result(result)

Retrieve result(s) matching specific result(s) attributes:

• data,

• error,

• shots.

Method of the class corresponding: load_similar().

Parameters:

result (TypeAliasForwardRef('Result') | list[TypeAliasForwardRef('Result')] | TypeAliasForwardRef('BatchResult')) – Result(s) to search for.

Returns:

Matching result(s) corresponding to the result(s) attribute.

Return type:

list[TypeAliasForwardRef(‘Result’)]

Example

>>> result = Result(
...     Job(JobType.STATE_VECTOR, QCircuit([], nb_qubits=2, label="circuit 1"), IBMDevice.AER_SIMULATOR),
...     StateVector([1, 0, 0, 0]),
...     0,
...     0,
... )
>>> for result in get_results_with_result(result):
...     print(repr(result))
Result(Job(JobType.STATE_VECTOR, QCircuit(...), IBMDevice.AER_SIMULATOR), StateVector(...), 0, 0)
Result(Job(JobType.STATE_VECTOR, QCircuit(...), IBMDevice.AER_SIMULATOR), StateVector(...), 0, 0)

get_results_with_result_and_job(result)

Retrieve result(s) associated with specific result(s) attributes:

• data,

• error,

• shots.

And also with the job attribute of the result(s):

• job type,

• circuit,

• device,

• measure.

Parameters:

result (TypeAliasForwardRef('Result') | list[TypeAliasForwardRef('Result')] | TypeAliasForwardRef('BatchResult')) – Result(s) to search for.

Returns:

Matching result(s) corresponding to the result(s) attribute and job attribute of the result(s).

Return type:

list[TypeAliasForwardRef(‘Result’)]

Example

>>> result = Result(
...     Job(JobType.STATE_VECTOR, QCircuit([], nb_qubits=2, label="circuit 1"), IBMDevice.AER_SIMULATOR),
...     StateVector([1, 0, 0, 0]),
...     0,
...     0,
... )
>>> for result in get_results_with_result_and_job(result):
...     print(repr(result))
Result(Job(JobType.STATE_VECTOR, QCircuit(...), IBMDevice.AER_SIMULATOR), StateVector(...), 0, 0)

jobs_local_storage_to_mpqp(jobs)

Convert a dictionary or list of dictionaries representing jobs into MPQP Job objects.

Parameters:

jobs (list[dict[str, Any]] | dict[str, Any] | None) – A dictionary or list of dictionaries retrieved from the database.

Returns:

A list of MPQP Job objects.

Return type:

list[TypeAliasForwardRef(‘Job’)]

Example

>>> job_local_storage = fetch_jobs_with_id(1)
>>> jobs_local_storage_to_mpqp(job_local_storage)
[Job(JobType.SAMPLE, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR)]

results_local_storage_to_mpqp(results)

Convert a dictionary or list of dictionaries representing results into a Result.

Parameters:

results (list[dict[str, Any]] | dict[str, Any] | None) – The results retrieved from the database.

Returns:

The converted result(s).

Return type:

list[TypeAliasForwardRef(‘Result’)]

Example

>>> result_local_storage = fetch_results_with_id([1, 2])
>>> results = results_local_storage_to_mpqp(result_local_storage)
>>> for result in results:
...     print(repr(result))
Result(Job(JobType.SAMPLE, QCircuit(...), GOOGLEDevice.CIRQ_LOCAL_SIMULATOR), [Sample(...), ...], None, 1024)
Result(Job(JobType.SAMPLE, QCircuit(...), IBMDevice.AER_SIMULATOR), [Sample(...), ...], None, 1024)

Deleting

clear_local_storage()

Clears all records from the database, including jobs and results.

This function resets the tables and their auto-increment counters.

Example

>>> clear_local_storage()
>>> fetch_all_results()
[]
>>> fetch_all_jobs()
[]

remove_all_with_job_id(job_id)

Removes jobs and their associated results for the specified job IDs.

Parameters:

job_id (int | list[int]) – Job ID(s) to remove.

Example

>>> remove_all_with_job_id(1)
>>> fetch_jobs_with_id(1)
[]
>>> fetch_results_with_job_id(1)
[]
>>> remove_all_with_job_id([2, 3])
>>> fetch_jobs_with_id([2, 3])
[]
>>> fetch_results_with_job_id([2, 3])
[]

remove_jobs_with_id(job_id)

Removes jobs with the specified job IDs.

Method of the class corresponding: delete_by_local_id().

Parameters:

job_id (int | list[int]) – Job ID(s) to remove.

Example

>>> remove_jobs_with_id(1)
>>> fetch_jobs_with_id(1)
[]
>>> remove_jobs_with_id([2, 3])
>>> fetch_jobs_with_id([2,3])
[]

remove_jobs_with_jobs_local_storage(jobs)

Removes the matching jobs.

Parameters:

jobs (list[dict[str, Any]] | dict[str, Any] | None) – Job dictionary(ies) for which the matching database row should be deleted.

Example

>>> jobs = fetch_jobs_with_id(1)
>>> remove_jobs_with_jobs_local_storage(jobs)
>>> fetch_jobs_with_id(1)
[]

remove_results_with_id(result_id)

Removes results with the specified result IDs.

Method of the class corresponding: delete_by_local_id().

Parameters:

result_id (int | list[int]) – Result ID(s) to remove.

Example

>>> remove_results_with_id(1)
>>> fetch_results_with_id(1)
[]
>>> remove_results_with_id([2, 3])
>>> fetch_results_with_id([2, 3])
[]

remove_results_with_job(jobs)

Removes results associated with the specified job(s).

Parameters:

jobs (TypeAliasForwardRef('Job') | list[TypeAliasForwardRef('Job')]) – Job(s) to remove results for.

Example

>>> job = Job(JobType.STATE_VECTOR, QCircuit(2), IBMDevice.AER_SIMULATOR)
>>> remove_results_with_job(job)
>>> fetch_results_with_job(job)
[]

remove_results_with_job_id(job_id)

Removes results related to the job(s) who’s ID is given as input.

Parameters:

job_id (int | list[int]) – Result Job_ID(s) to remove.

Example

>>> remove_results_with_job_id(1)
>>> fetch_results_with_job_id(1)
[]
>>> remove_results_with_job_id([2, 3])
>>> fetch_results_with_job_id([2, 3])
[]

remove_results_with_result(result)

Removes results matching the given result(s).

Parameters:

result (TypeAliasForwardRef('Result') | TypeAliasForwardRef('BatchResult') | list[TypeAliasForwardRef('Result')]) – Result(s) to remove.

Example

>>> result = Result(Job(JobType.STATE_VECTOR, QCircuit(2), IBMDevice.AER_SIMULATOR), StateVector([1, 0, 0, 0]))
>>> remove_results_with_result(result)
>>> fetch_results_with_result(result)
[]

remove_results_with_results_local_storage(results)

Removes the matching results.

Parameters:

results (list[dict[str, Any]] | dict[str, Any] | None) – Result dictionary(ies) for which the matching database row should be deleted.

Example

>>> results = fetch_results_with_id(1)
>>> remove_results_with_results_local_storage(results)
>>> fetch_results_with_id(1)
[]

The Setup

This module provides utilities for managing a SQLite database for quantum job and result records, as well as functions for removing entries based on various criteria.

It allows storing and managing job and result metadata related to quantum circuit executions.

ensure_local_storage(func)

Decorator for functions needing the database to be present.

Parameters:

func (Callable[[...], T]) – The function to be decorated.

Return type:

Callable[[…], T]

get_database_version()

Retrieves the current database version from the version table.

Return type:

str

setup_local_storage(path=None)

Sets up a SQLite database for storing quantum job and result records.

Two tables will be created, one for jobs and the other for results.

Parameters:

path (str | None) – Directory to save the database file. Defaults to the current working directory.

Example

>>> setup_local_storage("~/documents/my_database.db")
>>> os.remove(Path("~/documents/my_database.db").expanduser())
>>> setup_local_storage("my_database.db")
>>> os.remove("my_database.db")
>>> setup_local_storage()

Querying

provides utility functions to query and fetch data from the quantum job and result database. It includes methods to retrieve all records, specific records by ID, and filtered records based on Job or Result objects.

fetch_all_jobs()

Fetch all job records from the database.

Returns:

All jobs as dictionaries.

Return type:

list[dict[str, Any]]

Examples

>>> jobs = fetch_all_jobs()
>>> for job in jobs:
...    print("job:", job)
job: {'id': 1, 'type': 'SAMPLE', 'circuit': '"QCircuit(...)"', 'device': 'GOOGLEDevice.CIRQ_LOCAL_SIMULATOR', 'measure': '"BasisMeasure()"', 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 2, 'type': 'SAMPLE', 'circuit': '"QCircuit(...)"', 'device': 'IBMDevice.AER_SIMULATOR', 'measure': '"BasisMeasure()"', 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 3, 'type': 'SAMPLE', 'circuit': '"QCircuit(...)"', 'device': 'AWSDevice.BRAKET_LOCAL_SIMULATOR', 'measure': '"BasisMeasure()"', 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 4, 'type': 'SAMPLE', 'circuit': '"QCircuit(...)"', 'device': 'ATOSDevice.MYQLM_CLINALG', 'measure': '"BasisMeasure()"', 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 5, 'type': 'SAMPLE', 'circuit': '"QCircuit(...)"', 'device': 'GOOGLEDevice.CIRQ_LOCAL_SIMULATOR', 'measure': '"BasisMeasure()"', 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 6, 'type': 'SAMPLE', 'circuit': '"QCircuit(...)"', 'device': 'IBMDevice.AER_SIMULATOR', 'measure': '"BasisMeasure()"', 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 7, 'type': 'SAMPLE', 'circuit': '"QCircuit(...)"', 'device': 'AWSDevice.BRAKET_LOCAL_SIMULATOR', 'measure': '"BasisMeasure()"', 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 8, 'type': 'SAMPLE', 'circuit': '"QCircuit(...)"', 'device': 'ATOSDevice.MYQLM_CLINALG', 'measure': '"BasisMeasure()"', 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 9, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'GOOGLEDevice.CIRQ_LOCAL_SIMULATOR', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 10, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'IBMDevice.AER_SIMULATOR', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 11, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'AWSDevice.BRAKET_LOCAL_SIMULATOR', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 12, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'ATOSDevice.MYQLM_CLINALG', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 13, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'GOOGLEDevice.CIRQ_LOCAL_SIMULATOR', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 14, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'IBMDevice.AER_SIMULATOR', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 15, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'AWSDevice.BRAKET_LOCAL_SIMULATOR', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 16, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'ATOSDevice.MYQLM_CLINALG', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}

fetch_all_results()

Fetch all result records from the database.

Returns:

All results as dictionaries.

Return type:

list[dict[str, Any]]

Examples

>>> results = fetch_all_results()
>>> for result in results:
...    print("result:", result)
result: {'id': 1, 'job_id': 1, 'data': '"[Sample(...), Sample(...)]"', 'error': None, 'shots': 1024, 'created_at': '...'}
result: {'id': 2, 'job_id': 2, 'data': '"[Sample(...), Sample(...)]"', 'error': None, 'shots': 1024, 'created_at': '...'}
result: {'id': 3, 'job_id': 3, 'data': '"[Sample(...), Sample(...)]"', 'error': None, 'shots': 1024, 'created_at': '...'}
result: {'id': 4, 'job_id': 4, 'data': '"[Sample(...), Sample(...)]"', 'error': '...', 'shots': 1024, 'created_at': '...'}
result: {'id': 5, 'job_id': 1, 'data': '"[Sample(...), Sample(...)]"', 'error': None, 'shots': 1024, 'created_at': '...'}
result: {'id': 6, 'job_id': 2, 'data': '"[Sample(...), Sample(...)]"', 'error': None, 'shots': 1024, 'created_at': '...'}
result: {'id': 7, 'job_id': 3, 'data': '"[Sample(...), Sample(...)]"', 'error': None, 'shots': 1024, 'created_at': '...'}
result: {'id': 8, 'job_id': 4, 'data': '"[Sample(...), Sample(...)]"', 'error': '...', 'shots': 1024, 'created_at': '...'}
result: {'id': 9, 'job_id': 5, 'data': '"[Sample(...), Sample(...)]"', 'error': None, 'shots': 1024, 'created_at': '...'}
result: {'id': 10, 'job_id': 6, 'data': '"[Sample(...), Sample(...)]"', 'error': None, 'shots': 1024, 'created_at': '...'}
result: {'id': 11, 'job_id': 7, 'data': '"[Sample(...), Sample(...)]"', 'error': None, 'shots': 1024, 'created_at': '...'}
result: {'id': 12, 'job_id': 8, 'data': '"[Sample(...), Sample(...)]"', 'error': '...', 'shots': 1024, 'created_at': '...'}
result: {'id': 13, 'job_id': 9, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '...', 'shots': 0, 'created_at': '...'}
result: {'id': 14, 'job_id': 10, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}
result: {'id': 15, 'job_id': 11, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}
result: {'id': 16, 'job_id': 12, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}
result: {'id': 17, 'job_id': 13, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}
result: {'id': 18, 'job_id': 14, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}
result: {'id': 19, 'job_id': 15, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}
result: {'id': 20, 'job_id': 16, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}

fetch_jobs_with_id(job_id)

Fetch job(s) by their ID(s).

Parameters:

job_id (int | list[int]) – The ID(s) of the job(s) to fetch.

Returns:

Matching job(s) as dictionaries corresponding to the id(s).

Return type:

list[dict[str, Any]]

Examples

>>> jobs = fetch_jobs_with_id(1)
>>> for job in jobs:
...    print("job_id:", job['id'])
job_id: 1
>>> jobs = fetch_jobs_with_id([2, 3])
>>> for job in jobs:
...    print("job_id:", job['id'])
job_id: 2
job_id: 3

fetch_jobs_with_job(job)

Fetch job(s) records matching specific job(s) attributes:

• job type,

• circuit,

• device,

• measure.

Parameters:

job (TypeAliasForwardRef('Job') | list[TypeAliasForwardRef('Job')]) – Job(s) to match.

Returns:

Matching job(s) as dictionaries corresponding to the job(s) attributes

Return type:

list[dict[str, Any]]

Examples

>>> job = Job(JobType.STATE_VECTOR, QCircuit([], nb_qubits=2, label="circuit 1"), IBMDevice.AER_SIMULATOR)
>>> jobs = fetch_jobs_with_job(job)
>>> for job in jobs:
...    print("job:", job)
job: {'id': 10, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'IBMDevice.AER_SIMULATOR', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}

fetch_jobs_with_result(result)

Fetch job(s) associated with specific results(s) attributes:

• data,

• error,

• shots.

Parameters:

result (TypeAliasForwardRef('Result') | TypeAliasForwardRef('BatchResult') | list[TypeAliasForwardRef('Result')]) – Result(s) to match.

Returns:

Matching job(s) as dictionaries corresponding to the result(s) attribute.

Return type:

list[dict[str, Any]]

Examples

>>> result = Result(Job(JobType.STATE_VECTOR, QCircuit([], nb_qubits=2, label="circuit 1"), IBMDevice.AER_SIMULATOR,), StateVector([1, 0, 0, 0]),0,0)
>>> jobs = fetch_jobs_with_result(result)
>>> for job in jobs:
...    print("job:", job)
job: {'id': 9, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'GOOGLEDevice.CIRQ_LOCAL_SIMULATOR', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 10, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'IBMDevice.AER_SIMULATOR', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 11, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'AWSDevice.BRAKET_LOCAL_SIMULATOR', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 12, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'ATOSDevice.MYQLM_CLINALG', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 13, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'GOOGLEDevice.CIRQ_LOCAL_SIMULATOR', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 14, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'IBMDevice.AER_SIMULATOR', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 15, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'AWSDevice.BRAKET_LOCAL_SIMULATOR', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}
job: {'id': 16, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'ATOSDevice.MYQLM_CLINALG', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}

fetch_jobs_with_result_and_job(result)

Fetch job(s) associated with specific results(s) attributes:

• data,

• error,

• shots.

And also with the job attribute of the results(s):

• job type,

• circuit,

• device,

• measure.

Parameters:

result (TypeAliasForwardRef('Result') | TypeAliasForwardRef('BatchResult') | list[TypeAliasForwardRef('Result')]) – Result(s) to match.

Returns:

Matching job(s) as dictionaries corresponding to the result(s) attribute and job attribute of the result(s).

Return type:

list[dict[str, Any]]

Examples

>>> result = Result(Job(JobType.STATE_VECTOR, QCircuit([], nb_qubits=2, label="circuit 1"), IBMDevice.AER_SIMULATOR,), StateVector([1, 0, 0, 0]),0,0)
>>> jobs = fetch_jobs_with_result_and_job(result)
>>> for job in jobs:
...    print("job:", job)
job: {'id': 10, 'type': 'STATE_VECTOR', 'circuit': '"QCircuit(...)"', 'device': 'IBMDevice.AER_SIMULATOR', 'measure': None, 'remote_id': None, 'status': None, 'created_at': '...'}

fetch_results_with_id(result_id)

Fetch result(s) by their ID(s).

Parameters:

result_id (int | list[int]) – The ID(s) of the result(s) to fetch.

Returns:

Matching result(s) as dictionaries corresponding to the id(s).

Return type:

list[dict[str, Any]]

Examples

>>> results = fetch_results_with_id([1, 2, 3])
>>> for result in results:
...    print("result:", result)
result: {'id': 1, 'job_id': 1, 'data': '"[Sample(...), Sample(...)]"', 'error': None, 'shots': 1024, 'created_at': '...'}
result: {'id': 2, 'job_id': 2, 'data': '"[Sample(...), Sample(...)]"', 'error': None, 'shots': 1024, 'created_at': '...'}
result: {'id': 3, 'job_id': 3, 'data': '"[Sample(...), Sample(...)]"', 'error': None, 'shots': 1024, 'created_at': '...'}

fetch_results_with_job(jobs)

Fetch result(s) associated with the job attribute of the results(s)

• job type,

• circuit,

• device,

• measure.

Parameters:

jobs (TypeAliasForwardRef('Job') | list[TypeAliasForwardRef('Job')]) – The job(s) to match.

Returns:

Matching result(s) as dictionaries corresponding to job attribute of the result(s).

Return type:

list[dict[str, Any]]

Examples

>>> job = Job(JobType.STATE_VECTOR, QCircuit([], nb_qubits=2, label="circuit 1"), IBMDevice.AER_SIMULATOR)
>>> results = fetch_results_with_job(job)
>>> for result in results:
...    print("result:", result)
result: {'id': 14, 'job_id': 10, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}

fetch_results_with_job_id(job_id)

Fetch result(s) associated with specific job ID(s).

Parameters:

job_id (int | list[int]) – The ID(s) of job(s) to which the desired result(s) are attached.

Returns:

Matching result(s) as dictionaries corresponding to the job id(s).

Return type:

list[dict[str, Any]]

Examples

>>> results = fetch_results_with_job_id(1)
>>> for result in results:
...    print("result_id:", result['id'], ", job_id:", result['job_id'])
result_id: 1 , job_id: 1
result_id: 5 , job_id: 1

fetch_results_with_result(result)

Fetch result(s) matching specific results(s) attributes:

• data,

• error,

• shots.

Parameters:

result (TypeAliasForwardRef('Result') | TypeAliasForwardRef('BatchResult') | list[TypeAliasForwardRef('Result')]) – The result(s) to match.

Returns:

Matching result(s) as dictionaries corresponding to the result(s) attribute.

Return type:

list[dict[str, Any]]

Examples

>>> result = Result(Job(JobType.STATE_VECTOR, QCircuit([], nb_qubits=2, label="circuit 1"), IBMDevice.AER_SIMULATOR), StateVector([1, 0, 0, 0]), 0, 0)
>>> results = fetch_results_with_result(result)
>>> for result in results:
...    print("result:", result)
result: {'id': 13, 'job_id': 9, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}
result: {'id': 14, 'job_id': 10, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}
result: {'id': 15, 'job_id': 11, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}
result: {'id': 16, 'job_id': 12, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}
result: {'id': 17, 'job_id': 13, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}
result: {'id': 18, 'job_id': 14, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}
result: {'id': 19, 'job_id': 15, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}
result: {'id': 20, 'job_id': 16, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}

fetch_results_with_result_and_job(result)

Fetch result(s) associated with specific results(s) attributes:

• data,

• error,

• shots.

And also with the job attribute of the results(s):

• job type,

• circuit,

• device,

• measure.

Parameters:

result (TypeAliasForwardRef('Result') | TypeAliasForwardRef('BatchResult') | list[TypeAliasForwardRef('Result')]) – The Result(s) to match.

Returns:

Matching result(s) as dictionaries corresponding to the result(s) attribute and job attribute of the result(s).

Return type:

list[dict[str, Any]]

Examples

>>> result = Result(Job(JobType.STATE_VECTOR, QCircuit([], nb_qubits=2, label="circuit 1"), IBMDevice.AER_SIMULATOR), StateVector([1, 0, 0, 0]), 0, 0)
>>> results = fetch_results_with_result_and_job(result)
>>> for result in results:
...    print("result:", result)
result: {'id': 14, 'job_id': 10, 'data': '"StateVector([1, 0, 0, 0])"', 'error': '"0"', 'shots': 0, 'created_at': '...'}

Environment

In addition of saving results, the .mpqp folder in the user’s home directory is used to manage environment variables for MPQP, as described bellow.

This module takes care of saving and loading the configuration of supported providers in our configuration file, located at ~/.mpqp/.env.

config_key(key_name, configuration_name, test_connection)

Configure a key by setting the API token.

Parameters:

• key_name (str) – The name of the key to be saved in the environment variables.

• configuration_name (str) – The name of the service for which the API token is being configured.

• test_connection (Callable[[str], bool]) – A callable function taking as input token and returning a boolean indicating whether the connection setup was successful.

Returns:

A message indicating the result of the configuration and an empty list (used to conform to the protocol needed by the functions calling this one).

Return type:

tuple

get_env_variable(key)

Loads the configuration file and returns the value associated with the key in parameter. If the variable does not exist, an empty string is returned.

Parameters:

key (str) – The key for which we want to get the value.

Return type:

str

Example

>>> save_env_variable("BRAKET_CONFIGURED", 'True')
True
>>> get_env_variable("BRAKET_CONFIGURED")
'True'
>>> get_env_variable("RaNdOM")
''

get_existing_config_str()

Gets the content of the configuration file.

Returns:

The content of the configuration file.

Return type:

str

Example

>>> save_env_variable('QLM_USER', 'hjaffali')
True
>>> save_env_variable('QLM_PASSWD', '****************')
True
>>> save_env_variable('QLM_CONFIGURED', 'True')
True
>>> save_env_variable('BRAKET_CONFIGURED', 'True')
True
>>> print(get_existing_config_str())
QLM_USER='hjaffali'
QLM_PASSWD='****************'
QLM_CONFIGURED='True'
BRAKET_CONFIGURED='True'

load_env_variables()

Loads the variables stored in the configuration file.

Returns:

True if the variables are loaded correctly.

Return type:

bool

Example

>>> os.getenv("IBM_CONFIGURED")
>>> open(os.path.expanduser("~") + "/.mpqp/.env", "w").write("IBM_CONFIGURED='True'\n")
22
>>> os.getenv("IBM_CONFIGURED")
>>> load_env_variables()
True
>>> os.getenv("IBM_CONFIGURED")
'True'

save_env_variable(key, value)

Adds or updates the key environment variable in the configuration file.

Parameters:

• key (str) – Name of the environment variable.

• value (str) – Value of the environment variable.

Returns:

True if the save was successful.

Return type:

bool

Examples

>>> get_env_variable("RaNdOM")
''
>>> save_env_variable("RaNdOM", "azertyuiop")
True
>>> get_env_variable("RaNdOM")
'azertyuiop'