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, names, 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, names)

A tensor whose dimensions are labeled by names instead of ordered by position. It pairs an underlying array with one name per dimension (names), 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 by indexing an array by name, rather than constructed directly. ITensor is the NamedTensor with dimension names that are IndexNames.

A dimension is given either as a plain name or as an index (a NamedUnitRange such as an Index). An index also asserts a space, which has to match the array's corresponding axis, duality included, and an ArgumentError is thrown if it does not. A plain name asserts nothing, so the array's axis stands.

See also the NamedTensor(unnamed, codomain_inds, domain_inds) method for the map-shaped form.

Examples

julia> NamedTensor(zeros(2, 3), (:i, :j))
NamedOneTo(2, :i)×NamedOneTo(3, :j) NamedTensor{Symbol}:
2×3 Matrix{Float64}:
 0.0  0.0  0.0
 0.0  0.0  0.0

NamedTensor(unnamed, codomain_inds, domain_inds)

A tensor whose dimensions are split into a codomain group and a domain group, as a map from the domain to the codomain. The storage holds the codomain dimensions first and the domain dimensions last. codomain_inds and domain_inds hold indices or plain names, and the domain indices are given codomain-facing: the storage holds the domain axes dualized, following TensorAlgebra.similar_map and TensorAlgebra.unmatricize, so an index in domain_inds asserts the undualized space.

When the array carries a bipartition of its own, the claimed one has to agree with it. Dense storage carries none, so any bipartition may be claimed over it.

Examples

julia> i, j = NamedUnitRange(1:2, :i), NamedUnitRange(1:3, :j);

