Crate Rustb

Expand description

§Rustb – Tight-Binding Model Library

A Rust library for tight-binding model calculations in condensed matter physics. It supports model construction from both explicit hopping parameters and Slater-Koster integrals, band structure solving, topological analysis, and linear/nonlinear transport property calculations.

§Module overview

§Core data structures

Module	Purpose
`model`	Central `Model`<SPIN, DIM, R> struct with lattice, orbital, and hopping data, plus enums
`Gauge`, `Dimension`, `SpinDirection`
`atom_struct`	`Atom` and `OrbProj` types for describing atomic sites and orbital
projections

§Model construction and manipulation

Module	Purpose
`model_build`	Constructors (`Model::tb_model`), hopping setup (`add_hop`, `set_hop`),
on-site energies (`set_onsite`), and supercell building (`make_supercell`)
`hubbard`	Non-collinear unrestricted Hartree-Fock for on-site Hubbard
interactions, with fixed chemical potential or fixed initial filling
`cut`	`CutModel` trait for extracting finite slabs from supercells
`geometry`	Supercell geometry, dot structures, and related spatial operations
`model_utils`	Internal utility functions for model manipulation

§Hamiltonian solving

Module	Purpose
`solve_ham`	Parallel diagonalization of H(k) over k-point meshes
(`solve_all_parallel`, `solve_band_all_parallel`)
`ndarray_lapack`	LAPACK bindings for ndarray matrices

§k-space sampling

Module	Purpose
`kpath`	k-path generation along high-symmetry lines (`k_path`)
`kpoints`	Uniform k-mesh generation (`gen_kmesh`, `gen_krange`)

§Transport properties

Module	Purpose
`response`	Linear, nonlinear, and optical conductivity tensors via the Kubo
formalism and simplex quadrature: anomalous Hall, spin Hall, nonlinear
responses, and frequency-dependent optical conductivity

§Operators and observables

Module	Purpose
`velocity`	Velocity operator v_a(k) at each k-point
`orbital_angular`	Orbital angular momentum operator
`math`	Mathematical utilities (commutators, matrix operations)

§Topological analysis

Module	Purpose
`model_physics`	Density of states, Berry curvature, Chern numbers, Wilson loops,
and Wannier centers

§Surface and defect calculations

Module	Purpose
`surfgreen`	Surface Green’s function G^s(omega, k_parallel) for
semi-infinite systems; local density of states at surfaces and edges

§Interfaces

Module	Purpose
`wannier90`	Read Wannier90 `_hr.dat` and `_r.dat` files
`unfold`	Band unfolding for supercell calculations (the `Unfold` trait)

§Magnetic field

Module	Purpose
`magnetic_field`	Uniform magnetic field via Peierls substitution

§Output and I/O

Module	Purpose
`output`	Band structure and surface state plotting via gnuplot (`show_band`, etc.)
`io`	Text file I/O for 1D and 2D arrays (`write_txt`, `write_txt_1`)

§Supporting modules

Module	Purpose
`error`	Centralized error handling (`TbError`, `Result`)
`phy_const`	Physical constants (hbar, e, k_B, etc.)
`generics`	Numeric type abstractions

§Mathematical foundation

The tight-binding Hamiltonian in second-quantized form:

$$ H = \sum_{i,j} t_{ij} c_i^\dagger c_j + \sum_i \epsilon_i c_i^\dagger c_i $$

where t_{ij} are hopping parameters and epsilon_i are on-site energies.

The Bloch Hamiltonian at a given k-point is:

$$ H_{mn}(\mathbf{k}) = \sum_{\mathbf{R}} H_{mn}(\mathbf{R}), e^{i \mathbf{k} \cdot \mathbf{R}} $$

where R runs over lattice vectors and H_{mn}(R) is the hopping matrix element from orbital n to orbital m.

For transport, the Berry curvature is computed as:

$$ \Omega_n(\mathbf{k}) = -2,\operatorname{Im}\sum_{m\neq n} \frac{\bra{n}\partial_{k_x} H\ket{m}\bra{m}\partial_{k_y} H\ket{n}} {(E_n - E_m)^2} $$

and the anomalous Hall conductivity follows from the Brillouin-zone integral:

