API documentation#

Backends for processing pytket circuits with Quantinuum devices

enum pytket.extensions.quantinuum.Language(value)[source]#

Language used for submission of circuits.

Valid values are as follows:

QASM = <Language.QASM: 'OPENQASM 2.0'>#
QIR = <Language.QIR: 'QIR 1.0'>#
class pytket.extensions.quantinuum.QuantinuumAPI(token_store: CredentialStorage | None = None, api_url: str | None = None, api_version: int = 1, use_websocket: bool = True, provider: str | None = None, support_mfa: bool = True, session: Session | None = None, _QuantinuumAPI__user_name: str | None = None, _QuantinuumAPI__pwd: str | None = None)[source]#

Interface to the Quantinuum online remote API.

__init__(token_store: CredentialStorage | None = None, api_url: str | None = None, api_version: int = 1, use_websocket: bool = True, provider: str | None = None, support_mfa: bool = True, session: Session | None = None, _QuantinuumAPI__user_name: str | None = None, _QuantinuumAPI__pwd: str | None = None)[source]#

Initialize Quantinuum API client.

Parameters:
  • token_store (CredentialStorage, optional) – JWT Token store, defaults to None A new MemoryCredentialStorage will be initialised if None is provided.

  • api_url (Optional[str], optional) – _description_, defaults to DEFAULT_API_URL

  • api_version (int, optional) – API version, defaults to 1

  • use_websocket (bool, optional) – Whether to use websocket to retrieve, defaults to True

  • support_mfa (bool, optional) – Whether to wait for the user to input the auth code, defaults to True

  • session (requests.Session, optional) – Session for HTTP requests, defaults to None A new requests.Session will be initialised if None is provided

cancel(job_id: str) dict[source]#

Cancels job.

Parameters:

job_id (str) – job ID to cancel

Returns:

(dict) output from API

delete_authentication() None[source]#

Remove stored credentials and tokens

full_login() None[source]#

Ask for user credentials from std input and update JWT tokens

login() str[source]#

This methods checks if we have a valid (non-expired) id-token and returns it, otherwise it gets a new one with refresh-token. If refresh-token doesn’t exist, it asks user for credentials.

Returns:

(str) login token

retrieve_job(job_id: str, use_websocket: bool | None = None) Dict | None[source]#

Retrieves job from device.

Parameters:
  • job_id (str) – unique id of job

  • use_websocket (bool) – use websocket to minimize interaction

Returns:

(dict) output from API

retrieve_job_status(job_id: str, use_websocket: bool | None = None) Dict | None[source]#

Retrieves job status from device.

Parameters:
  • job_id (str) – unique id of job

  • use_websocket (bool) – use websocket to minimize interaction

Returns:

(dict) output from API

status(machine: str) str[source]#

Check status of machine.

Parameters:

machine (str) – machine name

Returns:

(str) status of machine

__weakref__#

list of weak references to the object (if defined)

class pytket.extensions.quantinuum.QuantinuumAPIOffline(machine_list: list | None = None)[source]#

Offline copy of the interface to the Quantinuum remote API.

__init__(machine_list: list | None = None)[source]#

Initialize offline API client.

Tries to allow all the operations of the QuantinuumAPI without any interaction with the remote device.

All jobs that are submitted to this offline API are stored and can be requested again later.

Parameters:

machine_list (list) – List of dictionaries each containing device information. The format of should match what a real backend would return. One short example: { “name”: “H1-1”, “n_qubits”: 20, “gateset”: [“RZZ”, “Riswap”, “Rxxyyzz”], “n_shots”: 10000, “batching”: True, }

cancel(job_id: str) dict[source]#

No cancel offline

full_login() None[source]#

No login offline with the offline API :return: None

get_jobs() list | None[source]#

The function will return all the jobs that have been submitted

Returns:

List of all the submitted jobs

login() str[source]#

No login offline with the offline API, this function will always return an empty api token :return: empty api token

retrieve_job(job_id: str, use_websocket: bool | None = None) None[source]#

No retrieve_job_status offline

retrieve_job_status(job_id: str, use_websocket: bool | None = None) None[source]#

