qamomile.linalg

Matrix types upstream of :mod:qamomile.observable.

Exposes:

• :class:HermitianMatrix, which wraps a dense Hermitian NumPy matrix and produces an exact Pauli decomposition as a :class:qamomile.observable.Hamiltonian via the Fast Walsh-Hadamard Transform.

• Sample-based partial-diagonalization helpers (:func:subspace_hamiltonian, :func:generalized_subspace_matrices, :func:solve_subspace) that build Hamiltonian / overlap matrices on a subspace spanned by a set of computational-basis or mixed-Pauli-basis product states and (optionally) solve the resulting (generalised) eigenvalue problem.

• Möttönen amplitude-encoding angle precomputation (:func:compute_mottonen_amplitude_encoding_ry_angles, :func:compute_mottonen_amplitude_encoding_rz_angles, :func:validate_and_normalize_amplitudes). The actual quantum gate emission lives under :mod:qamomile.circuit.stdlib.state_preparation; this module provides only the classical angle math so that hybrid loops can pre-compute angle vectors outside any kernel and feed them to mottonen_amplitude_encoding_from_angles via parameters=[...].

• :class:PauliLCU, which decomposes any finite complex power-of-two square matrix into immutable complex-weighted Pauli terms for LCU algorithms.

• :class:PeriodicShiftLCU, which validates constant-coefficient periodic shift structure and stores its immutable complex-weighted shift terms.

Overview¶

Functions¶

compute_mottonen_amplitude_encoding_ry_angles [source]¶

def compute_mottonen_amplitude_encoding_ry_angles(amplitudes: Sequence[float] | Sequence[complex] | np.ndarray) -> np.ndarray

Pre-compute the flat Ry angle vector for a Möttönen encoding.

Returns the Gray-walk Ry angles for the magnitude stage of the encoding. For real inputs (or complex inputs with zero imaginary part) this corresponds to the single-stage signed-Ry encoding. For complex inputs with non-zero imaginary part, these are the magnitude-stage angles only — pair with :func:compute_mottonen_amplitude_encoding_rz_angles to obtain the phase-stage angles needed to reproduce the full complex state.

Parameters:

Returns:

np.ndarray — np.ndarray: 1-D array of length 2**n - 1 holding the Gray-walk Ry angles laid out level by level.

Raises:

• ValueError — If the input is not a 1-D vector, the length is not a power of two (or is less than 2, i.e., would map to a zero-qubit register), or all amplitudes are zero.

compute_mottonen_amplitude_encoding_rz_angles [source]¶

def compute_mottonen_amplitude_encoding_rz_angles(amplitudes: Sequence[float] | Sequence[complex] | np.ndarray) -> np.ndarray

Pre-compute the flat Rz angle vector for the phase-restoration stage.

Returns the Gray-walk Rz angles for the phase stage of the Möttönen encoding. For real inputs (or complex inputs with zero imaginary part) the phase stage is unnecessary and the returned array is all zeros. For complex inputs with non-zero imaginary part, the returned angles together with the Ry angles from :func:compute_mottonen_amplitude_encoding_ry_angles reproduce the full complex state.

Parameters:

Returns:

np.ndarray — np.ndarray: 1-D array of length 2**n - 1 holding the Gray-walk Rz angles laid out level by level (all zeros for real inputs).

Raises:

• ValueError — If the input is not a 1-D vector, the length is not a power of two (or is less than 2, i.e., would map to a zero-qubit register), or all amplitudes are zero.

generalized_subspace_matrices [source]¶

def generalized_subspace_matrices(
    samples: Sequence[Sequence[int]] | np.ndarray,
    bases: Sequence[Sequence[BasisLike]] | Sequence[BasisLike] | np.ndarray,
    hamiltonian: qm_o.Hamiltonian,
) -> tuple[np.ndarray, np.ndarray]

Build (H_sub, S_sub) for samples in mixed X/Y/Z eigenbases.

Each sample |s_i; β_i⟩ = ⊗_q |β_{i,q}, s_{i,q}⟩ is a tensor product of single-qubit Pauli eigenstates with per-qubit basis β_{i,q} and bit s_{i,q}. The returned matrices are

H_sub[i, j] = ⟨s_i; β_i| H |s_j; β_j⟩,
S_sub[i, j] = ⟨s_i; β_i|     s_j; β_j⟩,

so the variational eigenpairs are recovered by solving the generalized eigenvalue problem H_sub v = λ S_sub v (see :func:solve_subspace).

Parameters:

Returns:

