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, auth_server_url: str | None = None, username: str | None = None, password: str | None = None, api_variant: APIVariant | 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 (Optional[str]) – String that IQMClient adds to User-Agent header of requests it sends to the server. The signature is appended to IQMClients own version information and is intended to carry additional version information, for example the version information of the caller.

  • token (Optional[str]) – Long-lived IQM token in plain text format. If token is given no other user authentication parameters should be given.

  • tokens_file (Optional[str]) – Path to a tokens file used for authentication. If tokens_file is given no other user authentication parameters should be given.

  • auth_server_url (Optional[str]) – Base URL of the authentication server. If auth_server_url is given also username and password must be given.

  • username (Optional[str]) – Username to log in to authentication server.

  • password (Optional[str]) – Password to log in to authentication server.

  • api_variant (Optional[APIVariant]) – API variant to use. Default is APIVariant.COCOS. Conviguable also by environment variable IQM_CLIENT_API_VARIANT.

Alternatively, the user authentication related keyword arguments can also be given in environment variables IQM_TOKEN, IQM_TOKENS_FILE, IQM_AUTH_SERVER, IQM_AUTH_USERNAME and IQM_AUTH_PASSWORD. 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)

_check_not_found_error(response)

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

_check_versions()

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

_default_headers()

_get_run_v1(job_id[, timeout_secs])

V1 API (Cocos circuits execution and Resonance) has an inefficient GET /jobs/<id> endpoint that returns the full job status, including the result and the original request, in a single call.

_get_run_v2(job_id[, timeout_secs])

V2 API (Station-based circuits execution) has granular endpoints for job status and result.

_retry_request_on_error(request)

This is a temporary workaround for 502 errors.

_validate_circuit_instructions(architecture, ...)

Validate the given circuits against the given quantum architecture.

_validate_circuit_moves(architecture, circuit)

Raises an error if the MOVE gates in the circuit are not valid in the given architecture.

_validate_instruction(architecture, instruction)

Validate an instruction against the dynamic quantum quantum architecture.

_validate_qubit_mapping(architecture, circuits)

Validates the given qubit mapping, if defined.

abort_job(job_id, *[, timeout_secs])

Abort a job that was submitted for execution.

close_auth_session()

Terminate session with authentication server if there was one created.

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

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

get_dynamic_quantum_architecture([...])

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

get_quantum_architecture(*[, timeout_secs])

Retrieve quantum architecture from server.

get_run(job_id, *[, timeout_secs])

Query the status and results of a submitted job.

get_run_status(job_id, *[, timeout_secs])

Query the status of a submitted job.

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

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

submit_run_request(run_request)

Submits a run request for execution on a quantum computer.

wait_for_compilation(job_id[, timeout_secs])

Poll results until a job is either 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.
submit_circuits(circuits: list[Circuit], *, 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#

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

Parameters:

  • circuits (list[Circuit]) – 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 latest one

  • 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], *, 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#

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

This is called inside 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]) – 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 latest one

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

Submits a run request for execution on a quantum computer.

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

Parameters:

run_request (RunRequest) – the 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 = 60.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

Returns:

result of the job (can be pending)

Raises:
Return type:

RunResult

get_run_status(job_id: UUID, *, timeout_secs: float = 60.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

Returns:

status of the job

Raises:
Return type:

RunStatus

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

Poll results until a job is either 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

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

Returns:

job result

Raises:

APITimeoutError – time exceeded the set timeout

Return type:

RunResult

abort_job(job_id: UUID, *, timeout_secs: float = 60.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

Raises:

JobAbortionError – if aborting the job failed

Return type:

None

get_quantum_architecture(*, timeout_secs: float = 60.0) → QuantumArchitectureSpecification#

Retrieve quantum architecture from server. Caches the result and returns the same result on later invocations.

Parameters:

timeout_secs (float) – network request timeout

Returns:

quantum architecture

Raises:
Return type:

QuantumArchitectureSpecification

get_dynamic_quantum_architecture(calibration_set_id: UUID | None = None, *, timeout_secs: float = 60.0) → DynamicQuantumArchitecture#

Retrieve dynamic quantum architecture (DQA) for the given calibration set from 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 returned. If None, use current default calibration set on the server.

  • timeout_secs (float) – network request timeout

Returns:

dynamic quantum architecture corresponding to the given calibration set

Raises:
Return type:

DynamicQuantumArchitecture

close_auth_session() → bool#

Terminate session with authentication server if there was one created.

Returns:

True iff session was successfully closed

Raises:
Return type:

bool