qten.linalg

Package reference for qten.linalg.

linalg

Linear-algebra routines built on top of QTen tensors.

This package contains decomposition algorithms and tensor-aware numerical helpers that operate on Tensor objects while preserving symbolic dimension metadata.

Decompositions

• eig General eigendecomposition for square tensor-valued matrices.
• eigh Hermitian eigendecomposition.
• eigvals General eigenvalues only.
• eigvalsh Hermitian eigenvalues only.
• qr QR factorization.
• svd Singular value decomposition.

Convenience re-exports

• einsum Tensor contraction helper re-exported from qten.linalg.tensors.
• norm Tensor norm helper re-exported from qten.linalg.tensors.

Related modules

• qten.linalg.tensors
• qten.linalg.decompose

Exported API

eig

eig(tensor: Tensor) -> EigH

Perform eigendecomposition on general square matrix axes.

This function applies torch.linalg.eig to the final two dimensions of a Tensor. The last two dimensions must span the same Hilbert space up to ray ordering so they can be interpreted as a square operator. Any leading dimensions are treated as batch dimensions and are preserved in both outputs.

Parameters:

Name	Type	Description	Default
tensor	Tensor	Input tensor whose last two dimensions form square matrices.	required

Returns:

Type	Description
EigH	EigH containing: - eigenvalues, whose dtype is the complex dtype associated with the input and whose dims replace the matrix axes with one IndexSpace. - eigenvectors, whose dtype matches that complex dtype and whose dims are the leading batch dims followed by (row_dim, spectrum).

Examples:

result = eig(tensor)
values = result.eigenvalues
vectors = result.eigenvectors

Notes

torch.linalg.eig does not guarantee any ordering of the eigenvalues. This function sorts eigenvalues lexicographically by (real, imag) and applies the same reordering to eigenvectors.

The returned tensors satisfy \(A V = V\Lambda\), where \(\Lambda\) is the diagonal matrix of eigenvalues. If the input matrix is diagonalizable, this gives the reconstruction \(A = V\Lambda V^{-1}\). In code, \(V\) is eigenvectors and \(\Lambda\) is the diagonal matrix built from eigenvalues.

Source code in src/qten/linalg/decompose.py

def eig(tensor: Tensor) -> EigH:
    r"""
    Perform eigendecomposition on general square matrix axes.

    This function applies [`torch.linalg.eig`](https://pytorch.org/docs/stable/generated/torch.linalg.eig.html)
    to the final two dimensions of a
    [`Tensor`][qten.linalg.tensors.Tensor]. The last two dimensions must span
    the same Hilbert space up to ray ordering so they can be interpreted as a
    square operator. Any leading dimensions are treated as batch dimensions and
    are preserved in both outputs.

    Parameters
    ----------
    tensor : Tensor
        Input tensor whose last two dimensions form square matrices.

    Returns
    -------
    EigH
        [`EigH`][qten.linalg.decompose.EigH] containing:
        - `eigenvalues`, whose dtype is the complex dtype associated with the
          input and whose dims replace the matrix axes with one
          [`IndexSpace`][qten.symbolics.state_space.IndexSpace].
        - `eigenvectors`, whose dtype matches that complex dtype and whose dims
          are the leading batch dims followed by `(row_dim, spectrum)`.

    Examples
    --------
    ```python
    result = eig(tensor)
    values = result.eigenvalues
    vectors = result.eigenvectors
    ```

    Notes
    -----
    `torch.linalg.eig` does not guarantee any ordering of the eigenvalues. This
    function sorts eigenvalues lexicographically by `(real, imag)` and applies
    the same reordering to eigenvectors.

    The returned tensors satisfy \(A V = V\Lambda\), where \(\Lambda\) is the
    diagonal matrix of eigenvalues. If the input matrix is diagonalizable, this
    gives the reconstruction \(A = V\Lambda V^{-1}\). In code, \(V\) is
    `eigenvectors` and \(\Lambda\) is the diagonal matrix built from
    `eigenvalues`.
    """
    _assert_eig_dims(tensor)

    dim0 = tensor.dims[-2]
    target = tensor.align(-1, dim0)  # Align column space to match the row space
    eigenvalues, eigenvectors = torch.linalg.eig(target.data)
    eigenvalues, eigenvectors = _sort_eigenpairs(eigenvalues, eigenvectors)

    spectrum = IndexSpace.linear(eigenvalues.shape[-1])

    eigvals = Tensor(
        data=eigenvalues,
        dims=target.dims[:-2] + (spectrum,),
    )
    eigvecs = Tensor(
        data=eigenvectors,
        dims=target.dims[:-2] + (dim0, spectrum),
    )

    return EigH(eigvals, eigvecs)

eigh

eigh(tensor: Tensor) -> EigH

Perform Hermitian eigendecomposition on the last two tensor dimensions.

This function applies torch.linalg.eigh to the matrix axes of a Tensor. The final two dimensions must span the same Hilbert space up to ray ordering so they can be interpreted as a Hermitian operator. Any leading dimensions are treated as batch dimensions and are preserved in both outputs.

Parameters:

Name	Type	Description	Default
tensor	Tensor	Input tensor whose last two dimensions form Hermitian matrices.	required

Returns:

Type	Description
EigH	EigH containing: - eigenvalues, whose dtype is the real dtype associated with the input and whose dims replace the matrix axes with one IndexSpace. - eigenvectors, whose dtype matches the input dtype and whose dims are the leading batch dims followed by (row_dim, spectrum).

Examples:

result = eigh(tensor)
eigenvalues = result.eigenvalues
eigenvectors = result.eigenvectors

