## Learn to Use ITensor

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

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

# IQIndex

## (subclass of Index)

An IQIndex is a tensor index with additional structure. As a subtype of Index, an IQIndex has a name, size, type, prime level, and unique id number. IQIndex also inherits all of the class methods of Index.

An IQIndex is also divided into quantum number "blocks". Each block is defined by a Index-QN pair (an IndexQN) where the size of each block is the size of its Index. The size of an IQIndex is the total size of all of its blocks. The order and number of blocks of an IQIndex cannot be changed after the IQIndex is constructed.

For example, the IQIndex representing a single spin 1/2 has total size 2, which is made up of two blocks:

• a spin up block of size 1, indicated by a QN(+1) paired with an Index of size 1
• a spin down block of size 1, indicated by a QN(-1) paired with an Index of size 1

An IQIndex also has a direction, which is of type Arrow. An Arrow can be In or Out, and the default for an IQIndex is Out.

IQIndex is defined in the header "itensor/iqindex.h".

## Synopsis

// Make an IQIndex with five blocks
// and total size 4+8+10+8+4=34
auto I = IQIndex("I",Index("I+2",4),QN(+2),
Index("I+1",8),QN(+1),
Index("I_0",10),QN(0),
Index("I-1",8),QN(-1),
Index("I-2",4),QN(-2));

Print(I.m()); //prints: I.m() = 34

//Get number of blocks of I
Print(I.nblock()); //prints: I.nblock() = 5

//Get Index and QN of block 2
Print(I.qn(2));    //prints: QN(+1)

//Get direction of I
Print(I.dir()); //prints: I.dir() = Out


## Class Methods (only showing those differing from Index)

• IQIndex(string name,
Index i1, QN q1,
Index i2, QN q2,
...,
Arrow dir = Out)


Construct an IQIndex with the given name and blocks corresponding to the Index-QN pairs provided.
Optionally, the last argument can be an Arrow direction, which defaults to Out.

Click to Show Example
auto I = IQIndex("I",Index("I+2",4),QN(+2),
Index("I+1",8),QN(+1),
Index("I_0",10),QN(0),
Index("I-1",8),QN(-1),
Index("I-2",4),QN(-2));

• IQIndex(std::string name,
std::vector<IndexQN> && iq,
Arrow dir = Out,
int plev = 0)


Construct an IQIndex with the following attributes:

• name is the name of the IQIndex
• iq is a std::vector<IndexQN> which defines the blocks, in order, of the IQIndex. iq is an rvalue and its contents will be moved into the IQIndex.
• Optional dir specifying the direction of the IQIndex
• Optional plev specifying the prime level of the IQIndex

Click to Show Example
auto v = stdx::reserve_vector<IndexQN>(5);
v.emplace_back(Index("I+2",4),QN(+2));
v.emplace_back(Index("I+1",8),QN(+1));
v.emplace_back(Index("I_0",10),QN(0));
v.emplace_back(Index("I-1",8),QN(-1));
v.emplace_back(Index("I-2",4),QN(-2));

auto I = IQIndex("I",std::move(v),Out,0);

• .nblock() -> long
.nindex() -> long

Return the number of blocks of this IQIndex.
(.nindex() is just an alternative name for backwards compatibility reasons.)

• .index(int i) -> Index

Return the Index of the nth block of this IQIndex.
n is 1-indexed.

• .operator[](int n) -> Index

Return the Index of the nth block of this IQIndex.
n is 0-indexed.

• .qn(int n) -> QN

Return the QN of the nth block of this IQIndex. n is 1-indexed.

• .dir() -> Arrow

Return the Arrow direction of this IQIndex. Can be In or Out.

• .operator()(int n) -> IQIndexVal

Return the IQIndexVal representing this IQIndex set to a specific value "n".
For an IQIndex I, n can range from [1,m] where m is the size of I.

• .dag()

Reverse the arrow of this IQIndex.

## Other Features of IQIndex

• An IQIndex can be compared to another using == or !=. IQIndex comparison ignores the Arrow direction, thus it works identically to Index comparison, only caring about the prime level and internal id number.

• An IQIndex supports iteration, for example

for(auto& iq : I)
{
println(iq.index);
println(iq.qn);
}


IQIndex iterators are read-only and dereference to IndexQN's.

• An IQIndex I can be read to and written from disk by calling I.read(s) and I.write(s) where s is a stream object.

## IQIndex Functions

• dag(IQIndex I) -> IQIndex

Return a copy of I with its arrow direction reversed.

• hasindex(IQIndex I, Index j) -> bool

Return true if the Index j labels one of the blocks of the IQIndex I.

• findindex(IQIndex I, Index j) -> long

Return the integer n of the block of I labeled by the Index j.
The returned integer fulfills the property I.index(n) == j.
If no block matching j is found, the return value is 0.

• offset(IQIndex I, Index j) -> long

Return the sum of sizes of all blocks of I preceding the block corresponding to j.

For example, if j labels the third block, and blocks one and two have sizes 4 and 7, then offset(I,j) returns 4+7=11.

• qn(IQIndex I, Index j) -> QN

Return the quantum number of the block labeled by j.
If there is no matching block, throws an exception.

• findByQN(IQIndex I, QN q) -> Index

Return the Index labeling the first block whose QN matches q.
If there is no matching block, throws an exception.

• showm(IQIndex I) -> string

Return a string with detailed information about the total size and individual block sizes and quantum numbers of the IQIndex.

## Prime Level Functions

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

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

• prime(IQIndex I,
IndexType type,
int inc = 1)
-> IQIndex


Return a copy of I with prime level increased by 1 (or inc) if I.type() equals specified type.

• noprime(IQIndex I, IndexType type = All) -> IQIndex

Return a copy of I with prime level set to zero (optionally only if I.type() matches type).

• mapprime(IQIndex I,
int plevold, int plevnew,
IndexType type = All)
-> IQIndex


Return a copy of I with prime level plevnew if I.primeLevel()==plevold. Otherwise has no effect. (Optionally, only map prime level if type of I` matches specified type.)