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 |
|
|
The model |
|
|
On-site energies |
|
|
Hoppings |
|
|
Spin |
2x2 amplitudes, or |
2x2 amplitudes, with |
Parameters |
string or callable amplitudes, |
value functions, |
A band structure |
|
|
A Berry phase |
|
|
A Chern number |
|
|
A Wilson loop |
|
|
Berry curvature, quantum geometry |
|
|
A ribbon, a finite piece |
|
|
Local Chern marker |
|
|
Wannier90 files |
|
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_hamandget_bandsin 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_hamuses 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_phasealong a line of loops makes the phase continuous;model.berry_phasereturns one loop in \((-\pi, \pi]\). Usenp.unwrapon 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.