General state (exact) simulation

Module for simulating circuits with no predetermined tensor network structure.

class pytket.extensions.cutensornet.general_state.GeneralState(circuit, libhandle, loglevel=30)[source]

Wrapper of cuTensorNet object for exact simulations via path optimisation.

__init__(circuit, libhandle, loglevel=30)[source]

Constructs a tensor network for the output state of a pytket circuit.

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

Note

A libhandle is created via a with CuTensorNetHandle() as libhandle: statement. The device where the GeneralState is stored will match the one specified by the library handle.

Note

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

Parameters:

  • circuit (Circuit) – A pytket circuit to be converted to a tensor network.

  • libhandle (CuTensorNetHandle) – An instance of a CuTensorNetHandle.

  • loglevel (int) – Internal logger output level.

get_statevector(attributes=None, scratch_fraction=0.75, on_host=True)[source]

Contracts the circuit and returns the final statevector.

Parameters:

  • attributes (Optional[dict]) – Optional. A dict of cuTensorNet StateAttribute keys and their values.

  • scratch_fraction (float) – Optional. Fraction of free memory on GPU to allocate as scratch space.

  • on_host (bool) – Optional. If True, converts cupy ndarray to numpy ndarray, copying it to host device (CPU).

Raises:

MemoryError – If there is insufficient workspace on GPU.

Return type:

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

expectation_value(operator, attributes=None, scratch_fraction=0.75)[source]

Calculates the expectation value of the given operator.

Parameters:

  • operator (QubitPauliOperator) – The operator whose expectation value is to be measured.

  • attributes (Optional[dict]) – Optional. A dict of cuTensorNet ExpectationAttribute keys and their values.

  • scratch_fraction (float) – Optional. Fraction of free memory on GPU to allocate as scratch space.

Raises:

ValueError – If the operator acts on qubits not present in the circuit.

Return type:

complex

Returns:

The expectation value.

sample(n_shots, attributes=None, scratch_fraction=0.75)[source]

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

Parameters:

  • n_shots (int) – The number of samples to obtain.

  • attributes (Optional[dict]) – Optional. A dict of cuTensorNet SamplerAttribute keys and their values.

  • scratch_fraction (float) – Optional. Fraction of free memory on GPU to allocate as scratch space.

Raises:

  • ValueError – If the circuit contains no measurements.

  • MemoryError – If there is insufficient workspace on GPU.

Return type:

BackendResult

Returns:

A pytket BackendResult with the data from the shots.

destroy()[source]

Destroy the tensor network and free up GPU memory. :rtype: None

Note

Users are required to call destroy() when done using a GeneralState object. GPU memory deallocation is not guaranteed otherwise.

cuQuantum contract API interface

class pytket.extensions.cutensornet.general_state.TensorNetwork(circuit, adj=False, loglevel=20)[source]

Responsible for converting pytket circuit to a tensor network and handling it.

class pytket.extensions.cutensornet.general_state.PauliOperatorTensorNetwork(paulis, bra, ket, loglevel=20)[source]

Handles a tensor network representing a Pauli operator string.

class pytket.extensions.cutensornet.general_state.ExpectationValueTensorNetwork(bra, paulis, ket, loglevel=20)[source]

Handles a tensor network representing an expectation value.

pytket.extensions.cutensornet.general_state.tk_to_tensor_network(tkc)[source]

Converts pytket circuit into a tensor network.

Parameters:

tkc (Circuit) – Circuit.

Return type:

List[Union[ndarray[Any, dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]], List]]

Returns:

A tensor network representing the input circuit in the interleaved format (list).

pytket.extensions.cutensornet.general_state.measure_qubits_state(ket, measurement_dict, loglevel=20)[source]

Measures a list of qubits in a tensor network.

Does so by appending a measurement gate to the tensor network. The measurment gate is applied via appending a tensor cap of the form: 0: [1, 0] or 1: [0, 1] to the interleaved einsum input. Therefor removing the open indices of the tensor network corresponding to the measured qubits.

Parameters:

  • ket (TensorNetwork) – a TensorNetwork object representing a quantum state.

  • measurement_dict (dict[Qubit, int]) – a dictionary of qubit ids and their corresponding bit values to be assigned to the measured qubits.

  • loglevel (int) – logging level.

Return type:

TensorNetwork

Returns:

A TensorNetwork object representing a quantum state after the measurement with a modified interleaved notation containing the extra measurement tensors.

pytket.extensions.cutensornet.general_state.get_operator_expectation_value(state_circuit, operator, post_selection=None)[source]

Calculates expectation value of an operator using cuTensorNet contraction.

Has an option to do post selection on an ancilla register.

Parameters:

  • state_circuit (Circuit) – Circuit representing state.

  • operator (QubitPauliOperator) – Operator which expectation value is to be calculated.

  • post_selection (Optional[dict[Qubit, int]]) – Dictionary of qubits to post select where the key is qubit and the value is bit outcome.

Return type:

float

Returns:

Expectation value.

pytket.extensions.cutensornet.general_state.get_circuit_overlap(circuit_ket, circuit_bra=None)[source]

Calculates an overlap of two states represented by two circuits.

Parameters:

  • circuit_bra (Optional[Circuit]) – Circuit representing the bra state.

  • circuit_ket (Circuit) – Circuit representing the ket state.

Return type:

float

Returns:

Overlap value.

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 SamplerAttribute enum (see NVIDIA’s CuTensorNet API) can be provided as arguments to this method. For instance: process_circuits(..., CONFIG_NUM_HYPER_SAMPLES=100).

Parameters:

  • circuits (Sequence[Circuit]) – List of circuits to be submitted.

  • n_shots (Union[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.

  • scratch_fraction – Optional. Fraction of free memory on GPU to allocate as scratch space. Defaults to 0.75.

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 StateAttribute enum (see NVIDIA’s CuTensorNet API) can be provided as arguments to this method. For instance: process_circuits(..., CONFIG_NUM_HYPER_SAMPLES=100).

Parameters:

  • circuits (Sequence[Circuit]) – List of circuits to be submitted.

  • n_shots (Union[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.

  • scratch_fraction – Optional. Fraction of free memory on GPU to allocate as scratch space. Defaults to 0.75.

Return type:

List[ResultHandle]

Returns:

Results handle objects.

property backend_info: BackendInfo | None

Returns information on the backend.