Module api

class QuantumInspireAPI(base_uri='https://api.quantum-inspire.com', authentication=None, project_name=None, coreapi_client_class=<class 'coreapi.client.Client'>)[source]

Python interface to the Quantum Inspire API (Application Programmer Interface).

The Quantum Inspire API supplies an interface for executing programs and can be used to access the different entities in the Quantum Inspire database needed for running the programs. The entities for which an interface is provided are:

Backend types: Depending on the user account more qubits can be used and simulated on faster hardware.

Projects: Executing programs is done from a project. Projects keep track of the other entities.

Jobs: A job contains all the information and the parameters needed for executing the program.

Assets: A container for a cQASM program. Is part of a job.

Results: After the job is finished, the results are gathered in the result-entity.

QuantumInspireAPI is a convenient interface (or wrapper) to the low level API and hides details for requesting data (via get) and performing operations on the different entities (via actions).

The API version that is used by SDK version 2.0.0 and higher defaults to 2.0. Version 2.0 is introduced for serving backends that support multiple measurement algorithms. Backends that support multiple measurement algorithms have a flag defined called ‘multiple_measurement’ in their backend type structure (See get_default_backend_type()).

To support multiple measurement the results structure has changed to hold the results for each measurement block defined in a multiple measurement algorithm. Backends that do not support multiple measurement algorithms have 1 measurement block. See get_result() for details.

For more documentation:

The knowledge base on: https://www.quantum-inspire.com/kbase/low-level-api/
The REST API can be found on: https://api.quantum-inspire.com/
The Core API schema is published on: https://api.quantum-inspire.com/schema/

Parameters:

base_uri (str) – The base uri of the Quantum Inspire API-location where the schema can be found in path ‘schema/’).
authentication (AuthBase | None) –
The authentication, can be one of the following coreapi authentications:
- BasicAuthentication(email, password), HTTP authentication with valid email/password.
- TokenAuthentication(token, scheme="token"), token authentication with a valid API-token.
When authentication is None, a token is read from the default location.
project_name (str | None) – The name of the project used for executing the jobs.
coreapi_client_class (Type[Client]) – Coreapi client to interact with the API through a schema. Default set to coreapi.Client.

Raises:

AuthenticationError – When no authentication is given and the token could not be loaded from the default location.
ApiError – When the schema could not be loaded.

Note

When no project name is given, a temporary project is created for the job and deleted after the job has finished. When a project name is given, a project is created if it does not exist, but re-used if a project with that name already exists. In either case, the project will not be deleted when the job has finished.

show_fsp_warning(enable=True)[source]

Enable or disable the warning that is printed when a non-FSP (full state projection) job is about to run.

Parameters:: enable (bool) – when True the fsp-warning is shown, otherwise not.
Return type:: None

list_backend_types()[source]

Prints the backend types with the name and the maximum number of qubits it supports.

Return type:: None

get_default_backend_type()[source]

Gets the properties of the default backend type.

Returns:

The default backend type with all of its properties:

Key	Type	Description
`url`	str	The url for the backend type.
`name`	str	Name of the backend.
`is_hardware_backend`	bool	Indicates whether the backend is a hardware backend (True) or a simulating backend (False).
`required_permission`	str	Describes the permission that is required to use this backend.
`number_of_qubits`	int	Maximum number of qubits the backend supports.
`description`	str	Short description of the backend.
`topology`	dict	Dictionary with property edges that contains a list of tuples that define qubit connectivity for 2-qubit gates.
`is_allowed`	bool	Indicates whether the user is allowed to use this backend.
`status`	str	Status of the backend.
`status_message`	str	Extra info about the status of the backend.
`chip_image_id`	str	Unique identification of the chip.
`calibration`	str	Calibration information (url).
`allowed_operations`	dict	The gates/operations names that the backend can handle.
`default_number_of_shots`	int	The default number of shots for an experiment.
`max_number_of_shots`	int	The maximum number of shots for an experiment.
`max_number_of_simultaneous_jobs`	int	The maximum number of jobs that is allowed to be queued for the backend simultaneously (0 = no limit).
`operations_count`	dict	The maximum number of gates that is allowed in an experiment for each qubit separately and for the experiment in total (0 = no limit).
`flags`	list[str]	flags defining capabilities of the backends. E.g. ‘multiple_measurement’, ‘parallel_computing’

Return type:

Dict[str, Any]

get_backend_types()[source]

Gets a list of backend types with properties.

Returns:: A list of backend types with all of their properties. See get_default_backend_type() for a description of the backend properties.
Return type:: List[Dict[str, Any]]

