Reference

AbstractITensor

Alias for AbstractNamedTensor{IndexName}: the AbstractNamedTensor supertype with dimension names fixed to IndexName (the names carried by Index).

AbstractNamedTensor{DimName}

Supertype for tensors whose dimensions are labeled by names of type DimName rather than ordered by position. Subtypes such as NamedTensor line their dimensions up by name under contraction, addition, and indexing. Unlike an AbstractArray, the rank and element type live in the data rather than the type, so ndims and eltype are not fixed at the type level.

See also NamedTensor, dimnames, inds.

ITensor

Alias for NamedTensor{IndexName}: a NamedTensor whose dimension names are IndexNames, the names carried by Index. This is the legacy ITensor type. Use NamedTensor for the dimname-flavor-generic type.

Index(space; tags, plev)

An index of an ITensor: a named unit range whose name is an IndexName, a freshly minted, unique identifier carrying tags and a prime level. The argument is a space that is converted to a range: Index(2) makes an index of length 2 over Base.OneTo(2), Index(1:3) makes one over an explicit range, and (with GradedArrays loaded) Index([U1(0) => 2, U1(1) => 3]) makes one over a graded range. Each call mints a new name, so two indices built the same way are still distinct, and tensors share a dimension only when they share the same Index.

tags and plev decorate the freshly minted name, as in Index(2; tags = "i" => "1", plev = 1), and default to no tags and prime level 0. tags accepts the same inputs as settags: a key => value pair, a bare label like "i" (a String or Symbol, taken as a tag with an empty value), a collection mixing these, or an AbstractDict.

Examples

julia> i = Index(2);

julia> length(i)
2

IndexName

The name carried by an Index: a freshly minted unique identifier together with a set of tags and an integer prime level. Two IndexNames compare equal only when their identifier, tags, and prime level all match, so independently constructed indices stay distinct. prime raises the prime level and noprime resets it. IndexName is the dimension-name type behind the legacy ITensor surface, where Index is NamedUnitRange{IndexName} and ITensor is NamedTensor{IndexName}.

NamedTensor(array::AbstractArray, dims)

A tensor whose dimensions are labeled by names instead of ordered by position. It pairs an underlying array with one name per dimension (dims), so contraction, addition, and indexing line dimensions up by name. A NamedTensor is usually built by calling randn, zeros, and the like on indices, or through nameddims, rather than constructed directly. ITensor is the NamedTensor with dimension names that are IndexNames.

Examples

julia> NamedTensor(zeros(2, 3), (:i, :j))
named(Base.OneTo(2), :i)×named(Base.OneTo(3), :j) NamedTensor{Symbol}:
2×3 Matrix{Float64}:
 0.0  0.0  0.0
 0.0  0.0  0.0

NamedUnitRange{Name}

A unit range with a name attached, used as a named dimension (axis) of a tensor. It pairs an underlying integer unit range with a name of type Name. Index is the NamedUnitRange flavor whose name is an IndexName. Build one by calling named on a range, or use Index to mint a fresh unique name.

Examples

julia> named(1:3, :i)
named(1:3, :i)

See also Index, named.

SortedDict{K,V} <: AbstractDict{K,V}

An associative container backed by two parallel Vectors kept sorted by key. Lookup is a linear scan, which is fastest for the small key counts this is used for (index-name tags). Equality and hashing are structural over the sorted vectors, so they are cheap and order-independent by construction.

Base.one(a::AbstractNamedTensor, dimnames_codomain, dimnames_domain) -> Id

Return an identity-operator-shaped named array sharing a's dimension names, codomain/domain partition, and element type. The fused codomain and domain sizes must match. a is treated as a shape prototype and is not mutated.

The identity acts as the multiplicative identity for ITensorBase.apply: it contracts on the domain names and renames the resulting codomain names back to the domain names, leaving the input unchanged.

Note that this is inspired by the tensor map function TensorKit.one in TensorKit.jl.

Examples

julia> using ITensorBase: Index

julia> using LinearAlgebra: tr

julia> i, j, k, l = Index.((2, 3, 2, 3));

julia> a = randn(i, j, k, l);

julia> tr(one(a, (i, j), (k, l)), (i, j), (k, l))
6.0

Base.one(op::NamedTensorOperator) -> Id

Return the identity operator with the same output/input names and shape as op. op is treated as a shape prototype and is not mutated.