Notes

torch.linalg.eigh is differentiable for Hermitian inputs, but the gradients can be ill-defined or unstable when eigenvalues are degenerate or nearly degenerate. If you use this in autograd, consider stabilizing the spectrum (e.g., with a small perturbation) or avoiding backpropagation through eigenvectors when bands are expected to merge.

The original matrix is recovered by forming a diagonal matrix from eigenvalues and evaluating \(V\Lambda V^\dagger\). In code, this is eigenvectors @ W @ eigenvectors.h(-2, -1).

Source code in src/qten/linalg/decompose.py

def eigh(tensor: Tensor) -> EigH:
    r"""
    Perform Hermitian eigendecomposition on the last two tensor dimensions.

    This function applies [`torch.linalg.eigh`](https://pytorch.org/docs/stable/generated/torch.linalg.eigh.html)
    to the matrix axes of a [`Tensor`][qten.linalg.tensors.Tensor]. The final
    two dimensions must span the same Hilbert space up to ray ordering so they
    can be interpreted as a Hermitian operator. Any leading dimensions are
    treated as batch dimensions and are preserved in both outputs.

    Parameters
    ----------
    tensor : Tensor
        Input tensor whose last two dimensions form Hermitian matrices.

    Returns
    -------
    EigH
        [`EigH`][qten.linalg.decompose.EigH] containing:
        - `eigenvalues`, whose dtype is the real dtype associated with the
          input and whose dims replace the matrix axes with one
          [`IndexSpace`][qten.symbolics.state_space.IndexSpace].
        - `eigenvectors`, whose dtype matches the input dtype and whose dims
          are the leading batch dims followed by `(row_dim, spectrum)`.

    Examples
    --------
    ```python
    result = eigh(tensor)
    eigenvalues = result.eigenvalues
    eigenvectors = result.eigenvectors
    ```

    Notes
    -----
    `torch.linalg.eigh` is differentiable for Hermitian inputs, but the gradients
    can be ill-defined or unstable when eigenvalues are degenerate or nearly
    degenerate. If you use this in autograd, consider stabilizing the spectrum
    (e.g., with a small perturbation) or avoiding backpropagation through
    eigenvectors when bands are expected to merge.

    The original matrix is recovered by forming a diagonal matrix from
    `eigenvalues` and evaluating \(V\Lambda V^\dagger\). In code, this is
    `eigenvectors @ W @ eigenvectors.h(-2, -1)`.
    """
    _assert_eig_dims(tensor)

    dim0 = tensor.dims[-2]
    target = tensor.align(-1, dim0)  # Align column space to match the row space
    eigenvalues, eigenvectors = torch.linalg.eigh(target.data)

    spectrum = IndexSpace.linear(eigenvalues.shape[-1])

    eigvals = Tensor(
        data=eigenvalues,
        dims=target.dims[:-2] + (spectrum,),
    )
    eigvecs = Tensor(
        data=eigenvectors,
        dims=target.dims[:-2] + (dim0, spectrum),
    )

    return EigH(eigvals, eigvecs)

eigvalsh

eigvalsh(tensor: Tensor) -> Tensor

Compute Hermitian eigenvalues on the last two tensor dimensions.

This is the eigenvalues-only companion to eigh. The last two dimensions must span the same Hilbert space up to ray ordering and represent a Hermitian operator. Leading dimensions are treated as batch dimensions.

Parameters:

Name	Type	Description	Default
tensor	Tensor	Input tensor whose last two dimensions form Hermitian matrices.	required

Returns:

Type	Description
Tensor	Eigenvalues as a Tensor whose dtype matches the real dtype associated with the input and whose dims keep the leading batch dimensions while replacing the matrix axes with a single IndexSpace.

Examples:

values = eigvalsh(tensor)

Source code in src/qten/linalg/decompose.py

def eigvalsh(tensor: Tensor) -> Tensor:
    """
    Compute Hermitian eigenvalues on the last two tensor dimensions.

    This is the eigenvalues-only companion to
    [`eigh`][qten.linalg.decompose.eigh]. The last two dimensions must span
    the same Hilbert space up to ray ordering and represent a Hermitian
    operator. Leading dimensions are treated as batch dimensions.

    Parameters
    ----------
    tensor : Tensor
        Input tensor whose last two dimensions form Hermitian matrices.

    Returns
    -------
    Tensor
        Eigenvalues as a [`Tensor`][qten.linalg.tensors.Tensor] whose dtype
        matches the real dtype associated with the input and whose dims keep
        the leading batch dimensions while replacing the matrix axes with a
        single [`IndexSpace`][qten.symbolics.state_space.IndexSpace].

    Examples
    --------
    ```python
    values = eigvalsh(tensor)
    ```
    """
    _assert_eig_dims(tensor)

    dim0 = tensor.dims[-2]
    target = tensor.align(-1, dim0)  # Align column space to match the row space
    eigenvalues = torch.linalg.eigvalsh(target.data)

    spectrum = IndexSpace.linear(eigenvalues.shape[-1])

    vals = Tensor(
        data=eigenvalues,
        dims=target.dims[:-2] + (spectrum,),
    )

    return vals

eigvals

eigvals(tensor: Tensor) -> Tensor

Compute eigenvalues of general square matrix axes.

This is the eigenvalues-only companion to eig. The last two dimensions must span the same Hilbert space up to ray ordering and represent a square operator. Leading dimensions are treated as batch dimensions.

Parameters:

Name	Type	Description	Default
tensor	Tensor	Input tensor whose last two dimensions form square matrices.	required

