Reference

Model Class

class tbmodels.Model(*, on_site: Optional[Sequence[float]] = None, hop: Optional[Dict[Tuple[int, ...], Any]] = None, size: Optional[int] = None, dim: Optional[int] = None, occ: Optional[int] = None, pos: Optional[Sequence[Sequence[float]]] = None, uc: Optional[Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]] = None, contains_cc: bool = True, cc_check_tolerance: float = 1e-12, sparse: bool = False)

A class describing a tight-binding model. It contains methods for modifying the model, evaluating the Hamiltonian or eigenvalues at specific k-points, and writing to and from different file formats.

Parameters:

• on_site – On-site energy of the states. This is equivalent to having a hopping within the same state and the same unit cell (diagonal terms of the R=(0, 0, 0) hopping matrix). The length of the list must be the same as the number of states.

• hop – Hopping matrices, as a dict containing the corresponding lattice vector R as a key.

• size – Number of states. Defaults to the size of the hopping matrices, if such are given.

• dim – Dimension of the tight-binding model. By default, the dimension is guessed from the other parameters if possible.

• occ – Number of occupied states.

• pos – Positions of the orbitals, in reduced coordinates. By default, all orbitals are set to be at the origin, i.e. at [0., 0., 0.].

• uc – Unit cell of the system. The unit cell vectors are given as rows in a dim x dim array

• contains_cc – Specifies whether the hopping matrices and on-site energies are given fully (contains_cc=True), or the complex conjugate should be added for each term to obtain the full model. The on_site parameter is not affected by this.

• cc_check_tolerance – Tolerance when checking if the complex conjugate values (if given) match.

• sparse – Specifies whether the hopping matrices should be saved in sparse format.

__add__(model: Model) → Model

Adds two models together by adding their hopping terms.

__mul__(x: float) → Model

Multiplies hopping terms by x.

__neg__() → Model

Changes the sign of all hopping terms.

__rmul__(x: float) → Model

Multiplies hopping terms by x.

__sub__(model: Model) → Model

Substracts one model from another by substracting all hopping terms.

__truediv__(x: float) → Model

Divides hopping terms by x.

add_hop(overlap: complex, orbital_1: int, orbital_2: int, R: Sequence[int])

Adds a hopping term with a given overlap (hopping strength) from orbital_2 (\(o_2\)), which lies in the unit cell pointed to by R, to orbital_1 (\(o_1\)) which is in the home unit cell. In other words, overlap is the matrix element \(\mathcal{H}_{o_1,o_2}(\mathbf{R}) = \langle o_1, \mathbf{0} | \mathcal{H} | o_2, \mathbf{R} \rangle\).

The complex conjugate of the hopping is added automatically. That is, the matrix element \(\langle o_2, \mathbf{R} | \mathcal{H} | o_1, \mathbf{0} \rangle\) does not have to be added manually.

Note

This means that adding a hopping of overlap \(\epsilon\) between an orbital and itself in the home unit cell increases the orbitals on-site energy by \(2 \epsilon\).

Parameters:

• overlap – Strength of the hopping term (in energy units).

• orbital_1 – Index of the first orbital.

• orbital_2 – Index of the second orbital.

• R – Lattice vector pointing to the unit cell where orbital_2 lies.

Warning

The positions given in the constructor of Model are automatically mapped into the home unit cell. This has to be taken into account when determining R.

add_hoppings_kwant(kwant_sys, kwant_sublattices=None)

Sets the on-site energies and hopping terms for an existing kwant system to those of the Model.

Note

The TBmodels - Kwant interface is experimental. Use it with caution.

add_on_site(on_site: Sequence[float])

Adds on-site energy to the orbitals. This adds to the existing on-site energy, and does not erase it.

Parameters:

on_site – On-site energies. This must be a sequence of real numbers, of the same length as the number of orbitals

change_unit_cell(*, uc: Optional[Sequence[Sequence[float]]] = None, offset: Sequence[float] = (0, 0, 0), cartesian: bool = False) → Model

Return a model with a different unit cell of the same volume.

Creates a model with a changed unit cell - with a different shape and / or origin. The new unit cell must be compatible with the current lattice, and have the same volume.

Parameters:

• uc – The new unit cell shape. Lattice vectors are given as rows in a (dim x dim) matrix. If no unit cell is given, the current unit cell shape is kept.

• offset – The position of the new unit cell origin, relative to the old one.

• cartesian – Specifies if the offset and unit cell are in cartesian or reduced coordinates. Reduced coordinates are with respect to the old unit cell.

construct_kdotp(k: Sequence[float], order: int)

Construct a k.p model around a given k-point. This is done by explicitly evaluating the derivatives which make up the Taylor expansion of the k.p models.

This method can currently only construct models using convention 2 for the Hamiltonian.

Parameters:

• k – The k-point around which the k.p model is constructed.

• order – The order (sum of powers) to which the Taylor expansion is performed.

eigenval(k: Union[Sequence[float], Sequence[Sequence[float]]]) → Union[ndarray[Any, dtype