Expand description
FFI bindings to the DFT-D4 dispersion correction library
This crate provides low-level Rust bindings to the C API of the DFT-D4 library. DFT-D4 is a generally applicable atomic-charge dependent London dispersion correction.
For more information, see: https://github.com/dftd4/dftd4
§Input validation: failure channels that bypass the error handle
The error handle (dftd4_error) is the C API’s only error channel, but the
pinned upstream (v4.2.0) does not report every invalid input through it.
Two classes of degenerate input bypass the handle entirely and cannot be
detected from Rust:
- Degenerate atom counts (
natoms <= 0).dftd4_new_structureaccepts them without setting the error handle,dftd4_new_d4_modelbuilds a model for the empty structure, and the first calculation (e.g.dftd4_get_dispersion) then terminates the host process with a Fortranerror stop(stderr:[Error]: Bunch-Kaufman factorization failed./ERROR STOP, exit code 1). An empty structure is a routine intermediate state in geometry-optimisation or sampling loops, where this is an uncatchable process abort. Checknatoms > 0before calling into the library. - Atomic numbers outside the element data tables (
number < 1ornumber > 118). Upstream maps them to zero-valued filler data, so calculations silently return wrong results (e.g.energy = 0.0) while the error handle stays empty.
The supported preconditions for the input functions are therefore
natoms > 0 and 1 <= numbers[i] <= 118
(see MAX_SUPPORTED_ATOMIC_NUMBER). Note that atomic numbers 104..=111
are reported through the error handle by dftd4_new_d4_model as
“unsupported element” — that channel works as documented.
A third bypass is detectable from Rust and therefore guarded by the
checked constructor: passing a null error handle. Every upstream entry
point that takes the handle checks it first and returns silently when it
is null — dftd4_new_structure yields a null structure handle and the
calculation functions leave their output arguments untouched (a
0.0-initialised energy then looks like a valid “no dispersion” result,
where a real handle gives e.g. -4.4e-4 Eh for the argon dimer used in
the tests). dftd4_check_error reports this only after the fact, with
status 2 — always pass a real handle created by dftd4_new_error.
Dftd4Structure::try_new is a checked variant of dftd4_new_structure
that rejects a null error handle and enforces both preconditions before the
FFI call, returning a catchable Dftd4StructureError instead of letting
the library misbehave.
Structs§
- Dftd4
Error - Safe wrapper for dftd4_error handle that automatically frees on drop
- Dftd4
Model - Safe wrapper for dftd4_model handle that automatically frees on drop
- Dftd4
Param - Safe wrapper for dftd4_param handle that automatically frees on drop
- Dftd4
Structure - Safe wrapper for dftd4_structure handle that automatically frees on drop
- _dftd4_
error - Opaque error handle
- _dftd4_
model - Opaque dispersion model
- _dftd4_
param - Opaque damping parameters
- _dftd4_
structure - Opaque molecular structure data
Enums§
- Dftd4
Structure Error - Input rejected by a checked constructor such as
Dftd4Structure::try_new.
Constants§
- MAX_
SUPPORTED_ ATOMIC_ NUMBER - Largest atomic number covered by the upstream element data tables.
Functions§
- dftd4_
check_ ⚠error - Check error handle status
- dftd4_
custom_ ⚠d4_ model - Create custom D4 dispersion model with parameters
- dftd4_
custom_ ⚠d4s_ model - Create custom D4S dispersion model with parameters
- dftd4_
delete_ ⚠error - Delete error handle object
- dftd4_
delete_ ⚠model - Delete dispersion model
- dftd4_
delete_ ⚠param - Delete damping parameters
- dftd4_
delete_ ⚠structure - Delete molecular structure data
- dftd4_
get_ ⚠dispersion - Evaluate the dispersion energy and its derivatives
- dftd4_
get_ ⚠error - Get error message from error handle.
- dftd4_
get_ ⚠numerical_ hessian - Evaluate the dispersion hessian numerically
- dftd4_
get_ ⚠pairwise_ dispersion - Evaluate the pairwise representation of the dispersion energy
- dftd4_
get_ ⚠properties - Evaluate properties related to the dispersion model
- dftd4_
get_ ⚠version - Obtain library version as major * 10000 + minor * 100 + patch
- dftd4_
load_ ⚠rational_ damping - Load rational damping parameters from internal storage
- dftd4_
new_ ⚠d4_ model - Create new D4 dispersion model
- dftd4_
new_ ⚠d4s_ model - Create new D4S dispersion model
- dftd4_
new_ ⚠error - Create new error handle object
- dftd4_
new_ ⚠rational_ damping - Create new rational damping parameters
- dftd4_
new_ ⚠structure - Create new molecular structure data (quantities in Bohr)
- dftd4_
set_ ⚠model_ realspace_ cutoff - Set realspace cutoffs (quantities in Bohr)
- dftd4_
set_ ⚠model_ realspace_ cutoff_ smooth - Set realspace cutoffs with smoothing widths (quantities in Bohr)
- dftd4_
update_ ⚠structure - Update coordinates and lattice parameters (quantities in Bohr)