## Learn to Use ITensor

main / classes / index C++v2 | C++v3

ITensor version 3 has not been released yet. This documentation is a preview only.

# Index

An Index represents a single tensor index with fixed dimension. Copies of an Index compare equal unless their prime levels and tags are set to different values.

An Index carries a TagSet, a set of tags which are small strings that specify properties of the Index to help distinguish it from other Indices.

Internally, an Index has a fixed id number, which is how the ITensor library knows two indices are copies of a single original Index. Index objects must have the same id, as well as the same prime level and tags to compare equal.

Index is defined in "itensor/index.h".

## Synopsis

auto i = Index(4);
Print(dim(i)); //prints: dim(i) = 4

//Copies of the same Index compare equal
auto ii = i; //ii is a copy of i
Print(ii == i); //prints: true

//The prime level of an Index can be
ii.prime(2);
Print(primeLevel(ii)); //prints: primeLevel(ii) = 2
Print(ii == i); //prints: false

ii.noPrime();
Print(ii == i); //prints: true

// Index objects can also hold a set of up to four tags
Print(hasTags(j,"j")); //prints: true

// Tags can be added to or removed from an index
// Indices must have the same tags to compare equal
Print(ia == i); //prints: false

Print(removeTags(ia,"a") == i); //prints: true

Print(tags(i)); //prints: ""
Print(tags(ia)); //prints: "a"
Print(tags(iab)); //prints: "a,b"

Print(hasTags(iab,"b,a")); //prints: true


## Constructors

• Index()

Default constructor. A default-constructed Index evaluates to false in a boolean context.

Click to Show Example
  auto i = Index();
if(!i) println("Index i is default constructed.");

• Index(int m, string tags)

Construct an Index with the following fields:

• The integer m is the size of the Index.
• The string tags is a comma seperated list of tags for the Index.
Click to Show Example
// Create an Index of dimension 2 with tags "Site" and "s3"
auto s1 = Index(2,"Site,s3");


## Accessor Methods

• dim(Index i) -> long

Return the index dimension.

• primeLevel(Index i) -> int

Return the prime level.

• tags(Index i) -> TagSet

Return the tags of this Index as a TagSet.

• .id() -> id_type

The unique id number of this Index (returned as a string)

## Prime Level Functions

• setPrime(Index I, intplev) -> Index

Return a copy of I with prime level set to plev.

• .setPrime(int plev)

Set the prime level of this Index to plev.

• prime(Index I, int inc = 1) -> Index

Return a copy of I with prime level increased by 1 (or optional amount inc).

• .prime(int inc = 1)

Increment prime level of this Index instance. (Optionally, increment by amount inc.)

• noPrime(Index I) -> Index

Return a copy of I with prime level set to zero.

• .noPrime()

Reset prime level to zero.

## Tag functions

• addTags(Index I, string tags) -> Index

Return a copy of I with tags added to the current TagSet.

• removeTags(Index I, string tags) -> Index

Return a copy of I with tags removed from the current TagSet.

• setTags(Index I, string tags) -> Index

Return a copy of I with a new TagSet specified by tags.

• replaceTags(Index I, string newtags, string oldtags)

Return a copy of I with tags oldtags removed and tags newtags added.

• hasTags(Index I, string tags)

Check if the Index I has a TagSet containing tags.

## Operators and Conversions

• operator()(int i) -> IndexVal

Return an IndexVal representing this Index set to value i. This method is one-indexed, meaning i can run from 1 to m().

Click to Show Example
auto mi = Index(10);

IndexVal iv = I(2); //call the operator() method of Index mi

Print(iv.i); //prints 2
Print(iv == I); //prints true

• operator bool()

An Index evaluates to true in a boolean context if it is constructed (a default constructed Index evalues to false).

• operator==(Index other) -> bool

operator!=(Index other) -> bool

Comparison operators: two Index objects are equal if they are copies of the same original Index (have the same id) and have the same prime level and tags.

The size of the Index objects play no explicit role in comparing them. (Of course, all Index objects which compare equal will have the same size, since they are all copies of the same original Index.) Creating a new Index "i2" with the same size, tags, and prime level as another Index "i1" does not mean that i2==i1, since i2 will have a different id number.

• operator<(Index other) -> bool

Defines an ordering of Index objects — useful for sorting and finding Index instances in collections.

• equalsIgnorePrime(Index i1, Index i2) -> bool

Return true if Index i1 and Index i2 are copies of the same original Index and have the same tags, regardless of prime level.

• explicit operator int()

explicit operator long()

explicit operator size_t()

Enables Index objects to be explicitly converting to various integer types. The resulting integer is the size of the Index.

## Other Index Class Methods

• .write(std::ostream& s)

Write Index to stream in binary form.

• .read(std::istream s)

Read Index from stream in binary form.

• .dag()

Has no effect. Currently only for interface compatibility with IQIndex.

• .dir() -> Arrow

Return the Arrow direction of this Index. Always returns Out. Currently only for interface compatibility with IQIndex.

## Other Functions

• showDim(Index I) -> string

Returns a string version of the dimension of Index I.