The identity acts as the multiplicative identity for ITensorBase.apply: it contracts on the input names and renames the resulting output names back to the input names, leaving the input unchanged.

Examples

julia> using ITensorBase: apply, namedoneto, operator

julia> i, j, k, l = namedoneto.((2, 3, 2, 3), ("i", "j", "k", "l"));

julia> op = operator(randn(i, j, k, l), ("i", "j"), ("k", "l"));

julia> Id = one(op);

julia> v = randn(k, l);

julia> apply(Id, v) ≈ v
true

aligndims(a::AbstractNamedTensor, codomain, domain)

Reorder the dimensions of a into (codomain..., domain...), matched by name, and forward the codomain/domain split to the underlying storage. Like the two-argument form, the result has the same data and dimension names as a, and a NameMismatch is thrown if (codomain..., domain...) is not a permutation of a's dimension names. A storage backend that supports a bipartition (such as a TensorKit TensorMap) uses it, while a dense backend stores the result flat.

aligndims(a::AbstractNamedTensor, dims)

Reorder the dimensions of a into the order given by dims, matched by name. Returns a tensor with the same data and dimension names as a but with the dimensions permuted, and throws a NameMismatch if dims is not a permutation of a's dimension names.

Examples

julia> a = nameddims(zeros(2, 3), (:i, :j));

julia> aligndims(a, (:j, :i))
named(Base.OneTo(3), :j)×named(Base.OneTo(2), :i) NamedTensor{Symbol}:
3×2 Matrix{Float64}:
 0.0  0.0
 0.0  0.0
 0.0  0.0

aligneddims(a::AbstractNamedTensor, dims)

Like aligndims, but returns a lazily-permuted view that shares data with a instead of copying. Reorders the dimensions of a into the order given by dims, matched by name, and throws a NameMismatch if dims is not a permutation of a's dimension names.

Examples

julia> a = nameddims(reshape(1:6, 2, 3), (:i, :j));

julia> dimnames(aligneddims(a, (:j, :i)))
2-element Vector{Symbol}:
 :j
 :i

See also aligndims.

apply(x::AbstractNamedTensor, y::AbstractNamedTensor)

Apply the operator x to y, contracting each input of x with the matching output (or dangling leg) of y and renaming each consumed output of x back to its paired input, so the result sits on x's input space. Uncontracted structure passes through: y's remaining input wires stay wires, and a part of x disjoint from y is tensored in. Applying an operator to a bare state gives a bare state, so applying the identity operator leaves y unchanged; applying it to another operator gives an operator.

Examples

julia> op = operator(reshape(Float64[1, 0, 0, 1], 2, 2), ("i",), ("j",));

julia> v = nameddims([3.0, 4.0], ("j",));

julia> apply(op, v) == v
true

See also operator, state, outputnames, inputnames.

commonind(a::AbstractNamedTensor, b::AbstractNamedTensor)

The single index shared by name between a and b. Errors unless there is exactly one shared index. Use trycommonind to get nothing instead of an error.

Examples

julia> i, j, k = Index.((2, 3, 2));

julia> a, b = randn(i, j), randn(j, k);

julia> commonind(a, b) == j
true

See also commoninds, uniqueind.

commoninds(a::AbstractNamedTensor, b::AbstractNamedTensor)

The indices shared by name between a and b, as a Vector in the order they appear in a.

Examples

julia> i, j, k = Index.((2, 3, 2));

julia> a, b = randn(i, j), randn(j, k);

julia> commoninds(a, b) == [j]
true

See also commonind, uniqueinds, hascommoninds.

decoration(i)

Return the decoration of an index or index name as a NamedTuple (; tags, plev). Splatting it into uniquename or the Index keyword constructor reproduces that decoration on a freshly minted, unique name, as in uniquename(IndexName; decoration(i)...). A name that carries no decoration returns an empty NamedTuple.

dimnames(a::AbstractNamedTensor)
dimnames(a::AbstractNamedTensor, dim::Int)

The dimension names of a, as a collection in dimension order. The second form returns the name of dimension dim.

Examples

julia> a = nameddims(zeros(2, 3), (:i, :j));

julia> dimnames(a)
2-element Vector{Symbol}:
 :i
 :j

julia> dimnames(a, 2)
:j

See also inds, nameddims.

dimnametype(a::AbstractNamedTensor)
dimnametype(type::Type{<:AbstractNamedTensor})

