Skip to main content

Crate dftd4_sys

Crate dftd4_sys 

Source
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_structure accepts them without setting the error handle, dftd4_new_d4_model builds a model for the empty structure, and the first calculation (e.g. dftd4_get_dispersion) then terminates the host process with a Fortran error 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. Check natoms > 0 before calling into the library.
  • Atomic numbers outside the element data tables (number < 1 or number > 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§

Dftd4Error
Safe wrapper for dftd4_error handle that automatically frees on drop
Dftd4Model
Safe wrapper for dftd4_model handle that automatically frees on drop
Dftd4Param
Safe wrapper for dftd4_param handle that automatically frees on drop
Dftd4Structure
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§

Dftd4StructureError
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)

Type Aliases§

dftd4_error
dftd4_model
dftd4_param
dftd4_structure