# Index

An Index represents a single tensor index with fixed dimension. Copies of an Index compare equal unless their tags are different.

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. There is a special tag which is referred to as the integer tag or prime level which can be incremented or decremented with special priming functions.

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 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(tags(i)); //prints:

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

Print(tags(iab)); //prints: a,b
Print(hasTags(iab,"b,a")); //prints: true
Print(removeTags(iab,"b") == ia); //prints: true

auto iap = prime(ia);
Print(tags(iap)); //prints: (a)'
Print(primeLevel(iap) == 1); //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 dim[, TagSet tags])

Construct an Index. The integer dim is the size of the Index (the dimension of the vector space that the Index defines). An Index is assigned a random id that is used to uniquely determine an Index (and indices that are made from copies of that Index).

Optionally, the TagSet tags can be specified as a comma seperated string listing the tags that that the Index will have. If none is specified, the Index will have no tags and the integer tag (prime level) will be set to 0.

Click to Show Example
// Create an Index of dimension 2
auto i = Index(2);

// Create a different Index of dimension 2
auto j = Index(2);

Print(i == j); //prints: false (since their ids are different)

// Create an Index of dimension 3 with tags "Site" and "s1"
auto s1 = Index(3,"Site,s1");

// Create an Index with dimension 4, tag "x" and integer tag (prime level) 1
auto x = Index(4,"x,1");

Print(hasTags(x,"x")); //prints: true
Print(hasTags(x,"x,1")); //prints: true
Print(primeLevel(x) == 1); //prints: true

//Not allowed: a TagSet can have only one integer tag (prime level)
//auto y = Index(4,"1,2");

• sim(Index i) -> Index

Make a new index with all of the same properties as i (dimension, tags, direction, and quantum numbers) but with a new id.

Click to Show Example
// Create an Index of dimension 2
auto s = Index(2,"s,Site");

auto t = sim(s);

Print(s == t); //prints: false
Print(tags(s) == tags(t)); //prints: true
Print(dim(s) == dim(t)); //prints: true


## Accessor Methods

• dim(Index i) -> long

Return the index dimension.

• tags(Index i) -> TagSet

Return all of the tags of this Index as a TagSet. This includes the integer tag (prime level).

• primeLevel(Index i) -> int

Return the value of the integer tag, referred to as the prime level.

• id(Index i) -> id_type

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

## Comparison Methods

• 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 TagSet.

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 j with the same size and TagSet as another Index i does not mean that i==j, since j will have a different id number.

Click to Show Example
// Create an Index of dimension 2
auto i = Index(2);

// Create a different Index of dimension 2
auto j = Index(2);

Print(i == j) // False, since their ids are different


## Tag Methods

• .addTags(TagSet tags)

addTags(Index I, TagSet tags) -> Index

Modify the TagSet of the Index, adding the specified tags. The first version modifies the Index in-place. The second version creates a new Index, keeping the original Index unmodified.

Note that every Index has one and only one integer tag, so an Integer tag cannot be added.

Click to Show Example
// Create an Index of dimension 2
auto i = Index(2,"i");

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

• .removeTags(TagSet tags)

removeTags(Index I, TagSet tags) -> Index

Modify the TagSet of the Index, removing the specified tags.

Note that every Index has one and only one integer tag, so an Integer tag cannot be removed.

Click to Show Example
// Create an Index of dimension 2
auto is = Index(2,"i,Site");

auto i = removeTags(is,"Site");

Print(hasTags(i,"Site")); //prints: false

• .replaceTags(TagSet oldtags, TagSet newtags)

replaceTags(Index I, TagSet oldtags, TagSet newtags) -> Index

Modify the TagSet of the Index, removing the tags oldtags and adding the tags newtags.

Note that an integer tag must be replaced by another integer tag. If no integer tag is specified, it is not modified.

Click to Show Example
// Create an Index of dimension 2
auto is = Index(2,"i,Site");


• .setTags(TagSet tags)

setTags(Index I, TagSet tags) -> Index

Modify the TagSet of the Index, removing all of the tags and setting them to the specified tags.

If no integer tag is specified, the integer tag is set to 0.

Click to Show Example
// Create an Index of dimension 2
auto i = Index(2,"i,1");

Print(tags(i) == "i,1"); //prints: true

auto a = setTags(i,"a");

Print(tags(a) == "a,0"); //prints: true

• .noTags()

noTags(Index I) -> Index

Remove all tags from an Index and set the integer tag to 0.

noTags(I) is the same as setTags(I,"") or setTags(I,"0").

For two indices I and J, noTags(I) == noTags(J) if and only if the ids of I and J are the same.

Click to Show Example
// Create Indices of dimension 2
auto i = Index(2);
auto j = Index(2);

Print(noTags(xp) == i); //prints: true
Print(noTags(xp) == j); //prints: false

• .prime(int inc = 1)

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

Convenience function to increment the integer tag (prime level) of the Index by 1. (Optionally, increment by amount inc.)

• .setPrime(int plev)

setPrime(Index I, intplev) -> Index

Convenience function to set the integer tag (prime level) of the Index to plev.

• .noPrime()

noPrime(Index I) -> Index

Convenience function to set the integer tag (prime level) of the Index to zero. noPrime(I) is the same as setPrime(I,0).

## Index properties

• hasTags(Index I, TagSet tags) -> bool

Check if the Index I has a TagSet that contains the TagSet tags.

• .dag()

dag(Index I) -> Index

Change the arrow direction of the Index. Only relevant for Indices with QN data.

• .setDir(Arrow)

Set the arrow direction of the Index. Only relevant for Indices with QN data.

• dir(Index) -> Arrow

Return the Arrow direction of this Index. Only relevant for Indices with QN data. Always returns Out if the Index has no QN data.

## Operators and Conversions

• operator=(int val) -> IndexVal

operator()(int val) -> IndexVal

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

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

auto iva = i=2; // Call the operator= method of Index i
auto ivb = i(2);  // This creates the same IndexVal

Print(iva == ivb); //prints: true
Print(val(iva)); //prints: 2
Print(index(iva) == 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).

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

• explicit operator int()

explicit operator long()

explicit operator size_t()

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

• .write(std::ostream& s)

Write Index to stream in binary form.

• .read(std::istream s)

Read Index from stream in binary form.

## Other Functions

• showDim(Index I) -> string

Returns a string version of the dimension of Index I.