Rustb 0.7.1

A package for calculating band, angle state, linear and nonlinear conductivities based on tight-binding models
Documentation

Rustb

Rustb is a Rust 2024 library for tight-binding calculations in condensed-matter physics. It provides model construction, band structures, density of states, linear and nonlinear response, quantum geometry, Wilson loops, surface Green functions, Wannier90 import, magnetic fields, band unfolding, Fermi surfaces, and Floquet calculations.

Crates.io

The current API version is 0.7.1 and uses the const-generic model type Model<SPIN, DIM, R>.

Installation

The default BLAS/LAPACK backend is openblas-system; it requires a system OpenBLAS (libopenblas). To use another backend, disable the default features and select exactly one of the mutually exclusive backend features:

[dependencies]
Rustb = { version = "0.7", default-features = false, features = ["intel-mkl-static"] }
ndarray = "0.17"
num-complex = "0.4"

Available backends are intel-mkl-static, intel-mkl-system, openblas-static, openblas-system, netlib-static, and netlib-system. Enabling more than one backend (including via --all-features) is not supported and is rejected at compile time. Add the optional cryspglib feature to enable crystallographic and magnetic symmetry analysis without a C dependency:

Rustb = { version = "0.7", default-features = false, features = ["intel-mkl-system", "cryspglib"] }

The optional mimalloc and jemalloc allocator features are mutually exclusive and can be combined with one backend feature.

Rustb requires Rust 1.90 or newer.

Quick start

This example builds a spinless two-dimensional graphene model, plots its band structure, and evaluates a Gaussian-broadened density of states:

use ndarray::{arr1, arr2, array, Array1};
use Rustb::*;

fn main() -> Result<()> {
    // Lattice vectors are stored as rows; orbital positions are rows in
    // fractional lattice coordinates.
    let lat = arr2(&[
        [3.0_f64.sqrt(), -1.0],
        [3.0_f64.sqrt(), 1.0],
    ]);
    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)?;

    // add_hop/set_hop also insert the Hermitian-conjugate hopping at -R.
    model.add_hop(-2.85, 0, 1, &array![0, 0], None);
    model.add_hop(-2.85, 0, 1, &array![-1, 0], None);
    model.add_hop(-2.85, 0, 1, &array![0, -1], None);

    let path = arr2(&[
        [0.0, 0.0],
        [2.0 / 3.0, 1.0 / 3.0],
        [0.5, 0.5],
        [0.0, 0.0],
    ]);
    let labels = vec!["Γ", "K", "M", "Γ"];
    model.show_band(&path, &labels, 501, "graphene")?;

    let k_mesh = arr1(&[101, 101]);
    let (_energy, _dos) = model.dos(&k_mesh, -4.0, 4.0, 801, 0.02)?;

    Ok(())
}

For a spinful model, use Model::<true, DIM>. Spin-independent terms take None; Pauli-matrix terms take SpinDirection::X, Y, or Z:

let mut model = Model::<true, 2>::tb_model(lat, orb, None)?;
model.set_onsite(&arr1(&[0.5, -0.5]), None);
model.add_hop(0.2, 0, 0, &array![1, 0], SpinDirection::Z);

Model types

Model<SPIN, DIM, R>
      │     │    └─ NoRMatrix (default) or HasRMatrix
      │     └────── real-space dimension, normally 1, 2, or 3
      └──────────── false: spinless, true: spinful

HasRMatrix stores Wannier position-matrix elements and enables the associated commutator contribution in velocity calculations. NoRMatrix is a zero-sized type.

Atoms explicitly reference the dense orbital basis through typed OrbitalId values. The model remains the sole owner of orbital positions, projections, and Hamiltonian arrays:

let carbon = Atom::with_orbitals(
    array![0.0, 0.0, 0.0],
    AtomType::C,
    [OrbitalId::new(0), OrbitalId::new(2)],
);

tb_model(lat, orb, None) creates a genuine orbital-only model and does not invent atoms or chemical species. Such a model remains valid for tight-binding calculations, but crystal-symmetry analysis returns MissingAtomicStructure.

Optional crystal symmetry

With the cryspglib feature, a three-dimensional model with explicit atoms can query structure and magnetic symmetry, high-symmetry points, complete character tables, and irreducible reciprocal meshes:

let atoms = vec![Atom::with_orbitals(
    array![0.0, 0.0, 0.0],
    AtomType::Si,
    [OrbitalId::new(0)],
)];
let mut model = Model::<false, 3>::tb_model(
    Array2::eye(3),
    array![[0.0, 0.0, 0.0]],
    Some(atoms),
)?;

let symmetry = model.crystal_symmetry(&SymmetryParameters::default())?;
let points = symmetry.high_symmetry_kpoints()?;
let gamma_table = symmetry.character_table_at("GM")?;
let gamma_columns = symmetry.character_table_operations()?;

let mesh = model.irreducible_kmesh(
    [12, 12, 12],
    true,
    &SymmetryParameters::default(),
)?;
assert!((mesh.weights.sum() - 1.0).abs() < 1e-12);

