API documentation

class pytket.extensions.qiskit.IBMQBackend(backend_name, instance=None, monitor=True, service=None, token=None, sampler_options=None)[source]

Bases: Backend

A backend for running circuits on remote IBMQ devices.

The provider arguments of hub, group and project can be specified here as parameters or set in the config file using pytket.extensions.qiskit.set_ibmq_config(). This function can also be used to set the IBMQ API token.

Parameters:
Raises:

ValueError – If no IBMQ account is loaded and none exists on the disk.

__init__(backend_name, instance=None, monitor=True, service=None, token=None, sampler_options=None)[source]
classmethod available_devices(**kwargs)[source]

Retrieve all available devices as a list of BackendInfo objects, including device name, architecture, supported gate set, gate errors, and other hardware-specific information.

Returns:

A list of BackendInfo objects describing available devices.

Return type:

List[BackendInfo]

cancel(handle)[source]

Cancel a job.

Parameters:

handle (ResultHandle) – handle to job

Raises:

NotImplementedError – If backend does not support job cancellation

Return type:

None

circuit_status(handle)[source]

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

Return type:

CircuitStatus

default_compilation_pass(optimisation_level=2, timeout=300)[source]

A suggested compilation pass that will will, if possible, produce an equivalent circuit suitable for running on this backend.

At a minimum it will ensure that compatible gates are used and that all two- qubit interactions are compatible with the backend’s qubit architecture. At higher optimisation levels, further optimisations may be applied.

This is a an abstract method which is implemented in the backend itself, and so is tailored to the backend’s requirements.

The default compilation passes for the IBMQBackend and the

Parameters:

  • optimisation_level (int) – The level of optimisation to perform during compilation.

  • timeout (int) –

    Parameter for optimisation level 3, given in seconds.

    • Level 0 does the minimum required to solves the device constraints, without any optimisation.

    • Level 1 additionally performs some light optimisations.

    • Level 2 (the default) adds more computationally intensive optimisations that should give the best results from execution.

    • Level 3 re-synthesises the circuit using the computationally intensive GreedyPauliSimp. This will remove any barriers while optimising.

Return type:

BasePass

Returns:

Compilation pass guaranteeing required predicates.

get_compiled_circuit(circuit, optimisation_level=2, timeout=300)[source]

Return a single circuit compiled with default_compilation_pass().

Parameters:

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

  • timeout (int, optional) – Only valid for optimisation level 3, gives a maximimum time for running a single thread of the pass GreedyPauliSimp. Increase for optimising larger circuits.

Returns:

An optimised quantum circuit

Return type:

Circuit

get_compiled_circuits(circuits, optimisation_level=2, timeout=300)[source]

Compile a sequence of circuits with default_compilation_pass() and return the list of compiled circuits (does not act in place).

As well as applying a degree of optimisation (controlled by the optimisation_level parameter), this method tries to ensure that the circuits can be run on the backend (i.e. successfully passed to process_circuits()), for example by rebasing to the supported gate set, or routing to match the connectivity of the device. However, this is not always possible, for example if the circuit contains classical operations that are not supported by the backend. You may use valid_circuit() to check whether the circuit meets the backend’s requirements after compilation. This validity check is included in process_circuits() by default, before any circuits are submitted to the backend.

If the validity check fails, you can obtain more information about the failure by iterating through the predicates in the required_predicates property of the backend, and running the verify() method on each in turn with your circuit.

Parameters:

  • circuits (Sequence[Circuit]) – The circuits to compile.

  • optimisation_level (int, optional) – The level of optimisation to perform during compilation. See default_compilation_pass() for a description of the different levels (0, 1, 2 or 3). Defaults to 2.

  • timeout (int, optional) – Only valid for optimisation level 3, gives a maximimum time for running a single thread of the pass GreedyPauliSimp. Increase for optimising larger circuits.

Returns:

Compiled circuits.

Return type:

List[Circuit]

get_result(handle, **kwargs)[source]

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

Return type:

BackendResult

process_circuits(circuits, n_shots=None, valid_check=True, **kwargs)[source]

See pytket.backends.Backend.process_circuits().

Keyword Arguments:
  • 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)

  • sampler_options:

    A customised qiskit_ibm_runtime SamplerOptions instance. See the Qiskit documentation at https://docs.quantum.ibm.com/api/qiskit-ibm-runtime/qiskit_ibm_runtime.options.SamplerOptions for details and default values.

Return type:

list[ResultHandle]

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

property backend_info: BackendInfo

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

class pytket.extensions.qiskit.IBMQEmulatorBackend(backend_name, instance=None, service=None, token=None)[source]

Bases: Backend

A backend which uses the AerBackend to loaclly emulate the behaviour of IBMQBackend. Identical to IBMQBackend except there is no monitor parameter. Performs the same compilation and predicate checks as IBMQBackend. Requires a valid IBM account.

__init__(backend_name, instance=None, service=None, token=None)[source]
cancel(handle)[source]

Cancel a job.

Parameters:

handle (ResultHandle) – handle to job

Raises:

NotImplementedError – If backend does not support job cancellation

Return type:

None

circuit_status(handle)[source]

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

Return type:

CircuitStatus

default_compilation_pass(optimisation_level=2)[source]

See documentation for IBMQBackend.default_compilation_pass().

Return type:

BasePass

get_result(handle, **kwargs)[source]

See pytket.backends.Backend.get_result(). Supported kwargs: none.

Return type:

BackendResult

process_circuits(circuits, n_shots=None, valid_check=True, **kwargs)[source]

