Github action for testing

.github/workflows/test-dftd3-src.yml

@@ -0,0 +1,54 @@
+name: test-dftd3-src
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-static:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: run tests directly
+        run: |
+          cd dftd3-src
+          export DFTD3_SRC_DEV=1
+          cargo test --test "*" -vv --features="build_from_source static" -- --nocapture
+
+  build-dynamic:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: run tests directly
+        run: |
+          cd dftd3-src
+          cargo test --test "*" -vv --features="build_from_source" -- --nocapture
+
+  external-static:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: conda-incubator/setup-miniconda@v3
+      - name: run tests directly
+        run: |
+          cd dftd3-src
+          conda install dftd3-python -c conda-forge
+          ls /usr/share/miniconda/lib
+          export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/share/miniconda/lib
+          export DFTD3_SRC_DEV=1
+          cargo test --test "*" -vv --features="static" -- --nocapture
+
+  external-dynamic:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: conda-incubator/setup-miniconda@v3
+      - name: run tests directly
+        run: |
+          cd dftd3-src
+          conda install dftd3-python -c conda-forge
+          ls /usr/share/miniconda/lib
+          export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/share/miniconda/lib
+          cargo test --test "*" -vv -- --nocapture

.github/workflows/test-dftd3.yml

@@ -0,0 +1,23 @@
+name: test-dftd3
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test-from-miniconda:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: conda-incubator/setup-miniconda@v3
+      - name: run tests directly
+        run: |
+          cd dftd3
+          conda install dftd3-python -c conda-forge
+          ls /usr/share/miniconda/lib
+          export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/share/miniconda/lib
+          export DFTD3_DEV=1
+          cargo test
+          cargo test --examples

dftd3-src/build.rs

@@ -83,8 +83,11 @@ fn main() {
     if cfg!(feature = "static") {
         println!("cargo:rustc-link-lib=static=s-dftd3");
         println!("cargo:rustc-link-lib=static=mctc-lib");
-        println!("cargo:rerun-if-env-changed=DFTD3_DEV_LINUX");
-        if std::env::var("DFTD3_DEV_LINUX").is_ok() {
+        // static linking may requires gomp and gfortran to be dynamically linked
+        // but that depends on the compiler and the system, so user should take care
+        // of that. We just provide a hint here.
+        println!("cargo:rerun-if-env-changed=DFTD3_SRC_DEV");
+        if std::env::var("DFTD3_SRC_DEV").is_ok() {
             println!("cargo:rustc-link-lib=gomp");
             println!("cargo:rustc-link-lib=gfortran");
         }

dftd3-src/src/lib.rs

@@ -1 +1,6 @@
+//! simple-dftd3 build-from-source or library selection
+//!
+//! This module is only used for rust-side configuration of library linking.
+//! Please see the following document for more details.
+#![doc = include_str!("../readme.md")]
 #![no_std]

dftd3/examples/energy_r2scan_d3zero.rs

@@ -31,6 +31,8 @@ fn main_test() {
     let model = DFTD3Model::new(&numbers, &positions, None, None);
     // explicitly set DFTD3 parameters
     for atm in [true, false] {
+        let energy_ref = if atm { -0.01410721853585842 } else { -0.014100267345314462 };
+
         let param = DFTD3ZeroDampingParamBuilder::default()
             .s8(1.683)
             .rs6(1.139)
@@ -40,7 +42,37 @@ fn main_test() {
         let (energy, _, _) = model.get_dispersion(&param, false).into();
 
         println!("Dispersion energy: {}", energy);
-        let energy_ref = if atm { -0.01410721853585842 } else { -0.014100267345314462 };
+        assert!((energy - energy_ref).abs() < 1e-9);
+
+        // this way to provide custom damping parameter is also valid
+        let param = DFTD3ZeroDampingParam {
+            s6: 1.0,
+            s8: 1.683,
+            rs6: 1.139,
+            rs8: 1.0,
+            alp: 14.0,
+            s9: if atm { 1.0 } else { 0.0 },
+        };
+        let param = param.new_param();
+        // obtain the dispersion energy without gradient and sigma
+        let (energy, _, _) = model.get_dispersion(&param, false).into();
+
+        println!("Dispersion energy: {}", energy);
+        assert!((energy - energy_ref).abs() < 1e-9);
+
+        // this way to provide custom damping parameter is also valid
+        let param = DFTD3Param::new_zero_damping(
+            1.0,                         // s6
+            1.683,                       // s8
+            if atm { 1.0 } else { 0.0 }, // s9
+            1.139,                       // rs6
+            1.0,                         // rs8
+            14.0,                        // alp
+        );
+        // obtain the dispersion energy without gradient and sigma
+        let (energy, _, _) = model.get_dispersion(&param, false).into();
+
+        println!("Dispersion energy: {}", energy);
         assert!((energy - energy_ref).abs() < 1e-9);
     }
 }

dftd3/src/damping_param_usage.md

@@ -0,0 +1,52 @@
+# Common API documentation for custom damping parameter specification
+
+If your task is to retrive damping parameters of some specific xc-functionals, you may wish to try [`dftd3_load_param`] function.
+
+In this crate, you may have three ways to define customized parameters:
+
+- By `DFTD3***DampingParam` struct. In this way, all parameters (include optional parameters with default value) must be provided. For example of B3-Zero:
+
+    ```rust
+  # use dftd3::prelude::*;
+  # let atm = true;
+    let param = DFTD3ZeroDampingParam {
+        s6: 1.0,
+        s8: 1.683,
+        rs6: 1.139,
+        rs8: 1.0,
+        alp: 14.0,
+        s9: if atm { 1.0 } else { 0.0 },
+    };
+    let param = param.new_param();
+    // this will give param: DFTD3Param
+    ```
+
+- By `DFTD3***DampingParamBuilder` struct. In this way, optional parameters can be omitted. For example of B3-Zero:
+
+    ```rust
+  # use dftd3::prelude::*;
+  # let atm = true;
+    let param = DFTD3ZeroDampingParamBuilder::default()
+        .s8(1.683)
+        .rs6(1.139)
+        .s9(if atm { 1.0 } else { 0.0 })
+        .init();
+    // this will give param: DFTD3Param
+    ```
+
+- By `DFTD3Param` utility. In this way, all parameters must be provided. For example of B3-Zero:
+
+    ```rust
+  # use dftd3::prelude::*;
+  # let atm = true;
+    let param = DFTD3Param::new_zero_damping(
+        1.0,                         // s6
+        1.683,                       // s8
+        if atm { 1.0 } else { 0.0 }, // s9
+        1.139,                       // rs6
+        1.0,                         // rs8
+        14.0,                        // alp
+    );
+    ```
+
+Please note that different DFT-D3 versions may have different parameters, for example modified zero damping have another parameter `bet` for beta, and rational damping (D3-BJ) have parameter name `a1`, `a2` instead of `rs6`, `rs8`.