get_backend_type_by_id(backend_type_id)[source]

Gets the properties of a specific backend type, given the backend type id.

Parameters:: backend_type_id (int) – The backend identification number.
Raises:: ApiError – When the backend type indicated by backend_type_id does not exist.
Returns:: The requested backend type indicated by backend_type_id with all of its properties. See get_default_backend_type() for a description of the backend type properties.
Return type:: Dict[str, Any]

get_backend_type_by_name(backend_name)[source]

Gets the properties of a backend type, given the backend name (case insensitive).

Parameters:: backend_name (str) – The backend name.
Raises:: ApiError – When the backend name does not exist.
Returns:: The properties of the backend type of the specific backend. See get_default_backend_type() for a description of the backend type properties.
Return type:: Dict[str, Any]

get_backend_type(identifier=None)[source]

Gets the properties of the backend type indicated by identifier.

If no identifier is given, the default backend type will be returned. With an identifier of type string or int, the backend type will be searched by name or id respectively.

Parameters:

identifier (int | str | None) – The backend type identifier.

Raises:

ApiError – If the requested backend type does not exist.
ValueError – If the backend type identifier is not of the correct type.

Returns:

This method returns the default backend type or the backend type as identified by the identifier parameter , or the default backend type if no identifier is provided. See get_default_backend_type() for a description of the backend type properties.

Return type:

Dict[str, Any]

list_projects()[source]

Prints a list of projects.

Prints all the projects registered to the current user the API is authenticated for. For each project the name, id and backend type is printed.

Return type:: None

get_project(project_id)[source]

Gets the properties of a project, given the project id.

Parameters:

project_id (int) – The project identification number.

Raises:

ApiError – If the requested project does not exist.

Returns:

The properties describing the project:

Key	Type	Description
`url`	str	The url for this project.
`id`	int	Unique id of the project.
`name`	str	Name of the project.
`owner`	int	Url to get the owner of the project.
`assets`	str	Url to get the assets of the project.
`backend_type`	str	Url to get the backend type of the project.
`default_number_of_shots`	int	Default number of executions for this project.
`created`	str	Date/time when the project was created.
`number_of_jobs`	int	Number of jobs managed within this project.
`last_saved`	str	Date/time when the project was saved.

Return type:

Dict[str, Any]

get_projects()[source]

Gets all the projects registered to the user the API is currently authenticated for.

Returns:: The projects with all of their properties. See get_project() for a description of the project properties.
Return type:: List[Dict[str, Any]]

create_project(name, default_number_of_shots, backend_type)[source]

Creates a new project for executing jobs.

Parameters:

name (str) – The name for the project. The name need not be unique.
default_number_of_shots (int) – The default number of executions of the program before collecting the results.
backend_type (Dict[str, Any]) – The properties of the backend type.

Returns:

The newly created project with all of its properties. See get_project() for a description of the project properties.

Return type:

Dict[str, Any]

delete_project(project_id)[source]

Delete a project.

Deletes the project identified by project_id together with all its assets, jobs and results. Only projects can be deleted that are registered for the user the API is currently authenticated for.

Parameters:: project_id (int) – The project identification number.
Raises:: ApiError – If the project identified by project_id does not exist.
Return type:: None

list_jobs()[source]

Prints a list of jobs.

Prints a list of all the jobs registered to the current user the API is authenticated for. For each job the name, identification number and status is printed.

Return type:: None

get_job(job_id)[source]

Gets the properties of a job, given the job id.

Parameters:

job_id (int) – The job identification number.

Raises:

ApiError – If the requested job does not exist.

Returns:

The properties describing the job:

Key	Type	Description
`url`	str	The url for the job.
`name`	str	Name of the circuit that is executed by this job.
`id`	int	Unique id of the job.
`status`	str	Execution status of the job: e.g. ‘NEW’, ‘COMPLETE’, ‘CANCELLED’, ‘RUNNING’.
`input`	str	Url to get the assets of the job.
`backend`	str	Url to get the backend the job is executed on.
`backend_type`	str	Url to get the backend type of the backend the job is executed on.
`results`	str	Url to get the results for the job.
`queued_at`	str	The date-time the job is queued at. The format is ‘yyyy-MM-ddTHH:mm:ss.SSSSSSZ’ Zulu Time.
`number_of_shots`	int	Number of executions for this job.
`full_state_projection`	bool	Indicates if the backend uses full state projection to determine the quantum state. Used for optimizing simulations. For more information see: https://www.quantum-inspire.com/kbase/optimization-of-simulations/
`user_data`	str	The user configuration data.

