NetworkState#

class cuquantum.tensornet.experimental.NetworkState(
state_mode_extents,
*,
dtype='complex128',
pure_state=True,
config=None,
state_labels=None,
options=None,
)[source]#

Create an empty tensor network state.

Parameters:

  • state_mode_extents – A sequence of integers specifying the extents for all state modes.

  • dtype –

    A string specifying the datatype for the network state, currently supports the following data types:

    • 'float32'

    • 'float64'

    • 'complex64'

    • 'complex128' (default)

  • pure_state – Whether the state is pure. True (default) selects pure-state simulation; False selects mixed-state (density matrix) simulation.

  • config –

    The simulation configuration for the state. It can be:

    • A TNConfig object for contraction based tensor network simulation (default).

    • A MPSConfig object for MPS based tensor network simulation.

    • A dict containing the parameters for the TNConfig or MPSConfig constructor.

  • state_labels – Optional, a sequence of different labels corresponding to each state dimension. If provided, users have the option to provide a sequence of these labels as the input arguments for the following APIs including apply_tensor_operator(), apply_mpo(), compute_batched_amplitudes(), compute_reduced_density_matrix() and compute_sampling(). See the docstring for each of these APIs for more details.

  • options – Specify options for the state computation as a cuquantum.tensornet.NetworkOptions object. Alternatively, a dict containing the parameters for the NetworkOptions constructor can also be provided. If not specified, the value will be set to the default-constructed NetworkOptions object.

Notes

  • Currently NetworkState only supports pure state representation.

  • The state is placed on CUDA device 0 by default. To use a different device, specify it explicitly via NetworkOptions.device_id, and ensure that all input operands reside on that same device.

  • For MPS simulation, currently only open boundary condition is supported.

Examples

In this example, we aim to directly perform simulation on a quantum circuit instance using tensor network contraction method.

>>> from cuquantum.tensornet.experimental import NetworkState, TNConfig
>>> import cirq

Define a random cirq.Circuit, note that qiskit.QuantumCircuit is supported as well using the same API call

>>> n_qubits = 4
>>> n_moments = 4
>>> op_density = 0.9
>>> circuit = cirq.testing.random_circuit(n_qubits, n_moments, op_density, random_state=2024)

Use tensor network contraction as the simulation method

>>> config = TNConfig(num_hyper_samples=4)

Create the network state object via from_circuit() method:

>>> state = NetworkState.from_circuit(circuit, dtype='complex128', backend='cupy', config=config)

Compute the amplitude for bitstring 0000

>>> amplitude = state.compute_amplitude('0000')

Compute the expectation for a series of Pauli strings with coefficients

>>> pauli_strings = {'IXIX': 0.4, 'IZIZ': 0.1}
>>> expec = state.compute_expectation(pauli_strings)

Compute the reduced density matrix for the first two qubits. Since the backend is specified to cupy, the returned rdm operand will be cupy.ndarray.

>>> where = (0, 1)
>>> rdm = state.compute_reduced_density_matrix(where)
>>> print(f"RDM shape for {where}: {rdm.shape}")
RDM shape for (0, 1): (2, 2, 2, 2)

Draw 1000 samples from the state

>>> shots = 1000
>>> samples = state.compute_sampling(shots)

Finally, free network state resources. If this call isn’t made, it may hinder further operations (especially if the network state is large) since the memory will be released only when the object goes out of scope. (To avoid having to explicitly make this call, it is recommended to use the NetworkState object as a context manager.)

>>> state.free()

In addition to initializing the state from a circuit instance, users can construct the state by sequentially applying tensor operators with apply_tensor_operator() and matrix product operators (MPOs) with apply_mpo() or apply_network_operator(). Alternatively, simulations can leverage exact or approximate matrix product state (MPS) method by specifing options as an MPSConfig instance. More detailed examples can be found in our NetworkState examples directory.

Methods

__init__(
state_mode_extents,
*,
dtype='complex128',
pure_state=True,
config=None,
state_labels=None,
options=None,
)[source]#
apply_general_tensor_channel(
modes,
operands,
*,
stream=None,
)[source]#