Returns:

Type	Description
Tensor	Eigenvalues as a Tensor whose dtype matches the complex dtype associated with the input and whose dims keep the leading batch dimensions while replacing the matrix axes with a single IndexSpace.

Notes

torch.linalg.eigvals does not guarantee any ordering of the eigenvalues. This function sorts eigenvalues lexicographically by (real, imag).

Examples:

values = eigvals(tensor)

Source code in src/qten/linalg/decompose.py

def eigvals(tensor: Tensor) -> Tensor:
    """
    Compute eigenvalues of general square matrix axes.

    This is the eigenvalues-only companion to
    [`eig`][qten.linalg.decompose.eig]. The last two dimensions must span the
    same Hilbert space up to ray ordering and represent a square operator.
    Leading dimensions are treated as batch dimensions.

    Parameters
    ----------
    tensor : Tensor
        Input tensor whose last two dimensions form square matrices.

    Returns
    -------
    Tensor
        Eigenvalues as a [`Tensor`][qten.linalg.tensors.Tensor] whose dtype
        matches the complex dtype associated with the input and whose dims keep
        the leading batch dimensions while replacing the matrix axes with a
        single [`IndexSpace`][qten.symbolics.state_space.IndexSpace].

    Notes
    -----
    `torch.linalg.eigvals` does not guarantee any ordering of the eigenvalues.
    This function sorts eigenvalues lexicographically by `(real, imag)`.

    Examples
    --------
    ```python
    values = eigvals(tensor)
    ```
    """
    _assert_eig_dims(tensor)

    dim0 = tensor.dims[-2]
    target = tensor.align(-1, dim0)  # Align column space to match the row space
    eigenvalues = torch.linalg.eigvals(target.data)
    eigenvalues, _ = _sort_eigenpairs(eigenvalues)

    spectrum = IndexSpace.linear(eigenvalues.shape[-1])

    vals = Tensor(
        data=eigenvalues,
        dims=target.dims[:-2] + (spectrum,),
    )

    return vals

qr

qr(tensor: Tensor) -> QR

Perform reduced QR decomposition on the last two tensor dimensions.

This function applies torch.linalg.qr with mode="reduced" to the matrix axes of the input tensor. The last two dimensions may be rectangular. Any leading dimensions are treated as batch dimensions and are preserved in both outputs.

Parameters:

Name	Type	Description	Default
tensor	Tensor	Input tensor whose last two dimensions form matrices.	required

Returns:

Type	Description
QR	QR containing: - Q, a Tensor with orthonormal columns and dims (..., row_dim, factor). - R, an upper-triangular Tensor with dims (..., factor, col_dim).

Examples:

result = qr(tensor)
q = result.Q
r = result.R

Notes

The shared factor axis is represented by an IndexSpace whose size equals the reduced QR bond dimension. The original matrix is recovered as \(Q R\), via Q @ R in code.

Source code in src/qten/linalg/decompose.py

def qr(tensor: Tensor) -> QR:
    r"""
    Perform reduced QR decomposition on the last two tensor dimensions.

    This function applies [`torch.linalg.qr`](https://pytorch.org/docs/stable/generated/torch.linalg.qr.html)
    with `mode="reduced"` to the matrix axes of the input tensor. The last two
    dimensions may be rectangular. Any leading dimensions are treated as batch
    dimensions and are preserved in both outputs.

    Parameters
    ----------
    tensor : Tensor
        Input tensor whose last two dimensions form matrices.

    Returns
    -------
    QR
        [`QR`][qten.linalg.decompose.QR] containing:
        - `Q`, a [`Tensor`][qten.linalg.tensors.Tensor] with orthonormal
          columns and dims `(..., row_dim, factor)`.
        - `R`, an upper-triangular
          [`Tensor`][qten.linalg.tensors.Tensor] with dims
          `(..., factor, col_dim)`.

    Examples
    --------
    ```python
    result = qr(tensor)
    q = result.Q
    r = result.R
    ```

    Notes
    -----
    The shared `factor` axis is represented by an
    [`IndexSpace`][qten.symbolics.state_space.IndexSpace] whose size equals the
    reduced QR bond dimension. The original matrix is recovered as \(Q R\), via
    `Q @ R` in code.
    """
    if tensor.rank() < 2:
        raise ValueError(
            "Input tensor must have at least two dimensions for matrix decomposition."
        )

    row_dim = tensor.dims[-2]
    col_dim = tensor.dims[-1]

    q_data, r_data = torch.linalg.qr(tensor.data, mode="reduced")
    spectral_dim = IndexSpace.linear(q_data.shape[-1])

    q = Tensor(
        data=q_data,
        dims=tensor.dims[:-2] + (row_dim, spectral_dim),
    )
    r = Tensor(
        data=r_data,
        dims=tensor.dims[:-2] + (spectral_dim, col_dim),
    )

    return QR(q, r)

svd

svd(
    tensor: Tensor,
    values_as_matrix: bool = False,
    full_matrices: bool = False,
) -> SVD

Perform singular value decomposition on the last two tensor dimensions.

This function applies torch.linalg.svd to the matrix axes of the input tensor and returns symbolic dimensions that distinguish reduced and full factorizations. The last two dimensions may be rectangular. Any leading dimensions are treated as batch dimensions and are preserved in all outputs.

Parameters:

Name	Type	Description	Default
tensor	Tensor	Input tensor whose last two dimensions form matrices.	required
values_as_matrix	bool	If True, return singular values as an explicit diagonal matrix tensor. If False, return them as a vector on a single spectral axis.	`False`
full_matrices	bool	If True, compute full-sized U and Vh. If False, compute the reduced SVD.	`False`