Return type:

Dict[str, Any]

get_jobs()[source]

Gets all the jobs registered to projects for the user the API is currently authenticated for.

Returns:: The jobs with all of its properties. See get_job() for a description of the job properties.
Return type:: List[Dict[str, Any]]

get_jobs_from_asset(asset_id)[source]

Gets the jobs with its properties for an asset, given the asset id.

Parameters:: asset_id (int) – The asset identification number.
Returns:: List of jobs with its properties for the asset with identification asset_id. An empty list is returned when the asset has no jobs.
Raises:: ApiError – If the asset identified by asset_id does not exist.
Return type:: List[Dict[str, Any]]

get_jobs_from_project(project_id)[source]

Gets the jobs with its properties for a single project, given the project id.

Parameters:: project_id (int) – The project identification number.
Returns:: List of jobs with its properties for the project with identification project_id. An empty list is returned when the project has no jobs.
Raises:: ApiError – If the project identified by project_id does not exist.
Return type:: List[Dict[str, Any]]

delete_job(job_id)[source]

Deletes the job identified by job_id.

Only jobs can be deleted that are registered for the user the API is currently authenticated for.

Parameters:: job_id (int) – The job identification number.
Raises:: ApiError – If the job identified by job_id does not exist.
Return type:: None

list_results()[source]

Prints a list of results.

Prints a list of all the results registered to the current user the API is authenticated for. For each result the identification number and creation date is printed.

Return type:: None

get_result(result_id)[source]

Gets the results of the executed job, given the result_id.

Using version 2.0 of the API, the results structure has changed to allow multiple measurement algorithms. Some items in the results structure (histogram, raw data, measurement mask, quantum states, measurement register) are defined as lists instead of single values. The lists hold the single values for each measurement block in the algorithm for backends that support multiple measurement. Backends that do not support multiple measurement always have a single measurement block and therefore return a single item in the results lists. For some items (raw data, measurement mask) in the results structure the type have changed to better express measured and not measured qubits. See get_raw_data_from_result() for details.

Parameters:

result_id (int) – The result identification number.

Raises:

ApiError – If the requested result does not exist.

Returns:

The properties describing the result:

Key	Type	Description
`id`	int	Unique id of the result.
`url`	str	The url to get this result.
`job`	str	The url to get the job that generated the result.
`created_at`	str	The date-time the result is created at. The format is ‘yyyy-MM-ddTHH:mm:ss.SSSSSSZ’ Zulu Time.
`number_of_qubits`	int	Number of qubits in the circuit for this experiment.
`execution_time_in_seconds`	float	The execution time of the job.
`raw_text`	str	Text string filled when an error occurred, else empty.
`raw_data_url`	str	Url to get the raw data of the result. The raw data exists of a list of integer values depicting the state for each shot.
`histogram`	list(dict)	The histograms as a list of dicts with tuples with state (str) and its probability (float).
`histogram_url`	str	Url to get the histogram with probabilities. This results in the dict as found in property `histogram` of result.
`measurement_mask`	list(list(0\|1))	For each measurement block a list of 0 (not measured) or 1 (measured) values for all the qubits in the cQASM program.
`quantum_states_url`	str	Url to get a list of quantum states for each measurement block.
`measurement_register_url`	str	Url to get a list of measurement registers for each measurement block.
`calibration`	str	Url to get calibration information.

Return type:

Dict[str, Any]

get_results()[source]

Gets all the results registered for the user the API is currently authenticated for.

Returns:: The results with all of its properties. See get_result() for a description of the result properties.
Return type:: List[Dict[str, Any]]

get_result_from_job(job_id)[source]

Gets the result with its properties for a single job, given the job id.

Parameters:: job_id (int) – The job identification number.
Returns:: The result with its properties for the job with identification job_id. See get_result() for a description of the result properties.
Raises:: ApiError – If the job identified by job_id does not exist.
Return type:: Dict[str, Any]

get_raw_data_from_result(result_id)[source]

Gets the raw data from the result.

Gets the raw data from the result of the executed job, given the result_id. The raw data consists of a list of measurements for each shot (job.number_of_shots). The measurements contain a list of data for each measurement in the job (len(measurement_mask)). The data consist of integer state values (0 or 1) for each measured qubit, else None (see measurement_mask). Actual type is: List[List[List[Optional[int]]]] with least significant qubit first.

Example for "measurement_mask": [[0, 1], [1, 1]] the raw_data for 6 shots is structured as follows:

