iqm.iqm_client.iqm_client.IQMClient#

class iqm.iqm_client.iqm_client.IQMClient(iqm_server_url: str, *, quantum_computer: str | None = None, token: str | None = None, tokens_file: str | None = None, client_signature: str | None = None)#

Bases: object

Provides access to IQM quantum computers, enabling quantum circuit execution with the selected quantum computer.

Parameters:

iqm_server_url (str) – URL for accessing the IQM Server. Has to start with http or https.
quantum_computer (str | None) – ID or alias of the quantum computer to connect to, if the IQM Server instance controls more than one.
token (str | None) – Long-lived authentication token in plain text format. If token is given no other user authentication parameters should be given.
tokens_file (str | None) – Path to a tokens file used for authentication. If tokens_file is given no other user authentication parameters should be given.
client_signature (str | None) – String that IQMClient adds to User-Agent header of requests it sends to the server. The signature is appended to IQMClient’s own version information and is intended to carry additional version information, for example the version information of the caller.

Alternatively, the user authentication related keyword arguments can also be given in environment variables IQM_TOKEN, IQM_TOKENS_FILE.

All parameters must be given either as keyword arguments or as environment variables. Same combination restrictions apply for values given as environment variables as for keyword arguments.

Methods

`_get_calibration_quality_metrics`([...])	See `get_calibration_quality_metrics()`.
`_get_dut_label`()	Get the singular dut_label of the quantum computer, or raise an error.
`_get_submit_circuits_payload`(job_id)	Get the original payload that created the given circuit job.
`cancel_job`(job_id)	Cancel a job that was submitted for execution.
`create_run_request`(circuits, *[, ...])	Create a run request for executing circuits without sending it to the server.
`delete_job`(job_id)
`get_about`()	Information about the quantum computer.
`get_calibration_quality_metrics`([...])	Retrieve the given calibration set and related quality metrics from the server.
`get_calibration_set`([calibration_set_id])	Retrieve the given calibration set from the server.
`get_dynamic_quantum_architecture`([...])	Retrieve the dynamic quantum architecture (DQA) for the given calibration set from the server.
`get_feedback_groups`()	Retrieve groups of qubits that can receive real-time feedback signals from each other.
`get_health`()	Status of the quantum computer.
`get_job`(job_id)	Query the status and results of a submitted job.
`get_job_measurement_counts`(job_id)	Query the measurement counts of an executed job.
`get_job_measurements`(job_id)	Query the measurement results of an executed job.
`get_quality_metric_set`([calibration_set_id])	Retrieve the latest quality metric set for the given calibration set from the server.
`get_static_quantum_architecture`()	Retrieve the static quantum architecture (SQA) from the server.
`submit_circuits`(circuits, *[, ...])	Submit a batch of quantum circuits for execution on a quantum computer.
`submit_run_request`(run_request[, use_timeslot])	Submit a run request for execution on a quantum computer.

get_health() → dict[str, Any]#

Status of the quantum computer.

Return type:: dict[str, Any]

get_about() → dict[str, Any]#

Information about the quantum computer.

Return type:: dict[str, Any]

submit_circuits(circuits: list[Circuit | _Circuit | str], *, qubit_mapping: dict[str, str] | None = None, calibration_set_id: UUID | None = None, shots: int = 1, options: CircuitCompilationOptions | None = None, use_timeslot: bool = False) → CircuitJob#

Submit a batch of quantum circuits for execution on a quantum computer.

Parameters:

circuits (list[Circuit | _Circuit | str]) – Circuits to be executed.
qubit_mapping (dict[str, str] | None) – Mapping of logical qubit names to physical qubit names. Can be set to None if all circuits already use physical qubit names. Note that the qubit_mapping is used for all circuits.
calibration_set_id (UUID | None) – ID of the calibration set to use, or None to use the current default calibration.
shots (int) – Number of times circuits are executed. Must be greater than zero.
options (CircuitCompilationOptions | None) – Various discrete options for compiling quantum circuits to instruction schedules.
use_timeslot (bool) – Submits the job to the timeslot queue if set to True. If set to False, the job is submitted to the normal on-demand queue.

Returns:

Job object, containing the ID for the created job. This ID is needed to query the job status and the execution results. Alternatively you can use the methods of the job object.

Return type:

CircuitJob

Create a run request for executing circuits without sending it to the server.

This is called in submit_circuits() and does not need to be called separately in normal usage.

Can be used to inspect the run request that would be submitted by submit_circuits(), without actually submitting it for execution.

Parameters:

circuits (list[Circuit | _Circuit | str]) – Circuits to be executed.
qubit_mapping (dict[str, str] | None) – Mapping of logical qubit names to physical qubit names. Can be set to None if all circuits already use physical qubit names. Note that the qubit_mapping is used for all circuits.
calibration_set_id (UUID | None) – ID of the calibration set to use, or None to use the current default calibration.
shots (int) – Number of times circuits are executed. Must be greater than zero.
options (CircuitCompilationOptions | None) – Various discrete options for compiling quantum circuits to instruction schedules.

