dftd4-sys 0.2.0

Raw FFI bindings to the DFT-D4 dispersion correction library (libdftd4 C API)
Documentation

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.

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 on Drop.
  • 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 { dftd4_sys::dftd4_get_version() };
let (major, minor, patch) = (version / 10000, version / 100 % 100, version % 100);
println!("libdftd4 {major}.{minor}.{patch}");

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 <= 0 is accepted silently and makes the calculation functions (e.g. dftd4_get_dispersion) abort the host process via a Fortran error stop; atomic numbers outside 1..=118 silently return zero-valued energies; a null error handle makes every entry point skip the whole call without any diagnostics. Dftd4Structure::try_new rejects all three up front and returns a catchable Dftd4StructureError; see the crate documentation for details.

Note on dftd4_get_dispersion virial calls: despite the documented independent nullability of gradient and sigma, upstream v4.2.0 kills the host process (SIGSEGV) when sigma is requested with a null gradient. The vendored source build patches this wrapper bug (see build.rs); a system library found via pkg-config or DFTD4_DIR is 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:

  1. 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.
    conda install -c conda-forge dftd4        # or dnf install dftd4-devel, etc.
    
  2. DFTD4_DIR=/path/to/install — an install prefix with lib/(or lib64/) and optionally lib/pkgconfig/dftd4.pc (its version is checked). A prefix with neither a lib/ nor a lib64/ directory fails the build immediately with an error naming DFTD4_DIR, instead of a bare linker error later. A prefix carrying a shared libdftd4.so/.dylib links as-is. A prefix with only the static archive libdftd4.a (what meson install with --default-library=static produces — including this crate's own vendored install tree) 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.
  3. Vendored source build — extract the SHA-256-pinned v4.2.0, mctc-lib v0.5.1 and multicharge v0.5.0 tarballs from the crate's vendor/ directory and build them with meson. Needs meson, ninja, gfortran and tar. 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

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test

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.