Returns:

Type	Description
SVD	SVD containing: - U, with dims (..., row_dim, factor) for reduced SVD or (..., row_dim, left_factor) for full SVD. - S, with dims (..., factor) by default, (..., factor, factor) when values_as_matrix=True in reduced mode, or (..., left_factor, right_factor) in full matrix form. - Vh, with dims (..., factor, col_dim) for reduced SVD or (..., right_factor, col_dim) for full SVD.

Examples:

result = svd(tensor)
u = result.U
s = result.S
vh = result.Vh

Notes

In reduced mode, factor is the shared singular-value IndexSpace. In full mode, left_factor and right_factor are sized to the full row and column spaces of the input matrix axes. The original matrix is recovered as \(U\Sigma V^\dagger\), using U @ Sigma @ Vh in code. Here Sigma is either the returned S tensor (values_as_matrix=True) or the diagonal matrix formed from the returned singular-value vector.

Source code in src/qten/linalg/decompose.py

def svd(
    tensor: Tensor,
    values_as_matrix: bool = False,
    full_matrices: bool = False,
) -> SVD:
    r"""
    Perform singular value decomposition on the last two tensor dimensions.

    This function applies [`torch.linalg.svd`](https://pytorch.org/docs/stable/generated/torch.linalg.svd.html)
    to the matrix axes of the input tensor and returns symbolic dimensions that
    distinguish reduced and full factorizations. The last two dimensions may be
    rectangular. Any leading dimensions are treated as batch dimensions and are
    preserved in all outputs.

    Parameters
    ----------
    tensor : Tensor
        Input tensor whose last two dimensions form matrices.
    values_as_matrix : bool, default `False`
        If `True`, return singular values as an explicit diagonal matrix
        tensor. If `False`, return them as a vector on a single spectral axis.
    full_matrices : bool, default `False`
        If `True`, compute full-sized `U` and `Vh`. If `False`, compute the
        reduced SVD.

    Returns
    -------
    SVD
        [`SVD`][qten.linalg.decompose.SVD] containing:
        - `U`, with dims `(..., row_dim, factor)` for reduced SVD or
          `(..., row_dim, left_factor)` for full SVD.
        - `S`, with dims `(..., factor)` by default, `(..., factor, factor)`
          when `values_as_matrix=True` in reduced mode, or
          `(..., left_factor, right_factor)` in full matrix form.
        - `Vh`, with dims `(..., factor, col_dim)` for reduced SVD or
          `(..., right_factor, col_dim)` for full SVD.

    Examples
    --------
    ```python
    result = svd(tensor)
    u = result.U
    s = result.S
    vh = result.Vh
    ```

    Notes
    -----
    In reduced mode, `factor` is the shared singular-value
    [`IndexSpace`][qten.symbolics.state_space.IndexSpace]. In full mode,
    `left_factor` and `right_factor` are sized to the full row and column
    spaces of the input matrix axes. The original matrix is recovered as
    \(U\Sigma V^\dagger\), using `U @ Sigma @ Vh` in code. Here `Sigma` is
    either the returned `S` tensor (`values_as_matrix=True`) or the diagonal
    matrix formed from the returned singular-value vector.
    """
    if tensor.rank() < 2:
        raise ValueError(
            "Input tensor must have at least two dimensions for matrix decomposition."
        )

    row_dim = tensor.dims[-2]
    col_dim = tensor.dims[-1]

    u_data, s_data, vh_data = torch.linalg.svd(tensor.data, full_matrices=full_matrices)

    factor = IndexSpace.linear(s_data.shape[-1])

    if full_matrices:
        left_factor = IndexSpace.linear(row_dim.dim)
        right_factor = IndexSpace.linear(col_dim.dim)
        u = Tensor(
            data=u_data,
            dims=tensor.dims[:-2] + (row_dim, left_factor),
        )
    else:
        u = Tensor(
            data=u_data,
            dims=tensor.dims[:-2] + (row_dim, factor),
        )
    if values_as_matrix:
        if full_matrices:
            k = s_data.shape[-1]
            s_mat = torch.zeros(
                *s_data.shape[:-1],
                left_factor.dim,
                right_factor.dim,
                dtype=s_data.dtype,
                device=s_data.device,
            )
            diag = torch.diag_embed(s_data)
            s_mat[..., :k, :k] = diag
            s = Tensor(
                data=s_mat,
                dims=tensor.dims[:-2] + (left_factor, right_factor),
            )
        else:
            s_mat = torch.diag_embed(s_data)
            s = Tensor(
                data=s_mat,
                dims=tensor.dims[:-2] + (factor, factor),
            )
    else:
        s = Tensor(
            data=s_data,
            dims=tensor.dims[:-2] + (factor,),
        )
    if full_matrices:
        vh = Tensor(
            data=vh_data,
            dims=tensor.dims[:-2] + (right_factor, col_dim),
        )
    else:
        vh = Tensor(
            data=vh_data,
            dims=tensor.dims[:-2] + (factor, col_dim),
        )

    return SVD(u, s, vh)

einsum

einsum(equation: str, *operands: Tensor) -> Tensor

Contract tensors with Einstein summation while aligning symbolic dims.

This mirrors torch.einsum at the numeric level, but first reconciles every labeled axis through QTen's StateSpace semantics:

• same labeled axes must be symbolically compatible,
• BroadcastSpace() may expand to a concrete labeled space,
• axes with the same rays but different ordering are permuted into a shared target ordering before contraction.

Equation guide

