pythtb.TBModel#

class TBModel(lattice, spinful=False)[source]#

Build, parametrize, and solve tight-binding Hamiltonians.

A tight-binding (TB) model describes single-particle dynamics in a discrete orbital basis (e.g., Wannier functions, atomic-like orbitals) placed on sites of a lattice. The Hamiltonian is specified by on-site and hopping terms between orbitals.

This class supports

Periodic systems (one or more reciprocal-space dimensions),
Finite real-space systems (open boundaries), or
Mixed geometries (some periodic, some open; e.g. ribbons or slabs).

Removed in version 2.0.0: Parameters dim_r and dim_k were removed. Real- and reciprocal-space dimensions are inferred from Lattice.

Parameters:

latticeLattice: Lattice and basis specification. This object defines the lattice vectors, the positions of the localized orbitals (basis functions) within the unit cell, and which lattice directions are treated as periodic. The orbital positions are given in reduced (fractional) coordinates relative to the lattice vectors. The periodic directions are a list of indices into the lattice vectors.

Changed in version 2.0.0: Replaced constructor arguments dim_k, dim_r, lat, orb, and per with a single Lattice argument. Real- and reciprocal-space dimensionalities are inferred from the lattice definition. For example, code that previously used TBModel(dim_r=2, dim_k=1, lat=..., orb=..., per=[1]) should now use TBModel(lattice=Lattice(lat_vecs=..., orb_vecs=..., periodic_dirs=[1])).
spinfulbool, optional: If True, each orbital carries two spin components (spin-1/2), and the Hamiltonian includes a 2x2 matrix structure for each orbital pair. If False, the model is spinless. Default is False.

Changed in version 2.0.0: Renamed from nspin to spinful and changed type to bool. Instead of specifying the number of spin components (1 or 2), now specify whether the model is spinful (True) or spinless (False).

Notes

The lattice geometry (primitive vectors, orbital positions, and periodic directions) is specified through a Lattice object. Periodic directions are treated in reciprocal space. Lattice also provides methods for constructing a finite model from a periodic one (e.g. ribbons, slabs, etc.).
Both spinless and spinful models are supported; spin-orbit effects may be encoded directly in the hopping matrices.
Beyond constructing and diagonalizing the Hamiltonian, this class provides methods for computing topological and quantum-geometric observables, including:
- Quantum geometric tensor (QGT) (in ≥ 2D periodic systems)
- Berry curvature and quantum metric (in ≥ 2D periodic systems)
- Chern number (in ≥ 2D periodic systems)
- Axion angle (in 3D periodic models + 1 varying parameter)
- Bianco-Resta local Chern marker (in 2D finite systems)
Hamiltonians may depend on external parameters (e.g. strain, adiabatic parameters), and can be registered by setting onsite or hopping terms with strings or callable functions that take parameter names as keyword arguments. Supply these values as keyword arguments when calling downstream methods and the class will automatically evaluate the Hamiltonian with the specified parameters.

Examples

Create a ribbon-like model: two real-space directions but only one periodic axis. The first lattice vector is [1, 1/2] and the second is [0, 2]; only the second direction is periodic, so we model a strip that repeats along \(\mathbf{a}_2\). Three orbitals sit at fractional coordinates inside the unit cell.

>>> from pythtb import TBModel, Lattice
>>> lat = Lattice(
...    lat_vecs=[[1, 1/2], [0, 2]],
...    orb_vecs=[[0.2, 0.3], [0.1, 0.1], [0.2, 0.2]],
...    periodic_dirs=[1],
... )
>>> tb = TBModel(lattice=lat, spinful=False)

Define on-site terms and a few hoppings (home cell hop plus one along the periodic direction):

>>> tb.set_onsite([0.0, 1.0, 0.5])  # onsite energies for all three orbitals
>>> tb.set_hop(1.0, 0, 1, [0, 0])   # 0 <-> 1 within home unit cell
>>> tb.set_hop(-0.8, 1, 2, [0, 0])  # 1 <-> 2 within home unit cell
>>> tb.set_hop(0.3, 2, 0, [0, 1])   # 2 <-> 0 shifted by one cell along periodic axis

Introduce parameters with strings or callables; the parameter names are remembered and must be supplied later:

>>> tb.set_onsite("U", ind_i=0)  # onsite energy for orbital 0 is parameter 'U'
>>> tb.set_onsite(lambda U: np.cos(U), ind_i=2)  # onsite energy for orbital 2 is parameter 'U'
>>> tb.set_hop(lambda t: t**2, 1, 2, [0, 0])  # hopping from orbital 1 to 2 is parameter 't'

Evaluate the Bloch Hamiltonian at a range of reduced momenta for specific parameter values:

>>> H = tb.hamiltonian(k_pts=np.linspace(0,1,10), return_eigvecs=True, U=0.4, t=0.7)
>>> H.shape
(10, 3, 3)

Diagonalize the Bloch Hamiltonian for a range of momenta and parameter values,

>>> U_vals = np.linspace(0, 2*np.pi, 11)
>>> t_vals = np.linspace(0, 1, 12)
>>> evals, evecs = tb.solve_ham(k_pts=np.linspace(0,1,10), return_eigvecs=True, U=U_vals, t=t_vals)
>>> evals.shape
(10, 11, 12, 3)
>>> evecs.shape
(10, 11, 12, 3, 3)

This pattern of setting parameters by name and supplying their values extends to all other methods that depend on the Hamiltonian, such as Berry curvature, quantum metric, etc.