See pytket.backends.Backend.process_circuits(). Supported kwargs: seed, postprocess.

Return type:

list[ResultHandle]

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

property backend_info: BackendInfo

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

class pytket.extensions.qiskit.AerBackend(noise_model=None, simulation_method='automatic', crosstalk_params=None, n_qubits=40)[source]

Backend for running simulations on the Qiskit Aer QASM simulator.

Parameters:
__init__(noise_model=None, simulation_method='automatic', crosstalk_params=None, n_qubits=40)[source]
classmethod available_devices(**kwargs)

Retrieve all available devices as a list of BackendInfo objects, including device name, architecture, supported gate set, gate errors, and other hardware-specific information.

Returns:

A list of BackendInfo objects describing available devices.

Return type:

List[BackendInfo]

cancel(handle)

Cancel a job.

Parameters:

handle (ResultHandle) – handle to job

Raises:

NotImplementedError – If backend does not support job cancellation

Return type:

None

circuit_status(handle)

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

Return type:

CircuitStatus

default_compilation_pass(optimisation_level=2, timeout=300)

See documentation for IBMQBackend.default_compilation_pass().

Return type:

BasePass

empty_cache()

Manually empty the result cache on the backend.

Return type:

None

get_compiled_circuit(circuit, optimisation_level=2, timeout=300)

Return a single circuit compiled with default_compilation_pass().

Parameters:

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

  • timeout (int, optional) – Only valid for optimisation level 3, gives a maximimum time for running a single thread of the pass GreedyPauliSimp. Increase for optimising larger circuits.

Returns:

An optimised quantum circuit

Return type:

Circuit

get_compiled_circuits(circuits, optimisation_level=2, timeout=300)

Compile a sequence of circuits with default_compilation_pass() and return the list of compiled circuits (does not act in place).

As well as applying a degree of optimisation (controlled by the optimisation_level parameter), this method tries to ensure that the circuits can be run on the backend (i.e. successfully passed to process_circuits()), for example by rebasing to the supported gate set, or routing to match the connectivity of the device. However, this is not always possible, for example if the circuit contains classical operations that are not supported by the backend. You may use valid_circuit() to check whether the circuit meets the backend’s requirements after compilation. This validity check is included in process_circuits() by default, before any circuits are submitted to the backend.

If the validity check fails, you can obtain more information about the failure by iterating through the predicates in the required_predicates property of the backend, and running the verify() method on each in turn with your circuit.

Parameters:

  • circuits (Sequence[Circuit]) – The circuits to compile.

  • optimisation_level (int, optional) – The level of optimisation to perform during compilation. See default_compilation_pass() for a description of the different levels (0, 1, 2 or 3). Defaults to 2.

  • timeout (int, optional) – Only valid for optimisation level 3, gives a maximimum time for running a single thread of the pass GreedyPauliSimp. Increase for optimising larger circuits.

Returns:

Compiled circuits.

Return type:

List[Circuit]

get_operator_expectation_value(state_circuit, operator, valid_check=True)

Calculates the expectation value of the given circuit with respect to the operator using the built-in Aer snapshot functionality Requires a simple circuit with default register qubits.

Parameters:

  • state_circuit (Circuit) – Circuit that generates the desired state \(\left|\psi\right>\).

  • operator (QubitPauliOperator) – Operator \(H\).

  • valid_check (bool) – Explicitly check that the circuit satisfies all required predicates to run on the backend. Defaults to True

Return type:

complex

Returns:

\(\left<\psi | H | \psi \right>\)

get_pauli_expectation_value(state_circuit, pauli, valid_check=True)

Calculates the expectation value of the given circuit using the built-in Aer snapshot functionality Requires a simple circuit with default register qubits.

Parameters:

  • state_circuit (Circuit) – Circuit that generates the desired state \(\left|\psi\right>\).

  • pauli (QubitPauliString) – Pauli operator

  • valid_check (bool) – Explicitly check that the circuit satisfies all required predicates to run on the backend. Defaults to True

Return type:

complex

Returns:

\(\left<\psi | P | \psi \right>\)

get_result(handle, **kwargs)

Return a BackendResult corresponding to the handle.

Use keyword arguments to specify parameters to be used in retrieving results. See specific Backend derived class for available parameters, from the following list:

  • timeout: maximum time to wait for remote job to finish

  • wait: polling interval between remote calls to check job status

Parameters:

handle (ResultHandle) – handle to results

Returns:

Results corresponding to handle.

Return type:

BackendResult

get_results(handles, **kwargs)

Return results corresponding to handles.

Parameters:

handles (Iterable[ResultHandle]) – Iterable of handles

Return type:

list[BackendResult]

Returns:

List of results

Keyword arguments are as for get_result, and apply to all jobs.

pop_result(handle)

Remove cache entry corresponding to handle from the cache and return.

Parameters:

handle (ResultHandle) – ResultHandle object

Returns:

Cache entry corresponding to handle, if it was present

Return type:

Optional[ResultCache]

process_circuit(circuit, n_shots=None, valid_check=True, **kwargs)

Submit a single circuit to the backend for running. See Backend.process_circuits().

Return type:

ResultHandle

process_circuits(circuits, n_shots=None, valid_check=True, **kwargs)

See pytket.backends.Backend.process_circuits(). Supported kwargs: seed, postprocess.

Return type:

list[ResultHandle]

rebase_pass()

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

run_circuit(circuit, n_shots=None, valid_check=True, **kwargs)

Submits a circuit to the backend and returns results