$$ \sigma_{xy} = \frac{e^2}{\hbar} \int \frac{d^d k}{(2\pi)^d}, \sum_n f_n(\mathbf{k}), \Omega_n(\mathbf{k}) $$

§Quick start

The example below builds a nearest-neighbor graphene model, computes the band structure and density of states, constructs a zigzag nanoribbon, and plots the edge states.

use ndarray::prelude::*;
use num_complex::Complex;
use Rustb::*;

// --- Build the graphene tight-binding model ---
let t1 = Complex::new(1.0, 0.0);     // nearest-neighbor hopping
let t2 = Complex::new(0.1, 0.0);     // next-nearest-neighbor hopping
let delta = 0.5;                     // staggered on-site potential

// Honeycomb lattice vectors
let lat = arr2(&[[3.0_f64.sqrt(), -1.0], [3.0_f64.sqrt(), 1.0]]);
// Two sublattice sites in fractional coordinates
let orb = arr2(&[[0.0, 0.0], [1.0 / 3.0, 1.0 / 3.0]]);

let mut model = Model::<false, 2>::tb_model(lat, orb, None)?;
model.set_onsite(&arr1(&[delta, -delta]), None);

// Nearest-neighbor hoppings (A <-> B)
model.add_hop(t1, 0, 1, &array![0, 0], None);
model.add_hop(t1, 0, 1, &array![-1, 0], None);
model.add_hop(t1, 0, 1, &array![0, -1], None);

// Next-nearest-neighbor hoppings (A-A and B-B)
for &(i, j) in &[(0, 0), (1, 1)] {
    for r in &[array![1, 0], array![0, 1], array![1, -1]] {
        model.add_hop(t2, i, j, r, None);
    }
}

// --- Band structure along high-symmetry path G -> K -> M -> G ---
let nk = 1001;
let path = arr2(&[[0.0, 0.0], [2.0 / 3.0, 1.0 / 3.0], [0.5, 0.5], [0.0, 0.0]]);
let label = vec!["G", "K", "M", "G"];
model.show_band(&path, &label, nk, "graphene")?;

// --- Zigzag nanoribbon and edge states ---
let U = arr2(&[[1.0, 1.0], [-1.0, 1.0]]);
let super_model = model.make_supercell(&U)?;
let zig_model = super_model.cut_piece(100, 0)?;
let path_edge = arr2(&[[0.0, 0.0], [0.0, 0.5], [0.0, 1.0]]);
let label_edge = vec!["G", "M", "G"];
zig_model.show_band(&path_edge, &label_edge, 501, "graphene_zig")?;

// --- Density of states ---
let kmesh = arr1(&[101, 101]);
let (energies, dos) = model.dos(&kmesh, -3.0, 3.0, 1000, 1e-2)?;
// Write DOS data to a text file
let dos_data = ndarray::stack![Axis(0), energies, dos];
write_txt(&dos_data, "dos.dat")?;

Re-exports§

