dftb-rs

Pure-Rust density functional tight binding (DFTB).

What it does

• DFTB1 (non-SCC), DFTB2 (SCC) and DFTB3, plus the multipole-extended mDFTB2/mDFTB3, DFTB+U, long-range-corrected LC-DFTB and D3 dispersion
• Molecular or periodic: Γ-point and Monkhorst-Pack k-sampling with time-reversal reduction, Ewald electrostatics
• Spin: colinear, with optional constrained magnetization, and non-colinear two-component spinors
• Derivatives: analytic gradients and stress throughout; analytic Hessians with vibrational analysis; third derivatives; phonons at finite q
• Geometry optimization: L-BFGS at fixed cell, with the trajectory streamed to extended XYZ as it runs
• Excited states: TD-DFTB, LC-TD-DFTB, spin-flip TD-SF-DFTB and the non-colinear response, with analytic ∂ω/∂R for most of them
• Divide-and-conquer (experimental): a linear-scaling diagonalization for DFTB1/2/3, energy and analytic gradient — 14× faster than the full solve at 384 atoms and agreeing with it to 1e-10 Ha per atom. The electrostatics is not made linear and is the next wall
• Interfaces: a Rust library, a CLI, Python bindings and an ASE calculator

docs/scope.md is the authoritative list — every combination that is supported, every one that is refused and why, and what "validated" means here. It is worth reading before comparing a number against another code.

Where something is missing the library says so and stops, rather than returning a number computed from a different model. The larger gaps: linear response beyond Γ, the gradient of a non-colinear response state, the periodic long-range-corrected Hessian, and phonons by perturbation theory rather than by supercell.

Using it

Rust:

use dftb_rs::model::{compute, DftbOptions};
use dftb_rs::structure::Structure;

let water = Structure::from_xyz_str("3\n\nO 0 0 0\nH 0 0.757 0.587\nH 0 -0.757 0.587\n")?;
let result = compute(&water, &DftbOptions::default())?;
println!("{:.6} Ha, gap {:.3} Ha", result.energy, result.gap().unwrap());

Command line:

cargo run --bin dftb_rs_cli -- energy water.xyz --level 3 --params 3ob

Subcommands: energy, grad, opt, stress, freq, phonon, third, td, td-grad, sf-td, sf-td-grad, params, info. Divide-and-conquer is reached from the library and the Python bindings, not the CLI.

cargo run --bin dftb_rs_cli -- opt water.xyz --traj traj.xyz --out relaxed.xyz

cargo run --bin dftb_rs_cli -- td-grad water.xyz --root 1

Python, through ASE:

from ase.build import molecule
from dftb_rs.calculator import DFTB

atoms = molecule("H2O")
atoms.calc = DFTB(params="3ob", level=3)
print(atoms.get_potential_energy(), "eV")
print(atoms.get_forces())

or directly:

import dftb_rs

result = dftb_rs.compute([8, 1, 1], [[0, 0, 0], [0, 1.430, 1.109], [0, -1.430, 1.109]])
print(result["energy"], "hartree")

Units. The library works in hartree and bohr, and dftb_rs — the functions in dftb_rs.native, re-exported at the top level — hands them back unchanged. The ASE calculator in dftb_rs.calculator is the one place a conversion happens, because ASE means eV and Ångström by a number. If it came from dftb_rs, it is atomic units; if it came from DFTB, it is eV/Å. Vibrational and phonon frequencies are cm⁻¹ on both sides.

Heavy properties on the calculator — the Hessian, phonons, excited-state forces — are computed on first request and cached against the geometry they were computed for. Asking for an energy never triggers one.

Full API documentation: docs/rust-api.md, docs/python-api.md; what is and is not implemented, in detail: docs/scope.md.

Building the Python package

pip install maturin
maturin develop --features python,embed-minimal

Design

