qamomile.linalg.hermitian

Dense Hermitian matrix wrapper with Pauli decomposition via FWHT.

Overview¶

Functions¶

fwht_pauli_coefficients [source]¶

def fwht_pauli_coefficients(matrix: np.ndarray, *, imag_tol: float = 1e-10) -> tuple[np.ndarray, int]

Compute real Pauli coefficients for a Hermitian matrix via FWHT.

Parameters:

Returns:

tuple[np.ndarray, int] — tuple[np.ndarray, int]: Pair (coeffs, num_qubits) where coeffs is an (N, N) float64 array indexed by (x_mask, z_mask).

Raises:

• ValueError — If the matrix fails the generic complex decomposition validation or produces an imaginary coefficient larger than imag_tol.

is_close_zero [source]¶

def is_close_zero(value: float, abs_tol: float = 1e-15) -> bool

Check if a given floating-point value is close to zero within a small tolerance.

Parameters:

Returns:

bool — True if the value is close to zero, False otherwise.

is_power_of_two [source]¶

def is_power_of_two(n: int) -> bool

Check whether n is a positive power of two.

Parameters:

Returns:

bool — True if n is a power of two, False otherwise.

Classes¶

HermitianMatrix [source]¶

class HermitianMatrix

Dense Hermitian operator on n qubits (a 2**n x 2**n matrix).

Wraps a NumPy array and validates on construction that it is 2D square, has a power-of-two dimension, and is Hermitian up to atol. The Hermitian check can be skipped via validate=False for internal use (for example, when the caller already knows a result is Hermitian by construction).

The main entry point for downstream quantum code is :meth:to_hamiltonian, which returns the exact Pauli decomposition as a :class:qamomile.observable.Hamiltonian via the Fast Walsh-Hadamard Transform in O(n * 4**n) time.

Example:

>>> import numpy as np
>>> from qamomile.linalg import HermitianMatrix
>>> X = np.array([[0, 1], [1, 0]], dtype=complex)
>>> Z = np.array([[1, 0], [0, -1]], dtype=complex)
>>> H = HermitianMatrix(np.kron(X, Z) + 0.5 * np.kron(Z, np.eye(2)))
>>> H.num_qubits
2
>>> ham = H.to_hamiltonian()

Constructor¶

def __init__(
    self,
    matrix: np.ndarray,
    *,
    validate: bool = True,
    atol: float = 1e-10,
) -> None

Attributes¶

• matrix: np.ndarray Return a read-only view of the underlying array.

• num_qubits: int Number of qubits (log2 of the matrix dimension).

• shape: tuple[int, int] Shape of the underlying matrix as (2**n, 2**n).

Methods¶

to_hamiltonian¶

def to_hamiltonian(self, *, tol: float = 1e-12) -> Hamiltonian

Return the exact Pauli decomposition as a Hamiltonian.

Uses FWHT internally. Pauli terms with |coeff| <= tol are dropped. The all-identity component is accumulated into :attr:qamomile.observable.Hamiltonian.constant. Qubit 0 corresponds to the least-significant bit of the matrix’s computational-basis indices.

Parameters:

Returns:

Hamiltonian — class:~qamomile.observable.Hamiltonian containing the Hamiltonian — Pauli decomposition.