The type of an individual dimension name of a. The primary method dispatches on the array type, and dimnametype(a) forwards to dimnametype(typeof(a)). A type that does not fix its dimname flavor (such as the unparameterized NamedTensor) returns Any, the same way eltype(Array) is Any.

Examples

julia> a = nameddims(zeros(2, 3), (:i, :j));

julia> dimnametype(a)
Symbol

julia> dimnametype(typeof(a))
Symbol

emptytags(i)

Return a new index or index name with all tags removed.

gettag(i, key)
gettag(i, key, default)

Return the tag value stored under key as a String. The two-argument form throws if key is absent; the three-argument form returns default instead. See also gettags.

gettags(i, keys)

Return the sub-dictionary of the index's tags whose keys are in keys, skipping any that are absent (so the result never has more keys than requested and never throws). The dictionary and string types are implementation details. See also gettag, tags.

hascommoninds(a::AbstractNamedTensor, b::AbstractNamedTensor)

Whether a and b share any index by name.

Examples

julia> i, j, k = Index.((2, 3, 2));

julia> a, b = randn(i, j), randn(j, k);

julia> hascommoninds(a, b)
true

See also commoninds.

hastag(i, key)

Return true if the index or index name carries a tag under key.

id(elt::Type, codomain, domain) -> Id

Construct a from-scratch identity-operator-shaped named tensor over the codomain and domain indices, with element type elt. The fused codomain and domain sizes must match. Unlike one, which follows a prototype tensor, id needs only the indices and an element type, so it is the right primitive when no prototype is in hand. The index axes select the backend: dense ranges give a dense tensor, graded ranges a block-sparse one.

Note that this is inspired by the tensor map function TensorKit.id in TensorKit.jl.

Examples

julia> using ITensorBase: Index, id

julia> using LinearAlgebra: tr

julia> i, j, k, l = Index.((2, 3, 2, 3));

julia> tr(id(Float64, (i, j), (k, l)), (i, j), (k, l))
6.0

See also one.

inds(a::AbstractNamedTensor)
inds(a::AbstractNamedTensor, dim::Int)

The named axes (indices) of a, as a Vector with one entry per dimension. Each entry pairs a dimension's axis with its name. The second form returns the index of dimension dim. Compare with dimnames, which returns just the names without the axes. The axes function returns the same indices as a Tuple, which the AbstractArray interface relies on; inds returns a Vector because the indices are most often manipulated as a collection (filter, setdiff, union).

Examples

julia> a = nameddims(zeros(2, 3), (:i, :j));

julia> inds(a)
2-element Vector{NamedUnitRange{Symbol, Int64, Base.OneTo{Int64}}}:
 named(Base.OneTo(2), :i)
 named(Base.OneTo(3), :j)

julia> inds(a, 1)
named(Base.OneTo(2), :i)

inputnames(a)

The input dimension names of an operator a. These are the names contracted over when the operator is applied to a tensor. A plain tensor is a trivial operator with no pairing, so its input names are empty.

Examples

julia> op = operator(zeros(2, 2), ("i",), ("j",));

julia> inputnames(op)
1-element Vector{String}:
 "j"

See also outputnames, operator, apply.

mapinds(f, a::AbstractNamedTensor)

Return a tensor with the same data as a, with each index i relabeled using f(i). This is the function form of replaceinds, taking a function input instead of old => new pairs.

Examples

julia> i, j = Index.((2, 3));

julia> t = randn(i, j);

julia> inds(mapinds(prime, t)) == [prime(i), prime(j)]
true

See also replaceinds.

name(a)

The name attached to a named object a, such as a Named scalar, a named array, or a named unit range. This is the inverse of the name component of named: name recovers the name, unnamed recovers the value.

Examples

julia> using ITensorBase: name

julia> name(named(2, :i))
:i

See also named, unnamed, setname.

named(value, name)

Attach name to value, pairing them into a single named object. On a scalar this produces a Named. Arrays and unit ranges have their own more specific methods.

Examples

julia> named(2, :i)
named(2, :i)

nameddims(a, dimnames)

Construct a named dimensions array from an unnamed parent a and named dimensions dimnames. The parent is usually an AbstractArray, but any object that a NamedTensor can wrap works (e.g. a TensorKit TensorMap).

Examples

julia> nameddims(zeros(2, 3), (:i, :j))
named(Base.OneTo(2), :i)×named(Base.OneTo(3), :j) NamedTensor{Symbol}:
2×3 Matrix{Float64}:
 0.0  0.0  0.0
 0.0  0.0  0.0