• Pure Rust, #![forbid(unsafe_code)] — dense linear algebra via faer, special functions via libm, no LAPACK/BLAS/FFI.
• One generic SCC driver over the matrix scalar: f64 for molecular and Γ real paths, c64 for k-point sampling and non-colinear spinors.
• Charge-functional energy terms (γ, DFTB3, spin-W) compose through a PotentialTerm trait. Terms that need the density matrix rather than the charges — +U and long-range exchange — join the SCC iteration variables instead, so the mixer accelerates them. The same split runs through the response: a moment-space coupled-perturbed solve for the first kind, an iterated density-matrix one for the second.
• Two-centre kernels are written once, generically over a Scalar AD trait, and instantiated at f64 / Dual / Dual2 / Dual3 for values, gradients, Hessians and third derivatives.
• Internal units: hartree and bohr.

Testing

cargo test                      # Rust
python -m pytest python/tests   # Python bindings and the ASE calculator

The suite is built around independent checks rather than pinned numbers — finite difference ladders against the analytic derivatives, sum rules, and limits that must hold exactly. Several implementation bugs were found only because those comparisons existed; each is recorded in the commit that fixed it. docs/scope.md sets out what is checked and why reference numbers from another code are not the primary check.

Parameters

Curated Slater-Koster sets are bundled with their license and provenance notices (mio, 3ob, ob2, pbc, matsci, trans3d, rare — all CC-BY-SA 4.0 from the dftbparams project). Only a minimal subset ships in the crate and the wheel, to stay inside the crates.io size limit; fetch the rest with scripts/fetch_params.py or dftb_rs.params.fetch(...), then point DFTB_RS_PARAMS at the result or pass a directory as the params option.

D3 dispersion reference data is not bundled: the C₆ tables are large and the damping parameters are fitted per method, so shipping values that could not be checked against their source would be worse than requiring scripts/fetch_dftd3.py.

Sets are not interchangeable — see docs/scope.md.

References

The methods this implements, and where they are defined. Where the implementation departs from a paper — or where a paper's number and this crate's would not be comparable — docs/scope.md says so.

DFTB1 — the non-SCC tight-binding basis of everything below:

• D. Porezag, Th. Frauenheim, Th. Köhler, G. Seifert, R. Kaschner, Construction of tight-binding-like potentials on the basis of density-functional theory: Application to carbon, Phys. Rev. B 51, 12947 (1995).
• G. Seifert, D. Porezag, Th. Frauenheim, Calculations of molecules, clusters, and solids with a simplified LCAO-DFT-LDA scheme, Int. J. Quantum Chem. 58, 185 (1996).

DFTB2 (SCC-DFTB) and DFTB3:

• M. Elstner, D. Porezag, G. Jungnickel, J. Elsner, M. Haugk, Th. Frauenheim, S. Suhai, G. Seifert, Self-consistent-charge density-functional tight-binding method for simulations of complex materials properties, Phys. Rev. B 58, 7260 (1998).
• Y. Yang, H. Yu, D. York, Q. Cui, M. Elstner, Extension of the self-consistent-charge density-functional tight-binding method: third-order expansion of the density functional theory total energy…, J. Phys. Chem. A 111, 10861 (2007).
• M. Gaus, Q. Cui, M. Elstner, DFTB3: Extension of the self-consistent-charge density-functional tight-binding method (SCC-DFTB), J. Chem. Theory Comput. 7, 931 (2011).

mDFTB — the atomic-multipole extension implemented here as mDFTB2/mDFTB3:

• V.-Q. Vuong, B. Aradi, A. M. N. Niklasson, Q. Cui, S. Irle, Multipole expansion of atomic electron density fluctuation interactions in the density-functional tight-binding method, J. Chem. Theory Comput. 19, 7592 (2023). doi:10.1021/acs.jctc.3c00778
• For the same idea in a related method: C. Bannwarth, S. Ehlert, S. Grimme, GFN2-xTB — an accurate and broadly parametrized self-consistent tight-binding quantum chemical method with multipole electrostatics and density-dependent dispersion contributions, J. Chem. Theory Comput. 15, 1652 (2019).

Spin, colinear and non-colinear, and DFTB+U:

