TBTK
Indices

See more details about the Index in the API

# Physical indices

Physical quantities often carry indices. For example, the wave function $$\Psi_{\sigma}(x, y, z)$$ has three spatial indices $$x, y, z$$, and a spin index $$\sigma$$. In TBTK, each such index is referred to as a Subindex and are grouped into an Index such as {x, y, z, spin}. The wave function is therefore said to be indexed by a single Index. Likewise, the two operators in the Hamiltonian $$H = \sum_{\mathbf{i}\mathbf{j}}a_{\mathbf{i}\mathbf{j}}c_{\mathbf{i}}^{\dagger}c_{\mathbf{j}}$$ are each indexed by a single Index, while the coefficient $$a_{\mathbf{i}\mathbf{j}}$$ carries two Indices.

An Index can contain an arbitrary number of Subindices and have an arbitrary structure. The Indices {x, y, z, spin}, {x, y, sublattice, orbital, spin}, {kx, ky, spin}, and {spin, orbital, x, y} all have valid Index structures. The only limitation is that the Subindices must be non-negative numbers.

# Creating indices

An Index can be created as follows

Index index({x, y, z, spin});

However, most of the time Indices enter as function arguments, in which case they commonly appear in code simply as

... {x, y, z, spin} ...

Given and Index, it is possible to get its size and compontents using

unsigned int size = index.size();
int x = index[0];
int y = index[1];
int z = index[2];
int spin = index[3];

# Hilbert space indices

Algorithms typically work most efficiently when the indices are linear. For example, if the indices $$\mathbf{i}$$ and $$\mathbf{j}$$ in the Hamiltonian $$H = \sum_{\mathbf{i}\mathbf{j}}a_{\mathbf{i}\mathbf{j}}c_{\mathbf{i}}^{\dagger}c_{\mathbf{j}}$$ are simple row and column indices, it is straight forward to express $$H$$ as a matrix and diagonalize it. A possible linearization of {x, y, z, spin} is h = 2*(sizeX*(sizeY*x + y) + z) + spin. In TBTK, a linearized index such as h is referred to as a Hilbert space index.

There are two major issues with hard coding a linearization like the one above. First, it locks the implementation to a particular system, in this case, a three-dimensional lattice of size sizeX*sizeY*sizeZ. Second, it is a mental burden to the developer. The more intuitive notation {x, y, z, spin} allows for emphasis to be put on physics rather than numerics.

Therefore, TBTK internally linearizes the indices in a way that is both generally applicable and which generates a minimal Hilbert space size for the given problem. This allows application developers to specify the Models and extract Properties using physical Indices alone. It also allows method developers to request the Model in a linear Hilbert space basis. Application developers can, therefore, focus on the physics of their particular problem, while method developers can write efficient general-purpose Solvers that are free from Model specific assumptions.