Apply a noise channel to the network state. The noise operators may be non-unitary. For a more efficient unitary tensor channel application, see NetworkState.apply_unitary_tensor_channel().

Parameters:

  • modes – A sequence of integers denoting the modes where the tensor operator acts on. If state_labels has been provided during initialization, modes can also be provided as a sequence of labels.

  • operands – A sequence of ndarray-like objects for the tensor operators defining the channel. The modes of the operand is expected to be ordered as ABC...abc..., where ABC... denotes output bra modes and abc... denotes input ket modes corresponding to modes

  • stream – Provide the CUDA stream to use for applying the tensor operator (this is used to copy the operands to the GPU if they are provided on the CPU). Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

Returns:

An integer channel_id specifying the location of the general channel.

Notes

  • This method requires the input channel to be trace-preserving. Supplying a non-trace-preserving channel may lead to unexpected results.

  • For pure states with TNConfig, general channels are not supported. Use MPSConfig or switch to mixed state simulation (pure_state=False).

  • For MPS simulation, the size of modes shall be restricted to no larger than 2 (two-body operator).

  • The channel_id cannot be used to update the channel using NetworkState.update_tensor_operator().

apply_mpo(
modes,
mpo_tensors,
*,
immutable=False,
adjoint=False,
unitary=False,
stream=None,
)[source]#

Apply an MPO operator specified by mpo_tensors and modes to the network state.

Parameters:

  • modes – A sequence of integers specifying each mode where the MPO acts on. If state_labels has been provided during initialization, modes can also be provided as a sequence of labels.

  • mpo_tensors – A sequence of tensors (ndarray-like objects) for each MPO operand. The currently supported types are numpy.ndarray, cupy.ndarray, and torch.Tensor. The mode of each operand is expected to follow the order of pknb where p denotes the mode connecting to the previous MPO tensor, n denotes the mode connecting to the next MPO tensor, k denotes the ket mode and b denotes the bra mode. Note that currently only MPO with open boundary condition is supported, therefore p and n mode should not be present in the first and last MPO tensor respectively. Note that the relative order of bra and ket modes here differs from that of operand in apply_tensor_operator().

  • immutable – Whether the full MPO is immutable (default False).

  • adjoint – Whether the full MPO should be applied in its adjoint form (default False).

  • unitary – Whether the full MPO is unitary (default False).

  • stream – Provide the CUDA stream to use for appending MPO (this is used to copy the operands to the GPU if they are provided on the CPU). Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

Returns:

An integer network_id specifying the location of the MPO.

apply_network_operator(
network_operator,
*,
immutable=False,
adjoint=False,
unitary=False,
)[source]#

Apply a network operator to the network state.

Parameters:

  • network_operator – A NetworkOperator object for the input network operator. Must contain only one MPO term or one tensor product term.

  • immutable – Whether the network operator is immutable (default False).

  • adjoint – Whether the network operator should be applied in its adjoint form (default False).

  • unitary – Whether the network operator is unitary (default False).

Returns:

An integer network_id specifying the location of the network operator.

apply_tensor_operator(
modes,
operand,
*,
control_modes=None,
control_values=None,
immutable=False,
adjoint=False,
unitary=False,
diagonal=False,
gradient=None,
stream=None,
)[source]#

Apply a tensor operator to the network state.

Parameters:

  • modes – A sequence of integers denoting the modes where the tensor operator acts on. If state_labels has been provided during initialization, modes can also be provided as a sequence of labels.

  • operand – A ndarray-like object for the tensor operator. The modes of the operand is expected to be ordered as ABC...abc..., where ABC... denotes output bra modes and abc... denotes input ket modes corresponding to modes

  • control_modes – A sequence of integers denotes the modes where control operation is acted on (default no control modes). If state_labels has been provided during initialization, control_modes can also be provided as a sequence of labels.

  • control_values – A sequence of integers specifying the control values corresponding to control_modes. If control_modes are specified and control_values are not provided, control values for all control modes will be set as 1.

  • immutable – Whether the operator is immutable (default False).

  • adjoint – Whether the operator should be applied in its adjoint form (default False).

  • unitary – Whether the operator is unitary (default False).

  • diagonal – Whether the operator is diagonal (default False).

  • gradient – Whether to register this operator for expectation gradients. If None (default), for PyTorch operands the choice follows operand.tensor.requires_grad; for other backends, gradient registration is disabled unless gradient is explicitly True. Use True / False to force registration on or off regardless of requires_grad.

  • stream – Provide the CUDA stream to use for applying the tensor operator (this is used to copy the operands to the GPU if they are provided on the CPU). Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