The equation uses the same label syntax as torch.einsum, with labels restricted to ASCII letters [A-Za-z].

• Each input operand is described by one comma-separated label term.
• Labels that appear in multiple operands identify axes that should be multiplied together.
• Labels omitted from the output are summed out.
• Labels kept in the output determine the order of the output dims.
• ... is supported and follows torch's broadcast convention for unnamed axes. It may appear at the start, middle, or end of a term.
• ...ij means "match the last two labeled axes and let ... absorb the preceding axes"; i...j means "match the first labeled axis, the last labeled axis, and let ... absorb the axes in between".
• If any input term uses ..., QTen normalizes any input term that omits it by prepending a leading ellipsis in the internal torch.einsum equation. This lets mixed equations such as "...ij,ij->...ij" behave like torch-style broadcasted contractions.
• When a term originally omits ..., QTen pads that operand with leading singleton broadcast axes (via unsqueeze(0)) and uses the leading-ellipsis form in the normalized torch.einsum equation. For example, "i...j,ij->i...j" is internally reconciled by treating the ij operand as a leading-ellipsis term rather than inserting singleton axes into the middle of that operand.
• QTen only normalizes input terms. The explicit output term, if present, is preserved as written.
• Repeating a label within one operand follows diagonal semantics. Those axes must already have matching sizes before any cross-operand alignment, and QTen does not expand a singleton BroadcastSpace() axis just to satisfy a repeated subscript within the same operand.

For example:

• "ij,ij->ij" means elementwise multiplication.
• "ij,jk->ik" means matrix multiplication over the shared j axis.
• "abc,dbe->acde" means multiply over the shared b axis and keep the surviving axes in the explicit output order (a, c, d, e).
• "...ij,ij->...ij" means "broadcast the ij operand across the leading unnamed axes of the other operand, then keep those axes in the output".
• "i...j,ij->i...j" means "broadcast the ij operand across the unnamed middle axes between i and j".

Symbolic alignment rules

Before dispatching to torch.einsum, QTen aligns axes label-by-label:

• if two axes with the same label already share the same StateSpace, nothing changes,
• if they have the same rays in a different order, the operand is permuted to the first compatible non-BroadcastSpace() ordering encountered for that label,
• if one side is BroadcastSpace(), it is expanded to the concrete shared space,
• if two same-labeled concrete axes are not symbolically compatible, the call raises ValueError.

When multiple same-ray orderings are possible, swapping operand order can therefore change the output dims ordering for shared labels.

This means einsum compatibility is stricter than raw shape-only tensor math: matching sizes alone are not enough when a label represents a symbolic axis.

Examples:

Elementwise product with broadcast:

left = Tensor(data=torch.randn(2, 1), dims=(row_space, BroadcastSpace()))
right = Tensor(data=torch.randn(1, 3), dims=(BroadcastSpace(), col_space))

out = einsum("ij,ij->ij", left, right)
# out.dims == (row_space, col_space)

Matrix multiplication:

left = Tensor(data=torch.randn(m.dim, k.dim), dims=(m, k))
right = Tensor(data=torch.randn(k.dim, n.dim), dims=(k, n))

out = einsum("ij,jk->ik", left, right)
# out.dims == (m, n)

Mixed leading ellipsis:

batch = IndexSpace.linear(5)
i = IndexSpace.linear(2)
j = IndexSpace.linear(3)

left = Tensor(data=torch.randn(batch.dim, i.dim, j.dim), dims=(batch, i, j))
right = Tensor(data=torch.randn(i.dim, j.dim), dims=(i, j))

out = einsum("...ij,ij->...ij", left, right)
# Equivalent numeric contraction: torch.einsum("...ij,...ij->...ij", ...)
# out.dims == (batch, i, j)

Mixed middle ellipsis:

i = IndexSpace.linear(2)
middle = IndexSpace.linear(4)
j = IndexSpace.linear(3)

left = Tensor(data=torch.randn(i.dim, middle.dim, j.dim), dims=(i, middle, j))
right = Tensor(data=torch.randn(i.dim, j.dim), dims=(i, j))

out = einsum("i...j,ij->i...j", left, right)
# Equivalent numeric contraction: torch.einsum("i...j,i...j->i...j", ...)
# out.dims == (i, middle, j)

Mixed trailing ellipsis:

i = IndexSpace.linear(2)
j = IndexSpace.linear(3)
tail = IndexSpace.linear(4)

left = Tensor(data=torch.randn(i.dim, j.dim, tail.dim), dims=(i, j, tail))
right = Tensor(data=torch.randn(i.dim, j.dim), dims=(i, j))

out = einsum("ij...,ij->ij...", left, right)
# Equivalent numeric contraction: torch.einsum("ij...,ij...->ij...", ...)
# out.dims == (i, j, tail)

Repeated labels within one operand:

tensor = Tensor(
    data=torch.randn(space_ab.dim, space_ba.dim),
    dims=(space_ab, space_ba),
)

out = einsum("ii->i", tensor)
# The second axis is aligned to the first before taking the diagonal.
# out.dims == (space_ab,)

Repeated labels do not use BroadcastSpace expansion:

tensor = Tensor(
    data=torch.randn(1, shared.dim),
    dims=(BroadcastSpace(), shared),
)

# Raises ValueError because repeated-label axes must already match in size.
out = einsum("ii->i", tensor)

Higher-rank contraction over one shared index:

out = einsum("abc,dbe->acde", x, y)

This computes \(out[a, c, d, e] = \sum_b x[a, b, c] \; y[d, b, e]\).

Higher-rank contraction over multiple shared indices:

