symmray.linalg_common

Common linear algebra utilities shared across backends.

Classes

Absorb

Absorb mode constants and parsing for SVD-like decompositions.

Functions

get_quimb_array_split()
array_split(*args, **kwargs)
absorb_svd_result(U, s, VH, absorb)	Apply absorption of singular values into U and/or VH.
blocklevel_svd_via_eig(x[, absorb, max_bond, ...])	SVD of (..., da, db) blocks via eigendecomposition of the
blocklevel_cholesky_regularized(blocks[, upper, shift])	Cholesky decomposition of symmetric positive-definite blocks
blocklevel_lq_via_cholesky(x[, absorb, shift, ...])	LQ decomposition of 2D blocks x via Cholesky factorization
blocklevel_qr_via_cholesky(x[, absorb, shift, ...])	QR decomposition of 2D blocks x via Cholesky factorization.
blocklevel_svd_rand_truncated(x, max_bond[, absorb, ...])	Randomized SVD of 2D blocks x, with static truncation

Module Contents

symmray.linalg_common.get_quimb_array_split()

symmray.linalg_common.array_split(*args, **kwargs)

class symmray.linalg_common.Absorb

Absorb mode constants and parsing for SVD-like decompositions.

Attributes give canonical integer codes for each mode. Use Absorb.parse to normalize user-facing string or integer aliases to the canonical code.

Modes

U_s_VHNone

Return all three factors unmodified (‘full’).

s2

Return only the singular values (‘svals’).

Usq-12

Absorb sqrt(s) into U, return (U√s, None, None) (‘lsqrt’).

VH-11

Return only VH (‘rorthog’).

Us-10

Absorb s into U, return (Us, None, None) (‘lfactor’).

Us_VH-1

Absorb s into U, return (Us, None, VH) (‘left’).

Usq_sqVH0

Absorb sqrt(s) into both, return (U√s, None, √sVH) (‘both’).

U_sVH1

Absorb s into VH, return (U, None, sVH) (‘right’).

U10

Return only U (‘lorthog’).

sVH11

Absorb s into VH, return (None, None, sVH) (‘rfactor’).

sqVH12

Absorb sqrt(s) into VH, return (None, None, √sVH) (‘rsqrt’).

U_s_VH = None

s = 2

Usq = -12

VH = -11

Us = -10

Us_VH = -1

Usq_sqVH = 0

U_sVH = 1

U = 10

sVH = 11

sqVH = 12

_map

_transpose_map

classmethod parse(absorb)

Normalize a user-facing absorb value to a canonical mode code.

Parameters:

absorb (int, str, or None) – Any valid absorb specification: a canonical integer code, a string alias (e.g. 'left', 'both', 'rfactor'), or None for full (no absorption).

Returns:

The canonical absorb mode code.

Return type:

int or None

Raises:

KeyError – If absorb is not a recognized mode or alias.

classmethod explain(absorb)

Get a human-readable explanation of an absorb mode.

Parameters:

absorb (int or None) – A canonical absorb mode code (already parsed).

Returns:

A human-readable explanation of the mode.

Return type:

str

classmethod transpose(absorb)

Map an absorb mode to its transposed equivalent.

Swaps left/right roles: e.g. U_sVH (‘right’) becomes Us_VH (‘left’), sVH (‘rfactor’) becomes Us (‘lfactor’), etc. Symmetric modes (both, full, svals) are unchanged.

Parameters:

absorb (int or None) – A canonical absorb mode code (already parsed).

Returns:

The transposed absorb mode code.

Return type:

int or None

static choose_charge_side(absorb, charge_side='auto')

symmray.linalg_common.absorb_svd_result(U, s, VH, absorb)

Apply absorption of singular values into U and/or VH.

Works on any symmray array objects that support multiply_diagonal and vectors that support .sqrt().

Parameters:

• U (SymmrayCommon) – Left singular vectors.

• s (VectorCommon) – Singular values.

• VH (SymmrayCommon) – Right singular vectors.

• absorb (int or None) – Absorption mode code (should already be parsed via Absorb.parse).

Returns:

• U (SymmrayCommon or None)

• s (VectorCommon or None)

• VH (SymmrayCommon or None)

symmray.linalg_common.blocklevel_svd_via_eig(x, absorb=Absorb.U_s_VH, max_bond=-1, descending=True, right=None)

SVD of (..., da, db) blocks via eigendecomposition of the Gram matrix, with static truncation and all absorb mode shortcuts.

Supports arbitrary leading batch dimensions (including none).

Parameters:

• x (array_like) – Input array with shape (..., da, db).

• absorb (int or None, optional) – Absorption mode code controlling what to compute / return.

• max_bond (int, optional) – Maximum bond dimension per block, use -1 for no truncation.

• descending (bool, optional) – Whether to return singular values in descending order.