Returns:

An integer tensor_id specifying the location of the input operator.

Notes

  • For MPS simulation, the size of modes shall be restricted to no larger than 2 (two-body operator).

apply_unitary_tensor_channel(
modes,
operands,
probabilities,
*,
stream=None,
)[source]#

Apply a unitary tensor channel to the network state. For an error channel with non-unitary operators, see NetworkState.apply_general_tensor_channel().

Parameters:

  • modes – A sequence of integers denoting the modes where the tensor operator acts on. If state_labels has been provided during initialization, modes can also be provided as a sequence of labels.

  • operands – A sequence of ndarray-like objects for the unitary tensor operators defining the unitary channel. The modes of the operand is expected to be ordered as ABC...abc..., where ABC... denotes output bra modes and abc... denotes input ket modes corresponding to modes

  • probabilities – A sequence of positive floats representing the probabilities of each operand.

  • stream – Provide the CUDA stream to use for applying the tensor operator (this is used to copy the operands to the GPU if they are provided on the CPU). Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

Returns:

An integer channel_id specifying the location of the unitary channel.

Notes

  • For MPS simulation, the size of modes shall be restricted to no larger than 2 (two-body operator).

compute_amplitude(
bitstring,
*,
return_norm=False,
stream=None,
release_workspace=False,
)[source]#

Compute a single element of the underlying state tensor.

For pure states, returns the complex amplitude \(\langle \text{bitstring} | \psi \rangle\). For mixed states, returns the density-matrix element \(\langle \text{ket\_bitstring} | \rho | \text{bra\_bitstring} \rangle\).

Parameters:

  • bitstring –

    • For pure states, a length-N sequence of integers specifying the desired basis state.

    • For mixed states, either a single length-N sequence – interpreted symmetrically as ket == bra to extract a diagonal element (probability) – or a 2-tuple (ket_bitstring, bra_bitstring) of length-N sequences specifying the row (ket) and column (bra) indices of the density matrix element to compute.

  • return_norm – If true, the squared norm of the state will also be returned.

  • stream – Provide the CUDA stream to use for the computation. Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

  • release_workspace – A value of True specifies that the state object should release workspace memory back to the package memory pool on function return, while a value of False specifies that the state object should retain the memory. This option may be set to True if the application performs other operations that consume a lot of memory between successive calls to the (same or different) execution API such as compute_sampling(), compute_reduced_density_matrix(), compute_amplitude(), compute_batched_amplitudes(), or compute_expectation(), but incurs a small overhead due to obtaining and releasing workspace memory from and to the package memory pool on every call. The default is False.

Returns:

If return_norm is False, a 0-D tensor for the bitstring amplitude on the state’s backend (the density-matrix element \(\langle \text{ket} | \rho | \text{bra} \rangle\) for mixed states). If return_norm is True, a 2-tuple (amplitude, norm) where norm is a 0-D tensor for the squared state norm \(\mathrm{Tr}(\rho)\) (equal to \(\langle \psi | \psi \rangle\) for pure states).

compute_batched_amplitudes(
fixed,
*,
return_norm=False,
stream=None,
release_workspace=False,
)[source]#

Compute a slice of the underlying state tensor.

For pure states, returns a slice of the state vector: \(\langle \text{bs} | \psi \rangle\) over open ket modes.

For mixed states, returns a slice of the density matrix with the requested ket and bra modes projected independently. Output modes are ordered as (open_ket_modes_asc, open_bra_modes_asc) to match the underlying mixed-state Accessor.

