General state (exact) simulation¶

Module for simulating circuits with no predetermined tensor network structure.

class pytket.extensions.cutensornet.general_state.GeneralState(circuit, attributes=None, scratch_fraction=0.8, loglevel=30, logfile=None)[source]¶

Wrapper of cuTensorNet’s NetworkState for exact simulation of states.

Constructs a tensor network for the output state of a pytket circuit. The qubits are assumed to be initialised in the |0> state. The object stores the uncontracted tensor network.

Note

Preferably used as with GeneralState(...) as state: so that GPU memory is automatically released after execution.

The circuit must not contain any CircBox or non-unitary command.

Parameters:

circuit (Circuit) – A pytket circuit to be converted into a tensor network.
attributes (dict | None) – Optional. A dict of cuTensorNet TNConfig keys and their values.
scratch_fraction (float) – Optional. Fraction of free memory on GPU to allocate as scratch space; value between 0 and 1. Defaults to 0.8.
loglevel (int) – Internal logger output level. Use 30 for warnings only, 20 for verbose and 10 for debug mode.
logfile (str | None) – If provided, log is written to this file rather than stream.

sample(n_shots, symbol_map=None, seed=None)[source]¶

Obtains samples from the measurements at the end of the circuit.

Parameters:

n_shots (int) – The number of samples to obtain.
symbol_map (dict[Symbol, float] | None) – A dictionary where each element of the pytket circuit’s .free_symbols() is assigned a real number.
seed (int | None) – An optional RNG seed. Different calls to sample with the same seed will generate the same list of shot outcomes.

Return type:

BackendResult

Returns:

A pytket BackendResult with the data from the shots.

Raises:

ValueError – If the circuit contains no measurements.
ValueError – If not every free symbol in the circuit is assigned a value in symbol_map.

get_amplitude(state, symbol_map=None)[source]¶

Returns the amplitude of the chosen computational state.

Note

The result is equivalent to state.get_statevector[b], but this method is faster when querying a single amplitude (or just a few).

Parameters:

state (int) – The integer whose bitstring describes the computational state. The qubits in the bitstring are in increasing lexicographic order.
symbol_map (dict[Symbol, float] | None) – A dictionary where each element of the pytket circuit’s .free_symbols() is assigned a real number.

Return type:

complex

Returns:

The amplitude of the computational state in self.

Raises:

ValueError – If not every free symbol in the circuit is assigned a value in symbol_map.

get_statevector(symbol_map=None, on_host=True)[source]¶

Contracts the circuit and returns the final statevector.

Parameters:

symbol_map (dict[Symbol, float] | None) – A dictionary where each element of the pytket circuit’s .free_symbols() is assigned a real number.
on_host (bool) – Optional. If True, converts cupy ndarray to numpy ndarray, copying it to host device (CPU). Defaults to True.

Return type:

cp.ndarray | np.ndarray

Returns:

Either a cupy.ndarray on a GPU, or a numpy.ndarray on a host device (CPU). Arrays are returned in a 1D shape.

Raises:

ValueError – If not every free symbol in the circuit is assigned a value in symbol_map.

expectation_value(operator, symbol_map=None)[source]¶

Calculates the expectation value of the given operator.

Parameters:

operator (QubitPauliOperator) – The operator whose expectation value is to be calculated.
symbol_map (dict[Symbol, float] | None) – A dictionary where each element of the pytket circuit’s .free_symbols() is assigned a real number.

Return type:

complex

Returns:

The expectation value.

Raises:

ValueError – If the operator acts on qubits not present in the circuit.
ValueError – If not every free symbol in the circuit is assigned a value in symbol_map.

destroy()[source]¶

Destroy the tensor network and free up GPU memory.

The preferred approach is to use a context manager as in with GeneralState(...) as state:. Otherwise, the user must release memory explicitly by calling destroy().

Return type:: None

class pytket.extensions.cutensornet.general_state.GeneralBraOpKet(bra, ket, attributes=None, scratch_fraction=0.8, loglevel=30, logfile=None)[source]¶

Constructs a tensor network for <bra|operator|ket>.

The qubits in ket and bra are assumed to be initialised in the |0> state. The object stores the uncontracted tensor network.