"raw_data": [
    [[None, 1], [0, 1]],
    [[None, 1], [1, 0]],
    [[None, 0], [1, 1]],
    [[None, 0], [1, 1]],
    [[None, 0], [0, 0]],
    [[None, 1], [0, 1]]
]

In this example in the first measurement block only qubit[1] is measured, in the second measurement block qubit[0] and qubit[1] are measured.

Parameters:: result_id (int) – The identification number of the result.
Raises:: ApiError – If the raw data url in result is invalid or the request for the raw data using the url failed.
Returns:: The raw data as a list of structures. A list with an empty list is returned when raw data has no elements.
Return type:: List[List[Any]]

get_quantum_states_from_result(result_id)[source]

Gets the quantum states for each measurement block from the result of the executed job, given the result_id.

Parameters:: result_id (int) – The identification number of the result.
Raises:: ApiError – If the quantum states url in result is invalid or the request for the quantum states using the url failed.
Returns:: A list of quantum states. The quantum states consists of a list of quantum state values and their corresponding probability. An empty list is returned when the backend does not return quantum states.
Return type:: List[List[Any]]

get_measurement_register_from_result(result_id)[source]

Gets the measurement register for each measurement block from the result of the executed code, given the result_id.

Parameters:: result_id (int) – The identification number of the result.
Raises:: ApiError – If the measurement register url in result is invalid or the request for the measurement register using the url failed.
Returns:: A list of measurement registers. The measurement register consists of a list of measurement register values. An empty list is returned when there is no data.
Return type:: List[List[Any]]

get_calibration_from_result(result_id)[source]

Gets the calibration information of the executed job, given the result_id.

Parameters:: result_id (int) – The identification number of the result.
Raises:: ApiError – If the calibration url in result is invalid or the request for the calibration info using the url failed.
Returns:: The calibration information from the backend. Calibration information may differ per backend type. None is returned when there is no calibration information (e.g. simulator backends).
Return type:: Any | None

list_assets()[source]

Prints a list of the assets registered to the current user the API is authenticated for.

For each asset the name, identification number and project identification number is printed.

Return type:: None

get_asset(asset_id)[source]

Gets the properties of the asset, given the asset_id.

Parameters:

asset_id (int) – The asset identification number.

Raises:

ApiError – If the requested asset does not exist.

Returns:

The properties describing the asset:

Key	Type	Description
`url`	str	The url to get this asset.
`id`	int	Unique id of this asset.
`name`	str	The name to get the asset.
`contentType`	str	The description of the content e.g. ‘application/qasm’ or ‘text/plain’.
`content`	str	The content itself. For example a cQASM program when linked to a job.
`project`	str	Url to get the project properties for which this asset was created.
`project_id`	int	The project id of the project for which this asset was created.

Return type:

Dict[str, Any]

get_assets()[source]

Gets all the assets registered for the user the API is currently authenticated for.

Returns:: The assets with all of its properties. See get_asset() for a description of the asset properties.
Return type:: List[Dict[str, Any]]

get_assets_from_project(project_id)[source]

Gets the assets with its properties for a single project, given the project id.

Parameters:: project_id (int) – The project identification number.
Returns:: List of assets with its properties for the project with identification project_id. An empty list is returned when the project has no assets.
Raises:: ApiError – If the project identified by project_id does not exist.
Return type:: List[Dict[str, Any]]

get_asset_from_job(job_id)[source]

Gets the asset data from the job, given the job_id.

Parameters:: job_id (int) – The identification number of the job.
Raises:: ApiError – If the requested asset with identification from the job ‘input’ field does not exist.
Returns:: The assets with all of its properties. See get_asset() for a description of the asset properties.
Return type:: Dict[str, Any]

wait_for_completed_job(quantum_inspire_job, collect_max_tries=None, sec_retry_delay=0.5)[source]

Wait for job completion.

Delays the process and requests the job status. The waiting loop is broken when the job status is completed or cancelled, or when the maximum number of tries is set and has been reached.

Parameters:

quantum_inspire_job (QuantumInspireJob) – A job object.
collect_max_tries (int | None) – The maximum number of times the job status is checked. When set, the value should be > 0. When not set, the method waits until the job status is either completed or cancelled.
sec_retry_delay (float) – The time delay in between job status checks in seconds.

Returns:

True if the job result could be collected else False in hte first part of the tuple. The latter part of the tuple contains an (error)message.

Return type:

Tuple[bool, str]

execute_qasm(qasm, backend_type=None, number_of_shots=None, collect_tries=None, default_number_of_shots=None, identifier=None, full_state_projection=False, user_data='')[source]

