Skip to content

Commit bb8fd83

Browse files
awvwgkawvwgk
authored
Add how-to guide for documentation (#114)
1 parent 2697ac7 commit bb8fd83

File tree

6 files changed

+216
-0
lines changed

6 files changed

+216
-0
lines changed

‎doc/guide/index.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
How-to guides
2+
=============
3+
4+
This section contains guides on how to use D3 for your applications.
5+
6+
.. toctree::
7+
8+
minimal-example

‎doc/guide/minimal-example.rst‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
How to use this library?
2+
========================
3+
4+
This section contains a few self-contained examples on how to use D3.
5+
6+
7+
Compute energy with rational damping
8+
------------------------------------
9+
10+
This example shows how to compute the dispersion energy with the rational damping function.
11+
12+
.. tab-set::
13+
:sync-group: code
14+
15+
.. tab-item:: Fortran
16+
:sync: fortran
17+
18+
.. literalinclude:: minimal-example/energy.f90
19+
:language: fortran
20+
:caption: energy.f90
21+
22+
.. tab-item:: C
23+
:sync: c
24+
25+
.. literalinclude:: minimal-example/energy.c
26+
:language: c
27+
:caption: energy.c
28+
29+
.. tab-item:: Python
30+
:sync: python
31+
32+
.. literalinclude:: minimal-example/energy.py
33+
:language: python
34+
:caption: energy.py
35+
36+
To test this example you can install the dependencies with
37+
38+
.. tab-set::
39+
:sync-group: code
40+
41+
.. tab-item:: Fortran
42+
:sync: fortran
43+
44+
.. code-block:: text
45+
46+
mamba create d3 simple-dftd3 fortran-compiler pkg-config
47+
mamba activate d3
48+
49+
.. tab-item:: C
50+
:sync: c
51+
52+
.. code-block:: text
53+
54+
mamba create d3 simple-dftd3 c-compiler pkg-config
55+
mamba activate d3
56+
57+
.. tab-item:: Python
58+
:sync: python
59+
60+
.. code-block:: text
61+
62+
mamba create d3 dftd3-python
63+
mamba activate d3
64+
65+
You can run the example code with
66+
67+
.. tab-set::
68+
:sync-group: code
69+
70+
.. tab-item:: Fortran
71+
:sync: fortran
72+
73+
.. code-block:: shell
74+
75+
❯ $FC energy.f90 $(pkg-config s-dftd3 mctc-lib --cflags --libs) && ./a.out
76+
Dispersion energy for PBE0-D3(BJ) is -0.0009218696 Hartree
77+
78+
.. tab-item:: C
79+
:sync: c
80+
81+
.. code-block:: shell
82+
83+
❯ $CC energy.c $(pkg-config s-dftd3 mctc-lib --cflags --libs) && ./a.out
84+
Dispersion energy for PBE0-D3(BJ) is -0.0009218696 Hartree
85+
86+
.. tab-item:: Python
87+
:sync: python
88+
89+
.. code-block:: shell
90+
91+
❯ python energy.py
92+
Dispersion energy for PBE0-D3(BJ) is -0.0009218696 Hartree
93+

‎doc/guide/minimal-example/energy.c‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
#include <stdio.h>
2+
#include <stdbool.h>
3+
4+
#include "dftd3.h"
5+
6+
int main(void)
7+
{
8+
dftd3_error error = dftd3_new_error();
9+
dftd3_structure mol = NULL;
10+
dftd3_model d3 = NULL;
11+
dftd3_param param = NULL;
12+
13+
int nat = 5;
14+
int num[5] = {6, 1, 1, 1, 1};
15+
double xyz[15] = { // coordinates in Bohr
16+
0.0000000, -0.0000000, 0.0000000,
17+
-1.1922080, 1.1922080, 1.1922080,
18+
1.1922080, -1.1922080, 1.1922080,
19+
-1.1922080, -1.1922080, -1.1922080,
20+
1.1922080, 1.1922080, -1.1922080};
21+
mol = dftd3_new_structure(error, nat, num, xyz, NULL, NULL);
22+
if (dftd3_check_error(error)) goto handle_error;
23+
24+
char method[5] = "PBE0";
25+
param = dftd3_load_rational_damping(error, method, false);
26+
if (dftd3_check_error(error)) goto handle_error;
27+
28+
d3 = dftd3_new_d3_model(error, mol);
29+
if (dftd3_check_error(error)) goto handle_error;
30+
31+
double energy;
32+
dftd3_get_dispersion(error, mol, d3, param, &energy, NULL, NULL);
33+
if (dftd3_check_error(error)) goto handle_error;
34+
35+
printf("Dispersion energy for %s-D3(BJ) is %13.10lf Hartree\n", method, energy);
36+
37+
dftd3_delete(error);
38+
dftd3_delete(mol);
39+
dftd3_delete(d3);
40+
dftd3_delete(param);
41+
return 0;
42+
43+
handle_error:
44+
char msg[512];
45+
dftd3_get_error(error, msg, NULL);
46+
printf("Error: %s\n", msg);
47+
48+
dftd3_delete(error);
49+
dftd3_delete(mol);
50+
dftd3_delete(d3);
51+
dftd3_delete(param);
52+
return 1;
53+
}

‎doc/guide/minimal-example/energy.f90‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
program test_simple_d3
2+
use, intrinsic :: iso_fortran_env, only : r8 => real64
3+
use mctc_env, only: error_type
4+
use mctc_io, only: structure_type, new
5+
use dftd3, only: d3_model, d3_param, rational_damping_param, get_rational_damping, &
6+
& new_rational_damping, new_d3_model, get_dispersion, realspace_cutoff
7+
implicit none
8+
9+
character(len=:), allocatable :: method
10+
type(structure_type) :: mol
11+
type(error_type), allocatable :: error
12+
integer, allocatable :: num(:)
13+
real(r8), allocatable :: xyz(:, :)
14+
real(r8) :: energy
15+
16+
type(d3_model) :: disp
17+
type(d3_param) :: inp
18+
type(rational_damping_param) :: param
19+
20+
method = 'PBE0'
21+
num = [6, 1, 1, 1, 1]
22+
xyz = reshape([ & ! coordinates in Bohr
23+
& 0.0000000_r8, -0.0000000_r8, 0.0000000_r8, &
24+
& -1.1922080_r8, 1.1922080_r8, 1.1922080_r8, &
25+
& 1.1922080_r8, -1.1922080_r8, 1.1922080_r8, &
26+
& -1.1922080_r8, -1.1922080_r8, -1.1922080_r8, &
27+
& 1.1922080_r8, 1.1922080_r8, -1.1922080_r8],&
28+
& [3, size(num)])
29+
call new(mol, num, xyz, charge=0.0_r8, uhf=0)
30+
31+
call get_rational_damping(inp, method, error, s9=1.0_r8)
32+
if (allocated(error)) then
33+
print '(2a)', "Error: ", error%message
34+
return
35+
end if
36+
call new_rational_damping(param, inp)
37+
call new_d3_model(disp, mol)
38+
39+
call get_dispersion(mol, disp, param, realspace_cutoff(), energy)
40+
print '(3a, f13.10, a)', 'Dispersion energy for ', method, '-D3(BJ) is ', energy, ' Hartree'
41+
42+
end program test_simple_d3

‎doc/guide/minimal-example/energy.py‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import numpy as np
2+
from dftd3.interface import RationalDampingParam, DispersionModel
3+
4+
num = np.array([6, 1, 1, 1, 1])
5+
xyz = np.array( # coordinates in Bohr
6+
[
7+
[ 0.0000000, -0.0000000, 0.0000000],
8+
[-1.1922080, 1.1922080, 1.1922080],
9+
[ 1.1922080, -1.1922080, 1.1922080],
10+
[-1.1922080, -1.1922080, -1.1922080],
11+
[ 1.1922080, 1.1922080, -1.1922080],
12+
]
13+
)
14+
method = "PBE0"
15+
16+
model = DispersionModel(num, xyz)
17+
res = model.get_dispersion(RationalDampingParam(method=method), grad=False)
18+
print(f"Dispersion energy for {method}-D3(BJ) is {res['energy']:13.10f} Hartree")

‎doc/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,10 @@ The *s-dftd3* project aims to provide a user-friendly and uniform interface to t
88
.. _s-dftd3: https://github.com/dftd3/simple-dftd3
99

1010
.. toctree::
11+
:maxdepth: 2
1112

1213
Installation <installation>
1314
Tutorial <tutorial/index>
15+
How-to <guide/index>
1416
Comparison <comparison>
1517
API <api/index>

0 commit comments

Comments
 (0)