IQMClient

Module: iqm.iqm_client.iqm_client

class iqm.iqm_client.iqm_client.IQMClient(*, executor: IQMServerExecutor, storage: IQMServerStorage)

Bases: object

Provides access to IQM quantum computers, enabling quantum circuit and pulse schedule execution.

IQMClient represents a connection to a quantum computer (real or simulated), and can be used to execute two kinds of jobs:

• batches of quantum circuits (circuit-level jobs), and

• playlists of control pulse schedules (pulse-level jobs).

Parameters:

• executor (IQMServerExecutor) – IQMServerExecutor instance mapping to backend services.

• storage (IQMServerStorage) – IQMServerStorage instance mapping to backend data repositories.

Attributes

quantum_computer_name

Name of the quantum computer this client is connected to.

Methods

cancel_job	Cancel a job that has been submitted for execution.
create_circuit_job_definition	Create a circuit execution job definition without sending it to the server.
delete_job	Delete a job that has been submitted for execution.
from_url	Utility constructor using IQMServerClient.
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_calibration_set_stash	Contents of a calibration set in a stash adapter.
get_chip_label	QPU label of the current quantum computer.
get_chip_topology	Chip topology of the current quantum computer.
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 tracker 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_standard_compiler	Create a compiler instance for the connected quantum computer.
get_static_quantum_architecture	Retrieve the static quantum architecture (SQA) from the server.
submit_circuit_job	Submit a circuit job to execute a circuit batch to a quantum computer.
submit_circuits	Submit a batch of quantum circuits for execution on a quantum computer.
submit_playlist	Submit a run definition for execution.

static from_url(iqm_server_url: str | None = None, *, quantum_computer: str | None = None, token: str | None = None, tokens_file: str | None = None, client_signature: str | None = None) → IQMClient

Utility constructor using IQMServerClient.

Parameters:

• iqm_server_url (str | None) – 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. If not given, uses the default one on the server.

• 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.

Return type:

IQMClient

Alternatively, the arguments can also be given in environment variables IQM_SERVER_URL, IQM_QUANTUM_COMPUTER, IQM_TOKEN, IQM_TOKENS_FILE. Same combination restrictions apply for values given as environment variables as for the arguments.

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) → CircuitJobTracker

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:

CircuitJobTracker

create_circuit_job_definition(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 circuit execution job definition 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 circuit job definition that would be submitted by submit_circuit_job(), 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:

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

Return type:

PostJobsRequest

submit_circuit_job(circuit_job_definition: PostJobsRequest, *, use_timeslot: bool = False) → CircuitJobTracker

Submit a circuit job 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:

• circuit_job_definition (PostJobsRequest) – Circuit job definition 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:

CircuitJobTracker object, can be used to query the results.

Return type:

CircuitJobTracker

get_job(job_id: UUID) → JobTracker

Build a new job tracker 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:

JobTracker object, can be used to query the results.

Return type:

JobTracker

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 executor.

Return type:

StaticQuantumArchitecture

get_quality_metric_set(calibration_set_id: UUID | None = None) → ObservationSetWithObservationData

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:

ObservationSetWithObservationData

get_calibration_set(calibration_set_id: UUID | None = None) → ObservationSetWithObservationData

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:

ObservationSetWithObservationData

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

property quantum_computer_name: str

Name of the quantum computer this client is connected to.

get_standard_compiler(loading_rules: Sequence[RuleType] | None = None, *, exa_style_pp: bool = True, controller_mapping: dict[str, dict[str, str]] | None = None, gate_definitions: dict[str, QuantumOp] | None = None) → Compiler

Create a compiler instance for the connected quantum computer.

Note

If you only intend to execute circuit-level jobs, you do not need to use this method.

The Compiler enables pulse-level access to the quantum computer. It is used for compiling

• quantum circuits to TimeBoxes

• TimeBoxes to abstract hardware instruction Schedules

• Schedules to a Playlists, which can be submitted for execution using submit_playlist(). TODO explain RunDefinition?

Parameters:

• loading_rules (Sequence[RuleType] | None) – Observation loading rules. If None, will use the current default calibration set.

• exa_style_pp (bool) – Whether to do EXA-style dataset post-processing by default.

• controller_mapping (dict[str, dict[str, str]] | None) – Dictionary that maps physical QPU component names to their device controller names. The dictionary is of the form: {<component_name>: {<operation_name>: <controller name>}}, where operation is one of the following: “drive”, “readout”, “flux” (not all components have all operations supported). If None, use the default controller mapping for the connected quantum computer.

• gate_definitions (dict[str, QuantumOp] | None) – Names of quantum operations mapped to their definitions, see QuantumOp. If None, use the default quantum operations from iqm.pulse.

Returns:

The compiler object.

Return type:

Compiler

submit_playlist(run_definition: RunDefinition, *, context: dict[str, Any], use_timeslot: bool = False) → RunJobTracker

Submit a run definition for execution.

Parameters:

• run_definition (RunDefinition)

• context (dict[str, Any])

• use_timeslot (bool)

Return type:

RunJobTracker

get_chip_label() → str

QPU label of the current quantum computer.

Return type:

str

get_chip_topology() → ChipTopology

Chip topology of the current quantum computer.

Describes the QPU components and their connectivity. Similar to get_static_quantum_architecture(), but provides more detailed information.

Return type:

ChipTopology

get_calibration_set_stash(calibration_set_id: str | UUID | Literal['default'] = 'default') → _ObservationSetStash

Contents of a calibration set in a stash adapter.

Parameters:

calibration_set_id (str | UUID | Literal['default'])

Return type:

_ObservationSetStash

Inheritance