Parameters:

  • fixed –

    A dictionary mapping a subset of mode indices [0, N) to fixed values; modes absent from the dictionary are left open. If state_labels has been provided during initialization, keys may also be provided as labels.

    • For pure states, each value is a single fixed index.

    • For mixed states, each value selects the ket and bra index for that mode and may be either

      • a single index – shorthand for fixing the ket and bra to the same value (a diagonal/symmetric projection), or

      • a 2-tuple (ket, bra) where each entry is an index or None; None leaves that side open, enabling independent ket/bra projection (e.g. (0, None) fixes only the ket).

  • return_norm – If true, the squared norm of the state will also be returned.

  • stream – Provide the CUDA stream to use for the computation. Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

  • release_workspace – A value of True specifies that the state object should release workspace memory back to the package memory pool on function return, while a value of False specifies that the state object should retain the memory. This option may be set to True if the application performs other operations that consume a lot of memory between successive calls to the (same or different) execution API such as compute_sampling(), compute_reduced_density_matrix(), compute_amplitude(), compute_batched_amplitudes(), or compute_expectation(), but incurs a small overhead due to obtaining and releasing workspace memory from and to the package memory pool on every call. The default is False.

Returns:

If return_norm is False, an ndarray-like slice of the state tensor. The package and storage location of the ndarray will be the same as the operands provided in apply_tensor_operator(), apply_mpo() and set_initial_mps(). Otherwise, a 2-tuple consisting of the slice and a scalar for the squared norm of the state \(\mathrm{Tr}(\rho)\) (equal to \(\langle \psi | \psi \rangle\) for pure states).

compute_density_matrix(
*,
stream=None,
release_workspace=False,
)[source]#

Compute the full density matrix.

This is supported for both pure and mixed states. For a pure state this returns :math:\rho = |\psi\rangle\langle\psi|; compute_state_vector() is the cheaper rank-N alternative in that case.

Parameters:

  • stream – Provide the CUDA stream to use for the computation. Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

  • release_workspace – A value of True specifies that the state object should release workspace memory back to the package memory pool on function return, while a value of False specifies that the state object should retain the memory. This option may be set to True if the application performs other operations that consume a lot of memory between successive calls to the (same or different) execution API such as compute_sampling(), compute_reduced_density_matrix(), compute_amplitude(), compute_batched_amplitudes(), or compute_expectation(), but incurs a small overhead due to obtaining and releasing workspace memory from and to the package memory pool on every call. The default is False.

Returns:

An ndarray-like density matrix of shape (d_0, ..., d_{N-1}, d_0, ..., d_{N-1}) where the first N modes are ket (row) indices and the last N modes are bra (column) indices.

compute_expectation(
operators,
*,
return_norm=False,
stream=None,
release_workspace=False,
)[source]#

Compute the expectation value (not normalized) for the given tensor network operator.

Parameters:

  • operators –

    The NetworkOperator operator object to compute expectation value on. If the underlying state dimensions are all 2 (qubits), it can also be:

    • A single pauli string specifying the pauli operator for each qubit.

    • A dictionary mapping each single pauli string to corresponding coefficient.

  • return_norm – If true, the squared norm of the state will also be returned.

  • stream – Provide the CUDA stream to use for the computation. Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

  • release_workspace – A value of True specifies that the state object should release workspace memory back to the package memory pool on function return, while a value of False specifies that the state object should retain the memory. This option may be set to True if the application performs other operations that consume a lot of memory between successive calls to the (same or different) execution API such as compute_sampling(), compute_reduced_density_matrix(), compute_amplitude(), compute_batched_amplitudes(), or compute_expectation(), but incurs a small overhead due to obtaining and releasing workspace memory from and to the package memory pool on every call. The default is False.

Returns:

If return_norm is False, a 0-D tensor for the expectation value on the state’s backend. If return_norm is True, a 2-tuple (expectation, norm) of 0-D tensors, where norm is the squared state norm \(\mathrm{Tr}(\rho)\) (equal to \(\langle \psi | \psi \rangle\) for pure states). On the PyTorch backend, outputs participate in the autograd graph when gradient-registered gate tensors have requires_grad=True; otherwise forward-only 0-D tensors are returned.

