qamomile.linalg.pauli_lcu

Represent general complex matrices as linear combinations of Paulis.

Overview¶

Functions¶

coerce_finite_complex_scalar [source]¶

def coerce_finite_complex_scalar(value: object, name: str) -> complex

Convert one numeric scalar to a canonical finite complex value.

Parameters:

Returns:

complex — Finite Python complex value whose zero components have a positive sign.

Raises:

• TypeError — If value is Boolean or not a numeric scalar.

• ValueError — If a numeric scalar cannot be represented as a finite Python complex value.

coerce_nonnegative_finite_real [source]¶

def coerce_nonnegative_finite_real(value: object, name: str) -> float

Convert one numeric scalar to a canonical non-negative finite float.

Parameters:

Returns:

float — Finite non-negative Python float with a positive zero sign.

Raises:

• TypeError — If value is Boolean or not a real numeric scalar.

• ValueError — If an accepted real scalar cannot be represented as a finite non-negative Python float.

fwht_complex_pauli_coefficients [source]¶

def fwht_complex_pauli_coefficients(matrix: ArrayLike) -> tuple[np.ndarray, int]

Compute complex Pauli coefficients via FWHT.

Uses the symplectic indexing where qubit k is determined by bit k of each mask::

(x_bit, z_bit) -> Pauli
(0, 0) -> I
(1, 0) -> X
(0, 1) -> Z
(1, 1) -> Y

Qubit 0 corresponds to the least-significant bit of the matrix’s computational-basis indices.

Parameters:

Returns:

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

Raises:

• ValueError — If matrix is not a finite square matrix whose dimension is a positive power of two, or cannot be converted to complex numeric data.

Classes¶

PauliLCU [source]¶

class PauliLCU

Store an immutable Pauli linear-combination decomposition.

Parameters:

Raises:

• TypeError — If num_qubits, terms, or truncation_error_bound has an invalid type.

• ValueError — If a term addresses a qubit outside the system, duplicate Pauli words are present, the LCU normalization exceeds the finite float range, or the error bound is negative or non-finite.

Constructor¶

def __init__(
    self,
    num_qubits: int,
    terms: tuple[PauliLCUTerm, ...],
    truncation_error_bound: float = 0.0,
) -> None

Attributes¶

• alpha: float Return the LCU one-norm normalization.

• num_qubits: int

• num_terms: int Return the number of retained Pauli terms.

• terms: tuple[PauliLCUTerm, ...]

• truncation_error_bound: float

Methods¶

from_matrix¶

@classmethod
def from_matrix(cls, matrix: ArrayLike, *, atol: float = 0.0) -> PauliLCU

Decompose a general complex matrix into the Pauli basis.

Qubit zero is the least-significant bit of the matrix’s computational basis index. Coefficients whose magnitude is at most atol are omitted, and their absolute values are accumulated into :attr:truncation_error_bound.

Parameters:

Returns:

PauliLCU — Immutable ordered Pauli decomposition.

Raises:

• TypeError — If atol is not a real number.

• ValueError — If atol is negative or non-finite, or matrix is not a finite square numeric matrix with power-of-two dimension, or the resulting LCU normalization exceeds the finite float range.

PauliLCUTerm [source]¶

class PauliLCUTerm

Store one nonzero complex coefficient and one sparse Pauli word.

The empty operator tuple denotes the identity. Non-identity operators are canonicalized into increasing qubit-index order.

Parameters:

Raises:

• TypeError — If the coefficient is not a numeric scalar, an operator is not a PauliOperator, its Pauli value is invalid, or its index is not an integer.

• ValueError — If the coefficient is zero or non-finite, an identity operator is stored explicitly, or multiple operators address the same qubit.

Constructor¶

def __init__(self, coefficient: complex, operators: tuple[PauliOperator, ...]) -> None

Attributes¶

• coefficient: complex

• operators: tuple[PauliOperator, ...]