qrunch.quantum.estimators.third_party_estimators.cuquantum_state_vector_estimator.utils

Utility functions for cuQuantum state vector estimator.

Functions

cleanup_gpu_resources([cutn_handle, cusv_handle])	Comprehensive GPU resource cleanup for cuQuantum SDK.
cupy_batched_diagonal_pauli_exponential_matrices(...)	Build one \(e^{-i\theta P}\) matrix per angle for a diagonal Pauli string, in a single kernel.
cupy_batched_double_excitation_unitary_matrices(thetas)	Build one double excitation matrix per angle, in a single kernel.
cupy_batched_phase_unitary_matrices(phis)	Build one phase gate matrix per angle, in a single kernel.
cupy_batched_rx_unitary_matrices(thetas)	Build one X-rotation matrix per angle, in a single kernel.
cupy_batched_ry_unitary_matrices(thetas)	Build one Y-rotation matrix per angle, in a single kernel.
cupy_batched_rz_unitary_matrices(thetas)	Build one Z-rotation matrix per angle, in a single kernel.
cupy_batched_single_excitation_unitary_matrices(thetas)	Build one single excitation matrix per angle, in a single kernel.
cupy_batched_xxplusyy_unitary_matrices(thetas)	Build one (XX+YY) matrix per angle, in a single kernel.
cupy_cx_unitary_matrix()	Construct a controlled-X (CNOT) unitary matrix for two qubits.
cupy_diagonal_pauli_exponential_matrix(...)	Construct the unitary \(e^{-i\theta P}\) for a diagonal Pauli string P.
cupy_double_excitation_unitary_matrix(theta)	Construct a double excitation unitary matrix for four qubits.
cupy_hadamard_unitary_matrix()	Construct a Hadamard unitary matrix.
cupy_pauli_x_unitary_matrix()	Construct a Pauli-X unitary matrix.
cupy_phase_unitary_matrix(phi)	Construct a phase gate unitary matrix.
cupy_rx_unitary_matrix(theta)	Construct an X-rotation unitary matrix.
cupy_ry_unitary_matrix(theta)	Construct a Y-rotation unitary matrix.
cupy_rz_unitary_matrix(theta)	Construct a Z-rotation unitary matrix.
cupy_single_excitation_unitary_matrix(theta)	Construct a single excitation unitary matrix for two qubits.
cupy_xxplusyy_unitary_matrix(theta)	Construct an (XX+YY) unitary matrix for two qubits.
get_pauli_string_as_str(pauli_string, num_qubits)	Convert a library PauliString to its dense literal form.

cleanup_gpu_resources(cutn_handle: int | None = None, cusv_handle: int | None = None) → None

Comprehensive GPU resource cleanup for cuQuantum SDK.

Parameters:

• cutn_handle (int | None) – cuTensorNet handle (int) if using low-level API

• cusv_handle (int | None) – cuStateVector handle (int) if using low-level API

Return type:

None

Note

This function is safe to call multiple times or with invalid handles. It will log warnings but not raise exceptions.

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_batched_diagonal_pauli_exponential_matrices(thetas: NDArray[float64], number_of_z_qubits: int) → NDArray[complex128]

Build one \(e^{-i\theta P}\) matrix per angle for a diagonal Pauli string, in a single kernel.

Mirrors cupy_diagonal_pauli_exponential_matrix() exactly, stacked along a leading batch axis. This is the dominant gate kind in a Trotterized time evolution, so batching it removes most of the per-gate host work.

Parameters:

• thetas (NDArray[float64]) – Device array of rotation angles.

• number_of_z_qubits (int) – Number of qubits carrying a Z factor.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_batched_double_excitation_unitary_matrices(thetas: NDArray[float64]) → NDArray[complex128]

Build one double excitation matrix per angle, in a single kernel.

Mirrors cupy_double_excitation_unitary_matrix() exactly, including the transposition required by cuStateVec’s reversed target order, stacked along a leading batch axis.

Parameters:

thetas (NDArray[float64]) – Device array of rotation angles.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_batched_phase_unitary_matrices(phis: NDArray[float64]) → NDArray[complex128]

Build one phase gate matrix per angle, in a single kernel.

Mirrors cupy_phase_unitary_matrix() exactly, stacked along a leading batch axis.

Parameters:

phis (NDArray[float64]) – Device array of phase angles.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_batched_rx_unitary_matrices(thetas: NDArray[float64]) → NDArray[complex128]

Build one X-rotation matrix per angle, in a single kernel.

Mirrors cupy_rx_unitary_matrix() exactly, stacked along a leading batch axis.

Parameters:

thetas (NDArray[float64]) – Device array of rotation angles.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_batched_ry_unitary_matrices(thetas: NDArray[float64]) → NDArray[complex128]

Build one Y-rotation matrix per angle, in a single kernel.

Mirrors cupy_ry_unitary_matrix() exactly, stacked along a leading batch axis.

Parameters:

thetas (NDArray[float64]) – Device array of rotation angles.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_batched_rz_unitary_matrices(thetas: NDArray[float64]) → NDArray[complex128]

Build one Z-rotation matrix per angle, in a single kernel.

Mirrors cupy_rz_unitary_matrix() exactly, stacked along a leading batch axis.

Parameters:

thetas (NDArray[float64]) – Device array of rotation angles.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_batched_single_excitation_unitary_matrices(thetas: NDArray[float64]) → NDArray[complex128]

Build one single excitation matrix per angle, in a single kernel.

Mirrors cupy_single_excitation_unitary_matrix() exactly, including the transposition required by cuStateVec’s reversed target order, stacked along a leading batch axis.