pub use crate::atom_struct::Atom;
pub use crate::atom_struct::AtomId;
pub use crate::atom_struct::AtomType;
pub use crate::atom_struct::OrbProj;
pub use crate::atom_struct::OrbitalId;
pub use crate::crystal_symmetry::CrystalSymmetry;
pub use crate::crystal_symmetry::CrystalSymmetryDataset;
pub use crate::crystal_symmetry::CrystalSymmetryOperation;
pub use crate::crystal_symmetry::ExternalFields;
pub use crate::crystal_symmetry::HighSymmetryKPoint;
pub use crate::crystal_symmetry::IrreducibleKMesh;
pub use crate::crystal_symmetry::MagneticCrystalSymmetry;
pub use crate::crystal_symmetry::MagneticGroupType;
pub use crate::crystal_symmetry::MagneticTableColumns;
pub use crate::crystal_symmetry::SymmetryParameters;
pub use crate::error::Result;
pub use crate::error::TbError;
pub use crate::hamiltonian_symmetry::BasisActionContext;
pub use crate::hamiltonian_symmetry::BasisRepresentationError;
pub use crate::hamiltonian_symmetry::BasisSymmetryRepresentation;
pub use crate::hamiltonian_symmetry::CellShiftAction;
pub use crate::hamiltonian_symmetry::FinalMagneticGroup;
pub use crate::hamiltonian_symmetry::HamiltonianCompatibility;
pub use crate::hamiltonian_symmetry::HamiltonianResidual;
pub use crate::hamiltonian_symmetry::HamiltonianResidualWitness;
pub use crate::hamiltonian_symmetry::HamiltonianSymmetrizationParameters;
pub use crate::hamiltonian_symmetry::HamiltonianSymmetryCandidates;
pub use crate::hamiltonian_symmetry::HamiltonianSymmetryCompleteness;
pub use crate::hamiltonian_symmetry::HamiltonianSymmetryReport;
pub use crate::hamiltonian_symmetry::HamiltonianSymmetryRequest;
pub use crate::hamiltonian_symmetry::HamiltonianSymmetryTolerances;
pub use crate::hamiltonian_symmetry::IdentifiedMagneticSubgroup;
pub use crate::hamiltonian_symmetry::LocalizedBasisAction;
pub use crate::hamiltonian_symmetry::OperationHamiltonianCheck;
pub use crate::hamiltonian_symmetry::OperationHamiltonianStatus;
pub use crate::hamiltonian_symmetry::ScalarSiteBasis;
pub use crate::solve_ham::Solve;
pub use crate::cut::*;
pub use crate::fermi_surface::*;
pub use crate::floquet::*;
pub use crate::geometry::*;
pub use crate::hubbard::*;
pub use crate::io::*;
pub use crate::kpath::*;
pub use crate::kplane::*;
pub use crate::kpoints::*;
pub use crate::magnetic_field::*;
pub use crate::math::*;
pub use crate::model::*;
pub use crate::output::*;
pub use crate::quantum_geometry::*;
pub use crate::response::*;
pub use crate::surfgreen::*;
pub use crate::thermodynamics::*;
pub use crate::unfold::*;
pub use crate::velocity::*;
pub use crate::wannier90::*;

Modules§

atom_struct
crystal_symmetry: Optional crystallographic-symmetry services backed by cryspglib.
cut: Tools for cutting slabs, ribbons, and shaped regions from a bulk model.
error: src/error.rs This module defines the custom error types for the entire tight-binding library. By using a centralized error enum, we can replace all panics with recoverable Results, making the library safer and more robust for consumers.
fermi_surface: Fermi surface visualization using marching squares (2D) and marching tetrahedra (3D).
floquet: Real-space Peierls-Floquet utilities.
generics: Generic trait definitions for numeric type flexibility and hopping parameter conversions.
geometry: Geometric and topological quantities computed via the Wilson loop method.
hamiltonian_symmetry: Hamiltonian symmetry certification and magnetic-subgroup identification.
hubbard: Non-collinear unrestricted Hartree-Fock solver for on-site Hubbard interactions.
io
kpath
kplane: k-plane generation for Fermi surface calculations.
kpoints: k-point generation and Brillouin zone sampling utilities.
magnetic_field: Uniform magnetic field for a tight-binding model.
math
model: Core implementation of tight-binding model operations and Hamiltonian construction.
model_build: Model construction and Hamiltonian manipulation methods.
model_physics: Physics calculation methods for tight-binding models
model_utils: Utility functions and macros for tight-binding model operations
ndarray_lapack: Partial eigensolver bindings to LAPACK routines (zheevx, zheevr, zheev).
orbital_angular: This module calculates the orbital Hall conductivity and the orbital angular moment
output: This module handles output in various standard formats, including:
phy_const: Physical constants.
quantum_geometry: Occupation-weighted quantum metric and Berry curvature.
response: Response functions via simplex quadrature
solve_ham: Eigenvalue solver for tight-binding Hamiltonians.
surfgreen: Surface Green’s function calculations for semi-infinite systems.
thermodynamics: Electronic occupations and thermal energy scales.
unfold
velocity: Velocity operator $\mathbf{v}(\mathbf{k}) = \nabla_{\mathbf{k}} H(\mathbf{k})$ for tight-binding models.
wannier90

Crate Rustb

Crate Rustb Copy item path

§Rustb – Tight-Binding Model Library

§Module overview

§Core data structures

§Model construction and manipulation

§Hamiltonian solving

§k-space sampling

§Transport properties

§Operators and observables

§Topological analysis

§Surface and defect calculations

§Interfaces

§Magnetic field

§Output and I/O

§Supporting modules

§Mathematical foundation

§Quick start

Re-exports§

Modules§

Crate Rustb