iqm.iqm_client.iqm_client.IQMClient

iqm.iqm_client.iqm_client.IQMClient#

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

Bases: object

Provides access to IQM quantum computers.

Parameters:

  • url (str) – Endpoint for accessing the server. Has to start with http or https.

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

  • token (str | None) – Long-lived authentication token in plain text format. Used by IQM Resonance. 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.

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

__del__()

_check_authentication_errors(result)

Raise ClientAuthenticationError with appropriate message if the authentication failed for some reason.

_check_not_found_error(response)

Raise HTTPError with appropriate message if response.status_code == 404.

_check_versions()

Check the client version against compatible client versions reported by server.

_default_headers()

Default headers for HTTP requests to the IQM server.

_deserialize_response(response, model_class)

Deserialize a HTTP endpoint response.

_get_calibration_quality_metrics([...])

See get_calibration_quality_metrics().

_get_dut_label()

_get_request(api_endpoint[, endpoint_args, ...])

Make an HTTP GET request to an IQM server endpoint.

abort_job(job_id, *[, timeout_secs])

Abort a job that was submitted for execution.

close_auth_session()

Terminate session with authentication server if there is one.

create_run_request(circuits, *[, ...])

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

get_about()

Return information about the IQM client.

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()

Return the status of the station control service.

get_quality_metric_set([calibration_set_id])

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

get_run(job_id, *[, timeout_secs])

Query the status and results of a submitted job.

get_run_counts(job_id, *[, timeout_secs])

Query the counts of an executed job.

get_run_status(job_id, *[, timeout_secs])

Query the status of a submitted job.

get_static_quantum_architecture()

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

get_supported_client_libraries([timeout_secs])

Retrieve information about supported client libraries from the server.

submit_circuits(circuits, *[, ...])

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

submit_run_request(run_request)

Submit a run request for execution on a quantum computer.

wait_for_compilation(job_id[, timeout_secs])

Poll results until a job is either compiled, pending execution, ready, failed, aborted, or timed out.

wait_for_results(job_id[, timeout_secs])

Poll results until a job is either ready, failed, aborted, or timed out.
get_about() → dict#

Return information about the IQM client.

Return type:

dict

get_health() → dict#

Return the status of the station control service.

Return type:

dict

submit_circuits(circuits: list[Circuit | str], *, qubit_mapping: dict[str, str] | None = None, custom_settings: dict[str, Any] | None = None, calibration_set_id: UUID | None = None, shots: int = 1, options: CircuitCompilationOptions | None = None) → UUID#

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

Parameters:

  • circuits (list[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.

  • custom_settings (dict[str, Any] | None) – Custom settings to override default settings and calibration data. Note: This field should always be None in normal use.

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

ID for the created job. This ID is needed to query the job status and the execution results.

Return type:

UUID

create_run_request(circuits: list[Circuit | str], *, qubit_mapping: dict[str, str] | None = None, custom_settings: dict[str, Any] | None = None, calibration_set_id: UUID | None = None, shots: int = 1, options: CircuitCompilationOptions | None = None) → RunRequest#

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

  • custom_settings (dict[str, Any] | None) – Custom settings to override default settings and calibration data. Note: This field should always be None in normal use.

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

RunRequest

submit_run_request(run_request: RunRequest) → UUID#

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 (RunRequest) – Run request to be submitted for execution.

Returns:

ID for the created job. This ID is needed to query the job status and the execution results.

Return type:

UUID

get_run(job_id: UUID, *, timeout_secs: float = 120.0) → RunResult#

Query the status and results of a submitted job.

Parameters:

  • job_id (UUID) – ID of the job to query.

  • timeout_secs (float) – Network request timeout (seconds).

Returns:

Result of the job (can be pending).

Raises:
Return type:

RunResult

get_run_status(job_id: UUID, *, timeout_secs: float = 120.0) → RunStatus#

Query the status of a submitted job.

Parameters:

  • job_id (UUID) – ID of the job to query.

  • timeout_secs (float) – Network request timeout (seconds).

Returns:

Job status.

Raises:
Return type:

RunStatus

wait_for_compilation(job_id: UUID, timeout_secs: float = 900) → RunResult#

Poll results until a job is either compiled, pending execution, ready, failed, aborted, or timed out.

Parameters:

  • job_id (UUID) – ID of the job to wait for.

  • timeout_secs (float) – How long to wait for a response before raising an APITimeoutError (seconds).

Returns:

Job result.

Raises:

APITimeoutError – time exceeded the set timeout

Return type:

RunResult

wait_for_results(job_id: UUID, timeout_secs: float = 900) → RunResult#

Poll results until a job is either ready, failed, aborted, or timed out.

Note that jobs handling on the server side is async and if we try to request the results right after submitting the job (which is usually the case) we will find the job is still pending at least for the first query.

Parameters:

  • job_id (UUID) – ID of the job to wait for.

  • timeout_secs (float) – How long to wait for a response before raising an APITimeoutError (seconds).

Returns:

Job result.

Raises:

APITimeoutError – time exceeded the set timeout

Return type:

RunResult

abort_job(job_id: UUID, *, timeout_secs: float = 120.0) → None#

Abort a job that was submitted for execution.

Parameters:

  • job_id (UUID) – ID of the job to be aborted.

  • timeout_secs (float) – Network request timeout (seconds).

Raises:

JobAbortionError – aborting the job failed

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

StaticQuantumArchitecture

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

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

QualityMetricSet

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

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

CalibrationSet

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

tuple[frozenset[str], …]

get_run_counts(job_id: UUID, *, timeout_secs: float = 120.0) → RunCounts#

Query the counts of an executed job.

Parameters:

  • job_id (UUID) – ID of the job to query.

  • timeout_secs (float) – Network request timeout (seconds).

Returns:

Measurement results of the job in histogram representation.

Raises:
Return type:

RunCounts

get_supported_client_libraries(timeout_secs: float = 120.0) → dict[str, ClientLibrary] | None#

Retrieve information about supported client libraries from the server.

Parameters:

timeout_secs (float) – Network request timeout (seconds).

Returns:

Mapping from library identifiers to their metadata.

Raises:
Return type:

dict[str, ClientLibrary] | None

close_auth_session() → bool#

Terminate session with authentication server if there is one.

Returns:

True iff session was successfully closed.

Raises:
Return type:

bool

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

ObservationFinder

Contents