Methods#

`pythtb.TBModel.add_orb`	Adds a new orbital to the model with the specified coordinates.
`pythtb.TBModel.axion_angle`	Axion angle change via the second Chern form.
`pythtb.TBModel.berry_curvature`	Compute the Berry curvature in energy eigenbasis via Kubo formula.
`pythtb.TBModel.change_nonperiodic_vector`	Change non-periodic lattice vector
`pythtb.TBModel.chern_number`	Compute the Chern number on the specified plane.
`pythtb.TBModel.clear_hoppings`	Remove all hopping terms from the model.
`pythtb.TBModel.clear_onsite`	Reset all on-site energies to zero.
`pythtb.TBModel.copy`	Return a deep copy of the model.
`pythtb.TBModel.cut_piece`	Cut a (d-1)-dimensional piece out of a d-dimensional tight-binding model.
`pythtb.TBModel.display`
`pythtb.TBModel.get_lat`
`pythtb.TBModel.get_lat_vecs`	Return lattice vectors in Cartesian coordinates.
`pythtb.TBModel.get_num_orbitals`
`pythtb.TBModel.get_orb`
`pythtb.TBModel.get_orb_vecs`	Return orbital positions.
`pythtb.TBModel.hamiltonian`	Generate the Bloch Hamiltonian of the tight-binding model.
`pythtb.TBModel.info`	Print or return a textual report describing the model.
`pythtb.TBModel.k_path`	Interpolates a path in reciprocal space.
`pythtb.TBModel.k_uniform_mesh`	Generate a uniform grid of k-points in reduced (fractional) coordinates.
`pythtb.TBModel.local_chern_marker`	Bianco-Resta local Chern marker.
`pythtb.TBModel.make_finite`	Returns a finite model.
`pythtb.TBModel.make_supercell`	Make model on a super-cell.
`pythtb.TBModel.nn_bonds`	Enumerate nearest-neighbor shells of the lattice.
`pythtb.TBModel.plot_bands`	Plot the band structure along a specified path in k-space.
`pythtb.TBModel.position_expectation`	Returns diagonal matrix elements of the position operator.
`pythtb.TBModel.position_hwf`	Eigenvalues and eigenvectors of the position operator
`pythtb.TBModel.position_matrix`	Position operator matrix elements
`pythtb.TBModel.quantum_geometric_tensor`	Quantum geometric tensor at a list of k-points via Kubo formula.
`pythtb.TBModel.quantum_metric`	Quantum metric in the energy eigenbasis computed via Kubo formula.
`pythtb.TBModel.reduce_dim`
`pythtb.TBModel.remove_orb`	Removes specified orbitals from the model.
`pythtb.TBModel.set_hop`	Define hopping amplitudes between tight-binding orbitals.
`pythtb.TBModel.set_onsite`	Define on-site energies for tight-binding orbitals.
`pythtb.TBModel.set_parameters`	Materialize parameterized on-site and hopping terms at fixed scalar values.
`pythtb.TBModel.set_shell_hops`	Set hopping amplitudes for entire nearest-neighbor shells.
`pythtb.TBModel.solve_all`
`pythtb.TBModel.solve_ham`	Diagonalize the tight-binding Hamiltonian.
`pythtb.TBModel.solve_one`
`pythtb.TBModel.velocity`	Generate the velocity operator in the orbital basis.
`pythtb.TBModel.visualize`	Visualizes the tight-binding model geometry.
`pythtb.TBModel.visualize_3d`	Visualize a 3D tight-binding model using `Plotly`.
`pythtb.TBModel.with_parameters`	Create a new TBModel instance with parameter-dependent terms evaluated at the supplied scalar values.

Attributes#

`pythtb.TBModel.assume_position_operator_diagonal`	Whether the position operator is assumed to be diagonal in the orbital basis.
`pythtb.TBModel.cell_volume`	Volume of the real-space unit cell in Cartesian units.
`pythtb.TBModel.dim_k`	Dimensionality of reciprocal space (number of periodic directions).
`pythtb.TBModel.dim_r`	Dimensionality of real space.
`pythtb.TBModel.from_w90`	Whether the model was constructed from `W90`.
`pythtb.TBModel.hoppings`	Hopping terms defined in the model.
`pythtb.TBModel.lat_vecs`	Lattice vectors in Cartesian coordinates.
`pythtb.TBModel.lattice`	The `Lattice` object associated with the model.
`pythtb.TBModel.nhops`	Number of hoppings defined in the model.
`pythtb.TBModel.norb`	Number of tight-binding orbitals per unit cell.
`pythtb.TBModel.nspin`	Number of spin components (1 for spinless, 2 for spinful).
`pythtb.TBModel.nstate`	Total number of electronic states (`norb * nspin`).
`pythtb.TBModel.onsite`	On-site energies for each orbital.
`pythtb.TBModel.orb_vecs`	Orbital positions in reduced coordinates.
`pythtb.TBModel.parameters`	Parameter providers registered on on‑site and hopping terms.
`pythtb.TBModel.periodic_dirs`	Periodic directions as indices into the lattice vectors.
`pythtb.TBModel.recip_lat_vecs`	Reciprocal lattice vectors in inverse Cartesian units.
`pythtb.TBModel.recip_volume`	Volume of the reciprocal unit cell in inverse Cartesian units.
`pythtb.TBModel.spinful`	Whether the model includes spin degrees of freedom.