Parameters:

  • circuit (Circuit) – Circuit to be executed

  • n_shots (Optional[int]) – Passed on to Backend.process_circuit()

  • valid_check (bool) – Passed on to Backend.process_circuit()

Return type:

BackendResult

Returns:

Result

This is a convenience method equivalent to calling Backend.process_circuit() followed by Backend.get_result(). Any additional keyword arguments are passed on to Backend.process_circuit() and Backend.get_result().

run_circuits(circuits, n_shots=None, valid_check=True, **kwargs)

Submits circuits to the backend and returns results

Parameters:

  • circuits (Sequence[Circuit]) – Sequence of Circuits to be executed

  • n_shots (Union[int, Sequence[int], None]) – Passed on to Backend.process_circuits()

  • valid_check (bool) – Passed on to Backend.process_circuits()

Return type:

list[BackendResult]

Returns:

List of results

This is a convenience method equivalent to calling Backend.process_circuits() followed by Backend.get_results(). Any additional keyword arguments are passed on to Backend.process_circuits() and Backend.get_results().

valid_circuit(circuit)

Checks that the circuit satisfies all of required_predicates.

Parameters:

circuit (Circuit) – The circuit to check.

Returns:

Whether or not all of required_predicates are satisfied.

Return type:

bool

property backend_info: BackendInfo

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 expectation_allows_nonhermitian: bool

If expectations are supported, is the operator allowed to be non-Hermitan?

property persistent_handles: bool

Whether the backend produces ResultHandle objects that can be reused with other instances of the backend class.

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 supports_contextual_optimisation: bool

Does this backend support contextual optimisation?

See process_circuits().

property supports_counts: bool

Does this backend support counts result retrieval via backendresult.BackendResult.get_counts().

property supports_density_matrix: bool

Does this backend support density matrix retrieval via get_density_matrix.

property supports_expectation: bool

Does this backend support expectation value calculation for operators.

property supports_shots: bool

Does this backend support shot result retrieval via backendresult.BackendResult.get_shots().

property supports_state: bool

Does this backend support statevector retrieval via backendresult.BackendResult.get_state().

property supports_unitary: bool

Does this backend support unitary retrieval via backendresult.BackendResult.get_unitary().

class pytket.extensions.qiskit.AerStateBackend(n_qubits=40)[source]

Backend for running simulations on the Qiskit Aer Statevector simulator.

Parameters:

n_qubits (int) – The maximum number of qubits supported by the backend.

__init__(n_qubits=40)[source]
classmethod available_devices(**kwargs)

Retrieve all available devices as a list of BackendInfo objects, including device name, architecture, supported gate set, gate errors, and other hardware-specific information.

Returns:

A list of BackendInfo objects describing available devices.

Return type:

List[BackendInfo]

cancel(handle)

Cancel a job.

Parameters:

handle (ResultHandle) – handle to job

Raises:

NotImplementedError – If backend does not support job cancellation

Return type:

None

circuit_status(handle)

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

Return type:

CircuitStatus

default_compilation_pass(optimisation_level=2, timeout=300)

See documentation for IBMQBackend.default_compilation_pass().

Return type:

BasePass

empty_cache()

Manually empty the result cache on the backend.

Return type:

None

get_compiled_circuit(circuit, optimisation_level=2, timeout=300)

Return a single circuit compiled with default_compilation_pass().

Parameters:

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

  • timeout (int, optional) – Only valid for optimisation level 3, gives a maximimum time for running a single thread of the pass GreedyPauliSimp. Increase for optimising larger circuits.

Returns:

An optimised quantum circuit

Return type:

Circuit

get_compiled_circuits(circuits, optimisation_level=2, timeout=300)

Compile a sequence of circuits with default_compilation_pass() and return the list of compiled circuits (does not act in place).

As well as applying a degree of optimisation (controlled by the optimisation_level parameter), this method tries to ensure that the circuits can be run on the backend (i.e. successfully passed to process_circuits()), for example by rebasing to the supported gate set, or routing to match the connectivity of the device. However, this is not always possible, for example if the circuit contains classical operations that are not supported by the backend. You may use valid_circuit() to check whether the circuit meets the backend’s requirements after compilation. This validity check is included in process_circuits() by default, before any circuits are submitted to the backend.

If the validity check fails, you can obtain more information about the failure by iterating through the predicates in the required_predicates property of the backend, and running the verify() method on each in turn with your circuit.

Parameters:

  • circuits (Sequence[Circuit]) – The circuits to compile.

  • optimisation_level (int, optional) – The level of optimisation to perform during compilation. See default_compilation_pass() for a description of the different levels (0, 1, 2 or 3). Defaults to 2.

  • timeout (int, optional) – Only valid for optimisation level 3, gives a maximimum time for running a single thread of the pass GreedyPauliSimp. Increase for optimising larger circuits.

Returns:

Compiled circuits.

Return type:

List[Circuit]

get_operator_expectation_value(state_circuit, operator, valid_check=True)

Calculates the expectation value of the given circuit with respect to the operator using the built-in Aer snapshot functionality Requires a simple circuit with default register qubits.

Parameters:

  • state_circuit (Circuit) – Circuit that generates the desired state \(\left|\psi\right>\).

  • operator (QubitPauliOperator) – Operator \(H\).

  • valid_check (bool) – Explicitly check that the circuit satisfies all required predicates to run on the backend. Defaults to True

Return type:

complex

Returns:

\(\left<\psi | H | \psi \right>\)

get_pauli_expectation_value(state_circuit, pauli, valid_check=True)

Calculates the expectation value of the given circuit using the built-in Aer snapshot functionality Requires a simple circuit with default register qubits.