• C. Köhler, G. Seifert, U. Gerstmann, M. Elstner, H. Overhof, Th. Frauenheim, Approximate density-functional calculations of spin densities in large molecular systems and complex solids, Phys. Chem. Chem. Phys. 3, 5109 (2001).
• C. Köhler, Th. Frauenheim, B. Hourahine, G. Seifert, M. Sternberg, Treatment of collinear and noncollinear electron spin within an approximate density functional based method, J. Phys. Chem. A 111, 5622 (2007).
• B. Hourahine, S. Sanna, B. Aradi, C. Köhler, T. Niehaus, Th. Frauenheim, Self-interaction and strong correlation in DFTB, J. Phys. Chem. A 111, 5671 (2007).
• S. L. Dudarev, G. A. Botton, S. Y. Savrasov, C. J. Humphreys, A. P. Sutton, Electron-energy-loss spectra and the structural stability of nickel oxide: an LSDA+U study, Phys. Rev. B 57, 1505 (1998).

LC-DFTB — the long-range correction:

• T. A. Niehaus, F. Della Sala, Range separated functionals in the density functional based tight-binding method: formalism, Phys. Status Solidi B 249, 237 (2012).
• V. Lutsker, B. Aradi, T. A. Niehaus, Implementation and benchmark of a long-range corrected functional in the density functional based tight-binding method, J. Chem. Phys. 143, 184107 (2015).

TD-DFTB — linear response, and its excited-state gradients:

• M. E. Casida, Time-dependent density functional response theory for molecules, in Recent Advances in Density Functional Methods, Part I, World Scientific (1995), p. 155 — the response equations this solves.
• T. A. Niehaus, S. Suhai, F. Della Sala, P. Lugli, M. Elstner, G. Seifert, Th. Frauenheim, Tight-binding approach to time-dependent density-functional response theory, Phys. Rev. B 63, 085108 (2001).
• D. Heringer, T. A. Niehaus, M. Wanko, Th. Frauenheim, Analytical excited state forces for the time-dependent density-functional tight-binding method, J. Comput. Chem. 28, 2589 (2007).
• J. J. Kranz, M. Elstner, B. Aradi, Th. Frauenheim, V. Lutsker, A. D. Garcia, T. A. Niehaus, Time-dependent extension of the long-range corrected density functional based tight-binding method, J. Chem. Theory Comput. 13, 1737 (2017) — LC-TD-DFTB.

SF-TD-DFTB — the spin-flip response:

• Y. Shao, M. Head-Gordon, A. I. Krylov, The spin-flip approach within time-dependent density functional theory: theory and applications to diradicals, J. Chem. Phys. 118, 4807 (2003) — the formulation.
• M. Inamori, T. Yoshikawa, Y. Ikabata, Y. Nishimura, H. Nakai, Spin-flip approach within time-dependent density functional tight-binding method: theory and applications, J. Comput. Chem. 41, 1538 (2020). doi:10.1002/jcc.26197
• For the non-colinear response: F. Wang, T. Ziegler, Time-dependent density functional theory based on a noncollinear formulation of the exchange-correlation potential, J. Chem. Phys. 121, 12191 (2004).

Dispersion:

• S. Grimme, J. Antony, S. Ehrlich, H. Krieg, A consistent and accurate ab initio parametrization of density functional dispersion correction (DFT-D) for the 94 elements H-Pu, J. Chem. Phys. 132, 154104 (2010).
• S. Grimme, S. Ehrlich, L. Goerigk, Effect of the damping function in dispersion corrected density functional theory, J. Comput. Chem. 32, 1456 (2011) — Becke-Johnson damping.

ASE — the calculator interface in dftb_rs.calculator targets:

• A. Hjorth Larsen et al., The atomic simulation environment — a Python library for working with atoms, J. Phys.: Condens. Matter 29, 273002 (2017). doi:10.1088/1361-648X/aa680e

The reference implementation, for anyone comparing:

• B. Hourahine et al., DFTB+, a software package for efficient approximate density functional theory based atomistic simulations, J. Chem. Phys. 152, 124101 (2020).

Slater-Koster parameter sets carry their own citations — dftb_rs.params.citation(name) returns the one for a set, and the CC-BY-SA 4.0 terms ask for it.

License

GPL-3.0-or-later. © ss0832.

Bundled Slater-Koster parameter data (under params/) is CC-BY-SA 4.0 — see the per-set LICENSE/NOTICE/SOURCE.txt files and THIRD_PARTY_NOTICES.md for attribution. CC-BY-SA 4.0 is one-way compatible with GPLv3, so the combination distributes under the GPL while the data keeps its own terms.