gfn0-rs

Version 0.4.1 bundles three experimental trained NN checkpoints, callable from Rust, Python native and ASE. No predictive-performance claim is made. See usage for all three APIs and checkpoint provenance.

An unofficial Rust implementation of the GFN0-xTB semiempirical tight-binding method with fully analytic derivatives, a command-line interface, and Python (native and ASE) bindings.

Disclaimer

This is an unofficial, independent reimplementation. Molecular results are validated against the official xtb 6.7.1 --gfn 0 binary, but the periodic extension beyond the Γ-point CCM scheme, the higher-order force constants, the strain-derivative machinery, and the EEQ-BC options are extensions that GFN0-xTB itself does not provide — they are verified by internal consistency, not against any official result. Use at your own risk.

Features

• Every derivative is analytic closed form (implicit KKT charge response, divided-difference spectral traces, set-partition chain rules). Finite differences appear only inside tests as independent oracles.
• Force-constant tensors of any order 1–6 are available as complete packed symmetric tensors, as atom-restricted blocks, as single components, and as mixed directional derivatives along arbitrary displacement fields (the directional path costs about as much as one component, not a tensor contraction). Dense tensors, blocks, and components all work for periodic systems too (Γ-point CCM, the Γ-point Bloch sum on request, and k-point meshes; metallic fillings run through a joint common-chemical-potential response over the whole mesh).
• Arbitrary-order nuclear derivatives (7th order and beyond) through the same component and directional APIs for molecular systems. Orders above six are intended for mathematical research, not chemical applications: the recurrences stay exact at every order, but the cost grows combinatorially, so they are practical only for few-atom systems.
• Second-order strain response for periodic systems (Γ-point CCM and k-point meshes, metallic fillings included through the common chemical-potential coupling): the strain-strain block d²E/dε² (9×9) and the mixed strain-coordinate block d²E/dεdx (9×3N) of the same affine deformation whose first derivative is the analytic virial/stress.
• Finite electronic temperature (Fermi smearing, 300 K default) consistent with the official implementation, including fractional occupations and open shells.
• Orbital analysis and Molden output: orbital energies, occupations, coefficients and aufbau-defined HOMO/LUMO from the Rust API, the CLI (orbitals, molden) and Python/ASE, with every smeared or degenerate frontier flagged instead of reported as a clean gap; the Molden file writes the STO-nG basis as the primitive Gaussians the crate evaluates, in Molden's [5D] convention, so a viewer shows the orbitals the calculation actually produced.
• Analytic parameter gradients dE/dθ for the fitted GFN0 globals, element/shell values, Slater exponents, pair scalings, SRB support, and D4-EEQ support parameters.
• Preconditioned L-BFGS geometry optimization on the analytic forces (fixed cell for periodic systems), with optional live XYZ trajectory output. The default graph-Laplacian ("Exp") preconditioner takes coherent steps along collective soft modes, which substantially deepens fixed-budget optimizations of molecular clusters; disable it with GeometryOptimizationOptions { precondition: false, .. }.
• Experimental EEQ-BC-2025 charge model, selectable independently for the D4 dispersion charges (d4_charge_model), for the H0 onsite shifts (hamiltonian_charge_model), and for the isotropic electrostatic energy term (electrostatic_charge_model, molecular systems only; the EEQ-BC electrostatic energy is the implementation-defined variational energy of the bond-capacity system).
• Experimental opt-in linear-scaling electronic solvers (all default off, energies/gradients/stress; divide-and-conquer also relaxes geometries): divide-and-conquer (--dc, configurable core size and buffer radius), Chebyshev Fermi-operator expansion (--foe), and McWeeny/SP2 purification (--mcweeny, gapped systems at zero electronic temperature). A conjugate-gradient EEQ solver engages automatically for large systems.
• Direct-comparison validation harness against the official xtb binary (energies, components, charges, gradients, Hessians).

Requirements

• Rust 1.85 or newer for the library, the CLI and the Python extension — the crate is on edition 2024, which is stable from 1.85, and Cargo.toml records that as rust-version, so an older toolchain stops with a version message instead of a page of syntax errors. See Installing Rust for how to get one on each platform, including what to do when a distribution ships an older rustc.
• maturin for the Python wheel, and Python 3.9 or newer.
• No parameter file is required: the fitted param_gfn0-xtb.txt is bundled under third_party/xtb/ as a verbatim copy of the upstream xtb file (LGPL-3.0-or-later) and is embedded in the binary. It stays replaceable at runtime — the resolution order is --param → GFN0_XTB_PARAM → XTBPATH → bundled default — so any modified or newer parameter file can be substituted without rebuilding.

# Rust library + CLI
cargo build --release

# Full physics test suite; no environment setup needed (bundled parameters)
cargo test

# Python wheel (distribution gfn0-rs-python, import name gfn0_rs)
pip install maturin
maturin build --release
pip install target/wheels/gfn0_rs_python-*.whl

Quick start

