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.

Advanced: Complex index structures

When setting up a Model, there are two rules:

  • Rule 1: For a given Index structure, not every Index in a range needs to be included.
  • Rule 2: If two Indices differ in value in a Subindex, the Index structures that result from the remaining Subindices to the right of it are allowed to be completely unrelated.

Example 1: Consider a square lattice with Index structure {x, y} and size 10x10. By rule 1, we are allowed to exclude N lattice points from the Model. TBTK ensures that a minimal Hilbert space is generated, which in this case, will have the size 100 - N.

Example 2: Consider a molecule on top of a three-dimensional substrate. Each subsystem may be best described by {x, spin} and {x, y, z, spin}, respectively. Moreover, the x-Subindices do not need to be related: neither by being aligned along the same direction nor by having the same ranges. This can be modeled using the Index structures {0, x, spin} and {1, x, y, z, spin}, where a subsystem Subindex has been prepended. Since the two subsystems differ in value in the first Subindex, rule 2 implies that there needs to be no relation between the Subindices to the right of it.

Example 3: Consider a two-dimensional lattice with a unit cell that contains two different types of atoms. An appropriate Index structure may be {x, y, sublattice, orbital, spin}. By rule 1, there is no problem if the number of orbitals is different for the two different sublattices.* Moreover, if one of the sublattices only has one orbital, it is possible to drop the orbital Subindex completely for that sublattice. By rule 2, it is possible to use the Index structures {x, y, 0, orbital, spin} and {x, y, 1, spin}. More specifically, this is possible since the sublattice Subindex differs in value for the two sublattices and it stands to the left of the orbital Subindex.

* In fact, by rule 1, it is also possible for two different sites on the same sublattice to have a different number of orbitals, as may be the case in a doped material.

Next: HoppingAmplitudes