IQMClient

IQMClient#

Module: iqm.iqm_client.iqm_client

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 e.g. quantum circuit execution.

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

`cancel_job`	Cancel a job that has been submitted for execution.
`create_run_request`	Create a run request for executing circuits without sending it to the server.
`delete_job`	Delete a job that has been submitted for execution.
`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`	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`	Health status of the quantum computer.
`get_job`	Build a new job object for a submitted job.
`get_job_measurement_counts`	Query the measurement counts of an executed job.
`get_job_measurements`	Query the measurement results of an executed job.
`get_quality_metric_set`	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`	Submit a batch of quantum circuits for execution on a quantum computer.
`submit_run_request`	Submit a request to execute a circuit batch to a quantum computer.

get_health() → dict[str, Any]#

Health 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: WithJsonSchema(json_schema={'anyOf': [{'type': 'array', 'items': {'type': 'object', 'required': ['logical_name', 'physical_name'], 'properties': {'logical_name': {'type': 'string'}, 'physical_name': {'type': 'string'}}, 'additionalProperties': False}}, {'type': 'null'}]}, mode=None)] | 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 (Annotated[dict[str, str], BeforeValidator(func=~iqm.station_control.interface.models.circuit._parse_legacy_qubit_mapping, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~iqm.station_control.interface.models.circuit._serialize_as_legacy_qubit_mapping, return_type=PydanticUndefined, when_used=always), WithJsonSchema(json_schema={'anyOf': [{'type': 'array', 'items': {'type': 'object', 'required': ['logical_name', 'physical_name'], 'properties': {'logical_name': {'type': 'string'}, 'physical_name': {'type': 'string'}}, 'additionalProperties': False}}, {'type': 'null'}]}, mode=None)] | 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. You can query the job status and the execution results using the methods of this object.

Return type:

CircuitJob

create_run_request(circuits: list[Circuit | _Circuit | str], *, qubit_mapping: WithJsonSchema(json_schema={'anyOf': [{'type': 'array', 'items': {'type': 'object', 'required': ['logical_name', 'physical_name'], 'properties': {'logical_name': {'type': 'string'}, 'physical_name': {'type': 'string'}}, 'additionalProperties': False}}, {'type': 'null'}]}, mode=None)] | None = None, calibration_set_id: UUID | None = None, shots: int = 1, options: CircuitCompilationOptions | None = None) → PostJobsRequest#

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 (Annotated[dict[str, str], BeforeValidator(func=~iqm.station_control.interface.models.circuit._parse_legacy_qubit_mapping, json_schema_input_type=PydanticUndefined), PlainSerializer(func=~iqm.station_control.interface.models.circuit._serialize_as_legacy_qubit_mapping, return_type=PydanticUndefined, when_used=always), WithJsonSchema(json_schema={'anyOf': [{'type': 'array', 'items': {'type': 'object', 'required': ['logical_name', 'physical_name'], 'properties': {'logical_name': {'type': 'string'}, 'physical_name': {'type': 'string'}}, 'additionalProperties': False}}, {'type': 'null'}]}, mode=None)] | 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 request to execute a circuit batch to 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.

Return type:

CircuitJob

get_job(job_id: UUID) → CircuitJob#

Build a new job object for a submitted job.

Can be used e.g. when you wish to query the results of a job submitted in a different Python session.

Parameters:: job_id (UUID) – ID of the job to query.
Returns:: Job object, can be used to query the results.
Return type:: CircuitJob

cancel_job(job_id: UUID) → None#

Cancel a job that has been submitted for execution.

A canceled job will remain in the server database, but it will not be executed. If the job is currently being executed, it is interrupted. If the job was already executed (or failed), it will remain in its current terminal state.

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

delete_job(job_id: UUID) → None#

Delete a job that has been submitted for execution.

Works like cancel_job(), but also removes the job from the IQM Server database.

Warning

There is no way to recover a deleted job.

Parameters:: job_id (UUID) – ID of the job to be deleted.
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.
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.
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.
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.
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.

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.
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.
Return type:: ObservationFinder

Inheritance

IQMClient

Contents

IQMClient#