See also NamedTensor, named.

nametype(type::Type)

The type of the name carried by a named type, such as a Named scalar type, a named array type, or a named unit range type.

Examples

julia> using ITensorBase: nametype

julia> nametype(typeof(named(2, :i)))
Symbol

See also name, unnamedtype.

noncommonind(a::AbstractNamedTensor, b::AbstractNamedTensor)

The single index not shared by name between a and b (the symmetric difference). Errors unless there is exactly one such index. Use trynoncommonind to get nothing instead of an error.

Examples

julia> i, j, k = Index.((2, 3, 2));

julia> a, b = randn(i, j), randn(i, j, k);

julia> noncommonind(a, b) == k
true

See also noncommoninds, uniqueind.

noncommoninds(a::AbstractNamedTensor, b::AbstractNamedTensor)

The indices not shared by name between a and b (the symmetric difference), as a Vector: the indices unique to a followed by those unique to b.

Examples

julia> i, j, k = Index.((2, 3, 2));

julia> a, b = randn(i, j), randn(j, k);

julia> noncommoninds(a, b) == [i, k]
true

See also uniqueinds, commoninds.

noprime(i)
noprime(t::AbstractNamedTensor)

Reset the prime level of an index or index name to zero, returning a new index. This undoes any number of prime calls. Given a tensor, reset the prime level of all of its indices.

Examples

julia> i = Index(2);

julia> noprime(prime(i)) == i
true

See also prime, Index.

operator(a, output, input)

Build a named operator from a tensor (or plain array) a by partitioning its dimension names into an output set and an input set. The operator pairs each output name with an input name, so it can be applied to a tensor with apply, contracting over the input. output and input may be given as dimension names or as named ranges such as Indexes. Recover the underlying tensor with state and the name sets with outputnames and inputnames.

Examples

julia> op = operator(zeros(2, 2), ("i",), ("j",));

julia> outputnames(op)
1-element Vector{String}:
 "i"

julia> inputnames(op)
1-element Vector{String}:
 "j"

See also state, outputnames, inputnames, apply, similar_operator.

outputnames(a)

The output dimension names of an operator a. An operator pairs each of its output names with an input name. Applying the operator contracts over the input and leaves the output. A plain tensor is a trivial operator with no pairing, so its output names are empty.

Examples

julia> op = operator(zeros(2, 2), ("i",), ("j",));

julia> outputnames(op)
1-element Vector{String}:
 "i"

See also inputnames, operator, apply.

plev(i)

Return the prime level of an index or index name: a non-negative integer raised by prime and reset by noprime.

prime(i)
prime(t::AbstractNamedTensor)

Increment the prime level of an index or index name by one, returning a new index that is distinct from i. Priming is the usual way to make a second copy of an index that carries the same tags but is not contracted against the original. The inverse is noprime, which resets the prime level to zero. Given a tensor, prime all of its indices.

Examples

julia> i = Index(2);

julia> prime(i) == i
false

julia> noprime(prime(i)) == i
true

See also noprime, Index.

replacedimnames(a::AbstractNamedTensor, replacements::Pair...)
replacedimnames(f, a::AbstractNamedTensor)

Return a tensor with the same data as a but with its dimension names replaced. The first form takes old => new pairs, replacing matching names and leaving the rest unchanged. The second form replaces each name with f(name).

Examples

julia> using ITensorBase: replacedimnames

julia> a = nameddims(zeros(2, 3), (:i, :j));

julia> dimnames(replacedimnames(a, :i => :k))
2-element Vector{Symbol}:
 :k
 :j

See also dimnames.

replaceinds(a::AbstractNamedTensor, replacements::Pair...)
replaceinds(f, a::AbstractNamedTensor)

Return a tensor with the same data as a, with its indices relabeled to the ones specified. The pair form takes old => new index pairs, and the function form relabels each index i using f(i).

Examples

julia> i, j, k = Index.((2, 3, 2));

julia> t = randn(i, j);

julia> inds(replaceinds(t, i => k)) == [k, j]
true

See also mapinds, replacedimnames.

setname(a, name)

Return a copy of the named object a with its name replaced by name, keeping the underlying value unchanged.

Examples

julia> using ITensorBase: setname

julia> setname(named(2, :i), :j)
named(2, :j)

See also named, name.

settags(i, key => value, ...)
settags(i, pairs)

