TBTK

Need a break? Support the development by playing Polarity Puzzles 
See more details about the Index in the API
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 nonnegative numbers.
An Index can be created as follows
However, most of the time Indices enter as function arguments, in which case they commonly appear in code simply as
Given and Index, it is possible to get its size and compontents using
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 threedimensional 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 generalpurpose Solvers that are free from Model specific assumptions.
When setting up a Model, there are two rules:
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 threedimensional substrate. Each subsystem may be best described by {x, spin} and {x, y, z, spin}, respectively. Moreover, the xSubindices 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 twodimensional 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.