out = einsum("abcd,bcde->ae", x, y)

This sums over the shared b, c, and d labels and keeps only the surviving a and e axes in the output.

Parameters:

Name	Type	Description	Default
equation	str	Einstein summation equation in the same format accepted by torch.einsum. Label characters must be ASCII letters [A-Za-z].	required
*operands	Tensor	Input tensors whose ranks must match the equation terms after any ... expansion.	()

Returns:

Type	Description
Tensor	Tensor whose data is computed by torch.einsum on the aligned operand data and whose dims follow the einsum output labels.

Raises:

Type	Description
ValueError	If the equation uses unsupported label characters, does not match the operand ranks, or if any shared label maps to incompatible symbolic dimensions.

See Also

matmul Specialized contraction helper for standard matrix multiplication. align Axis-alignment primitive used to reconcile same-labeled symbolic dims.

Source code in src/qten/linalg/tensors.py

def einsum(equation: str, *operands: Tensor) -> Tensor:
    r"""
    Contract tensors with Einstein summation while aligning symbolic dims.

    This mirrors `torch.einsum` at the numeric level, but first reconciles
    every labeled axis through QTen's [`StateSpace`][qten.symbolics.state_space.StateSpace]
    semantics:

    - same labeled axes must be symbolically compatible,
    - [`BroadcastSpace()`][qten.symbolics.state_space.BroadcastSpace] may
      expand to a concrete labeled space,
    - axes with the same rays but different ordering are permuted into a
      shared target ordering before contraction.

    Equation guide
    --------------
    The equation uses the same label syntax as `torch.einsum`, with labels
    restricted to ASCII letters `[A-Za-z]`.

    - Each input operand is described by one comma-separated label term.
    - Labels that appear in multiple operands identify axes that should be
      multiplied together.
    - Labels omitted from the output are summed out.
    - Labels kept in the output determine the order of the output `dims`.
    - `...` is supported and follows torch's broadcast convention for unnamed
      axes. It may appear at the start, middle, or end of a term.
    - `...ij` means "match the last two labeled axes and let `...` absorb the
      preceding axes"; `i...j` means "match the first labeled axis, the last
      labeled axis, and let `...` absorb the axes in between".
    - If any input term uses `...`, QTen normalizes any input term that omits
      it by prepending a leading ellipsis in the internal `torch.einsum`
      equation. This lets mixed equations such as `"...ij,ij->...ij"` behave
      like torch-style broadcasted contractions.
    - When a term originally omits `...`, QTen pads that operand with leading
      singleton broadcast axes (via `unsqueeze(0)`) and uses the leading-ellipsis
      form in the normalized `torch.einsum` equation. For example,
      `"i...j,ij->i...j"` is internally reconciled by treating the `ij` operand
      as a leading-ellipsis term rather than inserting singleton axes into the
      middle of that operand.
    - QTen only normalizes input terms. The explicit output term, if present,
      is preserved as written.
    - Repeating a label within one operand follows diagonal semantics. Those
      axes must already have matching sizes before any cross-operand
      alignment, and QTen does not expand a singleton
      [`BroadcastSpace()`][qten.symbolics.state_space.BroadcastSpace] axis just
      to satisfy a repeated subscript within the same operand.

    For example:

    - `"ij,ij->ij"` means elementwise multiplication.
    - `"ij,jk->ik"` means matrix multiplication over the shared `j` axis.
    - `"abc,dbe->acde"` means multiply over the shared `b` axis and keep the
      surviving axes in the explicit output order `(a, c, d, e)`.
    - `"...ij,ij->...ij"` means "broadcast the `ij` operand across the leading
      unnamed axes of the other operand, then keep those axes in the output".
    - `"i...j,ij->i...j"` means "broadcast the `ij` operand across the unnamed
      middle axes between `i` and `j`".

    Symbolic alignment rules
    ------------------------
    Before dispatching to `torch.einsum`, QTen aligns axes label-by-label:

    - if two axes with the same label already share the same
      [`StateSpace`][qten.symbolics.state_space.StateSpace], nothing changes,
    - if they have the same rays in a different order, the operand is
      permuted to the first compatible non-[`BroadcastSpace()`][qten.symbolics.state_space.BroadcastSpace]
      ordering encountered for that label,
    - if one side is [`BroadcastSpace()`][qten.symbolics.state_space.BroadcastSpace],
      it is expanded to the concrete shared space,
    - if two same-labeled concrete axes are not symbolically compatible, the
      call raises `ValueError`.

    When multiple same-ray orderings are possible, swapping operand order can
    therefore change the output `dims` ordering for shared labels.

    This means einsum compatibility is stricter than raw shape-only tensor
    math: matching sizes alone are not enough when a label represents a
    symbolic axis.

    Examples
    --------
    Elementwise product with broadcast:

    ```python
    left = Tensor(data=torch.randn(2, 1), dims=(row_space, BroadcastSpace()))
    right = Tensor(data=torch.randn(1, 3), dims=(BroadcastSpace(), col_space))

    out = einsum("ij,ij->ij", left, right)
    # out.dims == (row_space, col_space)
    ```

    Matrix multiplication:

    ```python
    left = Tensor(data=torch.randn(m.dim, k.dim), dims=(m, k))
    right = Tensor(data=torch.randn(k.dim, n.dim), dims=(k, n))

    out = einsum("ij,jk->ik", left, right)
    # out.dims == (m, n)
    ```

    Mixed leading ellipsis:

    ```python
    batch = IndexSpace.linear(5)
    i = IndexSpace.linear(2)
    j = IndexSpace.linear(3)

    left = Tensor(data=torch.randn(batch.dim, i.dim, j.dim), dims=(batch, i, j))
    right = Tensor(data=torch.randn(i.dim, j.dim), dims=(i, j))

    out = einsum("...ij,ij->...ij", left, right)
    # Equivalent numeric contraction: torch.einsum("...ij,...ij->...ij", ...)
    # out.dims == (batch, i, j)
    ```

    Mixed middle ellipsis:

    ```python
    i = IndexSpace.linear(2)
    middle = IndexSpace.linear(4)
    j = IndexSpace.linear(3)

    left = Tensor(data=torch.randn(i.dim, middle.dim, j.dim), dims=(i, middle, j))
    right = Tensor(data=torch.randn(i.dim, j.dim), dims=(i, j))

    out = einsum("i...j,ij->i...j", left, right)
    # Equivalent numeric contraction: torch.einsum("i...j,i...j->i...j", ...)
    # out.dims == (i, middle, j)
    ```

    Mixed trailing ellipsis:

    ```python
    i = IndexSpace.linear(2)
    j = IndexSpace.linear(3)
    tail = IndexSpace.linear(4)

    left = Tensor(data=torch.randn(i.dim, j.dim, tail.dim), dims=(i, j, tail))
    right = Tensor(data=torch.randn(i.dim, j.dim), dims=(i, j))

    out = einsum("ij...,ij->ij...", left, right)
    # Equivalent numeric contraction: torch.einsum("ij...,ij...->ij...", ...)
    # out.dims == (i, j, tail)
    ```

    Repeated labels within one operand:

    ```python
    tensor = Tensor(
        data=torch.randn(space_ab.dim, space_ba.dim),
        dims=(space_ab, space_ba),
    )

    out = einsum("ii->i", tensor)
    # The second axis is aligned to the first before taking the diagonal.
    # out.dims == (space_ab,)
    ```

    Repeated labels do not use BroadcastSpace expansion:

    ```python
    tensor = Tensor(
        data=torch.randn(1, shared.dim),
        dims=(BroadcastSpace(), shared),
    )

    # Raises ValueError because repeated-label axes must already match in size.
    out = einsum("ii->i", tensor)
    ```

    Higher-rank contraction over one shared index:

    ```python
    out = einsum("abc,dbe->acde", x, y)
    ```

    This computes
    \(out[a, c, d, e] = \sum_b x[a, b, c] \; y[d, b, e]\).

    Higher-rank contraction over multiple shared indices:

    ```python
    out = einsum("abcd,bcde->ae", x, y)
    ```

    This sums over the shared `b`, `c`, and `d` labels and keeps only the
    surviving `a` and `e` axes in the output.

    Parameters
    ----------
    equation : str
        Einstein summation equation in the same format accepted by
        `torch.einsum`. Label characters must be ASCII letters `[A-Za-z]`.
    *operands : Tensor
        Input tensors whose ranks must match the equation terms after any
        `...` expansion.

    Returns
    -------
    Tensor
        Tensor whose data is computed by `torch.einsum` on the aligned operand
        data and whose `dims` follow the einsum output labels.

    Raises
    ------
    ValueError
        If the equation uses unsupported label characters, does not match the
        operand ranks, or if any shared label maps to incompatible symbolic
        dimensions.

    See Also
    --------
    [`matmul`][qten.linalg.tensors.matmul]
        Specialized contraction helper for standard matrix multiplication.
    [`align`][qten.linalg.tensors.align]
        Axis-alignment primitive used to reconcile same-labeled symbolic dims.
    """
    (
        normalized_equation,
        expanded_terms,
        output_labels,
        normalized_operands,
    ) = _normalize_einsum_operands(equation, operands)

    for term, operand in zip(expanded_terms, normalized_operands):
        _validate_einsum_repeated_labels(term, operand)

    label_dims: Dict[str, StateSpace] = {}
    for term, operand in zip(expanded_terms, normalized_operands):
        for axis, label in enumerate(term):
            label_dims[label] = _merge_einsum_dim(
                label_dims.get(label), operand.dims[axis], label
            )

    aligned_operands: list[Tensor] = []
    for term, operand in zip(expanded_terms, normalized_operands):
        current = operand
        for axis, label in enumerate(term):
            current = current.align(axis, label_dims[label])
        aligned_operands.append(current)

    promoted_operands = _promote_einsum_operands(aligned_operands)
    data = torch.einsum(
        normalized_equation, *(operand.data for operand in promoted_operands)
    )
    dims = tuple(label_dims[label] for label in output_labels)
    return Tensor(data=data, dims=dims)