No retrieve_job_status offline

status(machine: str) str[source]#

No retrieve_job_status offline

__weakref__#

list of weak references to the object (if defined)

class pytket.extensions.quantinuum.QuantinuumBackend(device_name: str, label: str | None = 'job', simulator: str = 'state-vector', group: str | None = None, provider: str | None = None, machine_debug: bool = False, api_handler: ~pytket.extensions.quantinuum.backends.api_wrappers.QuantinuumAPI = <pytket.extensions.quantinuum.backends.api_wrappers.QuantinuumAPI object>, compilation_config: ~pytket.extensions.quantinuum.backends.quantinuum.QuantinuumBackendCompilationConfig | None = None, **kwargs: int | float | str | None | ~pytket.wasm.wasm.WasmFileHandler | ~typing.Dict[str, ~typing.Any] | ~pytket.circuit.OpType | bool)[source]#

Interface to a Quantinuum device. More information about the QuantinuumBackend can be found on this page https://tket.quantinuum.com/extensions/pytket-quantinuum/api/index.html

__init__(device_name: str, label: str | None = 'job', simulator: str = 'state-vector', group: str | None = None, provider: str | None = None, machine_debug: bool = False, api_handler: ~pytket.extensions.quantinuum.backends.api_wrappers.QuantinuumAPI = <pytket.extensions.quantinuum.backends.api_wrappers.QuantinuumAPI object>, compilation_config: ~pytket.extensions.quantinuum.backends.quantinuum.QuantinuumBackendCompilationConfig | None = None, **kwargs: int | float | str | None | ~pytket.wasm.wasm.WasmFileHandler | ~typing.Dict[str, ~typing.Any] | ~pytket.circuit.OpType | bool)[source]#

Construct a new Quantinuum backend.

Parameters:
  • device_name (str) – Name of device, e.g. “H1-1”

  • label (Optional[str], optional) – Job labels used if Circuits have no name, defaults to “job”

  • simulator (str, optional) – Only applies to simulator devices, options are “state-vector” or “stabilizer”, defaults to “state-vector”

  • group (Optional[str], optional) – string identifier of a collection of jobs, can be used for usage tracking.

  • provider (Optional[str], optional) – select a provider for federated authentication. We currently only support ‘microsoft’, which enables the microsoft Device Flow.

  • api_handler (QuantinuumAPI) – Instance of API handler, defaults to DEFAULT_API_HANDLER

  • compilation_config (QuantinuumBackendCompilationConfig) – Optional compilation configuration

Supported kwargs:

add_to_batch(batch_start_job: ResultHandle, circuit: Circuit, n_shots: None | int = None, batch_end: bool = False, valid_check: bool = True, **kwargs: int | float | str | None | WasmFileHandler | Dict[str, Any] | OpType | bool) ResultHandle[source]#

Add to a batch of jobs on the backend, behaves like process_circuit except in two ways:

1. The first argument must be the result handle of the first job of batch.

2. The optional argument batch_end should be set to “True” for the final circuit of the batch. By default it is False.

See pytket.backends.Backend.process_circuits() for documentation on remaining parameters.

Parameters:
  • batch_start_job (ResultHandle) – Handle of first circuit submitted to batch.

  • batch_end (bool, optional) – Boolean flag to signal the final circuit of batch, defaults to False

Returns:

Handle for submitted circuit.

Return type:

ResultHandle

classmethod available_devices(**kwargs: Any) List[BackendInfo][source]#

See pytket.backends.Backend.available_devices(). :param api_handler: Instance of API handler, defaults to DEFAULT_API_HANDLER :type api_handler: Optional[QuantinuumAPI]

cancel(handle: ResultHandle) None[source]#

Cancel a job.

Parameters:

handle (ResultHandle) – handle to job

Raises:

NotImplementedError – If backend does not support job cancellation

circuit_status(handle: ResultHandle, **kwargs: int | float | str | None) CircuitStatus[source]#

Return a CircuitStatus reporting the status of the circuit execution corresponding to the ResultHandle