• right (bool, optional) – Whether to eigendecompose xdag @ x (True) or x @ xdag (False). If None, choose based on shape and absorb mode.

Returns:

• U (array_like or None)

• s (array_like or None)

• VH (array_like or None)

symmray.linalg_common.blocklevel_cholesky_regularized(blocks, upper=False, shift=True)

Cholesky decomposition of symmetric positive-definite blocks with optional diagonal regularization.

Works for a single 2D block (d, d) or batched blocks with arbitrary leading dimensions (..., d, d).

Parameters:

• blocks (array_like) – Blocks of shape (..., d, d).

• upper (bool, optional) – Whether to return the upper triangular Cholesky factor. Default is False, returning the lower triangular factor.

• shift (float, optional) – Diagonal regularization shift. If True or negative, auto-compute from dtype machine epsilon. The shift is always applied as a relative shift scaled by the trace of each block. Default is True.

Returns:

L_or_R – The Cholesky factor, shape (..., d, d).

Return type:

array_like

symmray.linalg_common.blocklevel_lq_via_cholesky(x, absorb=Absorb.Us_VH, shift=True, solve_triangular=True)

LQ decomposition of 2D blocks x via Cholesky factorization of the Gram matrix x @ x^H.

Computes x = L @ Q where L is lower triangular and Q is isometric. Works for a single 2D block (da, db) or batched blocks with arbitrary leading dimensions (..., da, db).

Parameters:

• x (array_like) – Blocks of shape (..., da, db).

• absorb (int or None, optional) –

  Absorption mode code controlling what to return:

  • Absorb.Us_VH (-1, ‘left’): return (L, None, Q).

  • Absorb.Us (-10, ‘lfactor’): return (L, None, None).

  • Absorb.VH (-11, ‘rorthog’): return (None, None, Q).

• shift (float, optional) – Diagonal regularization shift. If True or negative, auto-compute from dtype machine epsilon. The shift is always applied as a relative shift scaled by the trace of each block. Default is True.

• solve_triangular (bool, optional) – Whether to use triangular solve (faster) or general solve to compute Q. Default is True.

Returns:

• L (array_like or None) – The lower triangular factor, shape (..., da, da).

• s (None) – Always None.

• Q (array_like or None) – The isometric factor, shape (..., da, db).

symmray.linalg_common.blocklevel_qr_via_cholesky(x, absorb=Absorb.U_sVH, shift=True, solve_triangular=True)

QR decomposition of 2D blocks x via Cholesky factorization. Implemented by transposing to LQ at the block level.

Computes x = Q @ R where Q is isometric and R is upper triangular. Works for a single 2D block (da, db) or batched blocks with arbitrary leading dimensions (..., da, db).

Parameters:

• x (array_like) – Blocks of shape (..., da, db).

• absorb (int or None, optional) –

  Absorption mode code controlling what to return:

  • Absorb.U_sVH (1, ‘right’): return (Q, None, R).

  • Absorb.sVH (11, ‘rfactor’): return (None, None, R).

  • Absorb.U (10, ‘lorthog’): return (Q, None, None).

• shift (float, optional) – Diagonal regularization shift. If True or negative, auto-compute from dtype machine epsilon. The shift is always applied as a relative shift scaled by the trace of each block. Default is True.

• solve_triangular (bool, optional) – Whether to use triangular solve (faster) or general solve to compute Q. Default is True.

Returns:

• Q (array_like or None) – The isometric factor, shape (..., da, db).

• s (None) – Always None.

• R (array_like or None) – The upper triangular factor, shape (..., db, db).

symmray.linalg_common.blocklevel_svd_rand_truncated(x, max_bond, absorb=Absorb.U_s_VH, oversample=10, num_iterations=2, seed=None, right=None)

Randomized SVD of 2D blocks x, with static truncation and all absorb mode shortcuts.

Uses a random sketch to approximate the column (or row) space, followed by eigendecomposition of the reduced matrix via blocklevel_svd_via_eig.

Works for a single 2D block (da, db) or batched blocks with arbitrary leading dimensions (..., da, db).

Parameters:

• x (array_like) – Blocks of shape (..., da, db).

• max_bond (int) – Maximum bond dimension per block (target rank).

• absorb (Absorb, optional) – Absorption mode code controlling what to compute / return.

• oversample (int, optional) – Extra dimensions added to the sketch for accuracy. Default is 10.

• num_iterations (int, optional) – Number of power iterations for accuracy. Default is 2.

• seed (int, Generator or None, optional) – Random seed or generator for reproducibility.

• right (bool, optional) – Whether to sketch from the right (True) or left (False). If None, choose based on shape and absorb mode.

Returns:

• U (array_like or None) – Left singular vectors, shape (..., da, k).

• s (array_like or None) – Singular values, shape (..., k).

• VH (array_like or None) – Right singular vectors, shape (..., k, db).