tbkit — a Tight-Binding package

tbkit is a Python package to build and solve Tight-Binding models, written in vectorized NumPy/SciPy. It aims to make the mechanics of Tight-Binding models — lattices, hoppings, Hamiltonians, spectra, band structures — explicit and easy to inspect, so it works as well for teaching as for research prototyping.

For computational physics beyond tight-binding — quantum mechanics, classical mechanics, statistical physics, general relativity, and more — see physicskit, whose physicskit.condensed subpackage covers tight-binding band theory and topology alongside superconductivity.

Features

• Real space: build arbitrarily complex finite lattices (flakes, ribbons, disordered structures, defects) site by site or via boolean selections (ellipses, half-planes, unions/differences of lattices), then diagonalize the resulting Hamiltonian directly.
• Reciprocal space: build the Bloch Hamiltonian H(k) of the infinite periodic lattice from a small set of intra-unit-cell hoppings, and compute band structures along a k-path through high-symmetry points.
• Topology: Berry curvature and Chern numbers of a group of bands, by the gauge-invariant Fukui-Hatsugai-Suzuki lattice method; Zak/Berry phases, Wannier centres and their flow, the Z2 invariant (Wilson loops and Fu-Kane parities), the quantum geometric tensor, symmetry checks and the tenfold way, magnetic supercells (TKNN), and the real-space local Chern marker.
• Hall conductivities: the intrinsic anomalous Hall conductivity at any Fermi level (Kubo formula over the Brillouin zone, in 2D and 3D, with adaptive mesh refinement), the spin Hall conductivity, and the real-space Kubo-Bastin Hall conductivity of large disordered samples by the kernel polynomial method.
• 3D: lattices, slabs, and Bloch Hamiltonians in three dimensions (Anderson transition, Weyl semimetals).
• Orbitals: several orbitals per site with Slater-Koster bond integrals (s, p, d), non-orthogonal bases, and spinful multi-orbital real-space models (OrbitalSystem: atomic/Kane-Mele spin-orbit, Rashba, Zeeman, Peierls phases).
• Large lattices: sparse neighbour search, shift-invert sparse eigensolvers, and the kernel polynomial method (DOS, LDOS, Kubo-Greenwood conductivity).
• Green's functions and transport: retarded Green's functions, LDOS, Fermi levels and occupations, and Landauer transmission through a device between semi-infinite leads.
• Interactions and superconductivity: the Hubbard model in mean field, and Bogoliubov-de Gennes Hamiltonians in real and reciprocal space.
• Non-Hermitian bands: non-reciprocal hoppings, spectral winding, the skin effect, and the generalized Brillouin zone.
• Exceptional points of 2D bands: eigenvalue vorticity, discriminant winding, an EP finder (charges, Jordan-block orders, exceptional rings, bulk Fermi arcs, the doubling theorem), encircling exceptional versus diabolical points, and biorthogonal Chern numbers of line-gapped bands.
• Floquet: quasienergies, Floquet and Sambe Hamiltonians, driven Bloch models (FloquetKSpace, DrivenKSpace), exact step drives of Bloch models, ribbons and flakes (step_drive), and anomalous Floquet phases: the Rudner winding number and edge-state counts.
• Spin: optional spin-1/2 degree of freedom on every site, with 2x2 (Pauli-matrix) hoppings/onsite terms, for spin-orbit coupling (Rashba, Kane-Mele) and Zeeman splitting.
• Edge states: cut a ribbon (periodic in one direction, finite in the other) out of any periodic model, to see edge/surface physics.
• Surface spectral functions of semi-infinite crystals (iterative surface Green's function): edge and surface states, e.g. the surface Dirac cone of a 3D topological insulator, without a finite slab.
• Density of states, Gaussian- or Lorentzian-broadened, from either a real-space spectrum or a Brillouin-zone mesh.
• A small library of ready-made lattices (chain, square, triangular, honeycomb, kagome, Lieb).
• Complex-valued onsite energies and hoppings; Hermitian and non-Hermitian Tight-Binding Hamiltonians.
• Multiple sublattices, with hoppings addressed by neighbor order (1st, 2nd, 3rd-nearest neighbor, ...), by angle, or by sublattice-pair tag.
• Built-in patterns for onsite disorder, hopping disorder, dimerization, strain, and an orbital magnetic field (Peierls substitution).
• Time propagation of a wavepacket under the Tight-Binding Hamiltonian (Crank-Nicolson).

tbkit is organized as a small set of composable classes and modules:

Install

Requires Python >= 3.10.

pip install tbkit

or, for an editable install from a clone (e.g. to run the test suite or work on tbkit itself):

git clone https://github.com/cpoli/tbkit
cd tbkit
pip install -e .

or, to also install the tools needed to run the test suite:

pip install -e ".[test]"
pytest tests/

The test suite has 100% line coverage of the tbkit package; see the HTML coverage report.

Quick start

Real-space flake, nearest-neighbor square lattice:

from tbkit.lattice import Lattice
from tbkit.system import System

lat = Lattice(unit_cell=[{'tag': 'a', 'r0': (0., 0.)}],
                       prim_vec=[(1., 0.), (0., 1.)])
lat.get_lattice(n1=10, n2=10)

sys = System(lat)
sys.set_hopping([{'n': 1, 't': 1.}])
sys.get_ham()
sys.get_eig()
print(sys.en)

Graphene band structure (reciprocal space):

import numpy as np
from tbkit.lattice import Lattice
from tbkit.kspace import KSpace, reciprocal_vectors

DX, DY = 0.5 * 3 ** 0.5, 0.5
unit_cell = [{'tag': 'a', 'r0': (0., 0.)}, {'tag': 'b', 'r0': (DX, DY)}]
prim_vec = [(2 * DX, 0.), (DX, 1.5)]
lat = Lattice(unit_cell=unit_cell, prim_vec=prim_vec)

gra = KSpace(lat)
gra.set_hopping([{'i': 0, 'j': 1, 'R': (0, 0), 't': 1.},
                        {'i': 0, 'j': 1, 'R': (-1, 0), 't': 1.},
                        {'i': 0, 'j': 1, 'R': (0, -1), 't': 1.}])

b1, b2 = (np.array(v) for v in reciprocal_vectors(prim_vec))
Gamma, K, M = np.zeros(2), (b1 - b2) / 3, b1 / 2
gra.k_path([Gamma, K, M, Gamma], nk=60)
fig = gra.plot_bands(node_labels=[r'$\Gamma$', 'K', 'M', r'$\Gamma$'])
fig.savefig('graphene_bands.png')

A magnetic field is added with System.set_magnetic_field (uniform field) or System.set_peierls_phase (arbitrary vector potential), applied to the hoppings after set_hopping/set_hopping_manual:

sys.set_hopping_manual(hop_dict)
sys.set_magnetic_field(alpha=0.01)  # flux quanta per unit area
sys.get_ham()

See examples/magnetic_field/plot_magnetic_field.py for a full worked example (an Aharonov-Bohm ring, reproducing the textbook result that the spectrum is periodic in the enclosed flux with period one flux quantum).

A Chern number is the Berry curvature of a group of bands, integrated over the Brillouin zone:

chern = gra.chern_number(bands=[0], nk=40)   # ~0 for plain graphene

See examples/topology/plot_haldane_topology.py for the Haldane model (the first Chern insulator), reproducing its topological phase transition (Chern number 1 -> 0) and Berry-curvature map.

A spin-1/2 degree of freedom is added with KSpace(lat, spin=True); onsite values and hoppings then also accept 2x2 (Pauli) matrices:

from tbkit.kspace import KSpace, PAULI

kmele = KSpace(lat, spin=True)
kmele.set_hopping([{'i': 0, 'j': 0, 'R': (1, 0), 't': 1j*lam*PAULI['z']}])  # intrinsic SOC

A ribbon -- periodic in one direction, finite in the other, the standard way to see edge states -- is cut out of a periodic model with tbkit.kspace.ribbon:

from tbkit.kspace import ribbon

rib = ribbon(lat, list_hop, width=30, direction=1)   # 30 unit cells wide
fig = rib.plot_bands()

See examples/topology/plot_edge_states.py for the zigzag graphene ribbon's zero-energy edge band, and the Kane-Mele ribbon's helical edge states crossing a spin-orbit gap.

Examples

examples/ is organized as a Sphinx-Gallery source tree, one topic per subfolder, each with a README.rst blurb. Every plot_*.py script is self-contained and runnable directly (python examples/<section>/<script>.py), and checks its own key numeric claims with assert before plotting -- nothing is asserted in the docs that isn't also verified in code. Building the docs (pip install -e ".[docs]" then cd docs && make html) renders these same scripts into an executed, thumbnailed example gallery under docs/source/api/gallery/.

The five pre-0.2 Jupyter notebooks were replaced by the gallery scripts tight_binding/plot_building_finite_lattices.py, tight_binding/plot_defects_and_impurities.py and dynamics/plot_wavepacket_interference.py (their other content is covered by the strain, correlations and non-Hermitian examples).

Documentation

Rendered docs (tutorial, API reference, example gallery): https://cpoli.github.io/tbkit/

• docs/source/tutorial.rst -- a narrative walkthrough of the package, from building a lattice through topology, spin-orbit coupling, and edge states.
• docs/source/history.rst -- a chronology of the breakthroughs behind Tight-Binding theory (Bloch's theorem through the Kane-Mele model), each one linked to the corresponding tbkit functionality and example above.
• docs/source/tbkit.rst -- the API reference (auto-generated from docstrings).
• ROADMAP.md -- what is planned next, and what tbkit does not do yet (compared with Kwant and PythTB).

Build the HTML docs with cd docs && make html (output in docs/build/html).

A note on the API

Version 0.2 modernized the package to run on current Python/NumPy/SciPy and cleaned up the API:

• Sublattice tags are plain one-character strings ('a') rather than byte strings (b'a').
• Classes are named in PascalCase (Lattice, System, ...) rather than lowercase names identical to their module (lattice.lattice, system.system, ...), which used to make import tbkit.lattice as lattice silently bind the wrong object.

For continuity, the pre-0.2 lowercase class names (lattice, system, plot, propagation, save) remain available as aliases of the new classes, so from tbkit.lattice import lattice still works.

License

BSD 3-Clause, see LICENSE.