Crate dftd3

Expand description

§DFTD3 API specification document entrance

For API users, the most important part of this crate is the interface module. The commonly used functions and structs can be

DFTD3Model: serve as main driver struct for DFTD3.
dftd3_load_param: load parameters with xc-functional and DFT-D3 version specified.
dftd3_parse_damping_param_from_toml: parse damping parameters from TOML string (supports method lookup and overrides). Similar counterpart of json can also found if crate feature json is enabled. Please refer to parsing module for more details and examples.

To specify custom DFT-D3 parameters, some structs you may interest.

DFTD3RationalDampingParam for rational damping;
DFTD3ZeroDampingParam for zero damping;
DFTD3ModifiedRationalDampingParam for modified rational damping;
DFTD3ModifiedZeroDampingParam for modified zero damping;
DFTD3OptimizedPowerDampingParam for optimized power damping.

You may also check DFTD3Param, but note that this struct is somehow low-level API, so use it with more care.

§simple-dftd3 FFI bindings

This project contains simple-dftd3 FFI bindings, wrapper and build-from-source.

Current binding of simple-dftd3:

Source code of simple-dftd3 is available on github.

This crate is not official bindgen project. It is originally intended to potentially serve rust electronic structure toolkit REST.

§Crate `dftd3`

This crate contains simple-dftd3 FFI bindings and wrapper.

Resources	Badges
Crate
API Document
FFI Binding

§Dynamic loading guide

This crate will default to dynamic loading (unless unset cargo feature dynamic_loading). Please refer to module ffi_dynamic for more details of dynamic loading.

§Example: r2SCAN with D3(BJ)

For example, full code for computing r2SCAN dispersion energy with D3(BJ):

use dftd3::prelude::*;

// atom indices
let numbers = vec![6, 6, 6, 6, 6, 6, 53, 1, 1, 1, 1, 1, 16, 1, 6, 1, 1, 1];
// geometry in angstrom
#[rustfmt::skip]
let positions = vec![
    -0.755422531,  -0.796459123,  -1.023590391,
     0.634274834,  -0.880017014,  -1.075233285,
     1.406955202,   0.199695367,  -0.653144334,
     0.798863737,   1.361204515,  -0.180597909,
    -0.593166787,   1.434312023,  -0.133597923,
    -1.376239198,   0.359205222,  -0.553258516,
    -1.514344238,   3.173268101,   0.573601106,
     1.110906949,  -1.778801728,  -1.440619836,
     1.399172302,   2.197767355,   0.147412751,
     2.486417780,   0.142466525,  -0.689380574,
    -2.454252250,   0.422581120,  -0.512807958,
    -1.362353593,  -1.630564523,  -1.348743149,
    -3.112683203,   6.289227834,   1.226984439,
    -4.328789697,   5.797771251,   0.973373089,
    -2.689135032,   6.703163830,  -0.489062886,
    -1.684433029,   7.115457372,  -0.460265708,
    -2.683867206,   5.816530502,  -1.115183775,
    -3.365330613,   7.451201412,  -0.890098894,
];
// convert angstrom to bohr
let positions = positions.iter().map(|&x| x / 0.52917721067).collect::<Vec<f64>>();
// generate DFTD3 model
let model = DFTD3Model::new(&numbers, &positions, None, None);
// retrive the DFTD3 parameters
let param = dftd3_load_param("d3bj", "r2SCAN", false);
// obtain the dispersion energy and gradient
let (energy, gradient, _) = model.get_dispersion(&param, true).into();
let gradient = gradient.unwrap();

println!("Dispersion energy: {}", energy);
let energy_ref = -0.00578401192369041;
assert!((energy - energy_ref).abs() < 1e-9);
println!("Dispersion gradient:");
gradient.chunks(3).for_each(|chunk| println!("{:16.9?}", chunk));

§Example: Custom parameters by toml

use dftd3::prelude::*;
// Use custom parameters by toml string
let input = r#"{version = "d3bj", a1 = 0.3981, s8 = 1.9889, a2 = 4.4211, atm = false}"#;
// You can also use the following input to specify B3LYP-D3(BJ) parameters
// let input = r#"{version = "d3bj", method = "b3lyp"}"#;
// toml parameter type
let damping_param = dftd3_parse_damping_param_from_toml(input);
// FFI parameter type
let dftd3_param = damping_param.new_param();

let atom_charges = vec![8, 1, 1];
// coordinates in bohr
#[rustfmt::skip]
let coordinates = vec![
    0.000000, 0.000000, 0.000000,
    0.000000, 0.000000, 1.807355,
    1.807355, 0.000000, -0.452500,
];
let model = DFTD3Model::new(&atom_charges, &coordinates, None, None);
let res = model.get_dispersion(&dftd3_param, false);
let eng = res.energy;
println!("Dispersion energy: {eng}");

§Cargo features of `dftd3`

Default cargo features of dftd3 are:

