dftd4-sys
Raw FFI bindings to the C API of DFT-D4, a generally applicable,
atomic-charge dependent London dispersion correction. This is a -sys crate: it
maps the libdftd4 C symbols declared in include/dftd4.h onto safe Rust
handle wrappers and lets you call them directly.
- Upstream library: https://github.com/dftd4/dftd4
- Pinned upstream release:
v4.2.0(see docs/SECURITY.md) - License: LGPL-3.0-or-later (matches the upstream library)
- MSRV: 1.98 (edition 2024)
What this crate provides
- Opaque handle types (
dftd4_error,dftd4_structure,dftd4_model,dftd4_param) and RAII wrappers (Dftd4Error,Dftd4Structure,Dftd4Model,Dftd4Param) that free the handle onDrop. extern "C"declarations for the whole D4/D4S C API (dftd4_new_d4_model,dftd4_new_d4s_model,dftd4_get_dispersion, …).
// SAFETY: requires a correctly linked libdftd4 at runtime.
let version = unsafe ;
let = ;
println!;
All extern functions are unsafe; consult the upstream C API documentation for
the invariants of each call.
Note on degenerate inputs: the upstream error handle does not report every failure. A structure with
natoms <= 0is accepted silently and makes the calculation functions (e.g.dftd4_get_dispersion) abort the host process via a Fortranerror stop; atomic numbers outside1..=118silently return zero-valued energies; a null error handle makes every entry point skip the whole call without any diagnostics.Dftd4Structure::try_newrejects all three up front and returns a catchableDftd4StructureError; see the crate documentation for details.
Note on
dftd4_get_dispersionvirial calls: despite the documented independent nullability ofgradientandsigma, upstream v4.2.0 kills the host process (SIGSEGV) whensigmais requested with a nullgradient. The vendored source build patches this wrapper bug (seebuild.rs); a system library found viapkg-configorDFTD4_DIRis not patched — there, request the gradient together with the sigma.
Build requirements
The crate declares links = "dftd4", so libdftd4 must be discoverable at build
time. The build script locates it in this order:
- System library via
pkg-config(recommended). Requires a dftd4 install of major version 4 providing the D4S API (dftd4_new_d4s_model, …); a different major is rejected rather than silently linked. DFTD4_DIR=/path/to/install— an install prefix withlib/(orlib64/) and optionallylib/pkgconfig/dftd4.pc(its version is checked). A prefix with neither alib/nor alib64/directory fails the build immediately with an error namingDFTD4_DIR, instead of a bare linker error later. A prefix carrying a sharedlibdftd4.so/.dyliblinks as-is. A prefix with only the static archivelibdftd4.a(whatmeson installwith--default-library=staticproduces — including this crate's own vendoredinstalltree) needs the libraries that archive calls; the build script detects the archive and emits them too (system BLAS/LAPACK,libgfortran,libgomp,libm), so those runtimes must be installed on the host.- Vendored source build — extract the SHA-256-pinned
v4.2.0,mctc-libv0.5.1andmultichargev0.5.0tarballs from the crate'svendor/directory and build them with meson. Needsmeson,ninja,gfortranandtar. No network access is required. See docs/PUBLISHING.md.
BLAS/LAPACK features
The default system-blas feature links the host BLAS/LAPACK installation, so the
default vendored source build does not need to download OpenBLAS. On Linux this
is usually provided by packages such as libblas-devel/liblapack-devel or a
conda environment.
The non-default openblas-static feature enables openblas-src and statically
links OpenBLAS. It is useful when a fully static consumer artifact is required,
but note that openblas-src itself may download OpenBLAS source during its
build. Use cargo build --no-default-features --features openblas-static.
Environment variables
| Variable | Effect |
|---|---|
DFTD4_DIR |
Use this install prefix instead of searching with pkg-config. |
DFTD4_SYS_SOURCE_DIR |
Where the from-source build places/reuses the pinned tree. Defaults to $OUT_DIR/dftd4-upstream (build-local, cleared by cargo clean). A stale dftd4 tree in this directory is replaced automatically; a directory that does not contain a dftd4 tree and is not empty is never deleted — the build stops with an error instead. |
Development
The tests link against a real libdftd4, so they exercise whatever the build
script resolved (system library or pinned source build). See
.gitlab-ci.yml for the CI contract.
Status of reviewed findings
See docs/REVIEW_RESOLUTION.md for how the upstream fastatomstruct code
review (2026-09) maps onto this extracted crate.