qdk_chemistry.utils.pauli_matrix module

Pure-Python Pauli matrix utilities.

Provides the same functionality as the C++ pybind11 pauli_matrix module using only NumPy (and SciPy for sparse output), preserving the original bitmask algorithms to minimise memory cost and keep efficiency.

All functions use Little-Endian label convention: label[0] corresponds to qubit n-1 (MSB).

qdk_chemistry.utils.pauli_matrix.pauli_string_to_masks(pauli_str)

Decompose a Pauli label string into bitmasks and phase factor.

X sets a bit in x_mask, Z sets a bit in z_mask, Y sets both. The cumulative phase factor (i)^(number of Y operators) is also returned.

Return type:

tuple[int, int, complex]

Parameters:

pauli_str (str) – Pauli string (characters in {I, X, Y, Z}), using Little-Endian label convention.

Returns:

(x_mask, z_mask, y_phase) where x_mask and z_mask are integers and y_phase is a complex number.

qdk_chemistry.utils.pauli_matrix.pauli_to_dense_matrix(pauli_strings, coefficients)

Build a dense Hamiltonian matrix from Pauli strings and coefficients.

Computes \(H = \sum_t \mathrm{coeff}[t] \cdot P_t\) where each \(P_t\) is a Pauli string in Little-Endian convention.

Return type:

ndarray

Parameters:

• pauli_strings (list[str]) – List of Pauli label strings (characters in {I, X, Y, Z}), all of the same length n.

• coefficients (ndarray) – Complex array of coefficients, one per Pauli term.

Returns:

Dense complex matrix of shape (2**n, 2**n).

qdk_chemistry.utils.pauli_matrix.pauli_to_sparse_matrix(pauli_strings, coefficients)

Build a sparse CSR Hamiltonian matrix from Pauli strings and coefficients.

Computes \(H = \sum_t \mathrm{coeff}[t] \cdot P_t\) and returns the result as a scipy.sparse.csr_matrix.

Return type:

csr_matrix

Parameters:

• pauli_strings (list[str]) – List of Pauli label strings (characters in {I, X, Y, Z}), all of the same length n.

• coefficients (ndarray) – Complex array of coefficients, one per Pauli term.

Returns:

Sparse complex matrix of shape (2**n, 2**n).

Raises:

RuntimeError – If the matrix dimensions exceed int32 index limits.