Coming from PythTB#

If you already write PythTB scripts, this page shows how the same tasks are written in tbkit, where the two codes use different conventions, and one model ported line by line. A model you already have converts in one line, either way, with tbkit.interop (PythTB 2.0 TBModel or 1.x tb_model):

from tbkit.interop import from_pythtb, to_pythtb

ks = from_pythtb(model)   # PythTB model -> tbkit KSpace
model = to_pythtb(ks)     # tbkit KSpace -> PythTB model

The models of PythTB’s pythtb.models are also in tbkit.models (haldane, kane_mele, ssh, …), with tbkit’s own parameter names.

The same tasks side by side#

Task

PythTB 2.0

tbkit

A lattice

Lattice(lat_vecs, orb_vecs, periodic_dirs=[0, 1]), orbitals in reduced coordinates

Lattice (unit_cell, prim_vec), a tag and a Cartesian position 'r0' per orbital

The model

model = TBModel(lattice=lat, spinful=False)

model = KSpace(lat) (spin=True for spinful)

On-site energies

model.set_onsite([-delta, delta])

model.set_onsite({'a': -delta, 'b': delta}), by tag

Hoppings

model.set_hop(t1, 0, 1, [0, 0]), one call per hopping

model.set_hopping([{'i': 0, 'j': 1, 'R': (0, 0), 't': t1}, ...]), one list

Spin

2x2 amplitudes, or [s0, sx, sy, sz]

2x2 amplitudes, with tbkit.kspace.PAULI

Parameters

string or callable amplitudes, set_parameters

value functions, model.set_params(**params)

A band structure

k_vec, k_dist, k_node = model.k_path(nodes, nk), then model.solve_ham(k_vec)

dist, bands = model.k_path(points, nk), or model.get_bands(k_points); high_symmetry_path(lat) gives standard points, and model.plot_bands() the figure

A Berry phase

wfa = WFArray(model.lattice, mesh), wfa.solve_model(model), wfa.berry_phase(0, state_idx=[0])

model.berry_phase(0, nk=81, direction=0, k_perp=k2), one loop, no wave-function array

A Chern number

model.chern_number((0, 1), (60, 60), occ_idxs=[0])

model.chern_number(0, nk=60)

A Wilson loop

wfa.berry_phase(..., berry_evals=True), wfa.wilson_loop

model.wannier_centers(bands, ...) (hybrid Wannier centres), model.wannier_flow(bands, ...) (their flow), model.z2_invariant(bands)

Berry curvature, quantum geometry

model.berry_curvature, model.quantum_metric, model.quantum_geometric_tensor

model.berry_curvature, model.quantum_geometric_tensor

A ribbon, a finite piece

model.cut_piece(n, dir), model.make_finite

tbkit.kspace.ribbon() (a 1D KSpace), model.finite_ham(n_cells), or a System from the same lattice

Local Chern marker

model.local_chern_marker

System.get_local_chern_marker

Wannier90 files

TBModel.from_w90

tbkit.io.read_wannier90()

Differences of convention#

  • Hoppings. Both codes store the amplitude as the matrix element \(\langle i,\mathbf{0}|H|j,\mathbf{R}\rangle\) and add its conjugate, so give each pair once and the hopping lists translate one to one, with the same signs.

  • k-points. PythTB takes k in units of the reciprocal vectors (reduced coordinates), tbkit’s get_ham and get_bands in Cartesian coordinates: multiply by the matrix whose rows are the reciprocal vectors, k_red @ np.array(reciprocal_vectors(lat.prim_vec)). tbkit’s loop positions (k_perp, k_fixed) are fractions of a reciprocal vector, as PythTB’s mesh points are.

  • Bloch phases. PythTB’s \(H(\mathbf{k})\) includes the orbital positions, \(e^{i\mathbf{k}\cdot(\mathbf{R}+\boldsymbol\tau_j-\boldsymbol\tau_i)}\); tbkit’s get_ham uses the periodic gauge \(e^{i\mathbf{k}\cdot\mathbf{R}}\). The two matrices differ by a diagonal unitary: the bands, Chern numbers and \(\mathbb{Z}_2\) invariants are the same. Berry phases and Wannier centres depend on the positions, and tbkit’s include them by default (positions=True), so they equal PythTB’s.

  • Berry phases are wrapped. wfa.berry_phase along a line of loops makes the phase continuous; model.berry_phase returns one loop in \((-\pi, \pi]\). Use np.unwrap on a list of them.

  • Units. Neither code has units: energies are in the units of the hoppings, lengths in those of the lattice vectors.

The Haldane model, ported line by line#

The Haldane model as pythtb.models.haldane builds it (\(\Delta = 0.2\), \(t_1 = -1\), \(t_2 = 0.15\), \(\phi = \pi/2\)): the bands at \(\Gamma\), K and M, the Chern number of the lower band, \(C = -1\), and the Berry phase of the lower band along \(\mathbf{b}_1\) for five values of \(k_2\). PythTB and tbkit agree to \(10^{-12}\).

