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)

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.

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.

Examples

julia> using ITensorBase: apply, namedoneto, operator

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

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

julia> Id = operator(one(a, (i, j), (k, l)), ("i", "j"), ("k", "l"));

julia> v = randn(k, l);

julia> apply(Id, v) ≈ v
true

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

Return the identity operator with the same codomain/domain 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 domain names and renames the resulting codomain names back to the domain 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. This contracts the state tensors of x and y over their shared names, then renames each surviving codomain name of x back to its paired domain name, so the result carries the same names y would map to. Applying the identity operator leaves y unchanged.

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, codomainnames, domainnames.

codomainnames(a)

The codomain (output) dimension names of an operator a. An operator pairs each of its codomain names with a domain name. Applying the operator contracts over the domain and leaves the codomain.

Examples

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

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

See also domainnames, operator, apply.

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

domainnames(a)

The domain (input) dimension names of an operator a. These are the names contracted over when the operator is applied to a tensor.

Examples

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

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

See also codomainnames, operator, apply.

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)

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.

noprime(i)

Reset the prime level of an index or index name to zero, returning a new index. This undoes any number of prime calls.

Examples

julia> i = Index(2);

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

See also prime, Index.

operator(a, codomain, domain)

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

Examples

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

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

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

See also state, codomainnames, domainnames, apply, similar_operator.

prime(i)

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.

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.

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.

similar_operator(prototype, [T,] unnamed_domain_axes, [codomain_names,] domain_names) -> op
similar_operator(prototype, [T,] named_domain_axes) -> op

Allocate an operator-shaped named array with undefined data, with the user-supplied side as the domain (input) and a matching codomain (output). Element type defaults to eltype(prototype). Codomain 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 domain. Storage layout (including the bra/ket flip on the domain side for graded axes) is delegated to TensorAlgebra.similar_map.

Examples

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

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

See also operator, uniquename.

state(a)

The underlying tensor of a named operator, with its codomain/domain structure forgotten. An operator carries a tensor together with a pairing of its codomain and domain 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, codomainnames, domainnames.

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.

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

Mint a fresh, unique name. Given an existing name (or a name type), 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. 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.

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 domain dimension names replaced by the corresponding codomain names of a. x carries a's domain dimension names and a fresh trailing rank name. The codomain and domain partition is taken from codomainnames(a) and domainnames(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 codomain and domain partition is taken from codomainnames(a) and domainnames(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.project(a::AbstractArray, codomain_inds, domain_inds) -> t
TensorAlgebra.project(a::AbstractArray, inds) -> t

Build a named tensor from the dense array a by projecting it into the symmetry-restricted space described by the indices. 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...).

See TensorAlgebra.checked_project for a version that verifies nothing outside the symmetry-allowed blocks was discarded.

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