Parameters:

  • state_circuit (Circuit) – Circuit that generates the desired state \(\left|\psi\right>\).

  • pauli (QubitPauliString) – Pauli operator

  • valid_check (bool) – Explicitly check that the circuit satisfies all required predicates to run on the backend. Defaults to True

Return type:

complex

Returns:

\(\left<\psi | P | \psi \right>\)

get_result(handle, **kwargs)

Return a BackendResult corresponding to the handle.

Use keyword arguments to specify parameters to be used in retrieving results. See specific Backend derived class for available parameters, from the following list:

  • timeout: maximum time to wait for remote job to finish

  • wait: polling interval between remote calls to check job status

Parameters:

handle (ResultHandle) – handle to results

Returns:

Results corresponding to handle.

Return type:

BackendResult

get_results(handles, **kwargs)

Return results corresponding to handles.

Parameters:

handles (Iterable[ResultHandle]) – Iterable of handles

Return type:

list[BackendResult]

Returns:

List of results

Keyword arguments are as for get_result, and apply to all jobs.

pop_result(handle)

Remove cache entry corresponding to handle from the cache and return.

Parameters:

handle (ResultHandle) – ResultHandle object

Returns:

Cache entry corresponding to handle, if it was present

Return type:

Optional[ResultCache]

process_circuit(circuit, n_shots=None, valid_check=True, **kwargs)

Submit a single circuit to the backend for running. See Backend.process_circuits().

Return type:

ResultHandle

process_circuits(circuits, n_shots=None, valid_check=True, **kwargs)

See pytket.backends.Backend.process_circuits(). Supported kwargs: seed, postprocess.

Return type:

list[ResultHandle]

rebase_pass()

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

run_circuit(circuit, n_shots=None, valid_check=True, **kwargs)

Submits a circuit to the backend and returns results

Parameters:

  • circuit (Circuit) – Circuit to be executed

  • n_shots (Optional[int]) – Passed on to Backend.process_circuit()

  • valid_check (bool) – Passed on to Backend.process_circuit()

Return type:

BackendResult

Returns:

Result

This is a convenience method equivalent to calling Backend.process_circuit() followed by Backend.get_result(). Any additional keyword arguments are passed on to Backend.process_circuit() and Backend.get_result().

run_circuits(circuits, n_shots=None, valid_check=True, **kwargs)

Submits circuits to the backend and returns results

Parameters:

  • circuits (Sequence[Circuit]) – Sequence of Circuits to be executed

  • n_shots (Union[int, Sequence[int], None]) – Passed on to Backend.process_circuits()

  • valid_check (bool) – Passed on to Backend.process_circuits()

Return type:

list[BackendResult]

Returns:

List of results

This is a convenience method equivalent to calling Backend.process_circuits() followed by Backend.get_results(). Any additional keyword arguments are passed on to Backend.process_circuits() and Backend.get_results().

valid_circuit(circuit)

Checks that the circuit satisfies all of required_predicates.

Parameters:

circuit (Circuit) – The circuit to check.

Returns:

Whether or not all of required_predicates are satisfied.

Return type:

bool

property backend_info: BackendInfo

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 expectation_allows_nonhermitian: bool

If expectations are supported, is the operator allowed to be non-Hermitan?

property persistent_handles: bool

Whether the backend produces ResultHandle objects that can be reused with other instances of the backend class.

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 supports_contextual_optimisation: bool

Does this backend support contextual optimisation?

See process_circuits().

property supports_counts: bool

Does this backend support counts result retrieval via backendresult.BackendResult.get_counts().

property supports_density_matrix: bool

Does this backend support density matrix retrieval via get_density_matrix.

property supports_expectation: bool

Does this backend support expectation value calculation for operators.

property supports_shots: bool

Does this backend support shot result retrieval via backendresult.BackendResult.get_shots().

property supports_state: bool

Does this backend support statevector retrieval via backendresult.BackendResult.get_state().

property supports_unitary: bool

Does this backend support unitary retrieval via backendresult.BackendResult.get_unitary().

class pytket.extensions.qiskit.AerUnitaryBackend(n_qubits=40)[source]

Backend for running simulations on the Qiskit Aer Unitary simulator.

Parameters:

n_qubits (int) – The maximum number of qubits supported by the backend.

__init__(n_qubits=40)[source]
classmethod available_devices(**kwargs)

Retrieve all available devices as a list of BackendInfo objects, including device name, architecture, supported gate set, gate errors, and other hardware-specific information.

Returns:

A list of BackendInfo objects describing available devices.

Return type:

List[BackendInfo]

cancel(handle)

Cancel a job.

Parameters:

handle (ResultHandle) – handle to job

Raises:

NotImplementedError – If backend does not support job cancellation

Return type:

None

circuit_status(handle)

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

Return type:

CircuitStatus

default_compilation_pass(optimisation_level=2, timeout=300)

See documentation for IBMQBackend.default_compilation_pass().

Return type:

BasePass

empty_cache()

Manually empty the result cache on the backend.

Return type:

None

get_compiled_circuit(circuit, optimisation_level=2, timeout=300)

Return a single circuit compiled with default_compilation_pass().

Parameters:

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

  • timeout (int, optional) – Only valid for optimisation level 3, gives a maximimum time for running a single thread of the pass GreedyPauliSimp. Increase for optimising larger circuits.

Returns:

An optimised quantum circuit

Return type:

Circuit

get_compiled_circuits(circuits, optimisation_level=2, timeout=300)