Parameters:

thetas (NDArray[float64]) – Device array of rotation angles.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_batched_xxplusyy_unitary_matrices(thetas: NDArray[float64]) → NDArray[complex128]

Build one (XX+YY) matrix per angle, in a single kernel.

Mirrors cupy_xxplusyy_unitary_matrix() exactly, stacked along a leading batch axis.

Parameters:

thetas (NDArray[float64]) – Device array of rotation angles.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_cx_unitary_matrix() → NDArray[complex128]

Construct a controlled-X (CNOT) unitary matrix for two qubits.

The matrix is \(\begin{bmatrix} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & 0 & 1 \\ 0 & 0 & 1 & 0 \end{bmatrix}\) It is symmetric, so the matrix is invariant under cuStateVec’s reversed target order.

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

Return type:

NDArray[complex128]

cupy_diagonal_pauli_exponential_matrix(theta: float64, number_of_z_qubits: int) → NDArray[complex128]

Construct the unitary \(e^{-i\theta P}\) for a diagonal Pauli string P.

A diagonal Pauli string contains only Z and identity factors, so the unitary is diagonal with entries \(e^{\mp i\theta}\) set by the parity of the participating qubits. Since it depends only on this parity, it is invariant under cuStateVec’s reversed target order.

Parameters:

• theta (float64) – Rotation angle parameter of the Pauli exponential.

• number_of_z_qubits (int) – Number of qubits carrying a Z factor.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_double_excitation_unitary_matrix(theta: float64) → NDArray[complex128]

Construct a double excitation unitary matrix for four qubits.

The matrix is adapted for cuStateVec’s little-endian qubit ordering combined with our reversed target order. This effectively swaps the |0011⟩ and |1100⟩ states compared to the standard qrunch convention.

Parameters:

theta (float64) – Rotation angle parameter for the excitation gate.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_hadamard_unitary_matrix() → NDArray[complex128]

Construct a Hadamard unitary matrix.

The Hadamard matrix is \(\frac{1}{\sqrt{2}} \begin{bmatrix} 1 & 1 \\ 1 & -1 \end{bmatrix}\). It is symmetric, so it is invariant under cuStateVec’s reversed target order.

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

Return type:

NDArray[complex128]

cupy_pauli_x_unitary_matrix() → NDArray[complex128]

Construct a Pauli-X unitary matrix.

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

Return type:

NDArray[complex128]

cupy_phase_unitary_matrix(phi: float64) → NDArray[complex128]

Construct a phase gate unitary matrix.

The phase matrix is \(\begin{bmatrix} 1 & 0 \\ 0 & e^{i\phi} \end{bmatrix}\). It is diagonal, so it is invariant under cuStateVec’s reversed target order.

Parameters:

phi (float64) – Phase angle applied to the |1> amplitude.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_rx_unitary_matrix(theta: float64) → NDArray[complex128]

Construct an X-rotation unitary matrix.

The matrix is \(\begin{bmatrix} \cos\theta/2 & -i\sin\theta/2 \\ -i\sin\theta/2 & \cos\theta/2 \end{bmatrix}\). It acts on a single qubit, so it is trivially invariant under cuStateVec’s reversed target order.

Parameters:

theta (float64) – Rotation angle parameter for the X-rotation.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_ry_unitary_matrix(theta: float64) → NDArray[complex128]

Construct a Y-rotation unitary matrix.

The matrix is \(\begin{bmatrix} \cos\theta/2 & -\sin\theta/2 \\ \sin\theta/2 & \cos\theta/2 \end{bmatrix}\). It acts on a single qubit, so it is trivially invariant under cuStateVec’s reversed target order.

Parameters:

theta (float64) – Rotation angle parameter for the Y-rotation.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_rz_unitary_matrix(theta: float64) → NDArray[complex128]

Construct a Z-rotation unitary matrix.

The matrix is \(\begin{bmatrix} e^{-i\theta/2} & 0 \\ 0 & e^{i\theta/2} \end{bmatrix}\). It is diagonal, so it is invariant under cuStateVec’s reversed target order.

Parameters:

theta (float64) – Rotation angle parameter for the Z-rotation.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_single_excitation_unitary_matrix(theta: float64) → NDArray[complex128]

Construct a single excitation unitary matrix for two qubits.

The matrix is adapted for cuStateVec’s little-endian qubit ordering combined with our reversed target order. This effectively transposes the 2x2 subspace in the |01⟩, |10⟩ basis compared to the standard qrunch convention.

Parameters:

theta (float64) – Rotation angle parameter for the excitation gate.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

cupy_xxplusyy_unitary_matrix(theta: float64) → NDArray[complex128]

Construct an (XX+YY) unitary matrix for two qubits.

The gate is the identity outside the |01>, |10> subspace, where it acts as \(\begin{bmatrix} \cos\theta & i\sin\theta \\ i\sin\theta & \cos\theta \end{bmatrix}\). This block is symmetric, so the matrix is invariant under cuStateVec’s reversed target order and no transposition is required.

Parameters:

theta (float64) – Rotation angle parameter for the (XX+YY) interaction.

Return type:

NDArray[complex128]

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.

get_pauli_string_as_str(pauli_string: PauliString, num_qubits: int) → str

Convert a library PauliString to its dense literal form.

Parameters:

• pauli_string (PauliString) – Object exposing x_indices, y_indices and z_indices that report the qubit positions of the corresponding Pauli operators.

• num_qubits (int) – Total number of qubits; determines the output length.

Return type:

str

Requirements:

• Qrunch install requirements: qrunch[cuda] (or qrunch[all]).

• A working cuda (cupy) installation.