symmray.linalg_common ===================== .. py:module:: symmray.linalg_common .. autoapi-nested-parse:: Common linear algebra utilities shared across backends. Classes ------- .. autoapisummary:: symmray.linalg_common.Absorb Functions --------- .. autoapisummary:: symmray.linalg_common.get_quimb_array_split symmray.linalg_common.array_split symmray.linalg_common.absorb_svd_result symmray.linalg_common.blocklevel_svd_via_eig symmray.linalg_common.blocklevel_cholesky_regularized symmray.linalg_common.blocklevel_lq_via_cholesky symmray.linalg_common.blocklevel_qr_via_cholesky symmray.linalg_common.blocklevel_svd_rand_truncated Module Contents --------------- .. py:function:: get_quimb_array_split() .. py:function:: array_split(*args, **kwargs) .. py:class:: 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_VH : None Return all three factors unmodified ('full'). s : 2 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_sqVH : 0 Absorb sqrt(s) into both, return (U√s, None, √sVH) ('both'). U_sVH : 1 Absorb s into VH, return (U, None, sVH) ('right'). U : 10 Return only U ('lorthog'). sVH : 11 Absorb s into VH, return (None, None, sVH) ('rfactor'). sqVH : 12 Absorb sqrt(s) into VH, return (None, None, √sVH) ('rsqrt'). .. py:attribute:: U_s_VH :value: None .. py:attribute:: s :value: 2 .. py:attribute:: Usq :value: -12 .. py:attribute:: VH :value: -11 .. py:attribute:: Us :value: -10 .. py:attribute:: Us_VH :value: -1 .. py:attribute:: Usq_sqVH :value: 0 .. py:attribute:: U_sVH :value: 1 .. py:attribute:: U :value: 10 .. py:attribute:: sVH :value: 11 .. py:attribute:: sqVH :value: 12 .. py:attribute:: _map .. py:attribute:: _transpose_map .. py:method:: parse(absorb) :classmethod: Normalize a user-facing absorb value to a canonical mode code. :param absorb: Any valid absorb specification: a canonical integer code, a string alias (e.g. ``'left'``, ``'both'``, ``'rfactor'``), or ``None`` for full (no absorption). :type absorb: int, str, or None :returns: The canonical absorb mode code. :rtype: int or None :raises KeyError: If ``absorb`` is not a recognized mode or alias. .. py:method:: explain(absorb) :classmethod: Get a human-readable explanation of an absorb mode. :param absorb: A canonical absorb mode code (already parsed). :type absorb: int or None :returns: A human-readable explanation of the mode. :rtype: str .. py:method:: transpose(absorb) :classmethod: 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. :param absorb: A canonical absorb mode code (already parsed). :type absorb: int or None :returns: The transposed absorb mode code. :rtype: int or None .. py:method:: choose_charge_side(absorb, charge_side='auto') :staticmethod: .. py:function:: 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()``. :param U: Left singular vectors. :type U: SymmrayCommon :param s: Singular values. :type s: VectorCommon :param VH: Right singular vectors. :type VH: SymmrayCommon :param absorb: Absorption mode code (should already be parsed via ``Absorb.parse``). :type absorb: int or None :returns: * **U** (*SymmrayCommon or None*) * **s** (*VectorCommon or None*) * **VH** (*SymmrayCommon or None*) .. py:function:: 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). :param x: Input array with shape ``(..., da, db)``. :type x: array_like :param absorb: Absorption mode code controlling what to compute / return. :type absorb: int or None, optional :param max_bond: Maximum bond dimension per block, use -1 for no truncation. :type max_bond: int, optional :param descending: Whether to return singular values in descending order. :type descending: bool, optional :param right: Whether to eigendecompose ``xdag @ x`` (True) or ``x @ xdag`` (False). If None, choose based on shape and absorb mode. :type right: bool, optional :returns: * **U** (*array_like or None*) * **s** (*array_like or None*) * **VH** (*array_like or None*) .. py:function:: 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)``. :param blocks: Blocks of shape ``(..., d, d)``. :type blocks: array_like :param upper: Whether to return the upper triangular Cholesky factor. Default is False, returning the lower triangular factor. :type upper: bool, optional :param shift: 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. :type shift: float, optional :returns: **L_or_R** -- The Cholesky factor, shape ``(..., d, d)``. :rtype: array_like .. py:function:: 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)``. :param x: Blocks of shape ``(..., da, db)``. :type x: array_like :param absorb: 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)``. :type absorb: int or None, optional :param shift: 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. :type shift: float, optional :param solve_triangular: Whether to use triangular solve (faster) or general solve to compute Q. Default is True. :type solve_triangular: bool, optional :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)``. .. py:function:: 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)``. :param x: Blocks of shape ``(..., da, db)``. :type x: array_like :param absorb: 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)``. :type absorb: int or None, optional :param shift: 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. :type shift: float, optional :param solve_triangular: Whether to use triangular solve (faster) or general solve to compute Q. Default is True. :type solve_triangular: bool, optional :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)``. .. py:function:: 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)``. :param x: Blocks of shape ``(..., da, db)``. :type x: array_like :param max_bond: Maximum bond dimension per block (target rank). :type max_bond: int :param absorb: Absorption mode code controlling what to compute / return. :type absorb: Absorb, optional :param oversample: Extra dimensions added to the sketch for accuracy. Default is 10. :type oversample: int, optional :param num_iterations: Number of power iterations for accuracy. Default is 2. :type num_iterations: int, optional :param seed: Random seed or generator for reproducibility. :type seed: int, Generator or None, optional :param right: Whether to sketch from the right (True) or left (False). If None, choose based on shape and absorb mode. :type right: bool, optional :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)``.