Compile a sequence of circuits with default_compilation_pass() and return the list of compiled circuits (does not act in place).

As well as applying a degree of optimisation (controlled by the optimisation_level parameter), this method tries to ensure that the circuits can be run on the backend (i.e. successfully passed to process_circuits()), for example by rebasing to the supported gate set, or routing to match the connectivity of the device. However, this is not always possible, for example if the circuit contains classical operations that are not supported by the backend. You may use valid_circuit() to check whether the circuit meets the backend’s requirements after compilation. This validity check is included in process_circuits() by default, before any circuits are submitted to the backend.

If the validity check fails, you can obtain more information about the failure by iterating through the predicates in the required_predicates property of the backend, and running the verify() method on each in turn with your circuit.

Parameters:

  • circuits (Sequence[Circuit]) – The circuits to compile.

  • optimisation_level (int, optional) – The level of optimisation to perform during compilation. See default_compilation_pass() for a description of the different levels (0, 1, 2 or 3). Defaults to 2.

  • timeout (int, optional) – Only valid for optimisation level 3, gives a maximimum time for running a single thread of the pass GreedyPauliSimp. Increase for optimising larger circuits.

Returns:

Compiled circuits.

Return type:

List[Circuit]

get_operator_expectation_value(state_circuit, operator, valid_check=True)

Calculates the expectation value of the given circuit with respect to the operator using the built-in Aer snapshot functionality Requires a simple circuit with default register qubits.

Parameters:

  • state_circuit (Circuit) – Circuit that generates the desired state \(\left|\psi\right>\).

  • operator (QubitPauliOperator) – Operator \(H\).

  • valid_check (bool) – Explicitly check that the circuit satisfies all required predicates to run on the backend. Defaults to True

Return type:

complex

Returns:

\(\left<\psi | H | \psi \right>\)

get_pauli_expectation_value(state_circuit, pauli, valid_check=True)

Calculates the expectation value of the given circuit using the built-in Aer snapshot functionality Requires a simple circuit with default register qubits.

Parameters:

  • state_circuit (Circuit) – Circuit that generates the desired state \(\left|\psi\right>\).

  • pauli (QubitPauliString) – Pauli operator

  • valid_check (bool) – Explicitly check that the circuit satisfies all required predicates to run on the backend. Defaults to True

Return type:

complex

Returns:

\(\left<\psi | P | \psi \right>\)

get_result(handle, **kwargs)

Return a BackendResult corresponding to the handle.

Use keyword arguments to specify parameters to be used in retrieving results. See specific Backend derived class for available parameters, from the following list:

  • timeout: maximum time to wait for remote job to finish

  • wait: polling interval between remote calls to check job status

Parameters:

handle (ResultHandle) – handle to results

Returns:

Results corresponding to handle.

Return type:

BackendResult

get_results(handles, **kwargs)

Return results corresponding to handles.

Parameters:

handles (Iterable[ResultHandle]) – Iterable of handles

Return type:

list[BackendResult]

Returns:

List of results

Keyword arguments are as for get_result, and apply to all jobs.

pop_result(handle)

Remove cache entry corresponding to handle from the cache and return.

Parameters:

handle (ResultHandle) – ResultHandle object

Returns:

Cache entry corresponding to handle, if it was present

Return type:

Optional[ResultCache]

process_circuit(circuit, n_shots=None, valid_check=True, **kwargs)

Submit a single circuit to the backend for running. See Backend.process_circuits().

Return type:

ResultHandle

process_circuits(circuits, n_shots=None, valid_check=True, **kwargs)

See pytket.backends.Backend.process_circuits(). Supported kwargs: seed, postprocess.

Return type:

list[ResultHandle]

rebase_pass()

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

run_circuit(circuit, n_shots=None, valid_check=True, **kwargs)

Submits a circuit to the backend and returns results

Parameters:

  • circuit (Circuit) – Circuit to be executed

  • n_shots (Optional[int]) – Passed on to Backend.process_circuit()

  • valid_check (bool) – Passed on to Backend.process_circuit()

Return type:

BackendResult

Returns:

Result

This is a convenience method equivalent to calling Backend.process_circuit() followed by Backend.get_result(). Any additional keyword arguments are passed on to Backend.process_circuit() and Backend.get_result().

run_circuits(circuits, n_shots=None, valid_check=True, **kwargs)

Submits circuits to the backend and returns results

Parameters:

  • circuits (Sequence[Circuit]) – Sequence of Circuits to be executed

  • n_shots (Union[int, Sequence[int], None]) – Passed on to Backend.process_circuits()

  • valid_check (bool) – Passed on to Backend.process_circuits()

Return type:

list[BackendResult]

Returns:

List of results

This is a convenience method equivalent to calling Backend.process_circuits() followed by Backend.get_results(). Any additional keyword arguments are passed on to Backend.process_circuits() and Backend.get_results().

valid_circuit(circuit)

Checks that the circuit satisfies all of required_predicates.

Parameters:

circuit (Circuit) – The circuit to check.

Returns:

Whether or not all of required_predicates are satisfied.

Return type:

bool

property backend_info: BackendInfo

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 expectation_allows_nonhermitian: bool

If expectations are supported, is the operator allowed to be non-Hermitan?

property persistent_handles: bool

Whether the backend produces ResultHandle objects that can be reused with other instances of the backend class.

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 supports_contextual_optimisation: bool

Does this backend support contextual optimisation?

See process_circuits().

property supports_counts: bool

Does this backend support counts result retrieval via backendresult.BackendResult.get_counts().

property supports_density_matrix: bool

