Skip to content

qten.linalg.orthogonalize

Module reference for qten.linalg.orthogonalize.

orthogonalize

Tensor-aware matrix orthogonalization routines for QTen.

This module provides orthogonalization algorithms that operate on Tensor objects while preserving symbolic dimension metadata.

Public orthogonalizations
  • lowdin_orthonormalize Symmetric orthonormalization of matrix columns using the positive-definite inverse square root of their Gram matrix.
Conventions

All orthogonalizations act on the last two tensor dimensions as matrix axes. The penultimate axis labels the ambient row space, the final axis labels the columns to orthonormalize, and any leading dimensions are treated as batch axes. The input dimensions and their ordering are preserved in the result.

The routines require every matrix in the batch to have full column rank at the requested numerical tolerance. Consequently, the number of columns cannot exceed the dimension of the row space. A rank-deficient input raises an error rather than silently dropping columns or changing symbolic spaces.

Unlike the routines in qten.linalg.decompose, these functions return a transformed tensor rather than decomposition factors.

lowdin_orthonormalize 

lowdin_orthonormalize(
    tensor: Tensor, rank_tolerance: float = 1e-10
) -> Tensor

Symmetrically orthonormalize the columns of a tensor.

Applies the Lowdin transformation \(A \mapsto A(A^\dagger A)^{-1/2}\) independently to every matrix in the leading batch dimensions. The input dimensions are preserved.

Parameters:

Name Type Description Default
tensor Tensor

Input whose last two dimensions are the row and column matrix axes.

 required
rank_tolerance float

Minimum allowed eigenvalue of the column Gram matrix. A non-positive value or one at or below this threshold indicates linearly dependent columns.

 1e-10

Returns:

Type Description
Tensor

A tensor with the same dimensions and orthonormal columns.

Raises:

Type Description
ValueError

If the input has fewer than two dimensions or rank_tolerance is negative.
RuntimeError

If any matrix in the batch has linearly dependent columns at the requested tolerance.
Source code in src/qten/linalg/orthogonalize.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def lowdin_orthonormalize(tensor: Tensor, rank_tolerance: float = 1e-10) -> Tensor:
    r"""Symmetrically orthonormalize the columns of a tensor.

    Applies the Lowdin transformation
    \(A \mapsto A(A^\dagger A)^{-1/2}\) independently to every matrix in the
    leading batch dimensions. The input dimensions are preserved.

    Parameters
    ----------
    tensor : Tensor
        Input whose last two dimensions are the row and column matrix axes.
    rank_tolerance : float, default=1e-10
        Minimum allowed eigenvalue of the column Gram matrix. A non-positive
        value or one at or below this threshold indicates linearly dependent
        columns.

    Returns
    -------
    Tensor
        A tensor with the same dimensions and orthonormal columns.

    Raises
    ------
    ValueError
        If the input has fewer than two dimensions or ``rank_tolerance`` is
        negative.
    RuntimeError
        If any matrix in the batch has linearly dependent columns at the
        requested tolerance.
    """
    if tensor.rank() < 2:
        raise ValueError(
            "Input tensor must have at least two dimensions for Lowdin "
            "orthonormalization."
        )
    if rank_tolerance < 0:
        raise ValueError("rank_tolerance must be non-negative.")

    if tensor.dims[-1].dim > tensor.dims[-2].dim:
        minimum_gram_eigenvalue = 0.0
        raise RuntimeError(
            "Lowdin orthonormalization encountered linearly dependent columns: "
            f"minimum Gram eigenvalue={minimum_gram_eigenvalue:.6e}."
        )

    decomposition = svd(tensor, full_matrices=False)
    minimum_singular_value = cast(float, decomposition.S.amin().item())
    minimum_gram_eigenvalue = minimum_singular_value**2
    if minimum_gram_eigenvalue <= rank_tolerance:
        raise RuntimeError(
            "Lowdin orthonormalization encountered linearly dependent columns: "
            f"minimum Gram eigenvalue={minimum_gram_eigenvalue:.6e}."
        )

    return decomposition.U @ decomposition.Vh