Reference

LinearBroadcasted

Abstract supertype for lazy linear broadcast expressions. Analogous to Base.Broadcast.Broadcasted but restricted to linear operations.

Materializes via the protocol: copy(lb) = copyto!(similar(lb), lb) copyto!(dest, lb) → add!(dest, lb, 1, 0)

add!(dest, src, α, β)

dest = β * dest + α * src.

add!(dest, src)

dest .+= src.

bipartition(t::Tuple, length1::Val) -> (t1, t2)
bipartition(t::Tuple, group1::Tuple, group2::Tuple) -> (p1, p2)

Split a flat tuple into two groups, returned as a pair of tuples.

The first form splits t in order, taking the first length1 entries as t1 and the remaining entries as t2. The second form gathers the entries of t at the two index groups group1 and group2, returning p1 = t[group1...] and p2 = t[group2...].

biperm(t, t1, t2) -> (p1, p2)

Locate the groups t1 and t2 within t, returning the positions of t1 as p1 and the positions of t2 as p2. The groups t1 and t2 must partition t, so the concatenation (p1..., p2...) is a permutation of eachindex(t) and the pair (p1, p2) is a bipartitioned permutation (a "biperm") splitting t into a codomain p1 and a domain p2.

bipermutedimsopadd!(dest, op, src, perm_codomain, perm_domain, α, β)

dest = β * dest + α * permutedims(op.(src), (perm_codomain..., perm_domain...)).

This is the primary overload point for downstream array types that want to implement op-aware bipartitioned permutation + accumulation (e.g., fuse conj into the copy, or use lazy wrappers like StridedView with op metadata).

The op is an element-wise linear map (e.g., identity, conj).

The default implementation flattens the bipartitioned permutation, applies op element-wise, permutes, then accumulates via broadcasting with Strided.jl optimization when possible.

checked_project_map(raw, codomain_axes, domain_axes; kwargs...) -> dest

Allocate a map-shaped array via similar_map and project raw into it with checked_projectto!. Keyword arguments are forwarded to checked_projectto!.

checked_projectto!(dest, src; kwargs...) -> dest

Project src into the restricted space of dest via projectto! and verify via isapprox(src, dest; kwargs...) that the discarded component is within tolerance. Keyword arguments are forwarded to isapprox. The default tolerances are subject to change in future versions.