PythTB (shown, not run when the docs are built):

import numpy as np
from pythtb import Lattice, Mesh, TBModel, WFArray

delta, t1, t2 = 0.2, -1., 0.15

lat = Lattice([[1, 0], [1 / 2, np.sqrt(3) / 2]],   # lattice vectors
              [[1 / 3, 1 / 3], [2 / 3, 2 / 3]],    # orbitals, reduced coordinates
              periodic_dirs=[0, 1])
model = TBModel(lattice=lat, spinful=False)
model.set_onsite([-delta, delta])
for R in ([0, 0], [-1, 0], [0, -1]):
    model.set_hop(t1, 0, 1, R)
for R in ([1, 0], [-1, 1], [0, -1]):
    model.set_hop(t2 * 1j, 0, 0, R)
for R in ([-1, 0], [1, -1], [0, 1]):
    model.set_hop(t2 * 1j, 1, 1, R)

# Bands at Gamma, K and M (k in reduced coordinates)
k_red = [[0, 0], [2 / 3, 1 / 3], [1 / 2, 0]]
print('E(Gamma, K, M) =', np.round(model.solve_ham(k_red), 13).tolist())

# Chern number of the lower band
print('C =', round(model.chern_number((0, 1), (60, 60), occ_idxs=[0]), 13))

# Berry phase of the lower band along k1, for five values of k2
mesh = Mesh(['k', 'k'])
mesh.build_grid((81, 5))
wfa = WFArray(model.lattice, mesh, spinful=False)
wfa.solve_model(model)
print('k2 =', mesh.get_k_points()[0, :, 1].tolist())
print('Berry phase =', np.round(wfa.berry_phase(0, state_idx=[0]), 13).tolist())

tbkit (run, with its assertions, when the docs are built):

import numpy as np

from tbkit.kspace import KSpace, reciprocal_vectors
from tbkit.lattice import Lattice

delta, t1, t2 = 0.2, -1., 0.15

a1, a2 = np.array([1., 0.]), np.array([1 / 2, np.sqrt(3) / 2])
lat = Lattice(unit_cell=[{'tag': 'a', 'r0': tuple((a1 + a2) / 3)},       # Cartesian positions
                         {'tag': 'b', 'r0': tuple(2 * (a1 + a2) / 3)}],
              prim_vec=[tuple(a1), tuple(a2)])
model = KSpace(lat)
model.set_onsite({'a': -delta, 'b': delta})
model.set_hopping([{'i': 0, 'j': 1, 'R': R, 't': t1} for R in [(0, 0), (-1, 0), (0, -1)]]
                  + [{'i': 0, 'j': 0, 'R': R, 't': t2 * 1j} for R in [(1, 0), (-1, 1), (0, -1)]]
                  + [{'i': 1, 'j': 1, 'R': R, 't': t2 * 1j} for R in [(-1, 0), (1, -1), (0, 1)]])

# Bands at Gamma, K and M (tbkit takes k in Cartesian coordinates)
B = np.array(reciprocal_vectors(lat.prim_vec))       # rows b1, b2
k_red = np.array([[0, 0], [2 / 3, 1 / 3], [1 / 2, 0]])
energies = np.array([np.linalg.eigvalsh(model.get_ham(k)) for k in k_red @ B])

# Chern number of the lower band
C = model.chern_number(0, nk=60)

# Berry phase of the lower band along k1, for five values of k2
k2 = np.arange(5) / 5
phases = np.array([model.berry_phase(0, nk=81, direction=0, k_perp=q) for q in k2])

# PythTB 2.0: model.solve_ham(k_red), model.chern_number(...), wfa.berry_phase(0, ...)
assert np.allclose(energies, [[-3.0066592756746, 3.0066592756746], [-0.579422863406, 0.579422863406],
                              [-1.0198039027186, 1.0198039027186]], atol=1e-12)
assert round(C) == -1 and abs(C + 1) < 1e-12
pythtb_phases = [2.9774265573673, 3.6265248471583, 5.4395118710551, 7.5722415357587,
                 8.6817552893025]
assert np.allclose(np.exp(1j * phases), np.exp(1j * np.array(pythtb_phases)), atol=1e-12)
print('E(Gamma, K, M) =', np.round(energies, 13).tolist())
print('C =', round(C, 13))
print('Berry phase =', np.round(np.unwrap(phases), 13).tolist())

What tbkit adds, and what it does not do#

The same lattice also gives real-space models (disorder, magnetic fields, defects), quantum transport, Hall, optical and thermoelectric responses, non-Hermitian and Floquet models, crystal symmetry and symmetry indicators, mean field and exact diagonalization (see the Tutorial and the example gallery).

tbkit has no WFArray: Berry phases, Wilson loops and Chern numbers take their k-mesh as an argument and diagonalize on it. It has no counterpart of PythTB’s parameter-space meshes (a Berry phase over a model parameter, Mesh(['k', 'l'])); vary the parameter with set_params and compute the phase at each value instead.