# ITensor #
An ITensor is a tensor with named indices (of type [[Index|classes/index]]).
The key feature of the ITensor is automatic contraction over all matching indices,
similar to Einstein summation.
An ITensor is created with a fixed number of Index objects specifying its indices.
Because Index objects carry identifying information, most of the
ITensor interface does not depend on the Index order. For example,
given an ITensor constructed with indices `a` and `b`,
calling `elt(T,a=2,b=5)` and `elt(T,b=5,a=2)` accesses the same tensor element.
In addition to real-valued storage, ITensors can have other storage types
such as complex storage or various sparse storage types.
If an ITensor is constructed with regular indices (Index objects `I` for which
`hasQNs(I)==false`) then its storage will be dense.
If instead an ITensor is constructed with indices carrying additional quantum number (QN)
block structure (Index objects `I` for which
`hasQNs(I)==true`) then its storage will be block-sparse.
(Up through version 2 of ITensor, such ITensors were called IQTensors.)
The `ITensor` class is defined in the header "itensor/itensor.h"
## Synopsis ##
auto b1 = Index(5);
auto b3 = Index(8);
auto s2 = Index(2,"Site");
auto s3 = Index(2,"Site");
auto phi = ITensor(b1,s2,s3,b3);
phi.set(b1=2,s2=1,s3=2,b3=2, -0.5);
phi.set(b1=3,s2=2,s3=1,b3=6, 1.4);
//...
auto nrm = norm(phi); //save the original norm of phi
phi /= nrm; //division by a scalar
Print(norm(phi)); //prints: 1.0
//The * operator automatically contracts all matching indices.
//The prime(phi,b3) method primes the b3 Index of the second
//ITensor in the product so it is not contracted.
ITensor rho = phi * prime(phi,b3);
Print(order(rho)); //prints 2
Print(hasIndex(rho,b3)); //prints: true
Print(hasIndex(rho,prime(b3))); //prints: true
Print(hasIndex(rho,s2)); //prints: false
## Constructors and Accessor Methods
* `ITensor()`
Default constructor.
A default-constructed ITensor evaluates to false in a boolean context.
To construct a order-zero (scalar) ITensor use the `ITensor(Cplx val)` constructor below.
* `ITensor(Index i1, Index i2, ...)`
`ITensor(std::vector inds)`
`ITensor(std::array inds)`
`ITensor(std::initializer_list inds)`
Construct an ITensor with one or more indices. All elements are initially zero.
For efficiency reasons no storage is actually allocated when calling this constructor,
but automatically gets allocated when, for example, setting an element.
Indices can be provided as a list or in a vector, array, or initializer_list.
Click to Show Example
auto s1 = Index(2,"Site");
auto s2 = Index(2,"Site");
auto T = ITensor(s1,s2);
* `ITensor(Cplx val)`
Construct an order-zero, scalar ITensor with its single component set to val.
If the imaginary part of `val` is exactly zero then the storage of the ITensor will
be real.
Because Real numbers automatically convert to Cplx, calling `ITensor(3.14)` calls
this constructor.
Click to Show Example
auto R = ITensor(2.71);
auto C = ITensor(3+4_i);
* `randomITensor(Index i1, Index i2, ...)`
`randomITensorC(Index i1, Index i2, ...)`
`randomITensor(IndexSet inds)`
Create an ITensor with the provided indices and with random elements.
`randomITensorC` makes an ITensor with random complex elements.
Click to Show Example
auto i = Index(2);
auto j = Index(3);
auto T = randomITensor(i,j);
auto TC = randomITensorC(i,j);
Print(isComplex(TC)); //prints: true
* `matrixITensor(Matrix&& M, Index i1, Index i2)`
Create an ITensor with the two indices i1 and i2, which correspond to the
row and column indices of the provided Matrix. The elements of the returned
ITensor are set to be those of the Matrix provided.
The Matrix M is expected to be passed as an lvalue, either by passing a temporary
or by calling std::move. Its storage will be moved into the returned ITensor and
the Matrix will have empty storage afterward.
Click to Show Example
auto M = Matrix(2,2);
M(0,0) = 11;
M(0,1) = 12;
M(1,0) = 21;
M(1,1) = 22;
auto r = Index(2);
auto c = Index(2);
auto T = matrixITensor(std::move(M),r,c);
* `inds(ITensor T) -> IndexSet const&`
Return a reference to the indices of this ITensor, as an [[IndexSet|classes/indexset]]
container.
This method is useful for iterating over all of the indices of an ITensor.
Click to Show Example
auto s1 = Index(2,"Site");
auto s2 = Index(2,"Site");
auto l1 = Index(10,"Link");
auto l2 = Index(24,"Link");
auto T = ITensor(l1,s1,s2,l2);
//Print out just the Link indices of T
for(auto& I : inds(T))
{
if(hasTags(I,"Link")) println(I);
}
* `explicit operator bool()`
Evaluate an ITensor in a boolean context. Evaluates to `false` only if an ITensor is default constructed.
Click to Show Example
auto T1 = ITensor();
if(T1) println("T1 evaluates to true");
else println("T1 evaluates to false");
//prints: T1 evaluates to false
auto T2 = ITensor(s1,s2);
if(T2) println("T2 evaluates to true");
else println("T2 evaluates to false");
//prints: T2 evaluates to true
## Element Access Methods
* `elt(ITensor T, IndexVal iv1, IndexVal iv2, ...) -> Real`
`eltC(ITensor T, IndexVal iv1, IndexVal iv2, ...) -> Cplx`
Returns the element of the ITensor `T` corresponding to the provided IndexVals.
An [[IndexVal|classes/indexval]] `iv` is a pairing of an Index `index(iv)`
and an integer `val(iv)`.
The element returned is the one corresponding to holding `index(iv1)`
equal to `val(iv1)`, `index(iv2)` equal to `val(iv2)`, etc.
For `elt(...)`, if the element to be accessed has a non-zero imaginary part, this method
throws an exception.
`eltC(...)` behaves identically to the `elt(...)` except its return type is a complex number.
It succeeds whether the ITensor has complex or real storage.
Click to Show Example
auto i = Index(4,"i");
auto j = Index(4,"j");
auto k = Index(4,"k");
//Make a scalar ITensor
auto S = ITensor(2.7);
//Access its value (a real number)
auto rs = elt(S);
//Make a random order 3 ITensor
auto T = randomITensor(i,j,k);
//Get one of its elements
auto rt = elt(T,j=2,k=1,i=4);
//Make a complex scalar ITensor
auto Sc = ITensor(2.7-4_i);
//Access its value as a complex number
auto zs = eltC(Sc);
* `elt(ITensor T, int i1, int i2, ...) -> Real`
`eltC(ITensor T, int i1, int i2, ...) -> Cplx`
Simplified version of `elt(ITensor, IndexVal, ...)` (or `eltC(...)`) when the ordering
of the indices of the ITensor are known. In such a case, integers can be provided instead
of IndexVal objects.
For example, for ITensor T with indices ordered as j,i,k, `elt(T,1,2,4)` is equivalent to
`elt(T,j=1,i=2,k=4)`.
Note that the ordering of the indices of an ITensor can be set using the
`permute(ITensor,IndexSet)` function.
Click to Show Example
auto i = Index(4,"i");
auto j = Index(4,"j");
auto k = Index(4,"k");
//Make a random order 3 ITensor
auto T = randomITensor(i,j,k);
//Order the indices
T = permute(T,{k,i,j});
//Get one of its elements
auto rt = elt(T,2,1,4);
Print(rt==elt(T,i=1,j=4,k=2)); //prints: true
* `elt(ITensor T, std::vector v) -> Real`
`eltC(ITensor T, std::vector v) -> Cplx`
Version of `elt(ITensor, IndexVal, ...)` (or `eltC(...)`) taking a `std::vector`
when the ordering of the indices of the ITensor are known.
In such a case, integers can be provided instead of IndexVal objects, and in this
overload of `elt` and `eltC` the integers can be passed in a vector (dynamically sized array).
Note that the ordering of the indices of an ITensor can be set using the
`permute(ITensor,IndexSet)` function.
* `.set(IndexVal iv1, IndexVal iv2, ... , Cplx z)`
Set the element of this ITensor corresponding to the provided IndexVals to the value `z`.
If `z` has exactly zero imaginary part and the ITensor storage is real, it will not be
switched to complex storage.
Because Real numbers are automatically convertible to Cplx, one can plug Real
numbers into this method.
Click to Show Example
//Make an order 3 ITensor
auto T = ITensor(i,j,k);
//Set an element to a real number
T.set(k=2,j=2,i=3, -1.24);
//Set an element to a complex number
T.set(k=4,j=1,i=2, 3.2-4.7_i);
* `.set(int i1, int i2, ... , Cplx z)`
Shorthand notation for `.set` above when the ordering of the indices of the ITensor are known.
For example, for ITensor T with indices ordered as j,i,k, `T.set(1,2,4, 3.2)` is equivalent to
`T.set(j=1,i=2,k=4, 3.2)`.
Note that the ordering of the indices of an ITensor can be set using the `permute` function
described below.
Click to Show Example
//Make an order 3 ITensor
auto T = ITensor(i,j,k);
T = permute(T,j,i,k);
//Set an element to a real number
T.set(1,2,3,-1.24);
Print(elt(T,j=1,i=2,k=3) == -1.24); //prints: true
## ITensor Prime and Tag Methods
ITensors have all of the same tagging and priming methods that are defined for
IndexSets.
Note: all of the following functions listed of the form:
`.f(TagSet, ...)`
`.f(TagSet, TagSet, ...)`
`.f(int, ...)`
perform an in-place modification of the ITensor. `...` stands for
optional arguments to specify a subset of indices of the ITensor
to apply the operation `.f()`.
- If no optional arguments are specified, `.f()` is applied to all
indices of the input ITensor.
- If `...` is a list of indices, an IndexSet, or a collection of indices
convertible to an IndexSet, `.f()` is applied to only the specified indices.
- If `...` is a TagSet, `.f()` is only applied to the indices in the IndexSet
containing all tags in the TagSet.
Functions of the form:
`f(ITensor, TagSet, ...) -> ITensor`
`f(ITensor, TagSet, TagSet, ...) -> ITensor`
`f(ITensor, int, ...) -> ITensor`
perform the same operation as the above in-place operations and accept the
same optional arguments, but do not modify the input ITensor and instead
return a new, modified ITensor.
* `.prime(int inc = 1, ...)`
`prime(ITensor is, int inc = 1, ...) -> ITensor`
Increment prime level of all indices by 1, or by the optional amount "inc".
Optionally, only modify the tags of the listed indices, or indices
with the matching tags, as described at the top of the section.
Click to Show Example
auto i1 = Index(2,"i,n=1");
auto i2 = Index(2,"i,n=2");
auto i3 = Index(2,"i,n=3");
auto A = randomITensor(i1,i2,i3);
auto Ap = prime(A);
Print(hasIndex(Ap,i1)); //prints: false
Print(hasIndex(Ap,prime(i1))); //prints: true
Print(hasIndex(Ap,prime(i2))); //prints: true
Print(hasIndex(Ap,prime(i3))); //prints: true
A.prime(2,"n=2");
Print(hasIndex(A,i1)); //prints: true
Print(hasIndex(A,prime(i2,2))); //prints: true
Print(hasIndex(A,i3)); //prints: true
* `.setPrime(int plnew, ...)`
`setPrime(ITensor A, int plnew, ...) -> ITensor`
Set the prime level of all indices to plnew. Optionally, only set the
prime levels of indices containing tags tsmatch
Optionally, only modify the tags of the listed indices, or indices
with the matching tags, as described at the top of the section.
* `.noPrime(...)`
`noPrime(ITensor is, ...) -> ITensor`
Set the prime level of all Index objects in the ITenssor to zero.
Optionally, only modify the tags of the listed indices, or indices
with the matching tags, as described at the top of the section.
* `.mapPrime(int plold, int plnew, ...)`
`mapPrime(ITensor is, int plold, int plnew, ...) -> ITensor`
Set the prime level of all indices with `plold` to `plnew`.
Optionally, only modify the tags of the listed indices, or indices
with the matching tags, as described at the top of the section
(note that if the tagset used for matching contains an integer tag
different from `plold`, this function won't do anything).
* `.swapPrime(int pl1, int pl2, ...)`
`swapPrime(ITensor is, int pl1, int pl1, ...) -> ITensor`
Swap the input prime levels, such that all indices with prime level
`pl1` have prime level `pl2` and vice versa.
Optionally, only swap the prime levels of the listed indices, or indices
with the matching tags, as described at the top of the section
(note that if the tagset used for matching contains an integer tag
different from one of the given prime levels, indices with those prime
levels won't be modified).
* `.addTags(TagSet tsadd, ...)`
`addTags(ITensor is, TagSet tsadd, ...) -> ITensor`
Add the tags in TagSet `tsadd` to the existing tags of
the indices in this ITensor.
Optionally, only modify the tags of the listed indices, or indices
with the matching tags, as described at the top of the section.
Click to Show Example
auto i1 = Index(2,"i,n=1");
auto i2 = Index(2,"i,n=2");
auto i3 = Index(2,"i,n=3");
auto A = randomITensor(i1,i2,i3);
auto isx = addTags(A,"x","n=1");
Print(hasIndex(Ax,i1)); //prints: false
Print(hasIndex(Ax,addTags(i1,"x"))); //prints: false
Print(hasIndex(Ax,i2)); //prints: true
Print(hasIndex(Ax,i3)); //prints: true
* `.removeTags(TagSet tsremove, ...)`
`removeTags(ITensor is, TagSet tsremove, ...) -> ITensor`
Remove the tags in TagSet `tsremove` from the existing tags of
the indices in this ITensor.
Optionally, only modify the tags of the listed indices, or indices
with the matching tags, as described at the top of the section.
* `.replaceTags(TagSet tsold, TagSet tsnew, ...)`
`replaceTags(ITensor is, TagSet tsold, TagSet tsnew, ...) -> ITensor`
For any index containing all of the tags in `tsold`, replace
these tags with those in `tsnew`.
Optionally, only modify the tags of the listed indices, or indices
with the matching tags, as described at the top of the section.
* `.swapTags(TagSet ts1, TagSet ts2, ...)`
`swapTags(ITensor is, TagSet ts1, TagSet ts2, ...) -> ITensor`
For any index containing all of the tags in `ts1`, replace
these tags with those in `ts2` and vice versa.
Optionally, only modify the tags of the listed indices, or indices
with the matching tags, as described at the top of the section.
* `.setTags(TagSet tsnew, ...)`
`setTags(ITensor A, TagSet tsnew, ...) -> ITensor`
Set the tags of the indices in this ITensor to be exactly those in the TagSet `tsnew`.
Optionally, only modify the tags of the listed indices, or indices
with the matching tags, as described at the top of the section.
* `.noTags(...)`
`noTags(ITensor A, TagSet tsnew, ...) -> ITensor`
Remove all tags of the indices in this ITensor.
Optionally, only modify the tags of the listed indices, or indices
with the matching tags, as described at the top of the section.
## Operators Supported By ITensors ##
In this section, expressions like `ITensor * ITensor -> ITensor` are pseudocode
indicating that two ITensors can be multiplied using the `*` operator,
and that the result will be an ITensor.
* `ITensor * ITensor -> ITensor`
`ITensor *= ITensor`
Contracting product. `A * B` contracts (sums) over all indices common to A and B.
The `*=` version overwrites the ITensor on the left afterward.
Show Example
auto l1 = Index(4);
auto s2 = Index(2,"Site");
auto s3 = Index(2,"Site");
auto l3 = Index(4);
auto A = ITensor(l1,s2,s3,l3);
auto B = ITensor(l1,s2,prime(s3),prime(l3));
//... set components of A and B ...
auto R = A * B; //contracts l1 and s2
Print(order(R)); //prints 4, the order of R
Print(hasIndex(R,s3)); //prints "true"
Print(hasIndex(R,l3)); //prints "true"
Print(hasIndex(R,prime(s3))); //prints "true"
Print(hasIndex(R,prime(l3))); //prints "true"
Print(hasIndex(R,l1)); //prints "false"
* `ITensor + ITensor -> ITensor`
`ITensor - ITensor -> ITensor`
`ITensor += ITensor`
`ITensor -= ITensor`
ITensor addition and subtraction. Adds ITensors element-wise.
Both ITensors must have the same set of indices, though they can be in
different orders.
Important note: if the left-hand-side
ITensor is default initialized, doing += or -= will assign the right-hand
ITensor to it (click to see example below). This is for convenience when summing multiple ITensors in
a loop.
Show Example
auto l1 = Index(4);
auto s2 = Index(2,"Site");
auto s3 = Index(2,"Site");
auto l3 = Index(4);
auto A = ITensor(l1,s2,s3,l3);
auto B = ITensor(l3,s3,s2,l1);
//...set components of A and B...
ITensor S = A + B; //sum of A and B
ITensor D = A - B; //difference of A and B
//
// Calling += on a default-initialized ITensor
//
auto T1 = ITensor();
auto T2 = ITensor(l1,l2);
if(not T1) print("T1 is default initialized");
T1 += T2;
if(T1) print("T1 is now initialized and equals T2");
* `-ITensor -> ITensor`
Negate each element of an ITensor.
* `ITensor * Real -> ITensor`
`Real * ITensor -> ITensor`
`ITensor / Real -> ITensor`
`ITensor *= Real`
`ITensor /= Real`
Multiply or divide each element of an ITensor by a real scalar.
* `ITensor * Cplx -> ITensor`
`Cplx * ITensor -> ITensor`
`ITensor / Cplx -> ITensor`
`ITensor *= Cplx`
`ITensor /= Cplx`
Multiply or divide each element of an ITensor by a complex scalar.
If the ITensor initially has real storage
and the complex scalar has a non-zero imaginary part, the storage automatically
converts to complex storage. If the complex number has exactly zero imaginary part, the ITensor
will continue to have real storage.
* `ITensor / ITensor -> ITensor`
`ITensor /= ITensor`
Non-contracting product (has no relationship to division).
`A / B` creates a new tensor out of A and B by "merging" any common indices
according to the rule Rijk = Aik Bjk (no sum over k).
(Here i, j, and k could be individual indices or represent groups of indices.)
Show Example
auto s2 = Index(2,"Site");
auto s3 = Index(2,"Site");
auto l3 = Index(4);
auto A = ITensor(s2,s3,l3);
auto B = ITensor(s3,l3);
//...set components of A and B...
ITensor R = A / B; //merge indices s3 and l3
Print(order(R)); //prints 3, order of R
Print(hasIndex(R,s2)); //prints "true"
Print(hasIndex(R,s3)); //prints "true"
Print(hasIndex(R,l3)); //prints "true"
* `ITensor * setElt(IndexVal) -> ITensor`
`setElt(IndexVal) * ITensor -> ITensor`
`ITensor *= setElt(IndexVal)`
When multiplied by an ITensor, a setElt(IndexVal) behaves like a order-1 (single Index) ITensor
whose only non-zero element is the element corresponding to the IndexVal, which has the value 1.0.
Show Example
auto i = Index(3);
auto j = Index(4);
auto T = ITensor(i,j);
randomize(T);
auto S = T * setElt(i(2));
// Now S will have only Index j
// and will correspond to the "slice"
// of T with i fixed to the value 2
Print(S.elt(j=3) - T.elt(i=2,j=3)); //prints: 0.0
## Complex ITensor Methods
* `.conj()`
`conj(ITensor T) -> ITensor`
Complex conjugate each element of this ITensor.
* `.takeReal()`
Replace each element of this ITensor with their real part. Afterwards the ITensor
will have real storage.
* `.takeImag()`
Replace each element of this ITensor with their imaginary part. Afterwards the ITensor
will have real storage.
* `.dag()`
`dag(ITensor T) -> ITensor`
Complex conjugate each element of this ITensor. Same as `.conj()` but
useful for interface compatibility with IQTensor.
## Elementwise Transformation Methods
* `.fill(Cplx z)`
Replace all elements with the number z. If z has zero imaginary part, the ITensor
will have real storage afterward. Note that Real scalars automatically convert
to Cplx so this method can be used for either type.
Click to Show Example
auto T = ITensor(i,j,k);
T.fill(1.);
T.fill(2.+3._i);
PrintData(T);
* `.generate(Func f)`
Set each element of this ITensor by repeatedly calling the function `f()`.
For example, if `f` is a random number generator, then the ITensor elements
will be randomized by calling `f` once for each element.
Click to Show Example
auto T = ITensor(i,j,k);
//create a lambda function
//which return a scalar
auto c = 1.0;
auto countUp = [&c]() { return c++; };
T.generate(countUp);
PrintData(T);
* `.apply(Func f)`
Transform this ITensor by applying the function `f` to each element
and replacing the element with the return value of `f`.
If the ITensor has real storage, the function `f` is only required
to accept Real arguments (accepting a Cplx argument works
too since Real is automatically convertible to Cplx).
Click to Show Example
auto T = ITensor(i,j,k);
randomize(T);
//create a lambda function
//which returns the square of its argument
auto square = [](Real r) { return r*r; };
T.apply(square);
PrintData(T);
* `.visit(Func f)`
Apply the function `f` to each element of this ITensor.
Calling `visit` has no effect on an ITensor but is useful
for inspecting each element. For example, it could be
print elements meeting a certain criterion.
Click to Show Example
auto T = ITensor(i,j,k);
randomize(T);
//create a lambda function
//which remembers the largest
//magnitude number given to it
Real max_mag = 0.;
auto maxComp = [&max_mag](Real r)
{
if(std::fabs(r) > max_mag) max_mag = std::fabs(r);
};
T.visit(maxComp);
println("Largest magnitude elt of T is ",max_mag);
## Other Facts About ITensors
* An ITensor `T` can be read from or written to a stream using
`read(s,T)` or `write(s,T)`.
* Printing an ITensor shows its indices and some other
information such as its norm.
To view all non-zero elements of an ITensor `T`,
do one of the following:
* PrintData(T);
* printfln("T = %f",T);
In the `printfln` command, the `%s` formatting token
does not display ITensor elements, whereas the `%f` token
shows all non-zero elements.
## Functions for Modifying ITensors
* `.randomize(Args args = Args::global())`
Randomize all elements the ITensor T. Optimized more for speed than for true randomness.
Afterward all elements will be real by default.
Optionally `.randomize()` accepts a named argument "Complex" which if set to `true`
will make the ITensor have random complex elements.
Click to Show Example
auto T = ITensor(i,j,k);
T.randomize(T);
T.randomize({"Complex",true});
## Functions for Transforming ITensors
* `apply(ITensor T, Func f) -> ITensor`
Return the ITensor resulting from transforming each element of T by calling `f(x) -> y`.
Works similarly to the `.apply` method discussed above but creates a new
ITensor instead of modifying an ITensor in-place.
* `permute(ITensor T, IndexSet is) -> ITensor`
`permute(ITensor T, Index i1, Index i2, ...) -> ITensor`
Given an ITensor T and an IndexSet or list of all of its indices in a particular order,
return an ITensor with indices in that order.
The data of the output ITensor is the appropriate permutation of the data
of the ITensor T.
Click to Show Example
auto T = randomITensor(i,j,k);
auto Tp = permute(T,{j,i,k});
Print(elt(Tp,1,2,4) == elt(Tp,j=1,i=2,k=4)); //prints "true"
* `random(ITensor T, Args args = Args::global()) -> ITensor`
Return a new ITensor with the same indices as T but with randomized, real elements.
Optionally `random` accepts a named argument "Complex" which if set to `true`
will make the returned ITensor have random complex elements.
Click to Show Example
auto T = ITensor(i,j,k);
auto RT = random(T);
auto CT = random(T,{"Complex",true});
* `realPart(ITensor T) -> ITensor`
Return just the real part of an ITensor T.
* `imagPart(ITensor T) -> ITensor`
Return just the imaginary part of an ITensor T.
## Extracting Properties of ITensors
* `order(ITensor T) -> long`
Return the order (number of indices) of the ITensor T.
Click to Show Example
auto s1 = Index(2,"Site");
auto s2 = Index(2,"Site");
auto T = ITensor(s1,s2);
Print(order(T)); //prints: order(T) = 2
* `maxDim(ITensor T) -> long`
Return the maximum dimension of all indices in the ITensor.
* `minDim(ITensor T) -> long`
Return the minimum dimension of all indices in the ITensor.
* `norm(ITensor T) -> Real`
Return the Euclidean norm of this ITensor
(the square root of the sum of squares of its elements).
Equivalent to, but much more efficient than, `sqrt(real(eltC(dag(T)*T)))`
* `isReal(ITensor T) -> bool`
Return `true` if the ITensor has real valued storage, otherwise `false`.
* `isComplex(ITensor T) -> bool`
Return `true` if the ITensor has complex valued storage, otherwise `false`.
Returns true even if the norm of the imaginary part happens to be zero.
* `sumels(ITensor const& T) -> Real`
`sumelsC(ITensor const& T) -> Cplx`
Return the sum of all elements of this ITensor. If the ITensor has a non-zero imaginary
part, throws an exception.
For a function that works for real or complex ITensors, use `sumelsC`.
## Analyzing ITensor Indices
* `hasInds(ITensor T, IndexSet is) -> bool`
Returns `true` if ITensor `T` has all of the indices in the IndexSet `is`
* `hasIndex(ITensor T, Index i) -> bool`
Returns `true` if ITensor T has an Index exactly matching `i` (including its tags).
* `findInds(ITensor T, TagSet tsmatch) -> IndexSet`
Find all indices of the ITensor containing tags in the specified TagSet.
* `findIndex(ITensor T, TagSet tags) -> Index`
Return the first Index of T that contains tags in `tags`. If no such Index is found, returns
a default-constructed Index (which evaluates to `false` in a boolean context).
If more than one Index is found, throws an error.
Click to Show Example
auto s = Index(3,"Site");
auto l = Index(10,"Link");
auto T = ITensor(s,l);
auto x = findIndex(T,"Site");
if(x) println("Found Index with tag Site: ",x);
auto y = findIndex(T,"x");
if(!y) println("T does not have an Index with tag x");
* `commonInds(ITensor A, ITensor B[, TagSet tags]) -> IndexSet`
Return the indices found on both ITensors A and B. If A and B
have no Index in common, returns a default constructed IndexSet
(one with no Indices).
If the optional TagSet `tags` is provided, only common
Indices with the specified tags will be returned.
Click to Show Example
auto i = Index(2,"i");
auto j = Index(2,"j");
auto k = Index(2,"k");
auto l = Index(2,"l");
auto A = ITensor(i,j,k);
auto B = ITensor(j,k,l);
auto c = commonInds(A,B);
Print(hasSameInds(c,{i,j})); //prints: true
* `commonIndex(ITensor A, ITensor B[, TagSet tags]) -> Index`
Return the Index found on both A and B. If A and B
have no Index in common, returns a default constructed Index
(which will evaluate to `false` in a boolean context).
Throws an error if more than one index is found (if A and B may
have more than one common Index, consider using the function
`commonInds`).
If the optional TagSet `tags` is provided, only the common
Index with the specified tags will be returned if found.
Click to Show Example
auto A = ITensor(i,j,k);
auto B = ITensor(k,m,n);
auto c = commonIndex(A,B);
if(c) println("Common Index of A and B is ",c);
* `uniqueInds(ITensor A, ITensor B) -> IndexSet`
`uniqueInds(ITensor A, std::vector const& B) -> IndexSet`
`uniqueInds(ITensor A, std::initializer_list B) -> IndexSet`
Return all indices of A not found in ITensor B (or not found in a vector of ITensors).
* `uniqueIndex(ITensor A, ITensor B[, TagSet tsmatch]) -> Index`
`uniqueIndex(ITensor A, std::vector B[, TagSet tsmatch]) -> Index`
`uniqueIndex(ITensor A, std::initializer_list B[, TagSet tsmatch]) -> Index`
Return the Index of A not found in ITensor B (or not found in a vector of ITensors).
Optionally, return the unique Index of the specified TagSet `tsmatch`.
If all of A's indices are also present on the other
ITensors provided, this function returns a default constructed Index
(which will evaluate to `false` in a boolean context).
If more than one Index is found, throw an error (and consider using `uniqueInds` instead).
Click to Show Example
auto A = ITensor(i,j,k,l);
auto B = ITensor(k,j);
auto C = ITensor(l);
auto u = uniqueIndex(A,{B,C});
Print(u == i); //prints "true"
## Other Functions
* `multSiteOps(ITensor A, ITensor B) -> ITensor`
Multiply two operators whose index structure follows the
ITensor convention for operators.
A and B are expected to have indices with a "Site" tag
s1, s2, s3, ... and s1', s2', s3', ...
and no other indices with a "Site" tag.
This function:
1. Increments the prime level of A's "Site"
indices by 1
2. Contracts A with B
3. Maps all "Site" indices with prime level 2
back to prime level 1.
Click to Show Example
auto s1 = Index(3,"Site");
auto s2 = Index(3,"Site");
auto A = ITensor(s1,s2,prime(s1),prime(s2));
auto B = ITensor(s1,s2,prime(s1),prime(s2));
//...set elements of A and B...
auto C = multSiteOps(A,B);
//ASCII art drawing:
s1'' s2''
| | s1'' s2'' s1' s2'
[ A ] | | | |
| | = [ C ] -> [ C ]
[ B ] | | | |
| | s1 s2 s1 s2
s1 s2
* `.replaceInds(IndexSet is1, IndexSet is2)`
`replaceInds(ITensor T, IndexSet is1, IndexSet is2) -> ITensor`
Search the input ITensor for the indices in IndexSet `is1`. For any
Index `i` in `is1` found in the ITensor, replace with the corresponding
index in `is2` (i.e., if `i` is the 3rd index in `is1` and is found in
ITensor `T`, it is replaced by `is2(3)`).
Any indices of the ITensor not listed in `is1` are left unchanged.
Note that for ITensors with QN conservation, the directions of the
indices are kept the same as the original ones.
Click to Show Example
auto s1 = Index(2,"Site,s=1");
auto s2 = Index(2,"Site,s=2");
auto s3 = Index(2,"Site,s=3");
auto s4 = Index(2,"Site,s=4");
auto T12 = randomITensor(s1,prime(s1),s2,prime(s2));
auto T34 = replaceInds(T12,{s1,s2,prime(s1),prime(s2)},{s3,s4,prime(s3,2),prime(s4,2)});
//ASCII art drawing:
s1' s2' s3'' s4''
| | | |
[T12] -> [T34]
| | | |
s1 s2 s3 s4
* `.swapInds(IndexSet is1, IndexSet is2)`
`swapInds(ITensor T, IndexSet is1, IndexSet is2) -> ITensor`
Swap the indices `is1` with the indices `is2` in the ITensor.
This is the same as calling `.replaceInds({is1,is2},{is2,is1})`.
Click to Show Example
auto s1 = Index(2,"Site,s=1");
auto s2 = Index(2,"Site,s=2");
auto T12 = randomITensor(s1,prime(s1),s2,prime(s2));
auto T21 = swapInds(T12,{s1,prime(s1)},{s2,prime(s2)});
//ASCII art drawing:
s1' s2' s2' s1'
| | | |
[T12] -> [T21]
| | | |
s1 s2 s2 s1
## Advanced / Developer Methods
* `.store() -> storage_ptr&`
Access the storage pointer, which is of an opaque "box"
type called `ITData`. Useful for writing new methods
that "dynamically overload" on the storage type
using the doTask system.
* `ITensor(IndexSet iset, StorageType&& store, LogNum scale = 1.)`
`ITensor(IndexSet iset, storage_ptr&& pstore, LogNum scale = 1.)`
Construct an ITensor having IndexSet `iset`, storage `dat`,
and optional scale. The storage object must be a temporary
or moved using `std::move`. The type of the storage object
must be one of the registered types in "itensor/itdata/storage_types.h".
Alternatively a `storage_ptr` can be passed instead of a storage object.
_This page current as of version 3.0.0_