eig_full(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> D, V
eig_full(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> D, V
eig_full(A::AbstractArray, ndims_codomain::Val; kwargs...) -> D, V

Compute the eigenvalue decomposition of a generic N-dimensional array interpreted as a general (non-Hermitian) linear map from the domain to the codomain dimensions. The output eltype is always <:Complex. The partition is specified either via labels or directly through a bi-permutation.

See also MatrixAlgebraKit.eig_full!.

eig_trunc(A::AbstractArray, labels_A, labels_codomain, labels_domain; trunc, kwargs...) -> D, V
eig_trunc(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; trunc, kwargs...) -> D, V
eig_trunc(A::AbstractArray, ndims_codomain::Val; trunc, kwargs...) -> D, V

Truncated general eigenvalue decomposition, like eig_full but keeping only the eigenvalues selected by the trunc strategy.

See also MatrixAlgebraKit.eig_trunc!.

eig_vals(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> D
eig_vals(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> D
eig_vals(A::AbstractArray, ndims_codomain::Val; kwargs...) -> D

Compute the eigenvalues of a generic N-dimensional array interpreted as a general (non-Hermitian) linear map from the domain to the codomain dimensions. The output is a vector of eigenvalues with <:Complex eltype.

See also MatrixAlgebraKit.eig_vals!.

eigh_full(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> D, V
eigh_full(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> D, V
eigh_full(A::AbstractArray, ndims_codomain::Val; kwargs...) -> D, V

Compute the eigenvalue decomposition of a generic N-dimensional array interpreted as a Hermitian linear map from the domain to the codomain dimensions. The partition is specified either via labels or directly through a bi-permutation.

See also MatrixAlgebraKit.eigh_full!.

eigh_trunc(A::AbstractArray, labels_A, labels_codomain, labels_domain; trunc, kwargs...) -> D, V
eigh_trunc(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; trunc, kwargs...) -> D, V
eigh_trunc(A::AbstractArray, ndims_codomain::Val; trunc, kwargs...) -> D, V

Truncated Hermitian eigenvalue decomposition, like eigh_full but keeping only the eigenvalues selected by the trunc strategy.

See also MatrixAlgebraKit.eigh_trunc!.

eigh_vals(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> D
eigh_vals(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> D
eigh_vals(A::AbstractArray, ndims_codomain::Val; kwargs...) -> D

Compute the eigenvalues of a generic N-dimensional array interpreted as a Hermitian linear map from the domain to the codomain dimensions. The output is a vector of eigenvalues.

See also MatrixAlgebraKit.eigh_vals!.

gram_eigh_full(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> X
gram_eigh_full(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> X
gram_eigh_full(A::AbstractArray, ndims_codomain::Val; kwargs...) -> X

Gram factorization of a generic N-dimensional array, interpreting it as a Hermitian positive semi-definite linear map from the domain to the codomain dimensions. Returns X such that A ≈ X * X' (contracted on the rank leg), i.e. the codomain axes of X match the codomain axes of A and X has a single trailing rank axis.

Keyword arguments

• alg: forwarded to MatrixAlgebraKit.eigh_full.

• atol::Real: absolute clamping threshold. Default 0.

• rtol::Real: relative clamping threshold. Default eps(real(eltype(A)))^(3//4) when atol = 0, else 0.

Examples

julia> using TensorAlgebra: contract, gram_eigh_full

julia> B = randn(3, 2, 2);

julia> A = contract((:a, :b, :c, :d), conj(B), (:r, :a, :b), B, (:r, :c, :d));

julia> X = gram_eigh_full(A, (:a, :b, :c, :d), (:a, :b), (:c, :d));

julia> A ≈ contract((:a, :b, :c, :d), X, (:a, :b, :r), conj(X), (:c, :d, :r))
true

See also gram_eigh_full_with_pinv and MatrixAlgebra.gram_eigh_full.

gram_eigh_full_with_pinv(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> X, Y
gram_eigh_full_with_pinv(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> X, Y
gram_eigh_full_with_pinv(A::AbstractArray, ndims_codomain::Val; kwargs...) -> X, Y

Like gram_eigh_full, but additionally returns Y ≈ pinv(X) such that Y * X ≈ I on the rank subspace (a left inverse). The codomain axes of X match the codomain axes of A; Y has a leading rank axis followed by the codomain axes.

Keyword arguments

• alg: forwarded to MatrixAlgebraKit.eigh_full.

• atol::Real: absolute clamping threshold. Default 0.

• rtol::Real: relative clamping threshold. Default eps(real(eltype(A)))^(3//4) when atol = 0, else 0.

Examples

julia> using LinearAlgebra: I

julia> using TensorAlgebra: contract, gram_eigh_full_with_pinv

julia> B = randn(8, 2, 2);

julia> A = contract((:a, :b, :c, :d), conj(B), (:r, :a, :b), B, (:r, :c, :d));

julia> X, Y = gram_eigh_full_with_pinv(A, (:a, :b, :c, :d), (:a, :b), (:c, :d));

julia> A ≈ contract((:a, :b, :c, :d), X, (:a, :b, :r), conj(X), (:c, :d, :r))
true

julia> contract((:r, :s), Y, (:r, :a, :b), X, (:a, :b, :s)) ≈ I
true

See also MatrixAlgebra.gram_eigh_full_with_pinv.

islinearbroadcast(f, args...) -> Bool

Per-node trait: can (f, args...) be expressed as a LinearBroadcasted? Extensible by downstream packages for additional linear operations.

left_null(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> N
left_null(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> N
left_null(A::AbstractArray, ndims_codomain::Val; kwargs...) -> N

Compute the left nullspace of a generic N-dimensional array, by interpreting it as a linear map from the domain to the codomain dimensions. These can be specified either via their labels or directly through a bi-permutation. The output satisfies N' * A ≈ 0 and N' * N ≈ I.

Keyword arguments

• atol::Real=0: absolute tolerance for the nullspace computation.
• rtol::Real=0: relative tolerance for the nullspace computation.
• kind::Symbol: specify the kind of decomposition used to compute the nullspace. The options are :qr, :qrpos and :svd. The former two require 0 == atol == rtol. The default is :qrpos if atol == rtol == 0, and :svd otherwise.

left_orth(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> V, C
left_orth(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> V, C
left_orth(A::AbstractArray, ndims_codomain::Val; kwargs...) -> V, C

Compute the left orthogonal decomposition of a generic N-dimensional array, by interpreting it as a linear map from the domain to the codomain dimensions. These can be specified either via their labels or directly through a bi-permutation.

Keyword arguments

• Keyword arguments are passed on directly to MatrixAlgebraKit.

See also MatrixAlgebraKit.left_orth!.

left_polar(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> W, P
left_polar(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> W, P
left_polar(A::AbstractArray, ndims_codomain::Val; kwargs...) -> W, P

Compute the left polar decomposition of a generic N-dimensional array, by interpreting it as a linear map from the domain to the codomain dimensions. These can be specified either via their labels or directly through a bi-permutation.

Keyword arguments

• Keyword arguments are passed on directly to MatrixAlgebraKit.

See also MatrixAlgebraKit.left_polar!.

linearbroadcasted(f, args...)

Construct a LinearBroadcasted subtype from function f and arguments. Analogous to Base.Broadcast.broadcasted(f, args...).

Examples

linearbroadcasted(*, 2.0, a)   # ScaledBroadcasted(2.0, a)
linearbroadcasted(conj, a)     # ConjBroadcasted(a)
linearbroadcasted(+, a, b)     # AddBroadcasted(a, b)

lq_compact(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> L, Q
lq_compact(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> L, Q
lq_compact(A::AbstractArray, ndims_codomain::Val; kwargs...) -> L, Q

Compute the compact LQ decomposition of a generic N-dimensional array, by interpreting it as a linear map from the domain to the codomain dimensions, where L is square. The partition is specified either via labels or directly through a bi-permutation.

Keyword arguments

• positive::Bool=false: specify if the diagonal of L should be positive, leading to a unique decomposition.
• Other keywords are passed on directly to MatrixAlgebraKit.

See also MatrixAlgebraKit.lq_compact!.

lq_full(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> L, Q
lq_full(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> L, Q
lq_full(A::AbstractArray, ndims_codomain::Val; kwargs...) -> L, Q

Compute the full LQ decomposition of a generic N-dimensional array, by interpreting it as a linear map from the domain to the codomain dimensions, where Q is unitary. The partition is specified either via labels or directly through a bi-permutation.

Keyword arguments

• positive::Bool=false: specify if the diagonal of L should be positive, leading to a unique decomposition.
• Other keywords are passed on directly to MatrixAlgebraKit.

See also MatrixAlgebraKit.lq_full!.

matricizeop(op, a, perm_codomain, perm_domain)

Matricize a with element-wise operation op folded in. Returns a matrix representing op.(matricize(a, perm_codomain, perm_domain)).

Has "maybe alias" semantics: the result may be a view/wrapper aliasing a or a fresh copy, depending on the fusion style and array type. The caller should treat the result as read-only.

TensorAlgebra.one(A::AbstractArray, labels_A, labels_codomain, labels_domain) -> Id
TensorAlgebra.one(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}) -> Id
TensorAlgebra.one(A::AbstractArray, ndims_codomain::Val) -> Id

Construct the identity operator tensor whose shape mirrors A, interpreted as a linear map from the domain to the codomain dimensions. The codomain and domain partition is specified either via labels or directly through a bi-permutation; fused codomain and domain sizes must match. A is treated as a shape prototype and is not mutated.

Not exported, since exporting would clash with the implicit Base.one. Qualify as TensorAlgebra.one(A, ...).

See also MatrixAlgebraKit.one!.

Examples

julia> using LinearAlgebra: I

julia> using TensorAlgebra: TensorAlgebra, matricize

julia> A = randn(2, 3, 2, 3);

julia> Id = TensorAlgebra.one(A, (:a, :b, :c, :d), (:a, :b), (:c, :d));

julia> matricize(Id, Val(2)) ≈ I
true

permuteddims(a::AbstractArray, perm)

Lazy permutedims, defaulting to a Base.PermutedDimsArray view. This is an extension hook: downstream array types can overload it to return a custom lazy permuted-dims type.

permutedimsadd!(dest, src, perm, α, β)

dest = β * dest + α * permutedims(src, perm).

permutedimsop(op, src, perm_codomain, perm_domain)

Non-mutating version of bipermutedimsopadd!: returns op.(permutedims(src, (perm_codomain..., perm_domain...))).

permutedimsopadd!(dest, op, src, perm, α, β)

dest = β * dest + α * permutedims(op.(src), perm).

This is the single materialization primitive for LinearBroadcasted types. Downstream array types should implement bipermutedimsopadd! for the bipartitioned permutation version; this flat-permutation overload forwards to it with perm_domain = ().

project_map(raw, codomain_axes, domain_axes) -> dest

Allocate a map-shaped array via similar_map and project raw into it with projectto!. See checked_project_map for a checked version.

projectto!(dest, src) -> dest

Project src into the restricted space of dest without checking which components may have been projected out. Defaults to copyto!. See checked_projectto! for a checked version.

qr_compact(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> Q, R
qr_compact(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> Q, R
qr_compact(A::AbstractArray, ndims_codomain::Val; kwargs...) -> Q, R

Compute the compact QR decomposition of a generic N-dimensional array, by interpreting it as a linear map from the domain to the codomain dimensions, where R is square. The partition is specified either via labels or directly through a bi-permutation.

Keyword arguments

• positive::Bool=false: specify if the diagonal of R should be positive, leading to a unique decomposition.
• Other keywords are passed on directly to MatrixAlgebraKit.

See also MatrixAlgebraKit.qr_compact!.

qr_full(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> Q, R
qr_full(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> Q, R
qr_full(A::AbstractArray, ndims_codomain::Val; kwargs...) -> Q, R

Compute the full QR decomposition of a generic N-dimensional array, by interpreting it as a linear map from the domain to the codomain dimensions, where Q is unitary. The partition is specified either via labels or directly through a bi-permutation.

Keyword arguments

• positive::Bool=false: specify if the diagonal of R should be positive, leading to a unique decomposition.
• Other keywords are passed on directly to MatrixAlgebraKit.

See also MatrixAlgebraKit.qr_full!.

right_null(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> Nᴴ
right_null(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> Nᴴ
right_null(A::AbstractArray, ndims_codomain::Val::Val; kwargs...) -> Nᴴ

Compute the right nullspace of a generic N-dimensional array, by interpreting it as a linear map from the domain to the codomain dimensions. These can be specified either via their labels or directly through a bi-permutation. The output satisfies A * Nᴴ' ≈ 0 and Nᴴ * Nᴴ' ≈ I.

Keyword arguments

• atol::Real=0: absolute tolerance for the nullspace computation.
• rtol::Real=0: relative tolerance for the nullspace computation.
• kind::Symbol: specify the kind of decomposition used to compute the nullspace. The options are :lq, :lqpos and :svd. The former two require 0 == atol == rtol. The default is :lqpos if atol == rtol == 0, and :svd otherwise.

right_orth(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> C, V
right_orth(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> C, V
right_orth(A::AbstractArray, ndims_codomain::Val; kwargs...) -> C, V

Compute the right orthogonal decomposition of a generic N-dimensional array, by interpreting it as a linear map from the domain to the codomain dimensions. These can be specified either via their labels or directly through a bi-permutation.

Keyword arguments

• Keyword arguments are passed on directly to MatrixAlgebraKit.

See also MatrixAlgebraKit.right_orth!.

right_polar(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> P, W
right_polar(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> P, W
right_polar(A::AbstractArray, ndims_codomain::Val; kwargs...) -> P, W

Compute the right polar decomposition of a generic N-dimensional array, by interpreting it as a linear map from the domain to the codomain dimensions. These can be specified either via their labels or directly through a bi-permutation.

Keyword arguments

• Keyword arguments are passed on directly to MatrixAlgebraKit.

See also MatrixAlgebraKit.right_polar!.

scale!(a::AbstractArray, β::Number) -> a

In-place scaling: multiply every entry of a by β.

similar_map(prototype, [T,] codomain_axes, domain_axes) -> M

Allocate an array shaped as a linear map from domain_axes to codomain_axes with element type T (defaulting to eltype(prototype)), using prototype to determine the array backend. Defaults to similar(prototype, T, (codomain_axes..., conj.(domain_axes)...)).

Examples

julia> using TensorAlgebra: similar_map

julia> cod, dom = (Base.OneTo(2), Base.OneTo(3)), (Base.OneTo(4), Base.OneTo(5));

julia> M = similar_map(randn(3), Float32, cod, dom);

julia> eltype(M), size(M)
(Float32, (2, 3, 4, 5))

svd_compact(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> U, S, Vᴴ
svd_compact(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> U, S, Vᴴ
svd_compact(A::AbstractArray, ndims_codomain::Val; kwargs...) -> U, S, Vᴴ

Compute the compact (thin) SVD of a generic N-dimensional array, by interpreting it as a linear map from the domain to the codomain dimensions, where U and Vᴴ are isometric. The partition is specified either via labels or directly through a bi-permutation.

See also MatrixAlgebraKit.svd_compact!.

svd_full(A::AbstractArray, labels_A, labels_codomain, labels_domain; kwargs...) -> U, S, Vᴴ
svd_full(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; kwargs...) -> U, S, Vᴴ
svd_full(A::AbstractArray, ndims_codomain::Val; kwargs...) -> U, S, Vᴴ

Compute the full (thick) SVD of a generic N-dimensional array, by interpreting it as a linear map from the domain to the codomain dimensions, where U and Vᴴ are unitary. The partition is specified either via labels or directly through a bi-permutation.

See also MatrixAlgebraKit.svd_full!.

svd_trunc(A::AbstractArray, labels_A, labels_codomain, labels_domain; trunc, kwargs...) -> U, S, Vᴴ
svd_trunc(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}; trunc, kwargs...) -> U, S, Vᴴ
svd_trunc(A::AbstractArray, ndims_codomain::Val; trunc, kwargs...) -> U, S, Vᴴ

Compute the truncated SVD of a generic N-dimensional array, by interpreting it as a linear map from the domain to the codomain dimensions. The partition is specified either via labels or directly through a bi-permutation.

Keyword arguments

• trunc: truncation strategy, passed on to MatrixAlgebraKit.svd_trunc.
• Other keywords are passed on directly to MatrixAlgebraKit.

See also MatrixAlgebraKit.svd_trunc!.

svd_vals(A::AbstractArray, labels_A, labels_codomain, labels_domain) -> S
svd_vals(A::AbstractArray, perm_codomain::Tuple{Vararg{Int}}, perm_domain::Tuple{Vararg{Int}}) -> S
svd_vals(A::AbstractArray, ndims_codomain::Val) -> S

Compute the singular values of a generic N-dimensional array, by interpreting it as a linear map from the domain to the codomain dimensions. The partition is specified either via labels or directly through a bi-permutation. The output is a vector of singular values.

See also MatrixAlgebraKit.svd_vals!.

TensorAlgebra.trivialrange(R::Type{<:AbstractUnitRange})
TensorAlgebra.trivialrange(r::AbstractUnitRange)

Return the identity range for tensor_product_axis on ranges of type R, i.e. a one-dimensional range t for which fusing t with any other range of the same family leaves that range unchanged. Defaults to Base.OneTo(1); downstream packages overload the type-level method to return their own identity (for example, a charge-0 one-dimensional sector for a graded range).

tryflattenlinear(bc::Broadcasted) -> LinearBroadcasted or nothing

Recursively convert a Broadcasted tree to a LinearBroadcasted tree. Returns nothing if any node is not linear (as determined by islinearbroadcast).

Analogous to Broadcast.flatten for Broadcasted trees, but converts to LinearBroadcasted subtypes via linearbroadcasted.

Downstream styles call this from Base.copy(::Broadcasted{MyStyle}) to opt into linear broadcasting at materialization time.

zero!(a::AbstractArray) -> a

In-place zero: set every entry of a to zero.

gram_eigh_full(A::AbstractMatrix; alg=nothing, atol=0, rtol=eps(real(eltype(A)))^(3//4)) -> X

Gram factorization of a Hermitian positive semi-definite matrix via its eigendecomposition (balanced eigh): returns X = V * sqrth_safe(D; atol, rtol) such that A ≈ X * X', where A = V * D * V'. The square-root of D is absorbed symmetrically into the two factors of the eigendecomposition. Eigenvalues below tol (see pow_diag_safe) are clamped to zero.

Keyword arguments

• alg: forwarded to MatrixAlgebraKit.eigh_full.

• atol::Real: absolute clamping threshold. Default 0.

• rtol::Real: relative clamping threshold. Default eps(real(eltype(A)))^(3//4) when atol = 0, else 0.

Examples

julia> using TensorAlgebra.MatrixAlgebra: gram_eigh_full

julia> B = [1.0 0.5; 0.5 2.0];

julia> A = B' * B;

julia> X = gram_eigh_full(A);

julia> X * X' ≈ A
true

See also gram_eigh_full_with_pinv.

gram_eigh_full_with_pinv(A::AbstractMatrix; alg=nothing, atol=0, rtol=eps(real(eltype(A)))^(3//4)) -> X, Y

Like gram_eigh_full, but additionally returns Y = invsqrth_safe(D; atol, rtol) * V' ≈ pinv(X), a left inverse of X on the rank subspace: Y * X ≈ I. Eigenvalues below tol are clamped to zero in both factors.

Keyword arguments

• alg: forwarded to MatrixAlgebraKit.eigh_full.

• atol::Real: absolute clamping threshold. Default 0.

• rtol::Real: relative clamping threshold. Default eps(real(eltype(A)))^(3//4) when atol = 0, else 0.

Examples

julia> using LinearAlgebra: I

julia> using TensorAlgebra.MatrixAlgebra: gram_eigh_full_with_pinv

julia> B = [1.0 0.5; 0.5 2.0];

julia> A = B' * B;

julia> X, Y = gram_eigh_full_with_pinv(A);

julia> X * X' ≈ A
true

julia> Y * X ≈ I
true

invsqrt_diag_safe(D::AbstractMatrix; atol=0, rtol=eps(real(eltype(D)))^(3//4)) -> D^(-1//2)

Inverse square root of a diagonal-structured matrix D, treating diagonal entries below tolerance as zero (Moore-Penrose convention). Equivalent to pow_diag_safe(D, -1//2; atol, rtol).

Keyword arguments

• atol::Real: absolute clamping threshold. Default 0.
• rtol::Real: relative clamping threshold. Default eps(real(eltype(D)))^(3//4) when atol = 0, else 0.

invsqrth_safe(M::AbstractMatrix; alg=nothing, atol=0, rtol=eps(real(eltype(M)))^(3//4)) -> M^(-1//2)

Inverse square root of an approximately Hermitian positive semi-definite matrix. Equivalent to powh_safe(M, -1//2; alg, atol, rtol).

Keyword arguments

• alg: forwarded to MatrixAlgebraKit.eigh_full.

• atol::Real: absolute clamping threshold. Default 0.

• rtol::Real: relative clamping threshold. Default eps(real(eltype(M)))^(3//4) when atol = 0, else 0.

pow_diag_safe(D::AbstractMatrix, p; atol=0, rtol=eps(real(eltype(D)))^(3//4)) -> D^p

Raise a diagonal-structured matrix D to the power p. Diagonal entries d of MAK.diagview(D) with abs(d) < tol are clamped to zero before exponentiation, where tol = max(atol, rtol * maximum(abs, diagview(D))). Negative d above tol cause d^p to error for fractional p (e.g. p = 1//2) and pass through for integer p, so the operation itself enforces the PSD precondition per-power. Errors if isdiag(D) is false.

The implementation extracts entries via MAK.diagview and rebuilds via MAK.diagonal, so types extending those (e.g. graded or block diagonal) automatically extend sqrt_diag_safe, invsqrt_diag_safe, and the powh_safe family.

Keyword arguments

• atol::Real: absolute clamping threshold. Default 0.
• rtol::Real: relative clamping threshold. Default eps(real(eltype(D)))^(3//4) when atol = 0, else 0.

powh_safe(M::AbstractMatrix, p; alg=nothing, atol=0, rtol=eps(real(eltype(M)))^(3//4)) -> M^p

Raise an approximately Hermitian positive semi-definite matrix to the power p. For diagonal-structured M (isdiag(M) == true), dispatches to pow_diag_safe and skips the eigendecomposition. Otherwise, computes via M = V * D * V' as V * pow_diag_safe(D, p; atol, rtol) * V'.

Keyword arguments

• alg: forwarded to MatrixAlgebraKit.eigh_full.

• atol::Real: absolute clamping threshold. Default 0.

• rtol::Real: relative clamping threshold. Default eps(real(eltype(M)))^(3//4) when atol = 0, else 0.

sqrt_diag_safe(D::AbstractMatrix; atol=0, rtol=eps(real(eltype(D)))^(3//4)) -> D^(1//2)

Square root of a diagonal-structured matrix D, equivalent to pow_diag_safe(D, 1//2; atol, rtol).

Keyword arguments

• atol::Real: absolute clamping threshold. Default 0.
• rtol::Real: relative clamping threshold. Default eps(real(eltype(D)))^(3//4) when atol = 0, else 0.

sqrth_safe(M::AbstractMatrix; alg=nothing, atol=0, rtol=eps(real(eltype(M)))^(3//4)) -> M^(1//2)

Square root of an approximately Hermitian positive semi-definite matrix. Equivalent to powh_safe(M, 1//2; alg, atol, rtol).

Keyword arguments

• alg: forwarded to MatrixAlgebraKit.eigh_full.

• atol::Real: absolute clamping threshold. Default 0.

• rtol::Real: relative clamping threshold. Default eps(real(eltype(M)))^(3//4) when atol = 0, else 0.

truncdegen(trunc::TruncationStrategy; atol::Real=0, rtol::Real=0)

Modify a truncation strategy so that if the truncation falls within a degenerate subspace, the entire subspace gets truncated as well. A value val is considered degenerate if norm(val - truncval) ≤ max(atol, rtol * norm(truncval)) where truncval is the largest value truncated by the original truncation strategy trunc.

For now, this truncation strategy assumes the spectrum being truncated has already been reverse sorted and the strategy being wrapped outputs a contiguous subset of values including the largest one. It also only truncates for now, so may not respect if a minimum dimension was requested in the strategy being wrapped. These restrictions may be lifted in the future or provided through a different truncation strategy.