Note

  • Repeated calls with the same Pauli convenience input (same string keys and coefficients given the state’s dtype) reuse a memoized NetworkOperator so CUTN expectation prepare can be amortized similarly to explicitly reusing one operator instance. The memo is invalidated when the state’s cached property objects are invalidated (see _mark_updated()) and when free() runs.

  • For workloads that assemble NetworkOperator outside the convenience path, see the variational expectation example.

  • For Pauli workloads that mutate coefficients every call, constructing a fresh NetworkOperator may remain appropriate.

  • For pauli operator expectation value computations, this method does not take advantage of lightcone simplification optimization. If user wishes to compute the expectation value on a pauli string operator with many identities in it, consider either using the compute_reduced_density_matrix() method or explicitly construct the NetworkOperator object with NetworkOperator.append_product() for optimal performance.

compute_expectation_with_gradients(
operators,
expectation_value_adjoint,
*,
return_norm=False,
state_norm_adjoint=None,
stream=None,
release_workspace=False,
)[source]#

Compute the expectation value of the given operator(s) and gradients with respect to tensor operators that were registered for gradients in apply_tensor_operator() (PyTorch: typically when the operand had requires_grad=True, or when gradient=True was passed explicitly).

Parameters:

  • operators – Pauli string, dict of pauli strings, or NetworkOperator.

  • return_norm – If True, the squared norm of the state is also computed and returned (see compute_expectation()). Must be True together with a non-None state_norm_adjoint, or False together with state_norm_adjoint=None.

  • expectation_value_adjoint – Scalar adjoint for the expectation value (e.g. 1.0 for d/d(expectation)).

  • state_norm_adjoint – Upstream gradient for the squared state 2-norm (scalar in self.dtype). Must be non-None exactly when return_norm is True, and None when return_norm is False.

  • stream – Execution stream (see compute_expectation()).

  • release_workspace – Whether to release workspace memory on return (see compute_expectation()).

Returns:

If return_norm is False, (expectation_value, gradients) where expectation_value is a 0-D tensor on the state’s backend. If return_norm is True, (expectation_value, norm, gradients) where norm is a 0-D tensor for the squared state 2-norm in the same form. gradients maps each tensor_id from gradient_tensor_ids() to a tensor with the same shape, dtype as the corresponding registered operand. If no operators were registered for gradients, gradients is empty.

compute_output_state(
*,
stream=None,
release_workspace=False,
release_operators=False,
)[source]#

Compute the final output state for the underlying network state object. This method currently is only valid for MPS based simulation.

Parameters:

  • stream – Provide the CUDA stream to use for the computation. Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

  • release_workspace – A value of True specifies that the state object should release workspace memory back to the package memory pool on function return, while a value of False specifies that the state object should retain the memory. This option may be set to True if the application performs other operations that consume a lot of memory between successive calls to the (same or different) execution API such as compute_sampling(), compute_reduced_density_matrix(), compute_amplitude(), compute_batched_amplitudes(), or compute_expectation(), but incurs a small overhead due to obtaining and releasing workspace memory from and to the package memory pool on every call. The default is False.

  • release_operators – A value of True will release the reference of all underlying tensor operators and NetworkOperator objects. The previous tensor_id returned by apply_tensor_operator(), apply_network_operator() and apply_mpo() will be invalid. If the output state has already been computed, which is an intermediate step in other compute_xxx methods, the output state will be cached and returned directly. Thus passing release_operators=True can be used to reset the underlying NetworkState object.

Returns:

For MPS simulation (MPSConfig in options), a sequence of ndarray-like MPS tensors on the state’s backend (respecting output_location). Each tensor uses mode order pkn: p (left bond), k (ket), n (right bond); the first and last tensors omit p and n respectively.

compute_reduced_density_matrix(
where,
*,
fixed=mappingproxy({}),
diagonal=False,
stream=None,
release_workspace=False,
)[source]#

Compute the reduced density matrix (or, optionally, only its diagonal) for the given marginal and fixed modes.