cost(circuit: Circuit, n_shots: int, syntax_checker: str | None = None, use_websocket: bool | None = None, **kwargs: int | float | str | None | WasmFileHandler | Dict[str, Any] | OpType | bool) float | None[source]#

Return the cost in HQC to complete this circuit with n_shots repeats. If the backend is not a syntax checker (backend name does not end with “SC”), it is automatically appended to check against the relevant syntax checker.

See QuantinuumBackend.process_circuits() for the supported kwargs.

Parameters:
  • circuit (Circuit) – Circuit to calculate runtime estimate for. Must be valid for backend.

  • n_shots (int) – Number of shots.

  • syntax_checker (str) – Optional. Name of the syntax checker to use to get cost. For example for the “H1-1” device that would be “H1-1SC”. For most devices this is automatically inferred, default=None.

  • use_websocket (bool) – Optional. Boolean flag to use a websocket connection.

Raises:

ValueError – Circuit is not valid, needs to be compiled.

Returns:

Cost in HQC to execute the shots.

Return type:

float

cost_estimate(circuit: Circuit, n_shots: int) float | None[source]#

Deprecated, use cost.

default_compilation_pass(optimisation_level: int = 2) BasePass[source]#
Parameters:

optimisation_level (int) – Allows values of 0,1 or 2, with higher values prompting more computationally heavy optimising compilation that can lead to reduced gate count in circuits.

Returns:

Compilation pass for compiling circuits to Quantinuum devices

Return type:

BasePass

classmethod device_state(device_name: str, api_handler: ~pytket.extensions.quantinuum.backends.api_wrappers.QuantinuumAPI = <pytket.extensions.quantinuum.backends.api_wrappers.QuantinuumAPI object>) str[source]#

Check the status of a device.

>>> QuantinuumBackend.device_state('H1') # e.g. "online"
Parameters:
  • device_name (str) – Name of the device.

  • api_handler (QuantinuumAPI) – Instance of API handler, defaults to DEFAULT_API_HANDLER

Returns:

String of state, e.g. “online”

Return type:

str

get_compilation_config() QuantinuumBackendCompilationConfig[source]#

Get the current compilation configuration.

static get_jobid(handle: ResultHandle) str[source]#

Return the corresponding Quantinuum Job ID from a ResultHandle.

Parameters:

handle (ResultHandle) – result handle.

Returns:

Quantinuum API Job ID string.

Return type:

str

get_partial_result(handle: ResultHandle) Tuple[BackendResult | None, CircuitStatus][source]#

Retrieve partial results for a given job, regardless of its current state.

Parameters:

handle (ResultHandle) – handle to results

Returns:

A tuple containing the results and circuit status. If no results are available, the first element is None.

Return type:

Tuple[Optional[BackendResult], CircuitStatus]

static get_ppcirc_rep(handle: ResultHandle) Any[source]#

Return the JSON serialization of the classiocal postprocessing circuit attached to a handle, if any.

Parameters:

handle – result handle

Returns:

serialized post-processing circuit, if any

get_result(handle: ResultHandle, **kwargs: int | float | str | None) BackendResult[source]#

See pytket.backends.Backend.get_result(). Supported kwargs: timeout, wait, use_websocket.

static get_results_selection(handle: ResultHandle) Any[source]#

Return a list of pairs (register name, register index) representing the order of the expected results in the response. If None, then all results in the response are used, in lexicographic order.

static get_results_width(handle: ResultHandle) int | None[source]#

Return the truncation width of the results, if any.

Parameters:

handle – result handle

Returns:

truncation width of results, if any

login() None[source]#

Log in to Quantinuum API. Requests username and password from stdin (e.g. shell input or dialogue box in Jupytet notebooks.). Passwords are not stored. After log in you should not need to provide credentials again while that session (script/notebook) is alive.

logout() None[source]#

Clear stored JWT tokens from login. Will need to login again to make API calls.

process_circuits(circuits: Sequence[Circuit], n_shots: None | int | Sequence[int | None] = None, valid_check: bool = True, **kwargs: int | float | str | None | WasmFileHandler | Dict[str, Any] | OpType | bool) List[ResultHandle][source]#

See pytket.backends.Backend.process_circuits().