# Works as-is on the bundled parameterization; export this only to override it.
# export GFN0_XTB_PARAM=/path/to/share/xtb/param_gfn0-xtb.txt

gfn0_rs_cli energy   molecule.xyz
gfn0_rs_cli stress   crystal.extxyz --second
gfn0_rs_cli optimize cluster.xyz --traj traj.xyz
gfn0_rs_cli sources                      # which parameter set is active

use gfn0_rs::{Gfn0Calculator, Gfn0Parameters, System};

let params = Gfn0Parameters::load_resolved(None)?;
let calculator = Gfn0Calculator::new(params);
let system = System::from_xyz_file("crystal.extxyz", 0.0, false)?;
let energy = calculator.energy(&system)?.total;
let elastic = calculator.elastic_properties(&system)?;

import gfn0_rs

calc = gfn0_rs.Gfn0NativeCalculator(kmesh=(2, 2, 2))
energy = calc.energy(numbers, positions_bohr, cell_bohr=cell, pbc=(True,) * 3)

from gfn0_rs import GFN0RSCalculator   # ASE interface (eV/A)

Documentation

The complete API reference lives under docs/:

• docs/README.md — which toolchain version this needs and how to get one, per platform; what an out-of-date distribution package looks like; offline and cross-compiled builds.
• docs/api.md — calculator options, single-point properties, force constants through sixth order (dense, block, component, directional), mixed strain/coordinate derivatives, elastic constants (second through fourth order), Grüneisen parameters, phonons, piezoelectric tensors, equations of state, molecular vibrations, geometry optimization, parameter gradients, environment variables.
• docs/api.md — native calculator (Hartree/bohr), periodic helpers, ASE calculator (eV/Å).
• docs/cli.md — every subcommand with flags and examples.
• docs/methods.md — the external-field model, its boundary conditions and what it deliberately leaves out.
• docs/api.md — the complete unit map across Rust, Python, CLI, and ASE.
• docs/limitations.md — honest notes on model and numerical edges.

Units and conventions

• Rust and the native Python API use Hartree atomic units throughout; the ASE calculator converts to Å/eV.
• Strain derivatives use the affine map r' = (I + ε)r; strain components are indexed s = 3*row + column in 9-blocks and Voigt order in 6-blocks.
• The reported energy at finite electronic temperature is the Mermin free energy, consistent with the analytic forces, Hessians, and stress.

License

GPL-3.0-or-later (see LICENSE). Bundled third-party parameter data and their licenses are documented in THIRD_PARTY_NOTICES.md; this includes the fitted GFN0 parameter file, redistributed verbatim under LGPL-3.0-or-later in third_party/xtb/.

References

• GFN0-xTB: P. Pracht, E. Caldeweyher, S. Ehlert, S. Grimme, A Robust Non-Self-Consistent Tight-Binding Quantum Chemistry Method for Large Molecules, ChemRxiv (2019). DOI: 10.26434/chemrxiv.8326202.v1
• xtb program package: C. Bannwarth, E. Caldeweyher, S. Ehlert, A. Hansen, P. Pracht, J. Seibert, S. Spicher, S. Grimme, Extended tight-binding quantum chemistry methods, WIREs Comput. Mol. Sci. 11, e1493 (2021). DOI: 10.1002/wcms.1493
• ASE: 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
• DFT-D4: E. Caldeweyher, S. Ehlert, A. Hansen, H. Neugebauer, S. Spicher, C. Bannwarth, S. Grimme, A generally applicable atomic-charge dependent London dispersion correction, J. Chem. Phys. 150, 154122 (2019). DOI: 10.1063/1.5090222
• EEQ-BC charge model (experimental options): T. Froitzheim, M. Müller, A. Hansen, S. Grimme, g-xTB: A general-purpose extended tight-binding electronic structure method for the elements H to Lr (Z = 1–103), J. Chem. Phys. 162, 214109 (2025). DOI: 10.1063/5.0268978; parameters from grimme-lab/multicharge v0.5.0.
• NN-xTB-inspired neural parameter field (experimental implementation): Y. Xia, A. Thie, J. Soon, G. M. J. Barca, NN-xTB: density functional accuracy at semi empirical speed with neural network extended tight binding, Nature Communications 17, 7302 (2026). DOI: 10.1038/s41467-026-73184-z.

Calculation and training commands

Use gfn0-rs energy INPUT.xyz for GFN0-xTB calculations, including inference with --nn-model MODEL. Training and model evaluation have their own command:

gfn0-train nn-train --data DATA --out MODEL
gfn0-train nn-eval --help
gfn0-train nn-info MODEL

Both commands are installed by Cargo or pip. gfn0_rs_cli remains a legacy calculation alias in Cargo installations. Training commands are no longer accepted by calculation entry points. One --lr updates NN weights, learned physical coefficients and risk thresholds through the same Adam optimizer.

The calculation command is gfn0-rs in both Cargo and pip installations; the training command is gfn0-train. On Windows MSVC, the calculation binary writes its debug symbols to a separate build output path so they do not overwrite the library debug symbols.