Parameters:

  • where – A sequence of integers for the target modes. If state_labels has been provided during initialization, where can also be provided as a sequence of labels.

  • fixed – A dictionary mapping a subset of fixed modes to the fixed value. If state_labels has been provided during initialization, fixed can also be provided as a dictionary mapping labels to the corresponding fixed values.

  • diagonal – If False (default), the full reduced density matrix is returned as a rank-2 * len(where) tensor. If True, only its diagonal is returned as a rank-len(where) tensor, which avoids materializing the full reduced density matrix (backed by cutensornetCreateMarginalDiagonal). These are the bare diagonal entries \(\rho_{\text{where}}[\text{bs}, \text{bs}]\) of the (projected) reduced density matrix; like the full reduced density matrix, they are not renormalized.

  • stream – Provide the CUDA stream to use for the computation. Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

  • release_workspace – A value of True specifies that the state object should release workspace memory back to the package memory pool on function return, while a value of False specifies that the state object should retain the memory. This option may be set to True if the application performs other operations that consume a lot of memory between successive calls to the (same or different) execution API such as compute_sampling(), compute_reduced_density_matrix(), compute_amplitude(), compute_batched_amplitudes(), or compute_expectation(), but incurs a small overhead due to obtaining and releasing workspace memory from and to the package memory pool on every call. The default is False.

Returns:

An ndarray-like object. By default, the reduced density matrix following the modes AB...ab... where AB... and ab... represent the corresponding output and input marginal modes. If diagonal=True, the rank-len(where) diagonal of the reduced density matrix following the modes AB....

compute_sampling(
nshots,
*,
modes=None,
seed=None,
stream=None,
release_workspace=False,
)[source]#

Perform sampling on the given modes.

Parameters:

  • nshots – The number of samples to collect.

  • modes – The target modes to sample on. If not provided, will sample all modes. If state_labels has been provided during initialization, modes can also be provided as a sequence of labels.

  • seed – A positive integer denoting the random seed to use for generating the samples. If not provided, the generator will continue from the previous seed state or from an unseeded state if no seed was previously set.

  • stream – Provide the CUDA stream to use for the computation. Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

  • release_workspace – A value of True specifies that the state object should release workspace memory back to the package memory pool on function return, while a value of False specifies that the state object should retain the memory. This option may be set to True if the application performs other operations that consume a lot of memory between successive calls to the (same or different) execution API such as compute_sampling(), compute_reduced_density_matrix(), compute_amplitude(), compute_batched_amplitudes(), or compute_expectation(), but incurs a small overhead due to obtaining and releasing workspace memory from and to the package memory pool on every call. The default is False.

Returns:

A dictionary mapping the bitstring to the corresponding count.

compute_state_vector(
*,
return_norm=False,
stream=None,
release_workspace=False,
)[source]#

Compute the state vector.

This method is only valid for pure states. For mixed states, use compute_density_matrix() to obtain the full density matrix.

Parameters:

  • return_norm – If true, the squared norm of the state will also be returned.

  • stream – Provide the CUDA stream to use for the computation. Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

  • release_workspace – A value of True specifies that the state object should release workspace memory back to the package memory pool on function return, while a value of False specifies that the state object should retain the memory. This option may be set to True if the application performs other operations that consume a lot of memory between successive calls to the (same or different) execution API such as compute_sampling(), compute_reduced_density_matrix(), compute_amplitude(), compute_batched_amplitudes(), or compute_expectation(), but incurs a small overhead due to obtaining and releasing workspace memory from and to the package memory pool on every call. The default is False.

Returns:

If return_norm is False, an ndarray-like state vector on the state’s backend. The package and storage location of the ndarray will be the same as the operands provided in apply_tensor_operator(), apply_mpo() and set_initial_mps(). If return_norm is True, a 2-tuple (state_vector, norm) where norm is a 0-D tensor for the squared state 2-norm.

free()[source]#

Free state resources.

It is recommended that the NetworkState object can be used within a context, but if it is not possible then this method must be called explicitly to ensure that the state resources are properly cleaned up.

classmethod from_circuit(
circuit,
*,
dtype='complex128',
backend='auto',
pure_state=True,
config=None,
options=None,
stream=None,
)[source]#

Create a state object from the given circuit.