Note

Preferably used as with GeneralBraOpKet(...) as braket: so that GPU memory is automatically released after execution.

The circuits must not contain any CircBox or non-unitary command.

The operator is provided when contract is called.

Parameters:

bra (Circuit) – A pytket circuit describing the |bra> state.
ket (Circuit) – A pytket circuit describing the |ket> state.
attributes (dict | None) – Optional. A dict of cuTensorNet TNConfig keys and their values.
scratch_fraction (float) – Optional. Fraction of free memory on GPU to allocate as scratch space; value between 0 and 1. Defaults to 0.8.
loglevel (int) – Internal logger output level. Use 30 for warnings only, 20 for verbose and 10 for debug mode.
logfile (str | None) – If provided, log is written to this file rather than stream.

Raises:

ValueError – If the circuits for ket or bra contain measurements.
ValueError – If the set of qubits of ket and bra do not match.

contract(operator=None, symbol_map=None)[source]¶

Contract the tensor network to obtain the value of <bra|operator|ket>.

Parameters:

operator (QubitPauliOperator | None) – A pytket QubitPauliOperator describing the operator. If not given, then the identity operator is used, so it computes inner product.
symbol_map (dict[Symbol, float] | None) – A dictionary where each element of both pytket circuits’ .free_symbols() is assigned a real number.

Return type:

complex

Returns:

The value of <bra|operator|ket>.

Raises:

ValueError – If operator acts on qubits that are not in the circuits.

destroy()[source]¶

Destroy the tensor network and free up GPU memory.

The preferred approach is to use a context manager as in with GeneralBraOpKet(...) as braket:. Otherwise, the user must release memory explicitly by calling destroy().

Return type:: None

Pytket backend¶

Module for conversion from tket primitives to cuQuantum primitives.

class pytket.extensions.cutensornet.CuTensorNetShotsBackend[source]¶

A pytket Backend using GeneralState to obtain shots.

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

Submits circuits to the backend for running.

The results will be stored in the backend’s result cache to be retrieved by the corresponding get_<data> method.

Note

Any element from the TNConfig enum (see NVIDIA’s CuTensorNet API) can be provided as arguments to this method. For instance: process_circuits(..., tn_config={"num_hyper_samples": 100}).

Parameters:

circuits (Sequence[Circuit]) – List of circuits to be submitted.
n_shots (int | Sequence[int] | None) – Number of shots in case of shot-based calculation. Optionally, this can be a list of shots specifying the number of shots for each circuit separately.
valid_check (bool) – Whether to check for circuit correctness.
seed – An optional RNG seed. Different calls to process_circuits with the same seed will generate the same list of shot outcomes.
tnconfig – Optional. A dict of cuTensorNet TNConfig keys and their values.
scratch_fraction – Optional. Fraction of free memory on GPU to allocate as scratch space; value between 0 and 1. Defaults to 0.8.

Return type:

list[ResultHandle]

Returns:

Results handle objects.

property backend_info: BackendInfo | None¶: Returns information on the backend.

class pytket.extensions.cutensornet.CuTensorNetStateBackend[source]¶

A pytket Backend using GeneralState to obtain state vectors.

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

Submits circuits to the backend for running.

The results will be stored in the backend’s result cache to be retrieved by the corresponding get_<data> method.

Note

Any element from the TNConfig enum (see NVIDIA’s CuTensorNet API) can be provided as arguments to this method. For instance: process_circuits(..., tn_config={"num_hyper_samples": 100}).

Parameters:

circuits (Sequence[Circuit]) – List of circuits to be submitted.
n_shots (int | Sequence[int] | None) – Number of shots in case of shot-based calculation. This should be None, since this backend does not support shots.
valid_check (bool) – Whether to check for circuit correctness.
tnconfig – Optional. A dict of cuTensorNet TNConfig keys and their values.
scratch_fraction – Optional. Fraction of free memory on GPU to allocate as scratch space; value between 0 and 1. Defaults to 0.8.

Return type:

list[ResultHandle]

Returns:

Results handle objects.

property backend_info: BackendInfo | None¶: Returns information on the backend.