Return a new index or index name with the given tags inserted or overwritten. This is a merge: tags under other keys are kept, and a key that already exists is overwritten. Tags are given as one or more key => value pairs, bare labels (a String or Symbol, taken as a tag with an empty value), a collection mixing these, or an AbstractDict; keys and values may be Strings or Symbols. See also unsettags, emptytags.

sim(i)
sim(t::AbstractNamedTensor)

Return a "similar" index: a new index (or, given a tensor, a tensor with all of its indices replaced) carrying the same tags and prime level as i but a fresh unique identifier, so it is distinct from i and will not contract against it. This is the index-manipulation spelling of uniquename on an index.

Examples

julia> i = Index(2);

julia> sim(i) == i
false

julia> length(sim(i))
2

See also uniquename, prime.

similar_operator(prototype, [T,] unnamed_input_axes, [outputnames,] inputnames) -> op
similar_operator(prototype, [T,] named_input_axes) -> op

Allocate an operator-shaped named array with undefined data, with the user-supplied side as the input and a matching output. Element type defaults to eltype(prototype). Output names default to fresh uniquename-generated names. The first form takes unnamed (raw) axes and explicit names, the second takes already-named axes and reuses their names as the input. Storage layout (including the bra/ket flip on the input side for graded axes) is delegated to TensorAlgebra.similar_map.

Examples

julia> op = similar_operator(zeros(2, 2), (Base.OneTo(2),), (:i,), (:j,));

julia> inputnames(op)
1-element Vector{Symbol}:
 :j

See also operator, uniquename.

space(i::NamedUnitRange)

The space of a named range i: its underlying (unnamed) range or axis object, with the name dropped. Equal to unnamed for a NamedUnitRange.

state(a)

The underlying tensor of a named operator, with its output/input structure forgotten. An operator carries a tensor together with a pairing of its output and input dimension names (its Choi, or state, representation). state returns that tensor on its own. For a plain tensor that is not an operator, state returns it unchanged.

Examples

julia> a = nameddims(zeros(2), (:i,));

julia> state(a) == a
true

See also operator, outputnames, inputnames.

tags(i)

Return the tags of an index or index name as an AbstractDict mapping tag names to tag values, both AbstractStrings.

The concrete dictionary type and string type are implementation details and may change.

trycommonind(a::AbstractNamedTensor, b::AbstractNamedTensor)

The single index shared by name between a and b, or nothing if they share no index or more than one. The non-erroring counterpart of commonind.

Examples

julia> i, j, k = Index.((2, 3, 2));

julia> a, b = randn(i, j), randn(j, k);

julia> trycommonind(a, b) == j
true

julia> isnothing(trycommonind(a, randn(k)))
true

trynoncommonind(a::AbstractNamedTensor, b::AbstractNamedTensor)

The single index not shared by name between a and b (the symmetric difference), or nothing if there is no such index or more than one. The non-erroring counterpart of noncommonind.

Examples

julia> i, j, k = Index.((2, 3, 2));

julia> a, b = randn(i, j), randn(i, j, k);

julia> trynoncommonind(a, b) == k
true

julia> isnothing(trynoncommonind(randn(i, j), randn(j, k)))
true

tryuniqueind(a::AbstractNamedTensor, b::AbstractNamedTensor)

The single index of a that does not appear by name in b, or nothing if there is no such index or more than one. The non-erroring counterpart of uniqueind.

Examples

julia> i, j, k = Index.((2, 3, 2));

julia> a, b = randn(i, j), randn(j, k);

julia> tryuniqueind(a, b) == i
true

unioninds(a::AbstractNamedTensor, b::AbstractNamedTensor)

The union by name of the indices of a and b, as a Vector: the indices of a followed by the indices of b not already present in a.

Examples

julia> i, j, k = Index.((2, 3, 2));

julia> a, b = randn(i, j), randn(j, k);

julia> unioninds(a, b) == [i, j, k]
true

See also commoninds, noncommoninds.

uniqueind(a::AbstractNamedTensor, b::AbstractNamedTensor)

The single index of a that does not appear by name in b. Errors unless there is exactly one such index. Use tryuniqueind to get nothing instead of an error.

Examples

julia> i, j, k = Index.((2, 3, 2));

julia> a, b = randn(i, j), randn(j, k);

julia> uniqueind(a, b) == i
true

See also uniqueinds, commonind.

uniqueinds(a::AbstractNamedTensor, b::AbstractNamedTensor)

