GFN-FF

A general force field for elements Z = 1–103

A standalone library implementation of the GFN-FF method by S. Spicher and S. Grimme, adapted from the xtb code (most recently at commit 6d44803 and validated against that version's results). It is meant to be linked into other Fortran, C, and C++ projects, and it also ships Python bindings. From this point forward, development may diverge from the upstream xtb implementation. As of version v0.3.0 of this repository divergence is the case in order to add analytical Hessians and other features.

GFN-FF (Geometries, Frequencies, Non-covalent interactions Force-Field) is a completely automated, topology-based force field for fast structure optimisations and non-covalent interaction energies. The topology and parametrisation are derived entirely from the input geometry, without user-defined atom types or connectivity.

Quick start

pip install "gfnff[ase]"

from ase.build import molecule
from gfnff import GFNFF

atoms = molecule("caffeine")
atoms.calc = GFNFF()

energy = atoms.get_potential_energy()   # eV
forces = atoms.get_forces()             # eV / Å

The same install provides a command-line tool:

gfnff molecule.xyz --opt --alpb h2o

Documentation

The documentation is hosted at https://pprcht.github.io/gfnff/. It contains the guides listed below and a Python API reference generated from the docstrings.

Topic	Page
Fortran, C and C++ interfaces, periodic systems, use as a CMake or Meson subproject	docs/library.md
Python: installation, command-line tool, GFNFFCalculator, ASE calculator, Hessians	docs/python.md
Force-field versions, conformer2020, custom parameter files, user-supplied molecular graphs	docs/parametrisation.md
Benchmarks and choice of BLAS backend	docs/performance.md
TOML parameter file format	param/README.md
Python API reference	pprcht.github.io/gfnff

Building from source

The library requires a Fortran and C compiler (e.g. gfortran/gcc), LAPACK/BLAS (e.g. OpenBLAS), and optionally OpenMP. Both CMake (≥ 3.21) and Meson (≥ 0.59) are supported.

	CMake	Meson
Build	cmake -B _build cmake --build _build	meson setup _build ninja -C _build
Test	cmake -B _build -DWITH_TESTS=ON cmake --build _build ctest --test-dir _build	meson setup _build -Dtests=true ninja -C _build test

The compiled library (libgfnff.a by default) is placed in the build directory and can be linked into any downstream project.

Using the library

Initialise a calculator once (topology setup, the expensive step), then call the singlepoint routine as often as needed:

use gfnff_interface
type(gfnff_data) :: calc

call calc%init(nat, at, xyz, ichrg=ichrg, iostat=io)
call calc%singlepoint(nat, at, xyz, energy, gradient, iostat=io, sigma=sigma)
call calc%deallocate()

Coordinates are in Bohr, energies in Hartree, gradients in Eh/Bohr. The C/C++ header include/gfnff_interface_c.h mirrors these calls; see docs/library.md.

Performance

Caffeine clusters from 24 to 1536 atoms on 8 cores. Energy and gradient are 1.2–1.6x faster than the pre-refactor code from 192 atoms upwards, and the analytic Hessian is 28x (24 atoms) to 59x (768 atoms) faster than finite differences. Hessian speed depends mainly on the BLAS backend; details are in docs/performance.md.

References

• Molecular GFN-FF, a generic, partially polarisable force field covering organic, organometallic, and biochemical systems: S. Spicher, S. Grimme, Angew. Chem. Int. Ed. 2020, 59, 15665. doi:10.1002/anie.202004239
• Periodic boundary conditions and molecular crystals, with adjusted non-covalent interactions for lattice energies and unit-cell optimisations: S. Grimme, T. Rose, Z. Naturforsch. B 2024, 79, 191. doi:10.1515/znb-2023-0088
• Lanthanide and actinide extension, a reparametrised f-element treatment: T. Rose, M. Bursch, J.-M. Mewes, S. Grimme, Inorg. Chem. 2024. doi:10.1021/acs.inorgchem.4c03215

License

This project is licensed (as the original xtb code) under the GNU Lesser General Public License v3 or later. See LICENSE for details.