With this method a cQASM program is executed, and the result is returned when the job is completed.

The method execute_qasm_async() is called which returns a QuantumInspireJob directly without waiting for the job to complete. After this call a waiting loop is started to wait for the job to finish and get the result. When no project name was given when the QuantumInspireAPI was created, the job is linked to a newly created temporary project in execute_qasm_async(). When the job has finished running, this project is deleted.

Depending on how busy the backend is, it takes some time to execute the job and returning the result. This method waits for the job to finish. The parameter collect_tries defines the maximum waiting time (collect_tries x 0.5 seconds). When the job takes longer to finish no results are returned. When set, the value of collect_tries must be > 0. When collect_tries is not set, the waiting time for completion is not limited.

Parameters:

qasm (str) – The cQASM code as string object.
backend_type (Dict[str, Any] | int | str | None) – The backend_type to execute the algorithm on.
number_of_shots (int | None) – Execution times of the algorithm before collecting the results.
collect_tries (int | None) – The number of times the status of the job is checked for completion before returning.
default_number_of_shots (int | None) – The default used number of shots for the project.
identifier (str | None) – The identifier to generate names for the project, asset and job when necessary.
full_state_projection (bool) – Do not use full state projection with simulations when set to False (default).
user_data (str) – Data that the user wants to pass along with the job.

Returns:

The results of the executed cQASM if successful else an error result if the results could not be collected within the given number of tries or the job failed. See get_result() for a description of the result properties.

Return type:

Dict[str, Any]

execute_qasm_async(qasm, backend_type=None, number_of_shots=None, default_number_of_shots=None, identifier=None, full_state_projection=False, project=None, job_name=None, user_data='')[source]

With this method a cQASM program (job) is scheduled to be executed asynchronously.

The method returns directly without waiting for the job to complete, as opposed to method execute_qasm() which waits for the job to finish and returns the result.

To execute a cQASM program a job is scheduled on a backend of type backend type as given by the parameter backend_type. Currently, there are 3 backend types available:

QX single-node simulator (default for anonymous accounts)

QX single-node simulator SurfSara (advanced account credentials needed)

QX multi-node simulator SurfSara (advanced account credentials needed)

When no backend_type is given, the default backend type currently being QX single-node simulator, is used.

The job has to be linked with a project before it can be scheduled to execute.

When a project name was supplied when the QuantumInspireAPI was created (see __init__()), the job is linked to an existing project with this project name. When no project exists with this name a project with this name is created.

When no project name was given when the QuantumInspireAPI was created, the job is linked to the project that is given as an argument project. When this project argument is empty, a project is created. First a project name is generated using the parameter identifier or when parameter identifier is empty an identifier is generated.

When the project is created, it is created for the backend type and the default number of shots given. When the project already existed the values of the existing project are used for backend type and default number of shots.

An asset with a unique id is created containing the cQASM program. This asset is linked to the project.

When the project and the asset containing the program are known, a job is created with the name given by parameter job_name. When this parameter job_name is not filled, a job name is generated.

The job that is created for running the program (contained in the asset) is linked to the project and will be executed number_of_shots times (as given by the parameter) before the results can be collected.

The jobs’ user_data is filled with the user data given as a parameter. This user data can be fetched and used later in the process.

The default value of job parameter full_state_projection is set to False which means that the algorithm is treated as non-deterministic. As a result a deterministic algorithm may take longer to execute than strictly needed. When full_state_projection is set to True, a non-deterministic algorithm may give wrong results. Parameter full_state_projection is only used for simulations.

Once the job is created, the method returns directly without waiting for the job to complete. The job is returned as a QuantumInspireJob. This class encapsulates the job and contains methods the get the status of the job and retrieve the execution results when the job is completed.

Parameters:

qasm (str) – The qasm code as a string object.
backend_type (Dict[str, Any] | int | str | None) – The backend_type to execute the algorithm on.
number_of_shots (int | None) – Execution times of the algorithm before the results can be collected.
default_number_of_shots (int | None) – The default used number of shots for the project.
identifier (str | None) – The identifier used for generating names for the project, asset and job.
full_state_projection (bool) – Do not use full state projection when set to False (default).
project (Dict[str, Any] | None) – The properties of an existing project, the asset and job are linked to. Only used when the project_name member of the api is empty.
job_name (str | None) – Name for the job that is to be executed, when None a job name is generated (see identifier)
user_data (str) – Data that the user wants to pass along with the job.

Returns:

An encapsulated job object containing methods the get the status of the job and retrieve the execution results.

Return type:

QuantumInspireJob