norm

norm(
    tensor: TensorType,
    ord: int | float | str | None = None,
    dim: int | tuple[int, int] | None = None,
) -> TensorType | Tensor

Compute a vector or matrix norm with metadata-aware dimension reduction.

This forwards to torch.linalg.norm for the numeric computation, then removes the reduced axes from the symbolic output dims.

See Also

torch.linalg.norm Official PyTorch reference for the underlying numeric operation. torch.linalg.vector_norm Clearer vector-only norm API in PyTorch. torch.linalg.matrix_norm Clearer matrix-only norm API in PyTorch.

Behavior

The interpretation of ord depends on dim:

• dim is an int: compute a vector norm along that axis.
• dim is a 2-tuple: compute a matrix norm over those two axes.
• dim is None: follow PyTorch's torch.linalg.norm rules. In particular, ord=None flattens the tensor and computes a vector 2-norm, while ord != None expects PyTorch's documented 1D/2D behavior.

Supported ord values

Vector-norm forms (dim is an int) - None - 0 - any finite int or float - float("inf") - -float("inf")

Matrix-norm forms (dim is a 2-tuple) - None - "fro" - "nuc" - 1, -1 - 2, -2 - float("inf") - -float("inf")

Parameters:

Name	Type	Description	Default
tensor	Tensor	The tensor to reduce.	required
ord	Optional[Union[int, float, str]]	Order of the norm forwarded to torch.linalg.norm. Common examples: - ord=2 for the Euclidean vector norm or spectral matrix norm - ord=1 for an L1 vector norm or induced 1 matrix norm - ord=float("inf") for max-based norms - ord="fro" for the Frobenius matrix norm - ord="nuc" for the nuclear matrix norm	None
dim	Optional[Union[int, Tuple[int, int]]]	Reduction axis or axes. int: vector norm Tuple[int, int]: matrix norm None: use PyTorch's default torch.linalg.norm behavior	None

