General state (exact) simulation

General state (exact) simulation#

Module for simulating circuits with no predetermined tensor network structure.

class pytket.extensions.cutensornet.general_state.GeneralState#

Wrapper of cuTensorNet object for exact simulations via path optimisation.

__init__(circuit: Circuit, libhandle: CuTensorNetHandle, loglevel: int = 20) → None#

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 – A pytket circuit to be converted to a tensor network.

  • libhandle – An instance of a CuTensorNetHandle.

  • loglevel – Internal logger output level.

get_statevector(attributes: dict | None = None, scratch_fraction: float = 0.5, on_host: bool = True) → cp.ndarray | np.ndarray#

Contracts the circuit and returns the final statevector.

Parameters:

  • attributes – Optional. A dict of cuTensorNet StateAttribute keys and their values.

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

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

Raises:

MemoryError – If there is insufficient workspace on GPU.

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: QubitPauliOperator, attributes: dict | None = None, scratch_fraction: float = 0.5) → complex#

Calculates the expectation value of the given operator.

Parameters:

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

  • attributes – Optional. A dict of cuTensorNet ExpectationAttribute keys and their values.

  • scratch_fraction – 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.

Returns:

The expectation value.

sample(n_shots: int, attributes: dict | None = None, scratch_fraction: float = 0.5) → BackendResult#

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

Parameters:

  • n_shots – The number of samples to obtain.

  • attributes – Optional. A dict of cuTensorNet SamplerAttribute keys and their values.

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

Raises:

MemoryError – If there is insufficient workspace on GPU.

Returns:

A pytket BackendResult with the data from the shots.

destroy() → None#

Destroy the tensor network and free up GPU memory.

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: Circuit, adj: bool = False, loglevel: int = 20)#

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

class pytket.extensions.cutensornet.general_state.PauliOperatorTensorNetwork(paulis: QubitPauliString, bra: TensorNetwork, ket: TensorNetwork, loglevel: int = 20)#

Handles a tensor network representing a Pauli operator string.

class pytket.extensions.cutensornet.general_state.ExpectationValueTensorNetwork(bra: TensorNetwork, paulis: QubitPauliString, ket: TensorNetwork, loglevel: int = 20)#

Handles a tensor network representing an expectation value.

pytket.extensions.cutensornet.general_state.tk_to_tensor_network(tkc: Circuit) → List[ndarray[Any, dtype[_ScalarType_co]] | List]#

Converts pytket circuit into a tensor network.

Parameters:

tkc – Circuit.

Returns:

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

pytket.extensions.cutensornet.general_state.measure_qubits_state(ket: TensorNetwork, measurement_dict: dict[pytket.unit_id.Qubit, int], loglevel: int = 20) → TensorNetwork#

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 – a TensorNetwork object representing a quantum state.

  • measurement_dict – a dictionary of qubit ids and their corresponding bit values to be assigned to the measured qubits.

  • loglevel – logging level.

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: Circuit, operator: QubitPauliOperator, post_selection: dict[pytket.unit_id.Qubit, int] | None = None) → float#

Calculates expectation value of an operator using cuTensorNet contraction.

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

Parameters:

  • state_circuit – Circuit representing state.

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

  • post_selection – Dictionary of qubits to post select where the key is qubit and the value is bit outcome.

Returns:

Expectation value.

pytket.extensions.cutensornet.general_state.get_circuit_overlap(circuit_ket: Circuit, circuit_bra: Circuit | None = None) → float#

Calculates an overlap of two states represented by two circuits.

Parameters:

  • circuit_bra – Circuit representing the bra state.

  • circuit_ket – Circuit representing the ket state.

Returns:

Overlap value.

Pytket backend#

Module for conversion from tket primitives to cuQuantum primitives.

class pytket.extensions.cutensornet.CuTensorNetShotsBackend#

A pytket Backend using GeneralState to obtain shots.

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

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.

Parameters:

  • circuits – List of circuits to be submitted.

  • n_shots – 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 – Whether to check for circuit correctness.

Returns:

Results handle objects.

property backend_info: BackendInfo | None#

Returns information on the backend.

class pytket.extensions.cutensornet.CuTensorNetStateBackend#

A pytket Backend using GeneralState to obtain state vectors.

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

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.

Parameters:

  • circuits – List of circuits to be submitted.

  • n_shots – Number of shots in case of shot-based calculation. This should be None, since this backend does not support shots.

  • valid_check – Whether to check for circuit correctness.

Returns:

Results handle objects.

property backend_info: BackendInfo | None#

Returns information on the backend.

Contents