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.

- Upstream library: <https://github.com/dftd4/dftd4>
- Pinned upstream release: **`v4.2.0`** (see [docs/SECURITY.md]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 on `Drop`.
- `extern "C"` declarations for the whole D4/D4S C API (`dftd4_new_d4_model`,
  `dftd4_new_d4s_model`, `dftd4_get_dispersion`, …).

```rust
// 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.
   ```sh
   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]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

```sh
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.

[FFI]: https://doc.rust-lang.org/book/ch20-01-unsafe-rust.html#using-extern-functions-to-call-external-code
[DFT-D4]: https://github.com/dftd4/dftd4
[`include/dftd4.h`]: https://github.com/dftd4/dftd4/blob/v4.2.0/include/dftd4.h
[`.gitlab-ci.yml`]: https://gitlab.git.nrw/uni-ms/ag-salinga/dftd4-sys/-/blob/main/.gitlab-ci.yml
[docs/REVIEW_RESOLUTION.md]: https://gitlab.git.nrw/uni-ms/ag-salinga/dftd4-sys/-/blob/main/docs/REVIEW_RESOLUTION.md