Does this backend support density matrix retrieval via get_density_matrix.

property supports_expectation: bool

Does this backend support expectation value calculation for operators.

property supports_shots: bool

Does this backend support shot result retrieval via backendresult.BackendResult.get_shots().

property supports_state: bool

Does this backend support statevector retrieval via backendresult.BackendResult.get_state().

property supports_unitary: bool

Does this backend support unitary retrieval via backendresult.BackendResult.get_unitary().

class pytket.extensions.qiskit.AerDensityMatrixBackend(noise_model=None, n_qubits=40)[source]

Backend for running simulations on the Qiskit Aer density matrix simulator.

Parameters:

  • noise_model (Optional[NoiseModel]) – Noise model to apply during simulation. Defaults to None.

  • n_qubits (int) – The maximum number of qubits supported by the backend.

__init__(noise_model=None, n_qubits=40)[source]
classmethod available_devices(**kwargs)

Retrieve all available devices as a list of BackendInfo objects, including device name, architecture, supported gate set, gate errors, and other hardware-specific information.

Returns:

A list of BackendInfo objects describing available devices.

Return type:

List[BackendInfo]

cancel(handle)

Cancel a job.

Parameters:

handle (ResultHandle) – handle to job

Raises:

NotImplementedError – If backend does not support job cancellation

Return type:

None

circuit_status(handle)

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

Return type:

CircuitStatus

default_compilation_pass(optimisation_level=2, timeout=300)

See documentation for IBMQBackend.default_compilation_pass().

Return type:

BasePass

empty_cache()

Manually empty the result cache on the backend.

Return type:

None

get_compiled_circuit(circuit, optimisation_level=2, timeout=300)

Return a single circuit compiled with default_compilation_pass().

Parameters:

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

  • timeout (int, optional) – Only valid for optimisation level 3, gives a maximimum time for running a single thread of the pass GreedyPauliSimp. Increase for optimising larger circuits.

Returns:

An optimised quantum circuit

Return type:

Circuit

get_compiled_circuits(circuits, optimisation_level=2, timeout=300)

Compile a sequence of circuits with default_compilation_pass() and return the list of compiled circuits (does not act in place).

As well as applying a degree of optimisation (controlled by the optimisation_level parameter), this method tries to ensure that the circuits can be run on the backend (i.e. successfully passed to process_circuits()), for example by rebasing to the supported gate set, or routing to match the connectivity of the device. However, this is not always possible, for example if the circuit contains classical operations that are not supported by the backend. You may use valid_circuit() to check whether the circuit meets the backend’s requirements after compilation. This validity check is included in process_circuits() by default, before any circuits are submitted to the backend.

If the validity check fails, you can obtain more information about the failure by iterating through the predicates in the required_predicates property of the backend, and running the verify() method on each in turn with your circuit.

Parameters:

  • circuits (Sequence[Circuit]) – The circuits to compile.

  • optimisation_level (int, optional) – The level of optimisation to perform during compilation. See default_compilation_pass() for a description of the different levels (0, 1, 2 or 3). Defaults to 2.

  • timeout (int, optional) – Only valid for optimisation level 3, gives a maximimum time for running a single thread of the pass GreedyPauliSimp. Increase for optimising larger circuits.

Returns:

Compiled circuits.

Return type:

List[Circuit]

get_operator_expectation_value(state_circuit, operator, valid_check=True)

Calculates the expectation value of the given circuit with respect to the operator using the built-in Aer snapshot functionality Requires a simple circuit with default register qubits.

Parameters:

  • state_circuit (Circuit) – Circuit that generates the desired state \(\left|\psi\right>\).

  • operator (QubitPauliOperator) – Operator \(H\).

  • valid_check (bool) – Explicitly check that the circuit satisfies all required predicates to run on the backend. Defaults to True

Return type:

complex

Returns:

\(\left<\psi | H | \psi \right>\)

get_pauli_expectation_value(state_circuit, pauli, valid_check=True)

Calculates the expectation value of the given circuit using the built-in Aer snapshot functionality Requires a simple circuit with default register qubits.

Parameters:

  • state_circuit (Circuit) – Circuit that generates the desired state \(\left|\psi\right>\).

  • pauli (QubitPauliString) – Pauli operator

  • valid_check (bool) – Explicitly check that the circuit satisfies all required predicates to run on the backend. Defaults to True

Return type:

complex

Returns:

\(\left<\psi | P | \psi \right>\)

get_result(handle, **kwargs)

Return a BackendResult corresponding to the handle.

Use keyword arguments to specify parameters to be used in retrieving results. See specific Backend derived class for available parameters, from the following list:

  • timeout: maximum time to wait for remote job to finish

  • wait: polling interval between remote calls to check job status

Parameters:

handle (ResultHandle) – handle to results

Returns:

Results corresponding to handle.

Return type:

BackendResult

get_results(handles, **kwargs)

Return results corresponding to handles.

Parameters:

handles (Iterable[ResultHandle]) – Iterable of handles

Return type:

list[BackendResult]

Returns:

List of results

Keyword arguments are as for get_result, and apply to all jobs.

pop_result(handle)

Remove cache entry corresponding to handle from the cache and return.

Parameters:

handle (ResultHandle) – ResultHandle object

Returns:

Cache entry corresponding to handle, if it was present

Return type:

Optional[ResultCache]

process_circuit(circuit, n_shots=None, valid_check=True, **kwargs)

Submit a single circuit to the backend for running. See Backend.process_circuits().

Return type:

ResultHandle