Supported kwargs:

  • postprocess: apply end-of-circuit simplifications and classical postprocessing to improve fidelity of results (bool, default False)

  • simplify_initial: apply the pytket SimplifyInitial pass to improve fidelity of results assuming all qubits initialized to zero (bool, default False)

  • noisy_simulation: boolean flag to specify whether the simulator should perform noisy simulation with an error model (default value is True).

  • group: string identifier of a collection of jobs, can be used for usage tracking. Overrides the instance variable group.

  • wasm_file_handler: a WasmFileHandler object for linked WASM module.

  • pytketpass: a pytket.passes.BasePass intended to be applied

    by the backend (beta feature, may be ignored).

  • no_opt: if true, requests that the backend perform no optimizations

  • allow_2q_gate_rebase: if true, allow rebasing of the two-qubit gates to a

    higher-fidelity alternative gate at the discretion of the backend

  • options: items to add to the “options” dictionary of the request body, as a json-style dictionary (in addition to any that were set in the backend constructor)

  • request_options: extra options to add to the request body as a json-style dictionary

  • language: languange for submission, of type Language, default QASM.

  • leakage_detection: if true, adds additional Qubit and Bit to Circuit to detect leakage errors. Run prune_shots_detected_as_leaky on returned BackendResult to get counts with leakage errors removed.

rebase_pass() BasePass[source]#

A single compilation pass that when run converts all gates in a Circuit to an OpType supported by the Backend (ignoring architecture constraints).

Returns:

Compilation pass that converts gates to primitives supported by Backend.

Return type:

BasePass

set_compilation_config_allow_implicit_swaps(allow_implicit_swaps: bool) None[source]#

Set the option to allow or disallow implicit swaps during compilation.

set_compilation_config_target_2qb_gate(target_2qb_gate: OpType) None[source]#

Set the target two-qubit gate for compilation.

start_batch(max_batch_cost: int, circuit: Circuit, n_shots: None | int = None, valid_check: bool = True, **kwargs: int | float | str | None | WasmFileHandler | Dict[str, Any] | OpType | bool) ResultHandle[source]#
Start a batch of jobs on the backend, behaves like process_circuit

but with additional parameter max_batch_cost as the first argument. See pytket.backends.Backend.process_circuits() for documentation on remaining parameters.

Parameters:

max_batch_cost (int) – Maximum cost to be used for the batch, if a job exceeds the batch max it will be rejected.

Returns:

Handle for submitted circuit.

Return type:

ResultHandle

submit_program(language: Language, program: str, n_shots: int, name: str | None = None, noisy_simulation: bool = True, group: str | None = None, wasm_file_handler: WasmFileHandler | None = None, pytket_pass: BasePass | None = None, no_opt: bool = False, allow_2q_gate_rebase: bool = False, options: Dict[str, Any] | None = None, request_options: Dict[str, Any] | None = None, results_selection: List[Tuple[str, int]] | None = None) ResultHandle[source]#

Submit a program directly to the backend.

Parameters:
  • program (str) – program (encoded as string)

  • language (Language) – language

  • n_shots (int) – Number of shots

  • name (Optional[str], optional) – Job name, defaults to None

  • noisy_simulation (bool) – Boolean flag to specify whether the simulator should perform noisy simulation with an error model defaults to True

  • group (Optional[str], optional) – String identifier of a collection of jobs, can be used for usage tracking. Overrides the instance variable group, defaults to None

  • wasm_file_handler (Optional[WasmFileHandler], optional) – WasmFileHandler object for linked WASM module, defaults to None

  • no_opt (bool, defaults to False) – if true, requests that the backend perform no optimizations

  • allow_2q_gate_rebase (bool, defaults to False) – if true, allow rebasing of the two-qubit gates to a higher-fidelity alternative gate at the discretion of the backend

  • pytket_pass (Optional[BasePass], optional) – pytket.passes.BasePass intended to be applied by the backend (beta feature, may be ignored), defaults to None

  • options (Optional[Dict[str, Any]], optional) – Items to add to the “options” dictionary of the request body

  • request_options (Optional[Dict[str, Any]], optional) – Extra options to add to the request body as a json-style dictionary, defaults to None

  • results_selection (Optional[List[Tuple[str, int]]]) – Ordered list of register names and indices used to construct final BackendResult. If None, all all results are used in lexicographic order.