Character-table operation columns use cryspglib's canonical database basis; character_table_operations() returns the headers in that exact frame and order. symmetry.operations instead remains in the input model basis.

Uniform electric and magnetic fields already encoded in a Hamiltonian must be supplied explicitly to the symmetry call because the atomic lattice alone does not contain this information:

let parameters = SymmetryParameters {
    external_fields: ExternalFields {
        electric: None,
        magnetic: Some([0.0, 0.0, 1.0]),
    },
    ..Default::default()
};
let symmetry = model.crystal_symmetry(&parameters)?;

symmetry.operations is the unchanged structural group; symmetry.field_preserving_operations is the effective subset compatible with the supplied fields. Rustb passes this context into cryspglib; it is not merely post-processing hidden in the model adapter. If the field reduces the group, structural-group high-symmetry points and character tables return FieldReducedSymmetryData instead of being mislabelled as effective data. The irreducible mesh is generated from the effective unitary and anti-unitary operations. The fields are analysis inputs and are not stored in Model.

Each Atom instead carries an optional Cartesian magnetic moment. It defaults to None, so ordinary structures are nonmagnetic until a caller explicitly attaches a moment:

assert_eq!(model.atoms[0].magnetic_moment(), None);
model.atoms[0].set_magnetic_moment([0.0, 0.0, 1.0])?;

let magnetic = model
    .magnetic_crystal_symmetry_from_atoms(&SymmetryParameters::default())?;

model.atoms[0].clear_magnetic_moment();

Some([0.0; 3]) is an explicit zero vector and None means no moment was attached; both contribute zero to crystallographic magnetic-group detection. The explicit magnetic_crystal_symmetry(&moments, ...) and magnetic_irreducible_kmesh(&moments, ...) methods remain available as per-call overrides. SPIN=true alone is never treated as magnetic order. The boolean time_reversal argument of irreducible_kmesh is likewise an explicit Hamiltonian-level assertion, not something inferred from SPIN.

Hamiltonian compatibility and the residual magnetic group

Structure symmetry is only a candidate symmetry of a tight-binding model. To test the actual hopping and onsite matrices, use the separate, read-only Hamiltonian certification API:

let report = model.check_hamiltonian_symmetry(
    &ScalarSiteBasis::default(),
    &HamiltonianSymmetryRequest::default(),
)?;

match &report.final_group {
    FinalMagneticGroup::Identified(group) => {
        println!("residual MSG: UNI {}, BNS {}", group.uni_number, group.bns_number);
    }
    FinalMagneticGroup::Inconclusive { reason } => {
        println!("more basis metadata is required: {reason}");
    }
}

The default request tests the Atom-derived grey candidate group G + G1' so that Type-II, Type-III, and Type-IV survivors can be discovered. Optional E/B fields in SymmetryParameters filter those candidates first. The checker then uses Rustb's exact finite real-space hopping support, including nonsymmorphic cell shifts; it does not infer a group from a sampled k mesh.

ScalarSiteBasis is deliberately limited to one atom-centred s orbital per Atom (with complete orbital ownership). For p/d/f, hybrid, local-frame, SOC entangled, or arbitrary Wannier bases, implement BasisSymmetryRepresentation—closures implementing the same signature are accepted as well—and return explicit LocalizedBasisAction cell-shift matrices. Missing basis metadata is Unresolved/Inconclusive, not a false claim that the Hamiltonian broke the operation.

Every decided operation contains absolute/relative residuals and a worst (R, bra, ket) witness. Validated sewing actions remain in the report for future little-group and band-irrep work. A final UNI/BNS label is returned only after cryspglib verifies group closure and derives the survivor's own family Hall setting; the original structural Hall is provenance only.

Forced Hamiltonian symmetrization

To project a slightly symmetry-broken Hamiltonian onto a chosen magnetic group, use the separate opt-in constructor. It returns a new Model and never mutates the input:

let target = model
    .magnetic_crystal_symmetry_from_atoms(&SymmetryParameters::default())?;

let symmetrized = model.symmetrize_hamiltonian(
    &target,
    &ScalarSiteBasis,
    &HamiltonianSymmetrizationParameters::default(),
)?;

Before resolving basis matrices or averaging any hopping, Rustb recomputes compatibility against the current lattice, Atom positions and species, optional Atom moments, and the supplied electric/magnetic field context. A target from another structure/setting, or one broken by these moments or fields, returns TbError::TargetMagneticGroupIncompatible immediately.

For a valid localized action, the implementation applies the complete real-space magnetic Reynolds average, including nonsymmorphic cell shifts and antiunitary conjugation. It validates projective group composition (so spin-half phases and T^2=-1 are supported), expands hamR to every generated hopping block, restores Hermiticity, and rechecks every target covariance equation. Existing rmatrix blocks remain aligned by lattice vector; newly generated support receives zero position-matrix blocks. As with certification, non-scalar Wannier gauges require an explicit BasisSymmetryRepresentation.