api-v0_5: Corresponding to the original simple-dftd3 v0.5. This will enable versions bj, zero, mbj, mzero, op. Note cso and cargo feature gcp are not included in api-v0_5.
dynamic_loading: This will enable dynamic loading of s-dftd3 library, which can be more flexible for users who do not want to perform static linking. Please place libs-dftd3.so in LD_LIBRARY_PATH (for macos, place libs-dftd3.dylib in DYLD_LIBRARY_PATH), and function symbols will be loaded at runtime.

Other cargo features of dftd3 are:

gcp: Support of geometric counterpoise correction. Please note that this is not available in latest stable release of simple-dftd3 (at the time writing this readme, is v1.4.0). Unless you build simple-dftd3 from git repository, you may not use this feature (especially installed simple-dftd3 from conda or similar).
api-v1_3: Corresponding to the original simple-dftd3 v1.3. This will additionally enable versions cso and cargo feature gcp.
json: This will enable JSON parsing for DFTD3 parameters. Note that toml parsing is builtin, and json is an optional feature.

§Installation guide and Crate `dftd3-src`

This crate is only useful for static loading: If you enabled cargo feature dynamic_loading (which is enabled by default), you just need to place libs-dftd3.so in LD_LIBRARY_PATH, or make dftd3 available in your python environment. The library will be loaded at runtime, so you do not need to perform any static loading.

If you need to link s-dftd3 library by static loading (either static linking by libs-dftd3.a or dynamic linking by libs-dftd3.so), proceed to the following instructions.

Resources	Badges
Crate

To use crate dftd3 in rust, you may need to perform some configuration to properly link libs-dftd3.so into your own program.

§Install `s-dftd3`

Please refer to original github repository for more instructions.

The easiest way is install from conda/mamba, and you can retrive the shared/static library therein.

§Manually link `s-dftd3` into your project

Similar to other projects, after library search path properly defined

println!("cargo:rustc-link-search=native={}", path);

you may link s-dftd3 and mctc-lib by cargo instructions in your own project:

// following code is for static linking
println!("cargo:rustc-link-lib=static=s-dftd3");
println!("cargo:rustc-link-lib=static=mctc-lib");
// following code is for dynamic linking
println!("cargo:rustc-link-lib=s-dftd3");
println!("cargo:rustc-link-lib=mctc-lib");

It should be noted that, for static linking, you may also need to dynamic link Fortran and OpenMP libraries (for the library installed by conda or mamba, it is usually gfortran and gomp).

§Link `s-dftd3` by crate `dftd3-src`

You can also link s-dftd3 by crate dftd3-src.

First, in your own project’s lib.rs or main.rs, you need to add a line for explicitly importing this library:

extern crate dftd3_src;

If you have compiled s-dftd3 library, make sure path of it (together with mctc-lib) is either in

DFTD3_DIR
REST_EXT_DIR
LD_LIBRARY_PATH
or in other common system library paths.

If you have not compiled s-dftd3 library, you may try out cargo feature build_from_source, but that can also cause trobule when distributing your program binary, so use with caution.

§Cargo features of `dftd3-src`

build_from_source: This will use CMake and meson, and pull code from github to first perform build for simple-dftd3. Though this option can be developer-friendly (you do not need to perform any other configurations to make program compile and run by cargo), build_from_source does not provide customized compilation.

CMake configurable variables (can be defined as environment variables):
- DFTD3_SRC: git repository source directory or URL;
- DFTD3_VER: version of DFT-D3 (default v1.4.0);
static: This will link static libary instead of dynamic one. Please note that 1. static linking may require additional Fortran and OpenMP linking, which is not provided in this crate; 2. staticly linking LGPL-3.0 license may require your project to be GPL-3.0.

§License

This repository is licensed under LGPL-3.0, the same to simple-dftd3.

Some parts of this project is derivative work of original library simple-dftd3, and contains some source code (headers, toml parameters) and AI-translated/generated code.

Re-exports§

pub use ffi_dynamic as ffi;

Modules§

ffi_dynamic: FFI module for dftd3 (dynamic loading).
interface: DFTD3 interface (safe wrapper).
interface_gcp
parameters: DFTD3 damping parameter database loaded from TOML.
parsing: Flexible parsing of DFT-D3 damping parameters from TOML or JSON input.
prelude: Use dftd3::prelude::* to import all the commonly used structs and functions.

Crate dftd3

Crate dftd3 Copy item path

§DFTD3 API specification document entrance

§simple-dftd3 FFI bindings

§Crate dftd3

§Dynamic loading guide

§Example: r2SCAN with D3(BJ)

§Example: Custom parameters by toml

§Cargo features of dftd3

§Installation guide and Crate dftd3-src

§Install s-dftd3

§Manually link s-dftd3 into your project

§Link s-dftd3 by crate dftd3-src

§Cargo features of dftd3-src

§License

Re-exports§

Modules§

Crate dftd3

§Crate `dftd3`

§Cargo features of `dftd3`

§Installation guide and Crate `dftd3-src`

§Install `s-dftd3`

§Manually link `s-dftd3` into your project

§Link `s-dftd3` by crate `dftd3-src`

§Cargo features of `dftd3-src`