Skip to content

Commit 1961f9e

Browse files
awvwgkawvwgk
committed
Create detailed documentation
- update handling of parameter constructors in Python
1 parent d7a382b commit 1961f9e

18 files changed

Lines changed: 1382 additions & 295 deletions

‎.github/workflows/build.yml‎

Lines changed: 246 additions & 191 deletions
Large diffs are not rendered by default.

‎.github/workflows/docs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,5 +19,5 @@ jobs:
1919
with:
2020
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
2121
BRANCH: gh-pages
22-
FOLDER: docs
22+
FOLDER: ford-docs
2323
CLEAN: true

‎doc/_static/references.bib‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
@article{grimme2010,
2+
author = {S. Grimme and J. Antony and S. Ehrlich and H. Krieg},
3+
title = {A consistent and accurate ab initio parametrization of density functional
4+
dispersion correction ({DFT-D}) for the 94 elements {H-Pu}},
5+
journal = {J. Chem. Phys.},
6+
year = {2010},
7+
volume = {132},
8+
pages = {154104},
9+
doi = {10.1063/1.3382344},
10+
url = {https://aip.scitation.org/doi/full/10.1063/1.3382344}
11+
}
12+
13+
@article{grimme2011,
14+
author = {S. Grimme and S. Ehrlich and L. Goerigk},
15+
title = {Effect of the Damping Function in Dispersion Corrected Density Functional
16+
Theory},
17+
journal = {J. Comput. Chem.},
18+
year = {2011},
19+
volume = {32},
20+
pages = {1456-1465},
21+
doi = {10.1002/jcc.21759},
22+
url = {https://onlinelibrary.wiley.com/doi/abs/10.1002/jcc.21759}
23+
}
24+
25+
@article{smith2016,
26+
title={Revised damping parameters for the D3 dispersion correction to density functional theory},
27+
author={Smith, Daniel GA and Burns, Lori A and Patkowski, Konrad and Sherrill, C David},
28+
journal={J. Phys. Chem. Lett.},
29+
volume={7},
30+
number={12},
31+
pages={2197--2203},
32+
year={2016},
33+
publisher={ACS Publications},
34+
url={https://doi.org/10.1021/acs.jpclett.6b00780},
35+
doi={10.1021/acs.jpclett.6b00780}
36+
}
37+
38+
@article{chai2008,
39+
title={Long-range corrected hybrid density functionals with damped atom--atom dispersion corrections},
40+
author={Chai, Jeng-Da and Head-Gordon, Martin},
41+
journal={Physical Chemistry Chemical Physics},
42+
volume={10},
43+
number={44},
44+
pages={6615--6620},
45+
year={2008},
46+
publisher={Royal Society of Chemistry},
47+
doi={10.1039/B810189B},
48+
url={https://pubs.rsc.org/en/content/articlelanding/2008/CP/b810189b}
49+
}
50+
51+
@article{johnson2006,
52+
title={A post-Hartree-Fock model of intermolecular interactions: Inclusion of higher-order corrections},
53+
author={Johnson, Erin R and Becke, Axel D},
54+
journal={J. Chem. Phys.},
55+
volume={124},
56+
number={17},
57+
pages={174104},
58+
year={2006},
59+
publisher={American Institute of Physics},
60+
url={https://aip.scitation.org/doi/10.1063/1.2190220},
61+
doi={10.1063/1.2190220}
62+
}
63+
64+
@article{johnson2005,
65+
title={A post-Hartree--Fock model of intermolecular interactions},
66+
author={Johnson, Erin R and Becke, Axel D},
67+
journal={J. Chem. Phys.},
68+
volume={123},
69+
number={2},
70+
pages={024101},
71+
year={2005},
72+
publisher={American Institute of Physics},
73+
url={https://aip.scitation.org/doi/10.1063/1.1949201},
74+
doi={10.1063/1.1949201}
75+
}
76+
77+
@article{becke2005,
78+
title={A density-functional model of the dispersion interaction},
79+
author={Becke, Axel D and Johnson, Erin R},
80+
journal={J. Chem. Phys.},
81+
volume={123},
82+
number={15},
83+
pages={154101},
84+
year={2005},
85+
publisher={American Institute of Physics},
86+
url={https://aip.scitation.org/doi/10.1063/1.2065267},
87+
doi={10.1063/1.2065267}
88+
}
89+

‎doc/api/c.rst‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
C API
2+
=====
3+
4+
The C API bindings are provided by using the ``iso_c_binding`` intrinsic module.
5+
Generally, objects are exported as opaque pointers and can only be manipulated within the library.
6+
The API user is required delete all objects created in the library by using the provided deconstructor functions to avoid mamory leaks.
7+
8+
Overall four classes of objects are provided by the library
9+
10+
- error handlers (``dftd3_error``),
11+
used to communicate exceptional conditions and errors from the library to the user
12+
- structure containers (``dftd3_structure``),
13+
used to represent the system specific information and geometry data,
14+
only the latter are mutable for the user
15+
- dispersion model objects (``dftd3_model``),
16+
general model for calculating dispersion releated properties
17+
- damping function objects (``dftd3_param``)
18+
polymorphic objects to represent the actual method parametrisation
19+
20+
.. note::
21+
22+
Generally, all quantities provided to the library are assumed to be in `atomic units <https://en.wikipedia.org/wiki/Hartree_atomic_units>`_.
23+
24+
.. contents::
25+
26+
27+
Error handling
28+
--------------
29+
30+
The library provides a light error handle type (``dftd3_error``) for storing error information
31+
The error handle requires only small overhead to construct and can only contain a single error.
32+
33+
The handler is represented by an opaque pointer and can only be manipulated by call from the library.
34+
The user of those objects is required to delete the handlers again using the library provided deconstructors to avoid memory leaks.
35+
36+
37+
Structure data
38+
--------------
39+
40+
The structure data is used to represent the system of interest in the library.
41+
It contains immutable system specific information like the number of atoms, the unique atom groups and the boundary conditions as well as mutable geometry data like cartesian coordinates and lattice parameters.
42+
43+
44+
Performing calculations
45+
-----------------------
46+
47+
An example wrapper to perform a DFT-D3(BJ)-ATM calculation is shown below.
48+
49+
50+
.. code-block:: c
51+
52+
#include <stdbool.h>
53+
#include <stdio.h>
54+
#include <stdlib.h>
55+
56+
#include "dftd3.h"
57+
58+
static const buffersize = 512;
59+
60+
int
61+
calc_dftd3(int natoms, int* numbers, double* positions,
62+
double* lattice, bool* periodic, char* method,
63+
double* energy, double* gradient, double* sigma)
64+
{
65+
// Local API objects from the s-dftd3 library
66+
dftd3_error error = dftd3_new_error();
67+
dftd3_structure mol = NULL;
68+
dftd3_model disp = NULL;
69+
dftd3_param param = NULL;
70+
int stat = EXIT_SUCCESS;
71+
72+
// Create a new geometry for the library to work with
73+
mol = dftd3_new_structure(error, natoms, numbers, positions, lattice, periodic);
74+
stat = dftd3_check_error(error);
75+
76+
if (stat) {
77+
// Initialize the D3 dispersion model for the given structure,
78+
// this step depends on the atomic numbers, but not on the actual geometry
79+
disp = dftd3_new_d3_model(error, mol);
80+
stat = dftd3_check_error(error);
81+
}
82+
83+
if (stat) {
84+
// Load D3(BJ)-ATM parameters for the given method from internal storage,
85+
// this step depends on the atomic numbers, but not on the actual geometry
86+
param = dftd3_load_rational_damping(error, mol, method, true);
87+
stat = dftd3_check_error(error);
88+
}
89+
90+
if (stat) {
91+
// Evaluate the dispersion energy, gradient and virial,
92+
// the gradient and virial are optional and can be replaced by NULL
93+
dftd3_get_dispersion(error, mol, disp, param, &energy, gradient, sigma);
94+
stat = dftd3_check_error(error);
95+
}
96+
97+
if (!stat) {
98+
char buffer[buffersize];
99+
dftd3_get_error(error, buffer, buffersize);
100+
printf("[Error] %s\n", buffer);
101+
}
102+
103+
// Always free the used memory
104+
dftd3_delete_error(&error);
105+
dftd3_delete_structure(&mol);
106+
dftd3_delete_model(&disp);
107+
dftd3_delete_param(&param);
108+
109+
return stat;
110+
}

‎doc/api/fortran.rst‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
Fortran API
2+
===========
3+
4+
The *s-dftd3* library seamlessly integrates with other Fortran projects via module interfaces,
5+
6+
.. note::
7+
8+
Generally, all quantities used in the library are stored in `atomic units <https://en.wikipedia.org/wiki/Hartree_atomic_units>`_.
9+
10+
.. contents::
11+
12+
13+
Handling of geometries and structure
14+
------------------------------------
15+
16+
The basic infrastructure to handle molecular and periodic structures is provided by the `modular computation tool chain library <https://github.com/grimme-lab/mctc-lib>`_.
17+
The library provides a structure type which is used to represent all geometry related informations in *s-dftd3*.
18+
A structure type can be constructed from arrays or read from a file.
19+
20+
The constructor is provided with the generic interface ``new`` and takes an array of atomic numbers (``integer``) or element symbols (``character(len=*)``) as well as the cartesian coordinates in Bohr.
21+
Additionally, the molecular charge and the number of unpaired electrons can be provided the ``charge`` and ``uhf`` keyword, respectively.
22+
To create a periodic structure the lattice parameters can be passed as 3 by 3 matrix with the ``lattice`` keyword.
23+
24+
An example for using the constructor is given here
25+
26+
.. code-block:: fortran
27+
28+
subroutine example
29+
use mctc_env, only : wp
30+
use mctc_io, only : structure_type, new
31+
implicit none
32+
type(structure_type) :: mol
33+
real(wp), allocatable :: xyz(:, :)
34+
integer, allocatable :: num(:)
35+
36+
num = [6, 1, 1, 1, 1]
37+
xyz = reshape([ &
38+
& 0.00000000000000_wp, -0.00000000000000_wp, 0.00000000000000_wp, &
39+
& -1.19220800552211_wp, 1.19220800552211_wp, 1.19220800552211_wp, &
40+
& 1.19220800552211_wp, -1.19220800552211_wp, 1.19220800552211_wp, &
41+
& -1.19220800552211_wp, -1.19220800552211_wp, -1.19220800552211_wp, &
42+
& 1.19220800552211_wp, 1.19220800552211_wp, -1.19220800552211_wp],&
43+
& [3, size(num)])
44+
45+
call new(mol, num, xyz, charge=0.0_wp, uhf=0)
46+
47+
! ...
48+
end subroutine example
49+
50+
51+
To interact with common input file formats for structures the ``read_structure`` procedure is available.
52+
The file type is inferred from the name of the file automatically or if a file type hint is provided directly from the enumerator of available file types.
53+
The ``read_structure`` routine can also use an already opened unit, but in this case the file type hint is mandatory to select the correct format to read from.
54+
55+
.. code-block:: fortran
56+
57+
subroutine example
58+
use mctc_env, only : error_type
59+
use mctc_io, only : structure_type, read_structure, file_type
60+
implicit none
61+
type(structure_type) :: mol
62+
type(error_type), allocatable :: error
63+
character(len=:), allocatable :: input
64+
65+
input = "struc.xyz"
66+
67+
call read_structure(mol, input, error, file_type%xyz)
68+
if (allocated(error)) then
69+
print '(a)', error%message
70+
stop 1
71+
end if
72+
73+
! ...
74+
end subroutine example
75+
76+
77+
The structure type as well as the error type are using only allocatable members and can therefore be used without requiring explicit deconstruction.
78+
79+
Certain members of the structure type should be considered immutable, like the number of atoms (``nat``), the identifiers for unique atoms (``id``) and the boundary conditions (``periodic``).
80+
To change those specific structure parameters the structure type and all dependent objects should be reconstructed to ensure a consistent setup.
81+
Other properties, like the geometry (``xyz``), molecular charge (``charge``), number of unpaired electrons (``uhf``) and lattice parameters (``lattice``) can be changed without requiring to reconstruct dependent objects like calculators or restart data.
82+
83+
84+
Error handling
85+
--------------
86+
87+
The basic error handler is an allocatable derived type, available from ``mctc_env`` as ``error_type``, which signals an error by its allocation status.
88+
89+
.. code-block:: fortran
90+
91+
use mctc_env, only : error_type, fatal_error
92+
implicit none
93+
type(error_type), allocatable :: error
94+
95+
call always_ok(error)
96+
if (allocated(error)) then
97+
print '(a)', "Unexpected failure:", error%message
98+
end if
99+
100+
call always_failed(error)
101+
if (allocated(error)) then
102+
print '(a)', "Error:", error%message
103+
end if
104+
105+
contains
106+
subroutine always_ok(error)
107+
type(error_type), allocatable, intent(out) :: error
108+
end subroutine always_ok
109+
110+
subroutine always_failed(error)
111+
type(error_type), allocatable, intent(out) :: error
112+
113+
call fatal_error(error, "Message associated with this error")
114+
end subroutine always_failed
115+
end
116+
117+
An unhandled error might get dropped by the next procedure call.
118+
119+
120+
Performing calculations
121+
-----------------------
122+
123+
An example for performing a calculation with DFT-D3(BJ)-ATM is shown below
124+
125+
.. code-block:: fortran
126+
127+
subroutine calc_dftd3(mol, method, energy, gradient, sigma, error)
128+
use mctc_env
129+
use mctc_io
130+
use dftd3
131+
type(structure_type), intent(in) :: mol
132+
character(len=*), intent(in) :: method
133+
real(wp), intent(out) :: energy
134+
real(wp), intent(out) :: gradient(:, :)
135+
real(wp), intent(out) :: sigma(:, :)
136+
type(error_type), allocatable, intent(out) :: error
137+
type(d3_model) :: disp
138+
type(d3_param) :: inp
139+
class(damping_param), allocatable :: param
140+
141+
call get_rational_damping(inp, method, error, s9=1.0_wp)
142+
if (allocated(error)) return
143+
call new_rational_damping(param, inp, mol)
144+
145+
call new_d3_model(disp, mol)
146+
147+
call get_dispersion(mol, disp, param, realspace_cutoff(), energy, &
148+
& gradient, sigma)
149+
150+
end subroutine calc_dftd3

‎doc/api/index.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.. _api:
2+
3+
Public API documentation
4+
========================
5+
6+
This DFT-D3 implementation provides first class API support Fortran, C and Python.
7+
Other programming languages should try to interface via one of those three APIs.
8+
To provide first class API support for a new language the interface specification should be available as meson build files.
9+
10+
.. toctree::
11+
12+
fortran
13+
c
14+
python
15+

0 commit comments

Comments
 (0)