Wannier90 models can be loaded as:

let model: Model<false, 3> =
    Model::from_hr("path/to/files/", "wannier90", 0.0)?;

let model_with_r: Model<false, 3, HasRMatrix> =
    Model::from_hr("path/to/files/", "wannier90", 0.0)?;

Response calculations

Every high-level response method shares a single configuration type, Parameters<DIM>, with fields T (kelvin; 0.0 = zero temperature), mu (eV), eta (broadening), kmesh, omega (eV), spin (None = charge current), direction (Array2<f64>, shape (rank, DIM)), integration (Integration::Direct/Simplex/EnergyCut), and field_symmetry (extrinsic NLH only). Methods ignore the fields they do not need, and each returns a named result structure:

let mu = Array1::linspace(-1.0, 1.0, 201);

let mut hall = Parameters::rank2([101, 101], [1.0, 0.0], [0.0, 1.0], mu.clone())
    .with_temperature(20.0);
hall.integration = Integration::EnergyCut;
let hall_result = model.hall_conductivity(&hall)?;

let mut geometry = Parameters::rank2([101, 101], [1.0, 0.0], [0.0, 1.0], mu.clone());
geometry.integration = Integration::Simplex;
let geometry_result = model.quantum_geometry(&geometry)?;

let mut optical = Parameters::rank2([101, 101], [1.0, 0.0], [0.0, 1.0], array![0.0]);
optical.omega = Array1::linspace(0.0, 4.0, 401);
optical.integration = Integration::Simplex;
let optical_result = model.optical_conductivity(&optical)?;

For nonlinear Hall calculations, all tensor indices are current-first — row 0 of the direction matrix is the current, rows 1-2 the fields:

let params = Parameters::rank3(
    [101, 101],
    [1.0, 0.0], // current
    [1.0, 0.0], // first field
    [0.0, 1.0], // second field
    mu,
)
.with_temperature(30.0);
let nonlinear_result = model.intrinsic_nonlinear_hall(&params)?;

Results use named fields such as conductivity, metric, berry_curvature, frequencies, and diagnostics; response methods no longer return positional tuples. Direct integration supports 1D–3D where the quantity is defined. Simplex and energy-cut paths support their documented 2D or 3D subsets.

Hubbard mean field

HubbardModel adds orbital-resolved on-site interactions to a spinful model. Its non-collinear unrestricted Hartree-Fock solver updates the complete local 2 × 2 spin-density matrix, including Hartree density terms and Fock spin-flip terms. It can either hold the chemical potential fixed or preserve the filling calculated from the bare model at a reference Fermi level:

let mut bare = Model::<true, 1>::tb_model(
    array![[1.0]],
    array![[0.0]],
    None,
)?;
bare.add_hop(-1.0, 0, 0, &array![1], None);

let hubbard = HubbardModel::with_uniform_u(bare, 2.0)?;
let mut params = MeanFieldParams::new(
    [200],
    MeanFieldConstraint::FixedInitialFilling {
        reference_mu: 0.0,
    },
    Occupation::FermiSmearing { width: 0.01 },
);
params.initial_magnetization = InitialMagnetization::UniformVector {
    moment_per_orbital: [1e-3, 0.0, 0.0],
};

let model = hubbard.solve_hartree_fock(&params)?;
let moment = model.spin_moment(&[200], 0.0, params.occupation)?;

The result is an ordinary Model<true, DIM, R>. Its converged chemical potential has already been shifted to zero. Direct occupation sums are used instead of integrating a broadened DOS; FermiSmearing is available for zero-temperature metallic calculations.

Main capabilities

  • Model construction and transformations: tb_model, set_hop, add_hop, set_onsite, make_supercell, cut_piece, and cut_dot.
  • Non-collinear unrestricted Hartree-Fock with orbital-dependent U, fixed chemical potential or fixed initial filling, metallic smearing, and spin observables.
  • Solvers and output: gen_ham, solve_band_onek, solve_band_all_parallel, show_band, and dos.
  • Response and geometry: anomalous Hall conductivity, nonlinear Hall conductivity, optical conductivity, Berry curvature, and quantum geometry.
  • Topology: Berry phases, Berry flux, Wilson loops, and hybrid Wannier centres.
  • Boundaries and fields: surface Green functions and uniform magnetic fields through the Peierls substitution.
  • Interfaces: Wannier90 import, BXSF/FRMSF export, and band unfolding.
  • Driven systems: Floquet-Sambe Hamiltonians and same-size van Vleck effective models.

See SKILLS.md for current signatures and practical examples. The generated rustdoc contains the detailed mathematical conventions.

Development

cargo fmt --check
cargo check --all-targets
cargo test --release --features intel-mkl-system
cargo clippy --all-targets --features intel-mkl-system
cargo doc --no-deps --features intel-mkl-system

Numerical tests should be run in release mode. Some integration-style tests invoke gnuplot and regenerate files below tests/.

License

Licensed under either of:

  • Apache License, Version 2.0
  • MIT License