julia> NamedTensor(zeros(2, 3), (i,), (j,))
NamedOneTo(2, :i)×NamedOneTo(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 from a range and a name, or use Index to mint a fresh unique name.

Examples

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

See also Index.

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, names_codomain, names_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: NamedOneTo, apply, 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

align(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.

align(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 = NamedTensor(zeros(2, 3), (:i, :j));

julia> align(a, (:j, :i))
NamedOneTo(3, :j)×NamedOneTo(2, :i) NamedTensor{Symbol}:
3×2 Matrix{Float64}:
 0.0  0.0
 0.0  0.0
 0.0  0.0

aligned(a::AbstractNamedTensor, dims)

Like align, 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 = NamedTensor(reshape(1:6, 2, 3), (:i, :j));

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

See also align.

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 = NamedTensor([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.

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 names, 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 = NamedTensor(zeros(2, 3), (:i, :j));

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

julia> inds(a, 1)
NamedOneTo(2, :i)

inputaxes(a)

The input (domain) indices of an operator a as a Tuple, the tuple form of inputinds (mirroring how axes relates to inds). Like inputinds it is the non-dual domain space, so a * randn(inputaxes(a)) contracts.

See also inputinds, outputaxes, operator.

inputinds(a)

The input (domain) indices of an operator a — the space of states it acts on — in the same order as inputnames. This is the domain in the sense of TensorKit's domain: the non-dual space a state occupies, so a * randn(Tuple(inputinds(a))) contracts. It is the conjugate of the operator's input legs as they appear fused in inds, which carry the dual. Compare with inputnames, which returns just the names. A plain tensor is a trivial operator with no pairing, so its input indices are empty.

Examples

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

julia> inputinds(op)
1-element Vector{NamedUnitRange{String, Int64, Base.OneTo{Int64}}}:
 NamedOneTo(2, "j")

See also inputnames, outputinds, inputaxes, operator.

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.

mulopadd!(a_dest, op1, a1, op2, a2, α, β; kwargs...)

Compute a_dest = α * op1(a1) * op2(a2) + β * a_dest, matching dimensions by name. op1 and op2 can be identity or conj, and keyword arguments (such as algorithm selection) are passed to TensorAlgebra.contractopadd!.

name(a)

The name attached to a named object a, such as a Named scalar, a named array, or a named unit range. name recovers the name, unnamed recovers the value.

Examples

julia> using ITensorBase: Named, name

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

See also unnamed, setname.

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

The dimension names of a, as a collection in dimension order. The second form returns the name of dimension dim. Base.names is an equivalent spelling that forwards here, so either can be called; a new tensor type overloads ITensorBase.names.

Examples

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

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

julia> names(a, 2)
:j

See also inds, NamedTensor.

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

The type of the name carried by a named object. For a Named scalar type, a named array type, or a named unit range type this is the type of its single name; for a named tensor it is the type of an individual dimension name. The primary methods dispatch on the type, and nametype(a::AbstractNamedTensor) forwards to nametype(typeof(a)). A named tensor type that does not fix its dimension-name flavor (such as the unparameterized NamedTensor) returns Any, the same way eltype(Array) is Any.

Examples

julia> using ITensorBase: Named

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

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

julia> nametype(a)
Symbol

julia> nametype(typeof(a))
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.

outputaxes(a)

The output (codomain) indices of an operator a as a Tuple, the tuple form of outputinds (mirroring how axes relates to inds). The Tuple feeds directly into constructors that take a (codomain, domain) pair of index tuples, such as id: id(eltype(a), outputaxes(a), inputaxes(a)) rebuilds an operator of a's shape.

See also outputinds, inputaxes, operator.

outputinds(a)

The output (codomain) indices of an operator a — the space it maps onto — in the same order as outputnames. Together with inputinds these are the codomain and domain of a viewed as a map, so id(eltype(a), outputinds(a), inputinds(a)) rebuilds an operator of the same shape. Compare with outputnames, which returns just the names. A plain tensor is a trivial operator with no pairing, so its output indices are empty.

Examples

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

julia> outputinds(op)
1-element Vector{NamedUnitRange{String, Int64, Base.OneTo{Int64}}}:
 NamedOneTo(2, "i")

See also outputnames, inputinds, outputaxes, 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.

rename(a::AbstractNamedTensor, replacements::Pair...)
rename(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> a = NamedTensor(zeros(2, 3), (:i, :j));

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

See also names.

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: Named, setname

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

See also 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 = NamedTensor(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. name recovers the name, unnamed recovers the value. On an AbstractNamedTensor it returns the underlying unnamed array.

Examples

julia> using ITensorBase: Named, unnamed

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

See also name.

unnamedtype(type::Type)

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

Examples

julia> using ITensorBase: Named, 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, names_codomain, names_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.invsqrth_safe(a::AbstractNamedTensor, names_codomain, names_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, names_codomain, names_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, names_codomain, names_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, domain)

Reshape the named tensor a into an unnamed 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.

Examples

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)

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

Build a named tensor by projecting the dense array a 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), and the two-argument form 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...).

project projects into exactly the given indices. To append a derived flux-carrying leg for a charge-shifting operator or non-invariant state, use TensorAlgebra.project_aux.

See also TensorAlgebra.tryproject and TensorAlgebra.unchecked_project.

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

Build a named tensor by projecting a and appending a derived auxiliary domain index carrying its flux, 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), and the two-argument form 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...).

a may carry the physical rank the indices account for, or one trailing slice axis. project_aux derives an auxiliary domain index to make the result symmetry-allowed (for example a flux-canceling charge leg for a charge-shifting operator) and returns it as a named dimension with a freshly generated name the caller can read off the result.

See also TensorAlgebra.tryproject_aux and TensorAlgebra.unchecked_project_aux.

TensorAlgebra.tryproject(a::AbstractArray, codomain_inds, domain_inds; kwargs...) -> Union{t, Nothing}
TensorAlgebra.tryproject(a::AbstractArray, inds; kwargs...) -> Union{t, Nothing}

Like TensorAlgebra.project, but return nothing instead of throwing when a non-negligible component of a would be discarded (keyword arguments are forwarded to the isapprox tolerance check).

The three-argument form takes an explicit codomain/domain split (an operator), and the two-argument form 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...).

See also TensorAlgebra.project, TensorAlgebra.unchecked_project, and TensorAlgebra.tryproject_aux.

TensorAlgebra.tryproject_aux(a::AbstractArray, codomain_inds, domain_inds; kwargs...) -> Union{t, Nothing}
TensorAlgebra.tryproject_aux(a::AbstractArray, inds; kwargs...) -> Union{t, Nothing}

Like TensorAlgebra.project_aux, but return nothing instead of throwing when a non-negligible component of a would be discarded (keyword arguments are forwarded to the isapprox tolerance check).

The three-argument form takes an explicit codomain/domain split (an operator), and the two-argument form 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...).

a may carry the physical rank the indices account for, or one trailing slice axis. project_aux derives an auxiliary domain index to make the result symmetry-allowed (for example a flux-canceling charge leg for a charge-shifting operator) and returns it as a named dimension with a freshly generated name the caller can read off the result.

See also TensorAlgebra.project_aux and TensorAlgebra.unchecked_project_aux.

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

Like TensorAlgebra.project, but skip the verification: components of a outside the symmetry-allowed structure are dropped without inspection.

The three-argument form takes an explicit codomain/domain split (an operator), and the two-argument form 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...).

See also TensorAlgebra.project, TensorAlgebra.tryproject, and TensorAlgebra.unchecked_project_aux.

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

Like TensorAlgebra.project_aux, but skip the verification: components of a outside the symmetry-allowed structure are dropped without inspection.

The three-argument form takes an explicit codomain/domain split (an operator), and the two-argument form 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...).

a may carry the physical rank the indices account for, or one trailing slice axis. project_aux derives an auxiliary domain index to make the result symmetry-allowed (for example a flux-canceling charge leg for a charge-shifting operator) and returns it as a named dimension with a freshly generated name the caller can read off the result.

See also TensorAlgebra.project_aux and TensorAlgebra.tryproject_aux.

@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;