qamomile.linalg.periodic_shift_lcu

Represent periodic-shift matrices as immutable LCU decompositions.

Overview¶

Functions¶

as_finite_square_complex_matrix [source]¶

def as_finite_square_complex_matrix(matrix: ArrayLike) -> np.ndarray

Convert one value to a finite square complex128 matrix.

Parameters:

Returns:

np.ndarray — np.ndarray: Finite square complex128 matrix.

Raises:

• ValueError — If conversion fails or the result is nonsquare or non-finite.

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.

Classes¶

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