The indices of a that do not appear by name in b, as a Vector in the order they appear in a.

Examples

julia> i, j, k = Index.((2, 3, 2));

julia> a, b = randn(i, j), randn(j, k);

julia> uniqueinds(a, b) == [i]
true

See also uniqueind, commoninds, noncommoninds.

uniquename([rng,] name)
uniquename([rng,] type::Type)

Mint a fresh, unique name. Given an existing name, produce a new name of the same flavor that is distinct from any other, for example to label a freshly generated dimension in a matrix factorization. Decoration carried by the seed is kept: uniquename on an IndexName keeps its tags and prime level, minting only a fresh id. Pass the name type instead of an instance to mint a bare name (for IndexName, no tags and prime level zero), for a fresh dimension that should not inherit any seed's decoration. Randomness defaults to OS entropy (Random.RandomDevice) so that minting a name neither perturbs nor is perturbed by the numerical RNG. Pass an explicit rng for a reproducible name.

Examples

julia> i = Index(2);

julia> uniquename(i) != i
true

unnamed(a)

The underlying value of a named object a, with its name stripped off. This is the inverse of the value component of named: name recovers the name, unnamed recovers the value. On an AbstractNamedTensor it returns the underlying unnamed array.

Examples

julia> using ITensorBase: unnamed

julia> unnamed(named(2, :i))
2

See also named, name.

unnamedtype(type::Type)

The type of the underlying (unnamed) value carried by a named type.

Examples

julia> using ITensorBase: unnamedtype

julia> unnamedtype(typeof(named(2, :i)))
Int64

See also unnamed, nametype.

unsettags(i, keys)

Return a new index or index name with the tags under each of keys removed. Keys that are not present are ignored, so this never throws. See also settags, emptytags.

LinearAlgebra.tr(a::AbstractNamedTensor, codomain, domain) -> scalar

Trace of a viewed as a map, pairing each codomain index with the domain index in the same position (matching sizes) and summing the diagonal. codomain and domain together must cover all of a's indices, so the result is a scalar. Forwards to TensorAlgebra.tr on the unnamed data, which matricizes a into its square matrix and takes the matrix trace, so it follows a's backend (dense, graded, or TensorMap).

Examples

julia> using ITensorBase: Index

julia> using LinearAlgebra: tr

julia> i, j, k, l = Index.((2, 3, 2, 3));

julia> tr(fill(2.0, (i, j, k, l)), (i, j), (k, l))
12.0

LinearAlgebra.tr(op::NamedTensorOperator) -> scalar

Trace of a named operator: contracts each output index with its paired input index and sums the diagonal, over the operator's intrinsic output/input split.

MatrixAlgebraKit.project_hermitian(a::AbstractNamedTensor, dimnames_codomain, dimnames_domain; kwargs...) -> h