np.ndarray — Tuple (H_sub, S_sub) of complex ndarray s with shape np.ndarray — (n_samples, n_samples).

Raises:

• ValueError — On shape, range, or label mismatches in samples or bases.

Example:

Mixed-basis subspace with one Z-basis sample (|0⟩) and one
X-basis sample (|+⟩) for H = Z:

>>> import qamomile.observable as qm_o
>>> from qamomile.linalg import generalized_subspace_matrices
>>> H = qm_o.Z(0)
>>> samples = [(0,), (0,)]  # bit=0 in each basis
>>> bases = [(qm_o.Pauli.Z,), (qm_o.Pauli.X,)]  # |0⟩ and |+⟩
>>> H_sub, S_sub = generalized_subspace_matrices(samples, bases, H)
>>> S_sub  # off-diagonal ⟨0|+⟩ = 1/√2, not identity
array([[1.    +0.j, 0.7071+0.j],
       [0.7071+0.j, 1.    +0.j]])
>>> H_sub  # ⟨0|Z|0⟩=1, ⟨+|Z|+⟩=0, ⟨0|Z|+⟩=1/√2
array([[1.    +0.j, 0.7071+0.j],
       [0.7071+0.j, 0.    +0.j]])

solve_subspace [source]¶

def solve_subspace(
    samples: Sequence[Sequence[int]] | np.ndarray,
    hamiltonian: qm_o.Hamiltonian,
    *,
    bases: Sequence[Sequence[BasisLike]] | Sequence[BasisLike] | np.ndarray | None = None,
    overlap_tol: float = 1e-12,
) -> tuple[np.ndarray, np.ndarray]

Solve the (generalized) subspace eigenvalue problem.

Every input, including the default Z-basis path, is solved as the generalised eigenvalue problem H_sub v = λ S_sub v. When bases is None, Z labels are synthesized and :func:generalized_subspace_matrices builds both matrices. Whitening S_sub via its eigendecomposition reduces the usable subspace to a standard Hermitian problem, with overlap_tol as the cutoff. This removes null directions caused by duplicate or near-duplicate samples instead of treating repeated Z samples as independent basis states.

Parameters:

Returns:

np.ndarray — Tuple (eigvals, eigvecs). eigvals is a real 1-D array np.ndarray — sorted in ascending order; eigvecs[:, k] is the variational tuple[np.ndarray, np.ndarray] — coefficient vector of the k-th eigenstate in the basis of tuple[np.ndarray, np.ndarray] — the supplied samples. In the rank-deficient fallback path the tuple[np.ndarray, np.ndarray] — number of returned eigenpairs is the effective rank of tuple[np.ndarray, np.ndarray] — S_sub.

Raises:

• ValueError — If overlap_tol is negative, any input fails validation in :func:subspace_hamiltonian / :func:generalized_subspace_matrices, or every overlap eigenvalue is below overlap_tol (the supplied basis spans no usable directions; lower overlap_tol or pass a better-conditioned set of samples).

Example:

>>> import qamomile.observable as qm_o
>>> from qamomile.linalg import solve_subspace
>>> H = -qm_o.X(0)
>>> # Sampling the |+⟩ eigenstate of X recovers the ground state.
>>> eigvals, _ = solve_subspace(
...     [(0,)], H, bases=(qm_o.Pauli.X,)
... )
>>> float(eigvals[0])
-1.0

subspace_hamiltonian [source]¶

def subspace_hamiltonian(
    samples: Sequence[Sequence[int]] | np.ndarray,
    hamiltonian: qm_o.Hamiltonian,
) -> np.ndarray

Build H_sub[i, j] = ⟨s_i| H |s_j⟩ for Z-basis bitstring samples.

Vectorised over all (i, j) pairs using XOR masks to detect the X/Y support of each Pauli term and Z/Y parities for the sign and phase. Identical bitstrings produce a degenerate row/column; dedupe upstream if the resulting subspace must be non-degenerate.

Parameters:

Returns:

np.ndarray — Complex ndarray of shape (n_samples, n_samples) holding np.ndarray — ⟨s_i|H|s_j⟩.

Raises:

• ValueError — If samples has the wrong rank, fewer columns than hamiltonian.num_qubits, or out-of-range entries.

Example:

>>> import qamomile.observable as qm_o
>>> from qamomile.linalg import subspace_hamiltonian
>>> H = qm_o.Z(0) + qm_o.X(1)
>>> # All four Z-basis bitstrings on 2 qubits
>>> samples = [(0, 0), (1, 0), (0, 1), (1, 1)]
>>> H_sub = subspace_hamiltonian(samples, H)
>>> H_sub.shape
(4, 4)