Raises:
  • WasmUnsupported – WASM submitted to backend that does not support it.

  • QuantinuumAPIError – API error.

  • ConnectionError – Connection to remote API failed

Returns:

ResultHandle for submitted job.

Return type:

ResultHandle

property backend_info: BackendInfo | None#

Retrieve all Backend properties in a BackendInfo object, including device architecture, supported gate set, gate errors and other hardware-specific information.

Returns:

The BackendInfo describing this backend if it exists.

Return type:

Optional[BackendInfo]

property default_two_qubit_gate: OpType#

Returns the default two-qubit gate for the device.

property required_predicates: List[Predicate]#

The minimum set of predicates that a circuit must satisfy before it can be successfully run on this backend.

Returns:

Required predicates.

Return type:

List[Predicate]

property two_qubit_gate_set: Set[OpType]#

Returns the set of supported two-qubit gates.

Submitted circuits must contain only one of these.

class pytket.extensions.quantinuum.QuantinuumBackendCompilationConfig(allow_implicit_swaps: bool = True, target_2qb_gate: OpType | None = None)[source]#

Options to configure default compilation and rebase passes.

  • allow_implicit_swaps: Whether to allow use of implicit swaps when rebasing. The default is to allow implicit swaps.

  • target_2qb_gate: Choice of two-qubit gate. The default is to use the device’s default.

__eq__(other)#

Return self==value.

__init__(allow_implicit_swaps: bool = True, target_2qb_gate: OpType | None = None) None#
__repr__()#

Return repr(self).

__hash__ = None#
__weakref__#

list of weak references to the object (if defined)

Quantinuum config.

class pytket.extensions.quantinuum.backends.config.QuantinuumConfig(username: str | None, refresh_token: str | None, id_token: str | None, refresh_token_timeout: str | None, id_token_timeout: str | None)[source]#

Holds config parameters for pytket-quantinuum.

classmethod from_extension_dict(ext_dict: Dict[str, Any]) QuantinuumConfig[source]#

Abstract method to build PytketExtConfig from dictionary serialized form.

pytket.extensions.quantinuum.backends.config.set_quantinuum_config(username: str | None) None[source]#

Set default value for Quantinuum username. Can be overriden in backend construction.

Methods for generating a leakage detection Pytket Circuit.

pytket.extensions.quantinuum.backends.leakage_gadget.get_detection_circuit(circuit: Circuit, n_device_qubits: int) Circuit[source]#

For a passed circuit, appends a leakage detection circuit for each end of circuit measurement using spare device qubits. All additional Qubit added for leakage detection are written to a new register “leakage_detection_qubit” and all additional Bit are written to a new register “leakage_detection_bit”.

Parameters:
  • circuit (Circuit) – Circuit to have leakage detection added.

  • n_device_qubits (int) – Total number of qubits supported by the device being compiled to.

Returns:

Circuit with leakage detection circuitry added.

Return type:

Circuit

pytket.extensions.quantinuum.backends.leakage_gadget.get_leakage_gadget_circuit(circuit_qubit: Qubit, postselection_qubit: Qubit, postselection_bit: Bit) Circuit[source]#

Returns a two qubit Circuit for detecting leakage errors.

Parameters:
  • circuit_qubit (Qubit) – Generated circuit detects whether leakage errors have occurred in this qubit.

  • postselection_qubit (Qubit) – Measured qubit to detect leakage error.

  • postselection_bit (Bit) – Leakage detection result is written to this bit.

Returns:

Circuit for detecting leakage errors for specified ids.

Return type:

Circuit

pytket.extensions.quantinuum.backends.leakage_gadget.prune_shots_detected_as_leaky(result: BackendResult) BackendResult[source]#

For all states with a Bit with name “leakage_detection_bit” in a state 1 sets the counts to 0.

Parameters:

result (BackendResult) – Shots returned from device.

Returns:

Shots with leakage cases removed.

Return type:

BackendResult