Returns:

Type	Description
Union[TensorType, Tensor]	Tensor containing the requested norm values with reduced axes removed from dims. For subclasses marked with strict_dims, this may return a plain Tensor.

Raises:

Type	Description
IndexError	If any requested reduction axis is out of range for the tensor rank.
ValueError	If dim contains duplicate axes.

Source code in src/qten/linalg/tensors.py

def norm(
    tensor: TensorType,
    ord: Optional[Union[int, float, str]] = None,
    dim: Optional[Union[int, Tuple[int, int]]] = None,
) -> Union[TensorType, Tensor]:
    """
    Compute a vector or matrix norm with metadata-aware dimension reduction.

    This forwards to `torch.linalg.norm` for the numeric computation, then
    removes the reduced axes from the symbolic output dims.

    See Also
    --------
    [`torch.linalg.norm`](https://docs.pytorch.org/docs/stable/generated/torch.linalg.norm.html)
        Official PyTorch reference for the underlying numeric operation.
    [`torch.linalg.vector_norm`](https://docs.pytorch.org/docs/stable/generated/torch.linalg.vector_norm.html)
        Clearer vector-only norm API in PyTorch.
    [`torch.linalg.matrix_norm`](https://docs.pytorch.org/docs/stable/generated/torch.linalg.matrix_norm.html)
        Clearer matrix-only norm API in PyTorch.

    Behavior
    --------
    The interpretation of `ord` depends on `dim`:

    - `dim` is an `int`: compute a vector norm along that axis.
    - `dim` is a 2-tuple: compute a matrix norm over those two axes.
    - `dim is None`: follow PyTorch's `torch.linalg.norm` rules. In
      particular, `ord=None` flattens the tensor and computes a vector 2-norm,
      while `ord != None` expects PyTorch's documented 1D/2D behavior.

    Supported `ord` values
    ----------------------
    Vector-norm forms (`dim` is an `int`)
    - `None`
    - `0`
    - any finite `int` or `float`
    - `float("inf")`
    - `-float("inf")`

    Matrix-norm forms (`dim` is a 2-tuple)
    - `None`
    - `"fro"`
    - `"nuc"`
    - `1`, `-1`
    - `2`, `-2`
    - `float("inf")`
    - `-float("inf")`

    Parameters
    ----------
    tensor : Tensor
        The tensor to reduce.
    ord : Optional[Union[int, float, str]], optional
        Order of the norm forwarded to `torch.linalg.norm`.

        Common examples:
        - `ord=2` for the Euclidean vector norm or spectral matrix norm
        - `ord=1` for an L1 vector norm or induced 1 matrix norm
        - `ord=float("inf")` for max-based norms
        - `ord="fro"` for the Frobenius matrix norm
        - `ord="nuc"` for the nuclear matrix norm
    dim : Optional[Union[int, Tuple[int, int]]], optional
        Reduction axis or axes.

        - `int`: vector norm
        - `Tuple[int, int]`: matrix norm
        - `None`: use PyTorch's default `torch.linalg.norm` behavior

    Returns
    -------
    Union[TensorType, Tensor]
        Tensor containing the requested norm values with reduced axes removed
        from `dims`. For subclasses marked with
        [`strict_dims`][qten.linalg.tensors.strict_dims], this may return a
        plain [`Tensor`][qten.linalg.tensors.Tensor].

    Raises
    ------
    IndexError
        If any requested reduction axis is out of range for the tensor rank.
    ValueError
        If `dim` contains duplicate axes.
    """
    reduced = torch.linalg.norm(tensor.data, ord=ord, dim=dim)
    if dim is None:
        return cast(
            TensorType,
            _wrap_tensor_result(
                tensor,
                data=reduced,
                dims=(),
                preserve_strict=False,
            ),
        )

    rank_ = tensor.rank()
    dims_tuple: Tuple[int, ...]
    if isinstance(dim, int):
        dims_tuple = (dim,)
    else:
        dims_tuple = dim

    normalized_dims: list[int] = []
    for d in dims_tuple:
        nd = d
        if nd < 0:
            nd += rank_
        if nd < 0 or nd >= rank_:
            raise IndexError(f"Dimension index {d} out of range for rank {rank_}")
        if nd in normalized_dims:
            raise ValueError("norm dim entries must be unique")
        normalized_dims.append(nd)

    reduced_dims_set = set(normalized_dims)
    new_dims = tuple(
        current_dim
        for idx, current_dim in enumerate(tensor.dims)
        if idx not in reduced_dims_set
    )
    return cast(
        TensorType,
        _wrap_tensor_result(
            tensor,
            data=reduced,
            dims=new_dims,
            preserve_strict=False,
        ),
    )