validate_and_normalize_amplitudes [source]¶

def validate_and_normalize_amplitudes(
    amplitudes: Sequence[float] | Sequence[complex] | np.ndarray,
) -> tuple[np.ndarray, int, bool]

Validate an amplitude vector and return its normalised form.

The Möttönen construction (arXiv:quant-ph/0407010, Section III) works on a unit-norm amplitude vector indexed by computational basis states; this helper enforces that pre-condition so the downstream angle computation can assume a well-formed input.

Inputs may be real or complex. A complex input whose imaginary part is identically zero (within np.allclose tolerance) is coerced to a real array; this preserves the cheaper signed-RY fast path for vectors that happen to arrive boxed as complex.

Parameters:

Returns:

tuple[np.ndarray, int, bool] — tuple[np.ndarray, int, bool]: (normalized, num_qubits, is_complex) where normalized is a unit-norm np.ndarray, num_qubits is log2(len(amplitudes)), and is_complex is True iff the input has a non-zero imaginary component (and therefore needs the phase-restoration stage downstream). When is_complex is False, normalized.dtype is float; otherwise it is complex.

Raises:

• ValueError — If the input is not a 1-D vector (e.g., a nested sequence or a 2-D np.ndarray), the length is not a power of two (or is less than 2, i.e., would map to a zero-qubit register), or all amplitudes are zero.

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.

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, ...]

PeriodicShiftLCU [source]¶

class PeriodicShiftLCU

Store an immutable periodic-shift linear-combination decomposition.

Axis zero occupies the least-significant bits of the flattened system basis. Each term represents coefficient * T_offset, where every axis of T_offset wraps modulo 2**register_sizes[axis].

Parameters:

Raises:

• TypeError — If a field has an invalid runtime type.

• ValueError — If an axis width, term, normalization, or truncation bound is invalid, or terms contain duplicate offsets.

Constructor¶

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

Attributes¶

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

• num_qubits: int Return the flattened system-register width.

• num_terms: int Return the number of retained periodic-shift terms.

• register_sizes: tuple[int, ...]

• terms: tuple[PeriodicShiftLCUTerm, ...]

• truncation_error_bound: float

Methods¶

from_coefficients¶

@classmethod
def from_coefficients(
    cls,
    coefficients: Mapping[Offset, complex],
    *,
    register_sizes: Sequence[int],
    atol: float = 0.0,
) -> PeriodicShiftLCU

Build a canonical decomposition from periodic-shift coefficients.

Equivalent signed or unsigned offsets are combined before pruning. Coefficients whose magnitude is at most atol are omitted, and the sum of their magnitudes is stored in truncation_error_bound.

Parameters:

Returns:

PeriodicShiftLCU — Immutable canonical decomposition.

Raises:

• TypeError — If coefficients, offsets, widths, or atol have invalid types.

• ValueError — If a value is non-finite, an offset has the wrong dimension, a width is invalid, or normalization overflows.

from_matrix¶

@classmethod
def from_matrix(
    cls,
    matrix: ArrayLike,
    *,
    register_sizes: Sequence[int],
    atol: float = 0.0,
) -> PeriodicShiftLCU

Decompose an exact constant-coefficient periodic-shift matrix.

After conversion to complex128, the structural check is exact: every column must be the periodic translation of the first column implied by register_sizes. The atol argument has the same meaning as in :meth:from_coefficients; it prunes extracted coefficients but does not relax the structural check. Hermiticity is not required.

Parameters:

Returns:

PeriodicShiftLCU — Immutable canonical shift decomposition.

Raises:

• TypeError — If widths or atol have invalid types.

• ValueError — If the matrix is nonnumeric, non-finite, nonsquare, has the wrong dimension, violates the periodic-shift structure, or produces an unrepresentable normalization.

PeriodicShiftLCUTerm [source]¶

class PeriodicShiftLCUTerm

Store one nonzero coefficient and one canonical periodic offset.

Parameters:

Raises:

• TypeError — If the coefficient is not numeric or the offset is not an iterable of non-Boolean integers.

• ValueError — If the coefficient is zero or non-finite, or an offset component is negative.

Constructor¶

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

Attributes¶

• coefficient: complex

• offset: tuple[int, ...]

Submodules¶

• qamomile.linalg.hermitian

• qamomile.linalg.mottonen

• qamomile.linalg.pauli_lcu

• qamomile.linalg.periodic_shift_lcu

• qamomile.linalg.subspace