Hermitian part (m + m') / 2 of a named array a, interpreting it as a linear map m from the domain to the codomain dimension names. The result carries the same dimension names as a.

TensorAlgebra.MatrixAlgebra.gram_eigh_full(a::AbstractNamedTensor, dimnames_codomain, dimnames_domain; kwargs...) -> x

Gram factorization of a Hermitian positive semi-definite named array a, returning x such that a ≈ x * x_cod, where x_cod is conj(x) with its domain dimension names replaced by the corresponding codomain names. x carries the domain dimension names of a (matching the convention that the stored factor labels a vector in a's input space) and a fresh trailing rank name.

kwargs are forwarded to TensorAlgebra.gram_eigh_full on the underlying unnamed array (e.g. atol, rtol).

Examples

julia> using ITensorBase: dimnames, namedoneto, replacedimnames

julia> using TensorAlgebra.MatrixAlgebra: gram_eigh_full

julia> i, j, k, l, aux = namedoneto.((2, 2, 2, 2, 8), ("i", "j", "k", "l", "aux"));

julia> b = randn(aux, i, k);

julia> a = conj(b) * replacedimnames(b, "i" => "j", "k" => "l");

julia> x = gram_eigh_full(a, (i, k), (j, l));

julia> replacedimnames(x, "j" => "i", "l" => "k") * conj(x) ≈ a
true

TensorAlgebra.MatrixAlgebra.gram_eigh_full(a::NamedTensorOperator; kwargs...) -> x

Gram factorization of a Hermitian positive semi-definite named operator a, returning x such that x * x_cod ≈ state(a), where x_cod is conj(x) with its input dimension names replaced by the corresponding output names of a. x carries a's input dimension names and a fresh trailing rank name. The output and input partition is taken from outputnames(a) and inputnames(a).

kwargs are forwarded to TensorAlgebra.MatrixAlgebra.gram_eigh_full on the underlying named array (e.g. atol, rtol).

Examples

julia> using ITensorBase: namedoneto, operator, replacedimnames, state

julia> using TensorAlgebra.MatrixAlgebra: gram_eigh_full

julia> i, j, k, l, aux = namedoneto.((2, 2, 2, 2, 8), ("i", "j", "k", "l", "aux"));

julia> b = randn(aux, i, k);

julia> a = operator(conj(b) * replacedimnames(b, "i" => "j", "k" => "l"), ("i", "k"), ("j", "l"));

julia> x = gram_eigh_full(a);

julia> replacedimnames(x, "j" => "i", "l" => "k") * conj(x) ≈ state(a)
true

TensorAlgebra.MatrixAlgebra.gram_eigh_full_with_pinv(a::AbstractNamedTensor, dimnames_codomain, dimnames_domain; kwargs...) -> x, y

Like TensorAlgebra.MatrixAlgebra.gram_eigh_full, but additionally returns a named array y that is a left inverse of x: y * x ≈ I on the rank subspace (equal to the identity when a is full rank). x has the rank-name last, y has it first, both sharing the domain dimension names of a.

Examples

julia> using LinearAlgebra: I

julia> using ITensorBase: unname, dimnames, namedoneto, replacedimnames

julia> using TensorAlgebra.MatrixAlgebra: gram_eigh_full_with_pinv

julia> i, j, k, l, aux = namedoneto.((2, 2, 2, 2, 8), ("i", "j", "k", "l", "aux"));

julia> b = randn(aux, i, k);

julia> a = conj(b) * replacedimnames(b, "i" => "j", "k" => "l");

julia> x, y = gram_eigh_full_with_pinv(a, (i, k), (j, l));

julia> replacedimnames(x, "j" => "i", "l" => "k") * conj(x) ≈ a
true

julia> rname = only(setdiff(dimnames(x), ("j", "l")));

julia> reshape(unname(y, (rname, "j", "l")), :, 4) *
       reshape(unname(x, ("j", "l", rname)), 4, :) ≈ I
true

TensorAlgebra.MatrixAlgebra.gram_eigh_full_with_pinv(a::NamedTensorOperator; kwargs...) -> x, y

Like TensorAlgebra.MatrixAlgebra.gram_eigh_full, but additionally returns a named array y that is a left inverse of x: y * x ≈ I on the rank subspace (equal to the identity when a is full rank). The output and input partition is taken from outputnames(a) and inputnames(a).

Examples

julia> using LinearAlgebra: I

julia> using ITensorBase: unname, dimnames, namedoneto, operator, replacedimnames

julia> using TensorAlgebra.MatrixAlgebra: gram_eigh_full_with_pinv

julia> i, j, k, l, aux = namedoneto.((2, 2, 2, 2, 8), ("i", "j", "k", "l", "aux"));

julia> b = randn(aux, i, k);

julia> a = operator(conj(b) * replacedimnames(b, "i" => "j", "k" => "l"), ("i", "k"), ("j", "l"));

julia> x, y = gram_eigh_full_with_pinv(a);

julia> rname = only(setdiff(dimnames(x), ("j", "l")));

julia> reshape(unname(y, (rname, "j", "l")), :, 4) *
       reshape(unname(x, ("j", "l", rname)), 4, :) ≈ I
true

TensorAlgebra.MatrixAlgebra.invsqrth_safe(a::AbstractNamedTensor, dimnames_codomain, dimnames_domain; kwargs...) -> p

Pseudo-inverse square root of a named array a, interpreting it as a Hermitian positive semi-definite linear map from the domain to the codomain dimension names. The result carries the same dimension names as a. Eigenvalues below tolerance are clamped to zero (Moore-Penrose convention). The input must be Hermitian: project with MatrixAlgebraKit.project_hermitian first if it is Hermitian only up to numerical noise.

kwargs are forwarded to TensorAlgebra.invsqrth_safe on the underlying unnamed array (e.g. atol, rtol).

See also TensorAlgebra.MatrixAlgebra.sqrth_safe and TensorAlgebra.MatrixAlgebra.sqrth_invsqrth_safe.

TensorAlgebra.MatrixAlgebra.sqrth_invsqrth_safe(a::AbstractNamedTensor, dimnames_codomain, dimnames_domain; kwargs...) -> p, pinv

Square root and pseudo-inverse square root of a named array a (see TensorAlgebra.MatrixAlgebra.sqrth_safe and TensorAlgebra.MatrixAlgebra.invsqrth_safe), from a single eigendecomposition. Both results carry the same dimension names as a.

kwargs are forwarded to TensorAlgebra.sqrth_invsqrth_safe on the underlying unnamed array (e.g. atol, rtol).

TensorAlgebra.MatrixAlgebra.sqrth_safe(a::AbstractNamedTensor, dimnames_codomain, dimnames_domain; kwargs...) -> p

Square root of a named array a, interpreting it as a Hermitian positive semi-definite linear map from the domain to the codomain dimension names. The result carries the same dimension names as a. Eigenvalues below tolerance are clamped to zero. The input must be Hermitian: project with MatrixAlgebraKit.project_hermitian first if it is Hermitian only up to numerical noise.

kwargs are forwarded to TensorAlgebra.sqrth_safe on the underlying unnamed array (e.g. atol, rtol).

See also TensorAlgebra.MatrixAlgebra.invsqrth_safe and TensorAlgebra.MatrixAlgebra.sqrth_invsqrth_safe.

directsum(A => inds_A, B => inds_B, ...)
directsum(out_inds, A => inds_A, B => inds_B, ...)

Direct sum of the named tensors A, B, … over the indices paired with each. The remaining ("shared") indices are common to every tensor; they are aligned and carried through unchanged, while the paired indices are concatenated block-diagonally. The result has the shared indices first and the summed indices trailing.

The first form mints fresh summed indices and returns S => out_inds, mirroring the tensor => indices inputs. The second form takes the summed indices' names from out_inds (names or NamedUnitRanges) and returns just S; the summed axes themselves come from the direct sum, so only the names of out_inds are used.

Examples

julia> using ITensorBase: Index

julia> using TensorAlgebra: directsum

julia> i, j, k = Index.((2, 2, 3));

julia> a = randn(i, j);

julia> b = randn(i, k);

julia> s, (l,) = directsum(a => (j,), b => (k,));

julia> length(l)
5

TensorAlgebra.matricize(a::AbstractNamedTensor, codomain => rowname, domain => colname)
TensorAlgebra.matricize(a::AbstractNamedTensor, codomain, domain)

Reshape the named tensor a into a matrix, fusing the codomain dimension group into the rows and the domain group into the columns. codomain and domain are each any iterable of dimensions (or dimension names) of a, and together they must cover all of a's dimensions. The pair form labels the two fused dimensions with the given rowname and colname; the positional form generates fresh unique names for them.

Examples

julia> using ITensorBase: Index

julia> using TensorAlgebra: matricize

julia> i, j, k, l = Index.((2, 3, 2, 3));

julia> a = randn(i, j, k, l);

julia> size(matricize(a, (i, k), (j, l)))
(4, 9)

julia> Array(matricize(a, (i, k), (j, l))) ==
       Array(matricize(a, (i, k) => "rows", (j, l) => "cols"))
true

TensorAlgebra.project(a::AbstractArray, codomain_inds, domain_inds; kwargs...) -> t
TensorAlgebra.project(a::AbstractArray, inds; kwargs...) -> t

Build a named tensor from the dense array a by projecting it into the symmetry-restricted space described by the indices, verifying that only a negligible component of a is discarded and throwing an InexactError otherwise (keyword arguments are forwarded to the isapprox tolerance check). The three-argument form takes an explicit codomain/domain split (an operator); the two-argument form takes a flat list of indices (a state, i.e. an empty domain). The index axes select the backend: dense ranges give an Array, graded ranges a block-sparse array, and TensorKit spaces a TensorMap. a is indexed positionally in the order (codomain_inds..., domain_inds...).

TensorAlgebra.tryproject returns nothing instead of throwing, and TensorAlgebra.unchecked_project skips the verification.

@names x y ...
@names x[1:3] y[1:3, 2:4] ...

Short-hand notation for constructing "named symbols", i.e. objects that can be used as names. @names x y z is equivalent to Name.((:x, :y, :z)), returning one name per symbol.

Examples

julia> using ITensorBase: @names

julia> x, y, z = @names x y z;