process_circuits(circuits, n_shots=None, valid_check=True, **kwargs)

See pytket.backends.Backend.process_circuits(). Supported kwargs: seed, postprocess.

Return type:

list[ResultHandle]

rebase_pass()

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

run_circuit(circuit, n_shots=None, valid_check=True, **kwargs)

Submits a circuit to the backend and returns results

Parameters:

  • circuit (Circuit) – Circuit to be executed

  • n_shots (Optional[int]) – Passed on to Backend.process_circuit()

  • valid_check (bool) – Passed on to Backend.process_circuit()

Return type:

BackendResult

Returns:

Result

This is a convenience method equivalent to calling Backend.process_circuit() followed by Backend.get_result(). Any additional keyword arguments are passed on to Backend.process_circuit() and Backend.get_result().

run_circuits(circuits, n_shots=None, valid_check=True, **kwargs)

Submits circuits to the backend and returns results

Parameters:

  • circuits (Sequence[Circuit]) – Sequence of Circuits to be executed

  • n_shots (Union[int, Sequence[int], None]) – Passed on to Backend.process_circuits()

  • valid_check (bool) – Passed on to Backend.process_circuits()

Return type:

list[BackendResult]

Returns:

List of results

This is a convenience method equivalent to calling Backend.process_circuits() followed by Backend.get_results(). Any additional keyword arguments are passed on to Backend.process_circuits() and Backend.get_results().

valid_circuit(circuit)

Checks that the circuit satisfies all of required_predicates.

Parameters:

circuit (Circuit) – The circuit to check.

Returns:

Whether or not all of required_predicates are satisfied.

Return type:

bool

property backend_info: BackendInfo

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 expectation_allows_nonhermitian: bool

If expectations are supported, is the operator allowed to be non-Hermitan?

property persistent_handles: bool

Whether the backend produces ResultHandle objects that can be reused with other instances of the backend class.

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 supports_contextual_optimisation: bool

Does this backend support contextual optimisation?

See process_circuits().

property supports_counts: bool

Does this backend support counts result retrieval via backendresult.BackendResult.get_counts().

property supports_density_matrix: bool

Does this backend support density matrix retrieval via get_density_matrix.

property supports_expectation: bool

Does this backend support expectation value calculation for operators.

property supports_shots: bool

Does this backend support shot result retrieval via backendresult.BackendResult.get_shots().

property supports_state: bool

Does this backend support statevector retrieval via backendresult.BackendResult.get_state().

property supports_unitary: bool

Does this backend support unitary retrieval via backendresult.BackendResult.get_unitary().

Module for conversion between IBM Qiskit and tket primitives.

pytket.extensions.qiskit.process_characterisation(backend)[source]

Convert a qiskit_ibm_runtime.ibm_backend.IBMBackend to a dictionary containing device Characteristics

Parameters:

backend (IBMBackend) – A backend to be converted

Return type:

dict[str, Any]

Returns:

A dictionary containing device characteristics

pytket.extensions.qiskit.qiskit_to_tk(qcirc, preserve_param_uuid=False)[source]

Converts a qiskit qiskit.QuantumCircuit to a pytket Circuit.

Parameters:

  • qcirc (QuantumCircuit) – A circuit to be converted

  • preserve_param_uuid (bool) – Whether to preserve symbolic Parameter uuids by appending them to the tket Circuit symbol names as “_UUID:<uuid>”. This can be useful if you want to reassign Parameters after conversion to tket and back, as it is necessary for Parameter object equality to be preserved.

Return type:

Circuit

Returns:

The converted circuit

pytket.extensions.qiskit.tk_to_qiskit(tkcirc, replace_implicit_swaps=False, perm_warning=True)[source]

Converts a pytket Circuit to a qiskit qiskit.QuantumCircuit.

In many cases there will be a qiskit gate to exactly replace each tket gate. If no exact replacement can be found for a part of the circuit then an equivalent circuit will be returned using the tket gates which are supported in qiskit.

Note that implicit swaps in a pytket Circuit are not handled by default. Consider using the replace_implicit_swaps flag to replace these implicit swaps with SWAP gates.

Parameters:

  • tkcirc (Circuit) – A Circuit to be converted

  • replace_implicit_swaps (bool) – Implement implicit permutation by adding SWAPs to the end of the circuit.

  • perm_warning (bool) – Warn if an input circuit has implicit qubit permutations, and replace_implicit_swaps is False. True by default.

Return type:

QuantumCircuit

Returns:

The converted circuit

class pytket.extensions.qiskit.tket_backend.TketBackend(backend, comp_pass=None)[source]

Bases: BackendV2

Wraps a Backend as a qiskit.providers.BaseBackend for use within the Qiskit software stack.

Each qiskit.circuit.quantumcircuit.QuantumCircuit passed in will be converted to a Circuit object. If a BasePass is provided for comp_pass, this is applied to the Circuit. Then it is processed by the Backend, wrapping the ResultHandle s in a TketJob, retrieving the results when called on the job object. The required predicates of the Backend are presented to the Qiskit transpiler to enable it to perform the compilation in many cases. This may not always be possible due to unsupported gatesets or additional constraints that cannot be captured in Qiskit’s transpiler, in which case a custom qiskit.transpiler.TranspilationPass should be used to map into a tket- compatible gateset and set comp_pass to compile for the backend. To compile with tket only, set comp_pass and just use Qiskit to map into a tket-compatible gateset. In Qiskit Aqua, you should wrap the TketBackend in a qiskit.aqua.QuantumInstance, providing a custom qiskit.transpiler.PassManager with a qiskit.transpiler.passes.Unroller. For examples, see the user manual or the Qiskit integration example.