Returns:

RunRequest that would be submitted by equivalent call to submit_circuits().

Return type:

PostJobsRequest

submit_run_request(run_request: PostJobsRequest, use_timeslot: bool = False) → CircuitJob#

Submit a run request for execution on a quantum computer.

This is called in submit_circuits() and does not need to be called separately in normal usage.

Parameters:

run_request (PostJobsRequest) – Run request to be submitted for execution.
use_timeslot (bool) – Submits the job to the timeslot queue if set to True. If set to False, the job is submitted to the normal on-demand queue.

Returns:

Job object, containing the ID for the created job. This ID is needed to query the job status and the execution results. Alternatively you can use the methods of the job object.

Return type:

CircuitJob

get_job(job_id: UUID) → CircuitJob#

Query the status and results of a submitted job.

Parameters:: job_id (UUID) – ID of the job to query.
Returns:: Status of the job, can be used to query the results if the job has finished.
Return type:: CircuitJob

cancel_job(job_id: UUID) → None#

Cancel a job that was submitted for execution.

Parameters:: job_id (UUID) – ID of the job to be canceled.
Return type:: None

get_static_quantum_architecture() → StaticQuantumArchitecture#

Retrieve the static quantum architecture (SQA) from the server.

Caches the result and returns it on later invocations.

Returns:: Static quantum architecture of the server.
Raises:: ClientAuthenticationError – no valid authentication provided
Return type:: StaticQuantumArchitecture

get_quality_metric_set(calibration_set_id: UUID | None = None) → ObservationSetWithObservations#

Retrieve the latest quality metric set for the given calibration set from the server.

Parameters:: calibration_set_id (UUID | None) – ID of the calibration set for which the quality metrics are returned. If None, the current default calibration set is used.
Returns:: Requested quality metric set.
Raises:: ClientAuthenticationError – no valid authentication provided
Return type:: ObservationSetWithObservations

get_calibration_set(calibration_set_id: UUID | None = None) → ObservationSetWithObservations#

Retrieve the given calibration set from the server.

Parameters:: calibration_set_id (UUID | None) – ID of the calibration set to retrieve. If None, the current default calibration set is retrieved.
Returns:: Requested calibration set.
Raises:: ClientAuthenticationError – no valid authentication provided
Return type:: ObservationSetWithObservations

get_dynamic_quantum_architecture(calibration_set_id: UUID | None = None) → DynamicQuantumArchitecture#

Retrieve the dynamic quantum architecture (DQA) for the given calibration set from the server.

Caches the result and returns the same result on later invocations, unless calibration_set_id is None. If calibration_set_id is None, always retrieves the result from the server because the default calibration set may have changed.

Parameters:: calibration_set_id (UUID | None) – ID of the calibration set for which the DQA is retrieved. If None, use current default calibration set on the server.
Returns:: Dynamic quantum architecture corresponding to the given calibration set.
Raises:: ClientAuthenticationError – no valid authentication provided
Return type:: DynamicQuantumArchitecture

get_feedback_groups() → tuple[frozenset[str], ...]#

Retrieve groups of qubits that can receive real-time feedback signals from each other.

Real-time feedback enables conditional gates such as cc_prx. Some hardware configurations support routing real-time feedback only between certain qubits.

Returns:

Feedback groups. Within a group, any qubit can receive real-time feedback from any other qubit in: the same group. A qubit can belong to multiple groups. If there is only one group, there are no restrictions regarding feedback routing.

Raises:

ClientAuthenticationError – no valid authentication provided

Return type:

tuple[frozenset[str], …]

get_job_measurement_counts(job_id: UUID) → list[CircuitMeasurementCounts]#

Query the measurement counts of an executed job.

Parameters:: job_id (UUID) – ID of the job to query.
Returns:: For each circuit in the batch, measurement results in histogram representation.
Raises:: ClientAuthenticationError – no valid authentication provided
Return type:: list[CircuitMeasurementCounts]

get_job_measurements(job_id: UUID) → list[dict[str, list[list[int]]]]#

Query the measurement results of an executed job.

Parameters:: job_id (UUID) – ID of the job to query.
Returns:: For each circuit in the batch, the measurement results.
Return type:: list[dict[str, list[list[int]]]]

get_calibration_quality_metrics(calibration_set_id: UUID | None = None) → ObservationFinder#

Retrieve the given calibration set and related quality metrics from the server.

Warning

This method is an experimental interface to the quality metrics and calibration data. The API may change considerably in the next versions with no backwards compatibility, including the API of the ObservationFinder class.

Parameters:: calibration_set_id (UUID | None) – ID of the calibration set to retrieve. If None, the current default calibration set is retrieved.
Returns:: Requested calibration set and related quality metrics in a searchable structure.
Raises:: ClientAuthenticationError – no valid authentication provided
Return type:: ObservationFinder

iqm.iqm_client.iqm_client.IQMClient

Contents

iqm.iqm_client.iqm_client.IQMClient#