Parameters:

  • circuit – A fully parameterized cirq.Circuit or qiskit.QuantumCircuit object.

  • dtype –

    A string specifying the datatype for the tensor network, currently supports the following data types:

    • 'complex64'

    • 'complex128' (default)

  • backend – The backend for all output tensor operands. If not specified, cupy is used when it is available, otherwise numpy is used.

  • pure_state – Whether the state is pure. True (default) for pure-state simulation; False for mixed-state (density matrix) simulation.

  • config –

    The simulation configuration for the state. It can be:

    • A TNConfig object for contraction based tensor network simulation (default).

    • A MPSConfig object for MPS based tensor network simulation.

    • A dict containing the parameters for the TNConfig or MPSConfig constructor.

  • options – Specify options for the computation as a NetworkOptions object. Alternatively, a dict containing the parameters for the NetworkOptions constructor can also be provided. If not specified, the value will be set to the default-constructed NetworkOptions object.

  • stream – Provide the CUDA stream to use for state initialization, which is needed for stream-ordered operations such as allocating memory. Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

Note

  • When parsing gates from the circuit object, all gate operands are assumed to be unitary. In the rare case where the target circuit object contains customized non-unitary gates, users are encouraged to use apply_tensor_operator() to construct the NetworkState object.

classmethod from_converter(
converter,
*,
pure_state=True,
config=None,
options=None,
stream=None,
)[source]#

Create a NetworkState object from the given cuquantum.tensornet.CircuitToEinsum converter.

Parameters:

  • converter – A cuquantum.tensornet.CircuitToEinsum object.

  • pure_state – Whether the state is pure. True (default) for pure-state simulation; False for mixed-state (density matrix) simulation.

  • config –

    The simulation configuration for the state simulator. It can be:

    • A TNConfig object for contraction based tensor network simulation (default).

    • A MPSConfig object for MPS based tensor network simulation.

    • A dict containing the parameters for the TNConfig or MPSConfig constructor.

  • options – Specify options for the state computation as a cuquantum.tensornet.NetworkOptions object. Alternatively, a dict containing the parameters for the NetworkOptions constructor can also be provided. If not specified, the value will be set to the default-constructed NetworkOptions object.

  • stream – Provide the CUDA stream to use for state initialization, which is needed for stream-ordered operations such as allocating memory. Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

gradient_tensor_ids()[source]#

Tensor operator IDs registered for gradient computation via apply_tensor_operator().

Returns:

A tuple of integers in ascending tensor_id order. When the library assigns monotonically increasing IDs (the usual case), this matches the order of apply_tensor_operator() calls that registered gradients.

set_initial_mps(mps_tensors, *, stream=None)[source]#

Set the initial state to a non-vacuum state in the MPS form.

Parameters:

  • mps_tensors – A sequence of tensors (ndarray-like objects) for each MPS operand. The currently supported types are numpy.ndarray, cupy.ndarray, and torch.Tensor. The modes of each operand are expected to follow the order of pkn where p denotes the mode connecting to the previous MPS tensor, k denotes the ket mode and n denotes the mode connecting to the next MPS tensor. Note that this method currently only support open boundary condition, and p and n mode should thus be dropped in the first and last MPS tensor respectively.

  • stream – Provide the CUDA stream to use for setting the initial state to the specified MPS (this is used to copy the operands to the GPU if they are provided on the CPU). Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.

Note

  • This API simply sets the initial state to the provided MPS and does not alter the nature of the simulation method, which is provided via the options parameter during initialization.

update_tensor_operator(
tensor_id,
operand,
*,
unitary=False,
stream=None,
)[source]#

Update a tensor operator in the state.

Parameters:

  • tensor_id – An integer specifing the tensor id assigned in NetworkState.apply_tensor_operator().

  • operand – A ndarray-like object for the tensor operator. The operand is expected to follow the same mode ordering, data type and strides as the original operand.

  • unitary – Whether the operator is unitary (default False).

  • stream – Provide the CUDA stream to use for updating tensor operand (this is used to copy the operands to the GPU if they are provided on the CPU). Acceptable inputs include cudaStream_t (as Python int), cuda.core.Stream for NumPy operands, cupy.cuda.Stream for CuPy operands, and torch.cuda.Stream for PyTorch operands. If a stream is not provided, the current stream will be used.