__init__(backend, comp_pass=None)[source]

Create a new TketBackend from a Backend.

Parameters:

  • backend (Backend) – The device or simulator to wrap up

  • comp_pass (Optional[BasePass]) – The (optional) tket compilation pass to apply to each circuit before submitting to the Backend, defaults to None

run(run_input, **options)[source]

Run on the backend.

This method returns a Job object that runs circuits. Depending on the backend this may be either an async or sync call. It is at the discretion of the provider to decide whether running should block until the execution is finished or not: the Job class can handle either situation.

Parameters:

  • run_input (QuantumCircuit or Schedule or ScheduleBlock or list) – An individual or a list of QuantumCircuit, ScheduleBlock, or Schedule objects to run on the backend.

  • options (Any) – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object.

Returns:

The job object for the run

Return type:

Job

property max_circuits: int

The maximum number of circuits (or Pulse schedules) that can be run in a single job.

If there is no limit this will return None

property target: Target

A qiskit.transpiler.Target object for the backend.

Return type:

Target

class pytket.extensions.qiskit.backends.crosstalk_model.CrosstalkParams(zz_crosstalks, single_q_phase_errors, two_q_induced_phase_errors, non_markovian_noise, virtual_z, N, gate_times, phase_damping_error, amplitude_damping_error)[source]

Stores various parameters for modelling crosstalk noise

Parameters:

  • zz_crosstalks (dict[tuple[Qubit, Qubit], float]) – symmetric crosstalks between qubit pairs

  • single_q_phase_errors (dict[Qubit, float]) – dict specify the single qubit phase error on each qubit

  • two_q_induced_phase_errors (dict[tuple[Qubit, Qubit], tuple[Qubit, float]]) – keys of dictionary specify the control and target qubit index, while the values are tuples with the spectator qubit index and the amount of phase error to be applied.

  • non_markovian_noise (list[tuple[Qubit, float, float]]) – List storing the non-Markovian noise parameters. Each tuple in the list contains the qubit index and the zx, zz noise parameters.

  • virtual_z (bool) – If True, then don’t break any single qubit Z gate into unitary fractions, instead add the full unitary.

  • N (float) – hyperparameter specifies splices per second. 1/N must divide all gate times.

  • gate_times (dict[tuple[OpType, tuple[Qubit, ...]], float]) – python dict to store the gate time information.

  • phase_damping_error (dict[Qubit, float]) – dict specify amplitude phase damping error on each qubit

  • amplitude_damping_error (dict[Qubit, float]) – dict pecify amplitude damping error on each qubit

get_noise_model()[source]

Construct a NoiseModel from phase_damping_error and amplitude_damping_error

Return type:

NoiseModel

class pytket.extensions.qiskit.tket_pass.TketAutoPass(backend, optimisation_level=2, token=None)[source]

The tket compiler to be plugged in to the Qiskit compilation sequence

__init__(backend, optimisation_level=2, token=None)[source]

Identifies a Qiskit backend and provides the corresponding default compilation pass from pytket as a qiskit.transpiler.TransformationPass.

Parameters:

  • backend (BackendV2) – The Qiskit backend to target. Accepts Aer or IBMQ backends.

  • optimisation_level (int) – The level of optimisation to perform during compilation. Level 0 just solves the device constraints without optimising. Level 1 additionally performs some light optimisations. Level 2 adds more computationally intensive optimisations. Defaults to 2.

  • token (Optional[str]) – Authentication token to use the QiskitRuntimeService.

class pytket.extensions.qiskit.tket_pass.TketPass(tket_pass)[source]

The tket compiler to be plugged in to the Qiskit compilation sequence

__init__(tket_pass)[source]

Wraps a pytket compiler pass as a qiskit.transpiler.TransformationPass. A qiskit.dagcircuit.DAGCircuit is converted to a pytket Circuit. tket_pass will be run and the result is converted back.

Parameters:

tket_pass (BasePass) – The pytket compiler pass to run

run(dag)[source]

Run a preconfigured optimisation pass on the circuit and route for the given backend.

Parameters:

dag (DAGCircuit) – The circuit to optimise and route

Return type:

DAGCircuit

Returns:

The modified circuit

class pytket.extensions.qiskit.tket_job.JobInfo(circuit_name, qbits, cbits, n_shots)[source]
__init__(circuit_name, qbits, cbits, n_shots)
class pytket.extensions.qiskit.tket_job.TketJob(backend, handles, jobinfos, final_maps)[source]

TketJob wraps a ResultHandle list as a qiskit.providers.JobV1

__init__(backend, handles, jobinfos, final_maps)[source]

Initializes the asynchronous job.

cancel()[source]

Attempt to cancel the job.

Return type:

None

result(**kwargs)[source]

Return the results of the job.

Return type:

Result

status()[source]

Return the status of the job, among the values of JobStatus.

Return type:

Any

submit()[source]

Submit the job to the backend for execution.

Return type:

None

class pytket.extensions.qiskit.backends.config.QiskitConfig(instance, ibmq_api_token)[source]

Holds config parameters for pytket-qiskit.

classmethod from_extension_dict(ext_dict)[source]

Abstract method to build PytketExtConfig from dictionary serialized form.

Return type:

QiskitConfig

pytket.extensions.qiskit.backends.config.set_ibmq_config(instance=None, ibmq_api_token=None)[source]

Set default values for any of hub, group, project or API token for your IBMQ provider. Can be overridden in backend construction.

Return type:

None