From 09a6402783a964c5f0960f0937d7ede09f8c8bc1 Mon Sep 17 00:00:00 2001 From: Anthony Scemama Date: Thu, 5 Nov 2020 15:34:58 +0100 Subject: [PATCH] Better org-mode for documentation --- src/README.org | 175 ++++++++-------- src/qmckl.org | 56 +++--- src/qmckl_ao.org | 306 ++++++++++++++-------------- src/qmckl_context.org | 446 ++++++++++++++++++++--------------------- src/qmckl_distance.org | 126 ++++++------ src/qmckl_footer.org | 5 + src/qmckl_memory.org | 86 ++++---- src/test_qmckl.org | 81 ++++---- 8 files changed, 635 insertions(+), 646 deletions(-) diff --git a/src/README.org b/src/README.org index 3601733..7ea4694 100644 --- a/src/README.org +++ b/src/README.org @@ -93,126 +93,117 @@ rm ${nb}.md Coding style can be automatically checked with [[https://clang.llvm.org/docs/ClangFormat.html][clang-format]]. -* Design of the library +** Design of the library - The proposed API should allow the library to: - - deal with memory transfers between CPU and accelerators - - use different levels of floating-point precision + The proposed API should allow the library to: + - deal with memory transfers between CPU and accelerators + - use different levels of floating-point precision - We chose a multi-layered design with low-level and high-level - functions (see below). + We chose a multi-layered design with low-level and high-level + functions (see below). -** Naming conventions +*** Naming conventions - Use =qmckl_= as a prefix for all exported functions and variables. - All exported header files should have a filename with the prefix - =qmckl_=. + Use =qmckl_= as a prefix for all exported functions and variables. + All exported header files should have a filename with the prefix + =qmckl_=. - If the name of the org-mode file is =xxx.org=, the name of the - produced C files should be =xxx.c= and =xxx.h= and the name of the - produced Fortran files should be =xxx.f90= + If the name of the org-mode file is =xxx.org=, the name of the + produced C files should be =xxx.c= and =xxx.h= and the name of the + produced Fortran files should be =xxx.f90= - Arrays are in uppercase and scalars are in lowercase. + Arrays are in uppercase and scalars are in lowercase. -** Application programming interface +*** Application programming interface - The application programming interface (API) is designed to be - compatible with the C programming language (not C++), to ensure - that the library will be easily usable in any language. - This implies that only the following data types are allowed in the API: + The application programming interface (API) is designed to be + compatible with the C programming language (not C++), to ensure + that the library will be easily usable in any language. + This implies that only the following data types are allowed in the API: - - 32-bit and 64-bit floats and arrays (=real= and =double=) - - 32-bit and 64-bit integers and arrays (=int32_t= and =int64_t=) - - Pointers should be represented as 64-bit integers (even on - 32-bit architectures) - - ASCII strings are represented as a pointers to a character arrays - and terminated by a zero character (C convention). + - 32-bit and 64-bit floats and arrays (=real= and =double=) + - 32-bit and 64-bit integers and arrays (=int32_t= and =int64_t=) + - Pointers should be represented as 64-bit integers (even on + 32-bit architectures) + - ASCII strings are represented as a pointers to a character arrays + and terminated by a zero character (C convention). - Complex numbers can be represented by an array of 2 floats. + Complex numbers can be represented by an array of 2 floats. - # TODO : Link to repositories for bindings - To facilitate the use in other languages than C, we provide some - bindings in other languages in other repositories. + # TODO : Link to repositories for bindings + To facilitate the use in other languages than C, we provide some + bindings in other languages in other repositories. -** Global state +*** Global state - Global variables should be avoided in the library, because it is - possible that one single program needs to use multiple instances of - the library. To solve this problem we propose to use a pointer to a - =context= variable, built by the library with the - =qmckl_context_create= function. The =context= contains the global - state of the library, and is used as the first argument of many - QMCkl functions. + Global variables should be avoided in the library, because it is + possible that one single program needs to use multiple instances of + the library. To solve this problem we propose to use a pointer to a + =context= variable, built by the library with the + =qmckl_context_create= function. The =context= contains the global + state of the library, and is used as the first argument of many + QMCkl functions. - Modifying the state is done by setters and getters, prefixed - by =qmckl_context_set_= an =qmckl_context_get_=. - When a context variable is modified by a setter, a copy of the old - data structure is made and updated, and the pointer to the new data - structure is returned, such that the old contexts can still be - accessed. - It is also possible to modify the state in an impure fashion, using - the =qmckl_context_update_= functions. - The context and its old versions can be destroyed with - =qmckl_context_destroy=. + Modifying the state is done by setters and getters, prefixed + by =qmckl_context_set_= an =qmckl_context_get_=. + When a context variable is modified by a setter, a copy of the old + data structure is made and updated, and the pointer to the new data + structure is returned, such that the old contexts can still be + accessed. + It is also possible to modify the state in an impure fashion, using + the =qmckl_context_update_= functions. + The context and its old versions can be destroyed with + =qmckl_context_destroy=. -** Low-level functions +*** Low-level functions - Low-level functions are very simple functions which are leaves of the - function call tree (they don't call any other QMCkl function). + Low-level functions are very simple functions which are leaves of the + function call tree (they don't call any other QMCkl function). - This functions are /pure/, and unaware of the QMCkl =context=. They are - not allowed to allocate/deallocate memory, and if they need - temporary memory it should be provided in input. + This functions are /pure/, and unaware of the QMCkl =context=. They are + not allowed to allocate/deallocate memory, and if they need + temporary memory it should be provided in input. -** High-level functions +*** High-level functions - High-level functions are at the top of the function call tree. - They are able to choose which lower-level function to call - depending on the required precision, and do the corresponding type - conversions. - These functions are also responsible for allocating temporary - storage, to simplify the use of accelerators. + High-level functions are at the top of the function call tree. + They are able to choose which lower-level function to call + depending on the required precision, and do the corresponding type + conversions. + These functions are also responsible for allocating temporary + storage, to simplify the use of accelerators. - The high-level functions should be pure, unless the introduction of - non-purity is justified. All the side effects should be made in the - =context= variable. + The high-level functions should be pure, unless the introduction of + non-purity is justified. All the side effects should be made in the + =context= variable. - # TODO : We need an identifier for impure functions + # TODO : We need an identifier for impure functions -** Numerical precision +*** Numerical precision - The number of bits of precision required for a function should be - given as an input of low-level computational functions. This input will - be used to define the values of the different thresholds that might - be used to avoid computing unnecessary noise. - High-level functions will use the precision specified in the - =context= variable. + The number of bits of precision required for a function should be + given as an input of low-level computational functions. This input will + be used to define the values of the different thresholds that might + be used to avoid computing unnecessary noise. + High-level functions will use the precision specified in the + =context= variable. -* Algorithms +** Algorithms - Reducing the scaling of an algorithm usually implies also reducing - its arithmetic complexity (number of flops per byte). Therefore, - for small sizes \(\mathcal{O}(N^3)\) and \(\mathcal{O}(N^2)\) algorithms - are better adapted than linear scaling algorithms. - As QMCkl is a general purpose library, multiple algorithms should - be implemented adapted to different problem sizes. + Reducing the scaling of an algorithm usually implies also reducing + its arithmetic complexity (number of flops per byte). Therefore, + for small sizes \(\mathcal{O}(N^3)\) and \(\mathcal{O}(N^2)\) algorithms + are better adapted than linear scaling algorithms. + As QMCkl is a general purpose library, multiple algorithms should + be implemented adapted to different problem sizes. -* Rules for the API +** Rules for the API - - =stdint= should be used for integers (=int32_t=, =int64_t=) - - integers used for counting should always be =int64_t= - - floats should be by default =double=, unless explicitly mentioned - - pointers are converted to =int64_t= to increase portability + - =stdint= should be used for integers (=int32_t=, =int64_t=) + - integers used for counting should always be =int64_t= + - floats should be by default =double=, unless explicitly mentioned + - pointers are converted to =int64_t= to increase portability * Documentation - - [[./qmckl.org][Main QMCkl header file]] - - [[./qmckl_memory.org][Memory management]] - - [[./qmckl_context.org][Context]] - - [[./qmckl_distance.org][Distance]] - - [[./qmckl_ao.org][Atomic orbitals]] -* Acknowledgments - - [[https://trex-coe.eu/sites/default/files/inline-images/euflag.jpg]] - [[https://trex-coe.eu][TREX: Targeting Real Chemical Accuracy at the Exascale]] project has received funding from the European Union’s Horizon 2020 - Research and Innovation program - under grant agreement no. 952165. The content of this document does not represent the opinion of the European Union, and the European Union is not responsible for any use that might be made of such content. diff --git a/src/qmckl.org b/src/qmckl.org index ad77abd..7620883 100644 --- a/src/qmckl.org +++ b/src/qmckl.org @@ -1,63 +1,63 @@ -* QMCKL header file +** =qmckl.h= header file -This file produces the =qmckl.h= header file, which is to be included -when qmckl functions are used. + This file produces the =qmckl.h= header file, which is to be included + when qmckl functions are used. -We also create here the =qmckl_f.f90= which is the Fortran interface file. + We also create here the =qmckl_f.f90= which is the Fortran interface file. -** Top of header files :noexport: +*** Top of header files :noexport: - #+BEGIN_SRC C :tangle qmckl.h + #+BEGIN_SRC C :tangle qmckl.h #ifndef QMCKL_H #define QMCKL_H #include #include - #+END_SRC + #+END_SRC - #+BEGIN_SRC f90 :tangle qmckl_f.f90 + #+BEGIN_SRC f90 :tangle qmckl_f.f90 module qmckl use, intrinsic :: iso_c_binding - #+END_SRC + #+END_SRC - The bottoms of the files are located in the [[qmckl_footer.org]] file. + The bottoms of the files are located in the [[qmckl_footer.org]] file. -** Constants +*** Constants -*** Success/failure +**** Success/failure - These are the codes returned by the functions to indicate success - or failure. All such functions should have as a return type =qmckl_exit_code=. + These are the codes returned by the functions to indicate success + or failure. All such functions should have as a return type =qmckl_exit_code=. - #+BEGIN_SRC C :comments org :tangle qmckl.h + #+BEGIN_SRC C :comments org :tangle qmckl.h #define QMCKL_SUCCESS 0 #define QMCKL_FAILURE 1 typedef int32_t qmckl_exit_code; typedef int64_t qmckl_context ; - #+END_SRC + #+END_SRC - #+BEGIN_SRC f90 :comments org :tangle qmckl_f.f90 + #+BEGIN_SRC f90 :comments org :tangle qmckl_f.f90 integer, parameter :: QMCKL_SUCCESS = 0 integer, parameter :: QMCKL_FAILURE = 0 - #+END_SRC + #+END_SRC -*** Precision-related constants +**** Precision-related constants - Controlling numerical precision enables optimizations. Here, the - default parameters determining the target numerical precision and - range are defined. + Controlling numerical precision enables optimizations. Here, the + default parameters determining the target numerical precision and + range are defined. - #+BEGIN_SRC C :comments org :tangle qmckl.h + #+BEGIN_SRC C :comments org :tangle qmckl.h #define QMCKL_DEFAULT_PRECISION 53 #define QMCKL_DEFAULT_RANGE 11 - #+END_SRC + #+END_SRC - #+BEGIN_SRC f90 :comments org :tangle qmckl_f.f90 + #+BEGIN_SRC f90 :comments org :tangle qmckl_f.f90 integer, parameter :: QMCKL_DEFAULT_PRECISION = 53 integer, parameter :: QMCKL_DEFAULT_RANGE = 11 - #+END_SRC + #+END_SRC - # -*- mode: org -*- - # vim: syntax=c + # -*- mode: org -*- + # vim: syntax=c diff --git a/src/qmckl_ao.org b/src/qmckl_ao.org index bcd46ed..506beb8 100644 --- a/src/qmckl_ao.org +++ b/src/qmckl_ao.org @@ -1,79 +1,79 @@ -* Atomic Orbitals +** Atomic Orbitals -This files contains all the routines for the computation of the -values, gradients and Laplacian of the atomic basis functions. + This files contains all the routines for the computation of the + values, gradients and Laplacian of the atomic basis functions. -3 files are produced: -- a source file : =qmckl_ao.f90= -- a C test file : =test_qmckl_ao.c= -- a Fortran test file : =test_qmckl_ao_f.f90= + 3 files are produced: + - a source file : =qmckl_ao.f90= + - a C test file : =test_qmckl_ao.c= + - a Fortran test file : =test_qmckl_ao_f.f90= -** Test :noexport: - #+BEGIN_SRC C :tangle test_qmckl_ao.c +*** Test :noexport: + #+BEGIN_SRC C :tangle test_qmckl_ao.c #include #include "qmckl.h" #include "munit.h" MunitResult test_qmckl_ao() { qmckl_context context; context = qmckl_context_create(); - #+END_SRC + #+END_SRC -** Polynomials +*** Polynomials - \[ - P_l(\mathbf{r},\mathbf{R}_i) = (x-X_i)^a (y-Y_i)^b (z-Z_i)^c - \] - \begin{eqnarray*} - \frac{\partial }{\partial x} P_l\left(\mathbf{r},\mathbf{R}_i \right) & = & a (x-X_i)^{a-1} (y-Y_i)^b (z-Z_i)^c \\ - \frac{\partial }{\partial y} P_l\left(\mathbf{r},\mathbf{R}_i \right) & = & b (x-X_i)^a (y-Y_i)^{b-1} (z-Z_i)^c \\ - \frac{\partial }{\partial z} P_l\left(\mathbf{r},\mathbf{R}_i \right) & = & c (x-X_i)^a (y-Y_i)^b (z-Z_i)^{c-1} \\ - \end{eqnarray*} - \begin{eqnarray*} - \left( \frac{\partial }{\partial x^2} + - \frac{\partial }{\partial y^2} + - \frac{\partial }{\partial z^2} \right) P_l - \left(\mathbf{r},\mathbf{R}_i \right) & = & - a(a-1) (x-X_i)^{a-2} (y-Y_i)^b (z-Z_i)^c + \\ - && b(b-1) (x-X_i)^a (y-Y_i)^{b-1} (z-Z_i)^c + \\ - && c(c-1) (x-X_i)^a (y-Y_i)^b (z-Z_i)^{c-1} - \end{eqnarray*} + \[ + P_l(\mathbf{r},\mathbf{R}_i) = (x-X_i)^a (y-Y_i)^b (z-Z_i)^c + \] + \begin{eqnarray*} + \frac{\partial }{\partial x} P_l\left(\mathbf{r},\mathbf{R}_i \right) & = & a (x-X_i)^{a-1} (y-Y_i)^b (z-Z_i)^c \\ + \frac{\partial }{\partial y} P_l\left(\mathbf{r},\mathbf{R}_i \right) & = & b (x-X_i)^a (y-Y_i)^{b-1} (z-Z_i)^c \\ + \frac{\partial }{\partial z} P_l\left(\mathbf{r},\mathbf{R}_i \right) & = & c (x-X_i)^a (y-Y_i)^b (z-Z_i)^{c-1} \\ + \end{eqnarray*} + \begin{eqnarray*} + \left( \frac{\partial }{\partial x^2} + + \frac{\partial }{\partial y^2} + + \frac{\partial }{\partial z^2} \right) P_l + \left(\mathbf{r},\mathbf{R}_i \right) & = & + a(a-1) (x-X_i)^{a-2} (y-Y_i)^b (z-Z_i)^c + \\ + && b(b-1) (x-X_i)^a (y-Y_i)^{b-1} (z-Z_i)^c + \\ + && c(c-1) (x-X_i)^a (y-Y_i)^b (z-Z_i)^{c-1} + \end{eqnarray*} -*** =qmckl_ao_powers= +**** =qmckl_ao_powers= - Computes all the powers of the =n= input data up to the given - maximum value given in input for each of the $n$ points: + Computes all the powers of the =n= input data up to the given + maximum value given in input for each of the $n$ points: - \[ P_{ij} = X_j^i \] + \[ P_{ij} = X_j^i \] -**** Arguments +***** Arguments - | =context= | input | Global state | - | =n= | input | Number of values | - | =X(n)= | input | Array containing the input values | - | =LMAX(n)= | input | Array containing the maximum power for each value | - | =P(LDP,n)= | output | Array containing all the powers of =X= | - | =LDP= | input | Leading dimension of array =P= | + | =context= | input | Global state | + | =n= | input | Number of values | + | =X(n)= | input | Array containing the input values | + | =LMAX(n)= | input | Array containing the maximum power for each value | + | =P(LDP,n)= | output | Array containing all the powers of =X= | + | =LDP= | input | Leading dimension of array =P= | -**** Requirements +***** Requirements - - =context= is not 0 - - =n= > 0 - - =X= is allocated with at least $n \times 8$ bytes - - =LMAX= is allocated with at least $n \times 4$ bytes - - =P= is allocated with at least $n \times \max_i \text{LMAX}_i \times 8$ bytes - - =LDP= >= $\max_i$ =LMAX[i]= + - =context= is not 0 + - =n= > 0 + - =X= is allocated with at least $n \times 8$ bytes + - =LMAX= is allocated with at least $n \times 4$ bytes + - =P= is allocated with at least $n \times \max_i \text{LMAX}_i \times 8$ bytes + - =LDP= >= $\max_i$ =LMAX[i]= -**** Header - #+BEGIN_SRC C :tangle qmckl.h +***** Header + #+BEGIN_SRC C :tangle qmckl.h qmckl_exit_code qmckl_ao_powers(const qmckl_context context, const int64_t n, const double *X, const int32_t *LMAX, const double *P, const int64_t LDP); - #+END_SRC + #+END_SRC -**** Source - #+BEGIN_SRC f90 :tangle qmckl_ao.f90 +***** Source + #+BEGIN_SRC f90 :tangle qmckl_ao.f90 integer function qmckl_ao_powers_f(context, n, X, LMAX, P, ldp) result(info) implicit none integer*8 , intent(in) :: context @@ -105,10 +105,10 @@ integer function qmckl_ao_powers_f(context, n, X, LMAX, P, ldp) result(info) end do end function qmckl_ao_powers_f - #+END_SRC + #+END_SRC -**** C interface :noexport: - #+BEGIN_SRC f90 :tangle qmckl_ao.f90 +***** C interface :noexport: + #+BEGIN_SRC f90 :tangle qmckl_ao.f90 integer(c_int32_t) function qmckl_ao_powers(context, n, X, LMAX, P, ldp) & bind(C) result(info) use, intrinsic :: iso_c_binding @@ -123,9 +123,9 @@ integer(c_int32_t) function qmckl_ao_powers(context, n, X, LMAX, P, ldp) & integer, external :: qmckl_ao_powers_f info = qmckl_ao_powers_f(context, n, X, LMAX, P, ldp) end function qmckl_ao_powers - #+END_SRC + #+END_SRC - #+BEGIN_SRC f90 :tangle qmckl_f.f90 + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface integer(c_int32_t) function qmckl_ao_powers(context, n, X, LMAX, P, ldp) bind(C) use, intrinsic :: iso_c_binding @@ -137,10 +137,10 @@ end function qmckl_ao_powers real (c_double) , intent(out) :: P(ldp,n) end function qmckl_ao_powers end interface - #+END_SRC + #+END_SRC -**** Test :noexport: - #+BEGIN_SRC f90 :tangle test_qmckl_ao_f.f90 +***** Test :noexport: + #+BEGIN_SRC f90 :tangle test_qmckl_ao_f.f90 integer(c_int32_t) function test_qmckl_ao_powers(context) bind(C) use qmckl implicit none @@ -183,55 +183,55 @@ integer(c_int32_t) function test_qmckl_ao_powers(context) bind(C) test_qmckl_ao_powers = 0 deallocate(X,P,LMAX) end function test_qmckl_ao_powers - #+END_SRC + #+END_SRC - #+BEGIN_SRC C :tangle test_qmckl_ao.c + #+BEGIN_SRC C :tangle test_qmckl_ao.c int test_qmckl_ao_powers(qmckl_context context); munit_assert_int(0, ==, test_qmckl_ao_powers(context)); - #+END_SRC + #+END_SRC -*** =qmckl_ao_polynomial_vgl= +**** =qmckl_ao_polynomial_vgl= - Computes the values, gradients and Laplacians at a given point of - all polynomials with an angular momentum up to =lmax=. + Computes the values, gradients and Laplacians at a given point of + all polynomials with an angular momentum up to =lmax=. -**** Arguments +***** Arguments - | =context= | input | Global state | - | =X(3)= | input | Array containing the coordinates of the points | - | =R(3)= | input | Array containing the x,y,z coordinates of the center | - | =lmax= | input | Maximum angular momentum | - | =n= | output | Number of computed polynomials | - | =L(ldl,n)= | output | Contains a,b,c for all =n= results | - | =ldl= | input | Leading dimension of =L= | - | =VGL(ldv,5)= | output | Value, gradients and Laplacian of the polynomials | - | =ldv= | input | Leading dimension of array =VGL= | + | =context= | input | Global state | + | =X(3)= | input | Array containing the coordinates of the points | + | =R(3)= | input | Array containing the x,y,z coordinates of the center | + | =lmax= | input | Maximum angular momentum | + | =n= | output | Number of computed polynomials | + | =L(ldl,n)= | output | Contains a,b,c for all =n= results | + | =ldl= | input | Leading dimension of =L= | + | =VGL(ldv,5)= | output | Value, gradients and Laplacian of the polynomials | + | =ldv= | input | Leading dimension of array =VGL= | -**** Requirements +***** Requirements - - =context= is not 0 - - =n= > 0 - - =lmax= >= 0 - - =ldl= >= 3 - - =ldv= >= (=lmax=+1)(=lmax=+2)(=lmax=+3)/6 - - =X= is allocated with at least $3 \times 8$ bytes - - =R= is allocated with at least $3 \times 8$ bytes - - =L= is allocated with at least $3 \times n \times 4$ bytes - - =VGL= is allocated with at least $n \times 5 \times 8$ bytes - - On output, =n= should be equal to (=lmax=+1)(=lmax=+2)(=lmax=+3)/6 + - =context= is not 0 + - =n= > 0 + - =lmax= >= 0 + - =ldl= >= 3 + - =ldv= >= (=lmax=+1)(=lmax=+2)(=lmax=+3)/6 + - =X= is allocated with at least $3 \times 8$ bytes + - =R= is allocated with at least $3 \times 8$ bytes + - =L= is allocated with at least $3 \times n \times 4$ bytes + - =VGL= is allocated with at least $n \times 5 \times 8$ bytes + - On output, =n= should be equal to (=lmax=+1)(=lmax=+2)(=lmax=+3)/6 -**** Header - #+BEGIN_SRC C :tangle qmckl.h +***** Header + #+BEGIN_SRC C :tangle qmckl.h qmckl_exit_code qmckl_ao_polynomial_vgl(const qmckl_context context, const double *X, const double *R, const int32_t lmax, const int64_t *n, const int32_t *L, const int64_t ldl, const double *VGL, const int64_t ldv); - #+END_SRC + #+END_SRC -**** Source - #+BEGIN_SRC f90 :tangle qmckl_ao.f90 +***** Source + #+BEGIN_SRC f90 :tangle qmckl_ao.f90 integer function qmckl_ao_polynomial_vgl_f(context, X, R, lmax, n, L, ldl, VGL, ldv) result(info) implicit none integer*8 , intent(in) :: context @@ -340,10 +340,10 @@ integer function qmckl_ao_polynomial_vgl_f(context, X, R, lmax, n, L, ldl, VGL, info = 0 end function qmckl_ao_polynomial_vgl_f - #+END_SRC + #+END_SRC -**** C interface :noexport: - #+BEGIN_SRC f90 :tangle qmckl_ao.f90 +***** C interface :noexport: + #+BEGIN_SRC f90 :tangle qmckl_ao.f90 integer(c_int32_t) function qmckl_ao_polynomial_vgl(context, X, R, lmax, n, L, ldl, VGL, ldv) & bind(C) result(info) use, intrinsic :: iso_c_binding @@ -360,9 +360,9 @@ integer(c_int32_t) function qmckl_ao_polynomial_vgl(context, X, R, lmax, n, L, l integer, external :: qmckl_ao_polynomial_vgl_f info = qmckl_ao_polynomial_vgl_f(context, X, R, lmax, n, L, ldl, VGL, ldv) end function qmckl_ao_polynomial_vgl - #+END_SRC + #+END_SRC - #+BEGIN_SRC f90 :tangle qmckl_f.f90 + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface integer(c_int32_t) function qmckl_ao_polynomial_vgl(context, X, R, lmax, n, L, ldl, VGL, ldv) & bind(C) @@ -377,9 +377,9 @@ end function qmckl_ao_polynomial_vgl real (c_double) , intent(out) :: VGL(ldv,5) end function qmckl_ao_polynomial_vgl end interface - #+END_SRC -**** Test :noexport: - #+BEGIN_SRC f90 :tangle test_qmckl_ao_f.f90 + #+END_SRC +***** Test :noexport: + #+BEGIN_SRC f90 :tangle test_qmckl_ao_f.f90 integer(c_int32_t) function test_qmckl_ao_polynomial_vgl(context) bind(C) use qmckl implicit none @@ -472,58 +472,58 @@ integer(c_int32_t) function test_qmckl_ao_polynomial_vgl(context) bind(C) deallocate(L,VGL) end function test_qmckl_ao_polynomial_vgl - #+END_SRC + #+END_SRC - #+BEGIN_SRC C :tangle test_qmckl_ao.c + #+BEGIN_SRC C :tangle test_qmckl_ao.c int test_qmckl_ao_polynomial_vgl(qmckl_context context); munit_assert_int(0, ==, test_qmckl_ao_polynomial_vgl(context)); - #+END_SRC - #+END_SRC + #+END_SRC + #+END_SRC -** Gaussian basis functions +*** Gaussian basis functions -*** =qmckl_ao_gaussians_vgl= +**** =qmckl_ao_gaussians_vgl= - Computes the values, gradients and Laplacians at a given point of - =n= Gaussian functions centered at the same point: + Computes the values, gradients and Laplacians at a given point of + =n= Gaussian functions centered at the same point: - \[ v_i = exp(-a_i |X-R|^2) \] - \[ \nabla_x v_i = -2 a_i (X_x - R_x) v_i \] - \[ \nabla_y v_i = -2 a_i (X_y - R_y) v_i \] - \[ \nabla_z v_i = -2 a_i (X_z - R_z) v_i \] - \[ \Delta v_i = a_i (4 |X-R|^2 a_i - 6) v_i \] + \[ v_i = exp(-a_i |X-R|^2) \] + \[ \nabla_x v_i = -2 a_i (X_x - R_x) v_i \] + \[ \nabla_y v_i = -2 a_i (X_y - R_y) v_i \] + \[ \nabla_z v_i = -2 a_i (X_z - R_z) v_i \] + \[ \Delta v_i = a_i (4 |X-R|^2 a_i - 6) v_i \] -**** Arguments +***** Arguments - | =context= | input | Global state | - | =X(3)= | input | Array containing the coordinates of the points | - | =R(3)= | input | Array containing the x,y,z coordinates of the center | - | =n= | input | Number of computed gaussians | - | =A(n)= | input | Exponents of the Gaussians | - | =VGL(ldv,5)= | output | Value, gradients and Laplacian of the Gaussians | - | =ldv= | input | Leading dimension of array =VGL= | + | =context= | input | Global state | + | =X(3)= | input | Array containing the coordinates of the points | + | =R(3)= | input | Array containing the x,y,z coordinates of the center | + | =n= | input | Number of computed gaussians | + | =A(n)= | input | Exponents of the Gaussians | + | =VGL(ldv,5)= | output | Value, gradients and Laplacian of the Gaussians | + | =ldv= | input | Leading dimension of array =VGL= | -**** Requirements +***** Requirements - - =context= is not 0 - - =n= > 0 - - =ldv= >= 5 - - =A(i)= > 0 for all =i= - - =X= is allocated with at least $3 \times 8$ bytes - - =R= is allocated with at least $3 \times 8$ bytes - - =A= is allocated with at least $n \times 8$ bytes - - =VGL= is allocated with at least $n \times 5 \times 8$ bytes + - =context= is not 0 + - =n= > 0 + - =ldv= >= 5 + - =A(i)= > 0 for all =i= + - =X= is allocated with at least $3 \times 8$ bytes + - =R= is allocated with at least $3 \times 8$ bytes + - =A= is allocated with at least $n \times 8$ bytes + - =VGL= is allocated with at least $n \times 5 \times 8$ bytes -**** Header - #+BEGIN_SRC C :tangle qmckl.h +***** Header + #+BEGIN_SRC C :tangle qmckl.h qmckl_exit_code qmckl_ao_gaussians_vgl(const qmckl_context context, const double *X, const double *R, const int64_t *n, const int64_t *A, const double *VGL, const int64_t ldv); - #+END_SRC + #+END_SRC -**** Source - #+BEGIN_SRC f90 :tangle qmckl_ao.f90 +***** Source + #+BEGIN_SRC f90 :tangle qmckl_ao.f90 integer function qmckl_ao_gaussians_vgl_f(context, X, R, n, A, VGL, ldv) result(info) implicit none integer*8 , intent(in) :: context @@ -583,10 +583,10 @@ integer function qmckl_ao_gaussians_vgl_f(context, X, R, n, A, VGL, ldv) result( end do end function qmckl_ao_gaussians_vgl_f - #+END_SRC + #+END_SRC -**** C interface :noexport: - #+BEGIN_SRC f90 :tangle qmckl_ao.f90 +***** C interface :noexport: + #+BEGIN_SRC f90 :tangle qmckl_ao.f90 integer(c_int32_t) function qmckl_ao_gaussians_vgl(context, X, R, n, A, VGL, ldv) & bind(C) result(info) use, intrinsic :: iso_c_binding @@ -601,9 +601,9 @@ integer(c_int32_t) function qmckl_ao_gaussians_vgl(context, X, R, n, A, VGL, ldv integer, external :: qmckl_ao_gaussians_vgl_f info = qmckl_ao_gaussians_vgl_f(context, X, R, n, A, VGL, ldv) end function qmckl_ao_gaussians_vgl - #+END_SRC + #+END_SRC - #+BEGIN_SRC f90 :tangle qmckl_f.f90 + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface integer(c_int32_t) function qmckl_ao_gaussians_vgl(context, X, R, n, A, VGL, ldv) & bind(C) @@ -615,9 +615,9 @@ end function qmckl_ao_gaussians_vgl real (c_double) , intent(out) :: VGL(ldv,5) end function qmckl_ao_gaussians_vgl end interface - #+END_SRC -**** Test :noexport: - #+BEGIN_SRC f90 :tangle test_qmckl_ao_f.f90 + #+END_SRC +***** Test :noexport: + #+BEGIN_SRC f90 :tangle test_qmckl_ao_f.f90 integer(c_int32_t) function test_qmckl_ao_gaussians_vgl(context) bind(C) use qmckl implicit none @@ -682,28 +682,28 @@ integer(c_int32_t) function test_qmckl_ao_gaussians_vgl(context) bind(C) deallocate(VGL) end function test_qmckl_ao_gaussians_vgl - #+END_SRC + #+END_SRC - #+BEGIN_SRC C :tangle test_qmckl_ao.c + #+BEGIN_SRC C :tangle test_qmckl_ao.c int test_qmckl_ao_gaussians_vgl(qmckl_context context); munit_assert_int(0, ==, test_qmckl_ao_gaussians_vgl(context)); - #+END_SRC - #+END_SRC + #+END_SRC + #+END_SRC -** TODO Slater basis functions +*** TODO Slater basis functions -** End of files :noexport: +*** End of files :noexport: -**** Test - #+BEGIN_SRC C :tangle test_qmckl_ao.c +***** Test + #+BEGIN_SRC C :tangle test_qmckl_ao.c if (qmckl_context_destroy(context) != QMCKL_SUCCESS) return QMCKL_FAILURE; return MUNIT_OK; } - #+END_SRC + #+END_SRC - # -*- mode: org -*- - # vim: syntax=c + # -*- mode: org -*- + # vim: syntax=c diff --git a/src/qmckl_context.org b/src/qmckl_context.org index dc1eeca..e407466 100644 --- a/src/qmckl_context.org +++ b/src/qmckl_context.org @@ -1,41 +1,41 @@ -* Context +** Context - This file is written in C because it is more natural to express the context in - C than in Fortran. + This file is written in C because it is more natural to express the context in + C than in Fortran. - 2 files are produced: - - a source file : =qmckl_context.c= - - a test file : =test_qmckl_context.c= + 2 files are produced: + - a source file : =qmckl_context.c= + - a test file : =test_qmckl_context.c= -** Headers :noexport: - #+BEGIN_SRC C :tangle qmckl_context.c +*** Headers :noexport: + #+BEGIN_SRC C :tangle qmckl_context.c #include "qmckl.h" - #+END_SRC + #+END_SRC - #+BEGIN_SRC C :tangle test_qmckl_context.c + #+BEGIN_SRC C :tangle test_qmckl_context.c #include "qmckl.h" #include "munit.h" MunitResult test_qmckl_context() { - #+END_SRC + #+END_SRC -** Context +*** Context - The context variable is a handle for the state of the library, and - is stored in the following data structure, which can't be seen - outside of the library. To simplify compatibility with other - languages, the pointer to the internal data structure is converted - into a 64-bit signed integer, defined in the =qmckl_context= type. - A value of 0 for the context is equivalent to a =NULL= pointer. + The context variable is a handle for the state of the library, and + is stored in the following data structure, which can't be seen + outside of the library. To simplify compatibility with other + languages, the pointer to the internal data structure is converted + into a 64-bit signed integer, defined in the =qmckl_context= type. + A value of 0 for the context is equivalent to a =NULL= pointer. - #+BEGIN_SRC C :comments org :tangle qmckl.h - #+END_SRC + #+BEGIN_SRC C :comments org :tangle qmckl.h + #+END_SRC -**** Source +***** Source - The tag is used internally to check if the memory domain pointed by - a pointer is a valid context. + The tag is used internally to check if the memory domain pointed by + a pointer is a valid context. - #+BEGIN_SRC C :comments org :tangle qmckl_context.c + #+BEGIN_SRC C :comments org :tangle qmckl_context.c typedef struct qmckl_context_struct { struct qmckl_context_struct * prev; uint32_t tag; @@ -45,26 +45,26 @@ typedef struct qmckl_context_struct { #define VALID_TAG 0xBEEFFACE #define INVALID_TAG 0xDEADBEEF - #+END_SRC + #+END_SRC -**** Test :noexport: - #+BEGIN_SRC C :tangle test_qmckl_context.c +***** Test :noexport: + #+BEGIN_SRC C :tangle test_qmckl_context.c qmckl_context context; qmckl_context new_context; + #+END_SRC + + +**** =qmckl_context_check= + + Checks if the domain pointed by the pointer is a valid context. + Returns the input =qmckl_context= if the context is valid, 0 otherwise. + + #+BEGIN_SRC C :comments org :tangle qmckl.h +qmckl_context qmckl_context_check(const qmckl_context context) ; #+END_SRC - -*** =qmckl_context_check= - - Checks if the domain pointed by the pointer is a valid context. - Returns the input =qmckl_context= if the context is valid, 0 otherwise. - - #+BEGIN_SRC C :comments org :tangle qmckl.h -qmckl_context qmckl_context_check(const qmckl_context context) ; - #+END_SRC - -**** Source - #+BEGIN_SRC C :tangle qmckl_context.c +***** Source + #+BEGIN_SRC C :tangle qmckl_context.c qmckl_context qmckl_context_check(const qmckl_context context) { if (context == (qmckl_context) 0) return (qmckl_context) 0; @@ -75,20 +75,20 @@ qmckl_context qmckl_context_check(const qmckl_context context) { return context; } - #+END_SRC - -*** =qmckl_context_create= - - To create a new context, use =qmckl_context_create()=. - - On success, returns a pointer to a context using the =qmckl_context= type - - Returns 0 upon failure to allocate the internal data structure - - #+BEGIN_SRC C :comments org :tangle qmckl.h -qmckl_context qmckl_context_create(); #+END_SRC -**** Source - #+BEGIN_SRC C :tangle qmckl_context.c +**** =qmckl_context_create= + + To create a new context, use =qmckl_context_create()=. + - On success, returns a pointer to a context using the =qmckl_context= type + - Returns 0 upon failure to allocate the internal data structure + + #+BEGIN_SRC C :comments org :tangle qmckl.h +qmckl_context qmckl_context_create(); + #+END_SRC + +***** Source + #+BEGIN_SRC C :tangle qmckl_context.c qmckl_context qmckl_context_create() { qmckl_context_struct* context = @@ -104,38 +104,38 @@ qmckl_context qmckl_context_create() { return (qmckl_context) context; } - #+END_SRC + #+END_SRC -**** Fortran interface - #+BEGIN_SRC f90 :tangle qmckl_f.f90 +***** Fortran interface + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface integer (c_int64_t) function qmckl_context_create() bind(C) use, intrinsic :: iso_c_binding end function qmckl_context_create end interface - #+END_SRC + #+END_SRC -**** Test :noexport: - #+BEGIN_SRC C :comments link :tangle test_qmckl_context.c +***** Test :noexport: + #+BEGIN_SRC C :comments link :tangle test_qmckl_context.c context = qmckl_context_create(); munit_assert_int64( context, !=, (qmckl_context) 0); munit_assert_int64( qmckl_context_check(context), ==, context); - #+END_SRC - -*** =qmckl_context_copy= - - This function makes a shallow copy of the current context. - - Copying the 0-valued context returns 0 - - On success, returns a pointer to the new context using the =qmckl_context= type - - Returns 0 upon failure to allocate the internal data structure - for the new context - - #+BEGIN_SRC C :comments org :tangle qmckl.h -qmckl_context qmckl_context_copy(const qmckl_context context); #+END_SRC -**** Source - #+BEGIN_SRC C :tangle qmckl_context.c +**** =qmckl_context_copy= + + This function makes a shallow copy of the current context. + - Copying the 0-valued context returns 0 + - On success, returns a pointer to the new context using the =qmckl_context= type + - Returns 0 upon failure to allocate the internal data structure + for the new context + + #+BEGIN_SRC C :comments org :tangle qmckl.h +qmckl_context qmckl_context_copy(const qmckl_context context); + #+END_SRC + +***** Source + #+BEGIN_SRC C :tangle qmckl_context.c qmckl_context qmckl_context_copy(const qmckl_context context) { const qmckl_context checked_context = qmckl_context_check(context); @@ -160,39 +160,39 @@ qmckl_context qmckl_context_copy(const qmckl_context context) { return (qmckl_context) new_context; } - #+END_SRC + #+END_SRC -**** Fortran interface - #+BEGIN_SRC f90 :tangle qmckl_f.f90 +***** Fortran interface + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface integer (c_int64_t) function qmckl_context_copy(context) bind(C) use, intrinsic :: iso_c_binding integer (c_int64_t), intent(in), value :: context end function qmckl_context_copy end interface - #+END_SRC + #+END_SRC -**** Test :noexport: - #+BEGIN_SRC C :comments link :tangle test_qmckl_context.c +***** Test :noexport: + #+BEGIN_SRC C :comments link :tangle test_qmckl_context.c new_context = qmckl_context_copy(context); munit_assert_int64(new_context, !=, (qmckl_context) 0); munit_assert_int64(new_context, !=, context); munit_assert_int64(qmckl_context_check(new_context), ==, new_context); - #+END_SRC - -*** =qmckl_context_previous= - - Returns the previous context - - On success, returns the ancestor of the current context - - Returns 0 for the initial context - - Returns 0 for the 0-valued context - - #+BEGIN_SRC C :comments org :tangle qmckl.h -qmckl_context qmckl_context_previous(const qmckl_context context); #+END_SRC -**** Source - #+BEGIN_SRC C :tangle qmckl_context.c +**** =qmckl_context_previous= + + Returns the previous context + - On success, returns the ancestor of the current context + - Returns 0 for the initial context + - Returns 0 for the 0-valued context + + #+BEGIN_SRC C :comments org :tangle qmckl.h +qmckl_context qmckl_context_previous(const qmckl_context context); + #+END_SRC + +***** Source + #+BEGIN_SRC C :tangle qmckl_context.c qmckl_context qmckl_context_previous(const qmckl_context context) { const qmckl_context checked_context = qmckl_context_check(context); @@ -203,40 +203,40 @@ qmckl_context qmckl_context_previous(const qmckl_context context) { const qmckl_context_struct* ctx = (qmckl_context_struct*) checked_context; return qmckl_context_check((qmckl_context) ctx->prev); } - #+END_SRC + #+END_SRC -**** Fortran interface - #+BEGIN_SRC f90 :tangle qmckl_f.f90 +***** Fortran interface + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface integer (c_int64_t) function qmckl_context_previous(context) bind(C) use, intrinsic :: iso_c_binding integer (c_int64_t), intent(in), value :: context end function qmckl_context_previous end interface - #+END_SRC + #+END_SRC -**** Test :noexport: - #+BEGIN_SRC C :comments link :tangle test_qmckl_context.c +***** Test :noexport: + #+BEGIN_SRC C :comments link :tangle test_qmckl_context.c munit_assert_int64(qmckl_context_previous(new_context), !=, (qmckl_context) 0); munit_assert_int64(qmckl_context_previous(new_context), ==, context); munit_assert_int64(qmckl_context_previous(context), ==, (qmckl_context) 0); munit_assert_int64(qmckl_context_previous((qmckl_context) 0), ==, (qmckl_context) 0); - #+END_SRC - -*** =qmckl_context_destroy= - - Destroys the current context, leaving the ancestors untouched. - - Succeeds if the current context is properly destroyed - - Fails otherwise - - Fails if the 0-valued context is given in argument - - Fails if the the pointer is not a valid context - - #+BEGIN_SRC C :comments org :tangle qmckl.h -qmckl_exit_code qmckl_context_destroy(qmckl_context context); #+END_SRC -**** Source - #+BEGIN_SRC C :tangle qmckl_context.c +**** =qmckl_context_destroy= + + Destroys the current context, leaving the ancestors untouched. + - Succeeds if the current context is properly destroyed + - Fails otherwise + - Fails if the 0-valued context is given in argument + - Fails if the the pointer is not a valid context + + #+BEGIN_SRC C :comments org :tangle qmckl.h +qmckl_exit_code qmckl_context_destroy(qmckl_context context); + #+END_SRC + +***** Source + #+BEGIN_SRC C :tangle qmckl_context.c qmckl_exit_code qmckl_context_destroy(const qmckl_context context) { const qmckl_context checked_context = qmckl_context_check(context); @@ -249,47 +249,47 @@ qmckl_exit_code qmckl_context_destroy(const qmckl_context context) { qmckl_free(ctx); return QMCKL_SUCCESS; } - #+END_SRC + #+END_SRC -**** Fortran interface - #+BEGIN_SRC f90 :tangle qmckl_f.f90 +***** Fortran interface + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface integer (c_int32_t) function qmckl_context_destroy(context) bind(C) use, intrinsic :: iso_c_binding integer (c_int64_t), intent(in), value :: context end function qmckl_context_destroy end interface - #+END_SRC + #+END_SRC -**** Test :noexport: - #+BEGIN_SRC C :tangle test_qmckl_context.c +***** Test :noexport: + #+BEGIN_SRC C :tangle test_qmckl_context.c munit_assert_int64(qmckl_context_check(new_context), ==, new_context); munit_assert_int64(new_context, !=, (qmckl_context) 0); munit_assert_int32(qmckl_context_destroy(new_context), ==, QMCKL_SUCCESS); munit_assert_int64(qmckl_context_check(new_context), !=, new_context); munit_assert_int64(qmckl_context_check(new_context), ==, (qmckl_context) 0); munit_assert_int64(qmckl_context_destroy((qmckl_context) 0), ==, QMCKL_FAILURE); + #+END_SRC + + +*** Precision + + The following functions set and get the expected required precision + and range. =precision= should be an integer between 2 and 53, and + =range= should be an integer between 2 and 11. + + The setter functions functions return a new context as a 64-bit integer. + The getter functions return the value, as a 32-bit integer. + The update functions return =QMCKL_SUCCESS= or =QMCKL_FAILURE=. + +**** =qmckl_context_update_precision= + Modifies the parameter for the numerical precision in a given context. + #+BEGIN_SRC C :comments org :tangle qmckl.h +qmckl_exit_code qmckl_context_update_precision(const qmckl_context context, const int precision); #+END_SRC - -** Precision - - The following functions set and get the expected required precision - and range. =precision= should be an integer between 2 and 53, and - =range= should be an integer between 2 and 11. - - The setter functions functions return a new context as a 64-bit integer. - The getter functions return the value, as a 32-bit integer. - The update functions return =QMCKL_SUCCESS= or =QMCKL_FAILURE=. - -*** =qmckl_context_update_precision= - Modifies the parameter for the numerical precision in a given context. - #+BEGIN_SRC C :comments org :tangle qmckl.h -qmckl_exit_code qmckl_context_update_precision(const qmckl_context context, const int precision); - #+END_SRC - -**** Source - #+BEGIN_SRC C :tangle qmckl_context.c +***** Source + #+BEGIN_SRC C :tangle qmckl_context.c qmckl_exit_code qmckl_context_update_precision(const qmckl_context context, const int precision) { if (precision < 2) return QMCKL_FAILURE; @@ -301,10 +301,10 @@ qmckl_exit_code qmckl_context_update_precision(const qmckl_context context, cons ctx->precision = precision; return QMCKL_SUCCESS; } - #+END_SRC + #+END_SRC -**** Fortran interface - #+BEGIN_SRC f90 :tangle qmckl_f.f90 +***** Fortran interface + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface integer (c_int32_t) function qmckl_context_update_precision(context, precision) bind(C) use, intrinsic :: iso_c_binding @@ -312,17 +312,17 @@ qmckl_exit_code qmckl_context_update_precision(const qmckl_context context, cons integer (c_int32_t), intent(in), value :: precision end function qmckl_context_update_precision end interface - #+END_SRC + #+END_SRC -**** TODO Tests :noexport: -*** =qmckl_context_update_range= - Modifies the parameter for the numerical range in a given context. - #+BEGIN_SRC C :comments org :tangle qmckl.h +***** TODO Tests :noexport: +**** =qmckl_context_update_range= + Modifies the parameter for the numerical range in a given context. + #+BEGIN_SRC C :comments org :tangle qmckl.h qmckl_exit_code qmckl_context_update_range(const qmckl_context context, const int range); - #+END_SRC + #+END_SRC -**** Source - #+BEGIN_SRC C :tangle qmckl_context.c +***** Source + #+BEGIN_SRC C :tangle qmckl_context.c qmckl_exit_code qmckl_context_update_range(const qmckl_context context, const int range) { if (range < 2) return QMCKL_FAILURE; @@ -334,10 +334,10 @@ qmckl_exit_code qmckl_context_update_range(const qmckl_context context, const in ctx->range = range; return QMCKL_SUCCESS; } - #+END_SRC + #+END_SRC -**** Fortran interface - #+BEGIN_SRC f90 :tangle qmckl_f.f90 +***** Fortran interface + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface integer (c_int32_t) function qmckl_context_update_range(context, range) bind(C) use, intrinsic :: iso_c_binding @@ -345,17 +345,17 @@ qmckl_exit_code qmckl_context_update_range(const qmckl_context context, const in integer (c_int32_t), intent(in), value :: range end function qmckl_context_update_range end interface + #+END_SRC + +***** TODO Tests :noexport: +**** =qmckl_context_set_precision= + Returns a copy of the context with a different precision parameter. + #+BEGIN_SRC C :comments or :tangle qmckl.h +qmckl_context qmckl_context_set_precision(const qmckl_context context, const int precision); #+END_SRC -**** TODO Tests :noexport: -*** =qmckl_context_set_precision= - Returns a copy of the context with a different precision parameter. - #+BEGIN_SRC C :comments or :tangle qmckl.h -qmckl_context qmckl_context_set_precision(const qmckl_context context, const int precision); - #+END_SRC - -**** Source - #+BEGIN_SRC C :tangle qmckl_context.c +***** Source + #+BEGIN_SRC C :tangle qmckl_context.c qmckl_context qmckl_context_set_precision(const qmckl_context context, const int precision) { qmckl_context new_context = qmckl_context_copy(context); if (new_context == 0) return 0; @@ -364,10 +364,10 @@ qmckl_context qmckl_context_set_precision(const qmckl_context context, const int return new_context; } - #+END_SRC + #+END_SRC -**** Fortran interface - #+BEGIN_SRC f90 :tangle qmckl_f.f90 +***** Fortran interface + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface integer (c_int32_t) function qmckl_context_set_precision(context, precision) bind(C) use, intrinsic :: iso_c_binding @@ -375,17 +375,17 @@ qmckl_context qmckl_context_set_precision(const qmckl_context context, const int integer (c_int32_t), intent(in), value :: precision end function qmckl_context_set_precision end interface + #+END_SRC + +***** TODO Tests :noexport: +**** =qmckl_context_set_range= + Returns a copy of the context with a different precision parameter. + #+BEGIN_SRC C :comments org :tangle qmckl.h +qmckl_context qmckl_context_set_range(const qmckl_context context, const int range); #+END_SRC -**** TODO Tests :noexport: -*** =qmckl_context_set_range= - Returns a copy of the context with a different precision parameter. - #+BEGIN_SRC C :comments org :tangle qmckl.h -qmckl_context qmckl_context_set_range(const qmckl_context context, const int range); - #+END_SRC - -**** Source - #+BEGIN_SRC C :tangle qmckl_context.c +***** Source + #+BEGIN_SRC C :tangle qmckl_context.c qmckl_context qmckl_context_set_range(const qmckl_context context, const int range) { qmckl_context new_context = qmckl_context_copy(context); if (new_context == 0) return 0; @@ -394,10 +394,10 @@ qmckl_context qmckl_context_set_range(const qmckl_context context, const int ran return new_context; } - #+END_SRC + #+END_SRC -**** Fortran interface - #+BEGIN_SRC f90 :tangle qmckl_f.f90 +***** Fortran interface + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface integer (c_int32_t) function qmckl_context_set_range(context, range) bind(C) use, intrinsic :: iso_c_binding @@ -405,102 +405,102 @@ qmckl_context qmckl_context_set_range(const qmckl_context context, const int ran integer (c_int32_t), intent(in), value :: range end function qmckl_context_set_range end interface + #+END_SRC + +***** TODO Tests :noexport: + +**** =qmckl_context_get_precision= + Returns the value of the numerical precision in the context + #+BEGIN_SRC C :comments org :tangle qmckl.h +int32_t qmckl_context_get_precision(const qmckl_context context); #+END_SRC -**** TODO Tests :noexport: - -*** =qmckl_context_get_precision= - Returns the value of the numerical precision in the context - #+BEGIN_SRC C :comments org :tangle qmckl.h -int32_t qmckl_context_get_precision(const qmckl_context context); - #+END_SRC - -**** Source - #+BEGIN_SRC C :tangle qmckl_context.c +***** Source + #+BEGIN_SRC C :tangle qmckl_context.c int qmckl_context_get_precision(const qmckl_context context) { const qmckl_context_struct* ctx = (qmckl_context_struct*) context; return ctx->precision; } - #+END_SRC + #+END_SRC -**** Fortran interface - #+BEGIN_SRC f90 :tangle qmckl_f.f90 +***** Fortran interface + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface integer (c_int32_t) function qmckl_context_get_precision(context) bind(C) use, intrinsic :: iso_c_binding integer (c_int64_t), intent(in), value :: context end function qmckl_context_get_precision end interface + #+END_SRC + +***** TODO Tests :noexport: +**** =qmckl_context_get_range= + Returns the value of the numerical range in the context + #+BEGIN_SRC C :comments org :tangle qmckl.h +int32_t qmckl_context_get_range(const qmckl_context context); #+END_SRC -**** TODO Tests :noexport: -*** =qmckl_context_get_range= - Returns the value of the numerical range in the context - #+BEGIN_SRC C :comments org :tangle qmckl.h -int32_t qmckl_context_get_range(const qmckl_context context); - #+END_SRC - -**** Source - #+BEGIN_SRC C :tangle qmckl_context.c +***** Source + #+BEGIN_SRC C :tangle qmckl_context.c int qmckl_context_get_range(const qmckl_context context) { const qmckl_context_struct* ctx = (qmckl_context_struct*) context; return ctx->range; } - #+END_SRC + #+END_SRC -**** Fortran interface - #+BEGIN_SRC f90 :tangle qmckl_f.f90 +***** Fortran interface + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface integer (c_int32_t) function qmckl_context_get_range(context) bind(C) use, intrinsic :: iso_c_binding integer (c_int64_t), intent(in), value :: context end function qmckl_context_get_range end interface + #+END_SRC + +***** TODO Tests :noexport: + +**** =qmckl_context_get_epsilon= + Returns $\epsilon = 2 / \log_{10} 2^{n-1}$ where =n= is the precision + #+BEGIN_SRC C :comments org :tangle qmckl.h +double qmckl_context_get_epsilon(const qmckl_context context); #+END_SRC -**** TODO Tests :noexport: - -*** =qmckl_context_get_epsilon= - Returns $\epsilon = 2 / \log_{10} 2^{n-1}$ where =n= is the precision - #+BEGIN_SRC C :comments org :tangle qmckl.h -double qmckl_context_get_epsilon(const qmckl_context context); - #+END_SRC - -**** Source - #+BEGIN_SRC C :tangle qmckl_context.c +***** Source + #+BEGIN_SRC C :tangle qmckl_context.c double qmckl_context_get_epsilon(const qmckl_context context) { const qmckl_context_struct* ctx = (qmckl_context_struct*) context; return 1.0 / ((double) ((int64_t) 1 << (ctx->precision-1))); } - #+END_SRC + #+END_SRC -**** Fortran interface - #+BEGIN_SRC f90 :tangle qmckl_f.f90 +***** Fortran interface + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface real (c_double) function qmckl_context_get_epsilon(context) bind(C) use, intrinsic :: iso_c_binding integer (c_int64_t), intent(in), value :: context end function qmckl_context_get_epsilon end interface - #+END_SRC + #+END_SRC -**** TODO Tests :noexport: +***** TODO Tests :noexport: -** Info about the molecular system +*** Info about the molecular system -*** TODO =qmckl_context_set_nucl_coord= -*** TODO =qmckl_context_set_nucl_charge= -*** TODO =qmckl_context_set_elec_num= +**** TODO =qmckl_context_set_nucl_coord= +**** TODO =qmckl_context_set_nucl_charge= +**** TODO =qmckl_context_set_elec_num= -** End of files :noexport: +*** End of files :noexport: -**** Test - #+BEGIN_SRC C :comments link :tangle test_qmckl_context.c +***** Test + #+BEGIN_SRC C :comments link :tangle test_qmckl_context.c return MUNIT_OK; } - #+END_SRC + #+END_SRC -# -*- mode: org -*- -# vim: syntax=c + # -*- mode: org -*- + # vim: syntax=c diff --git a/src/qmckl_distance.org b/src/qmckl_distance.org index f50361d..06c8015 100644 --- a/src/qmckl_distance.org +++ b/src/qmckl_distance.org @@ -1,14 +1,14 @@ -* Computation of distances +** Computation of distances -Function for the computation of distances between particles. + Function for the computation of distances between particles. -3 files are produced: -- a source file : =qmckl_distance.f90= -- a C test file : =test_qmckl_distance.c= -- a Fortran test file : =test_qmckl_distance_f.f90= + 3 files are produced: + - a source file : =qmckl_distance.f90= + - a C test file : =test_qmckl_distance.c= + - a Fortran test file : =test_qmckl_distance_f.f90= -*** Headers :noexport: - #+BEGIN_SRC C :comments link :tangle test_qmckl_distance.c +**** Headers :noexport: + #+BEGIN_SRC C :comments link :tangle test_qmckl_distance.c #include #include "qmckl.h" #include "munit.h" @@ -16,63 +16,63 @@ MunitResult test_qmckl_distance() { qmckl_context context; context = qmckl_context_create(); - #+END_SRC + #+END_SRC -** Squared distance +*** Squared distance -*** =qmckl_distance_sq= +**** =qmckl_distance_sq= - Computes the matrix of the squared distances between all pairs of - points in two sets, one point within each set: - \[ - C_{ij} = \sum_{k=1}^3 (A_{k,i}-B_{k,j})^2 - \] + Computes the matrix of the squared distances between all pairs of + points in two sets, one point within each set: + \[ + C_{ij} = \sum_{k=1}^3 (A_{k,i}-B_{k,j})^2 + \] -**** Arguments +***** Arguments - | =context= | input | Global state | - | =transa= | input | Array =A= is =N=: Normal, =T=: Transposed | - | =transb= | input | Array =B= is =N=: Normal, =T=: Transposed | - | =m= | input | Number of points in the first set | - | =n= | input | Number of points in the second set | - | =A(lda,3)= | input | Array containing the $m \times 3$ matrix $A$ | - | =lda= | input | Leading dimension of array =A= | - | =B(ldb,3)= | input | Array containing the $n \times 3$ matrix $B$ | - | =ldb= | input | Leading dimension of array =B= | - | =C(ldc,n)= | output | Array containing the $m \times n$ matrix $C$ | - | =ldc= | input | Leading dimension of array =C= | + | =context= | input | Global state | + | =transa= | input | Array =A= is =N=: Normal, =T=: Transposed | + | =transb= | input | Array =B= is =N=: Normal, =T=: Transposed | + | =m= | input | Number of points in the first set | + | =n= | input | Number of points in the second set | + | =A(lda,3)= | input | Array containing the $m \times 3$ matrix $A$ | + | =lda= | input | Leading dimension of array =A= | + | =B(ldb,3)= | input | Array containing the $n \times 3$ matrix $B$ | + | =ldb= | input | Leading dimension of array =B= | + | =C(ldc,n)= | output | Array containing the $m \times n$ matrix $C$ | + | =ldc= | input | Leading dimension of array =C= | -**** Requirements +***** Requirements - - =context= is not 0 - - =m= > 0 - - =n= > 0 - - =lda= >= 3 if =transa= is =N= - - =lda= >= m if =transa= is =T= - - =ldb= >= 3 if =transb= is =N= - - =ldb= >= n if =transb= is =T= - - =ldc= >= m if =transa= is = - - =A= is allocated with at least $3 \times m \times 8$ bytes - - =B= is allocated with at least $3 \times n \times 8$ bytes - - =C= is allocated with at least $m \times n \times 8$ bytes + - =context= is not 0 + - =m= > 0 + - =n= > 0 + - =lda= >= 3 if =transa= is =N= + - =lda= >= m if =transa= is =T= + - =ldb= >= 3 if =transb= is =N= + - =ldb= >= n if =transb= is =T= + - =ldc= >= m if =transa= is = + - =A= is allocated with at least $3 \times m \times 8$ bytes + - =B= is allocated with at least $3 \times n \times 8$ bytes + - =C= is allocated with at least $m \times n \times 8$ bytes -**** Performance +***** Performance - This function might be more efficient when =A= and =B= are - transposed. + This function might be more efficient when =A= and =B= are + transposed. - #+BEGIN_SRC C :comments org :tangle qmckl.h + #+BEGIN_SRC C :comments org :tangle qmckl.h qmckl_exit_code qmckl_distance_sq(const qmckl_context context, const char transa, const char transb, const int64_t m, const int64_t n, const double *A, const int64_t lda, const double *B, const int64_t ldb, const double *C, const int64_t ldc); - #+END_SRC + #+END_SRC -**** Source - #+BEGIN_SRC f90 :tangle qmckl_distance.f90 +***** Source + #+BEGIN_SRC f90 :tangle qmckl_distance.f90 integer function qmckl_distance_sq_f(context, transa, transb, m, n, A, LDA, B, LDB, C, LDC) result(info) implicit none integer*8 , intent(in) :: context @@ -197,10 +197,10 @@ integer function qmckl_distance_sq_f(context, transa, transb, m, n, A, LDA, B, L end select end function qmckl_distance_sq_f - #+END_SRC + #+END_SRC -**** C interface :noexport: - #+BEGIN_SRC f90 :tangle qmckl_distance.f90 +***** C interface :noexport: + #+BEGIN_SRC f90 :tangle qmckl_distance.f90 integer(c_int32_t) function qmckl_distance_sq(context, transa, transb, m, n, A, LDA, B, LDB, C, LDC) & bind(C) result(info) use, intrinsic :: iso_c_binding @@ -218,9 +218,9 @@ integer(c_int32_t) function qmckl_distance_sq(context, transa, transb, m, n, A, integer, external :: qmckl_distance_sq_f info = qmckl_distance_sq_f(context, transa, transb, m, n, A, LDA, B, LDB, C, LDC) end function qmckl_distance_sq - #+END_SRC + #+END_SRC - #+BEGIN_SRC f90 :tangle qmckl_f.f90 + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface integer(c_int32_t) function qmckl_distance_sq(context, transa, transb, m, n, A, LDA, B, LDB, C, LDC) & bind(C) @@ -237,10 +237,10 @@ end function qmckl_distance_sq real (c_double) , intent(out) :: C(ldc,n) end function qmckl_distance_sq end interface - #+END_SRC + #+END_SRC -**** Test :noexport: - #+BEGIN_SRC f90 :tangle test_qmckl_distance_f.f90 +***** Test :noexport: + #+BEGIN_SRC f90 :tangle test_qmckl_distance_f.f90 integer(c_int32_t) function test_qmckl_distance_sq(context) bind(C) use qmckl implicit none @@ -336,22 +336,22 @@ integer(c_int32_t) function test_qmckl_distance_sq(context) bind(C) deallocate(A,B,C) end function test_qmckl_distance_sq - #+END_SRC + #+END_SRC - #+BEGIN_SRC C :comments link :tangle test_qmckl_distance.c + #+BEGIN_SRC C :comments link :tangle test_qmckl_distance.c int test_qmckl_distance_sq(qmckl_context context); munit_assert_int(0, ==, test_qmckl_distance_sq(context)); - #+END_SRC -** End of files :noexport: + #+END_SRC +*** End of files :noexport: - #+BEGIN_SRC C :comments link :tangle test_qmckl_distance.c + #+BEGIN_SRC C :comments link :tangle test_qmckl_distance.c if (qmckl_context_destroy(context) != QMCKL_SUCCESS) return QMCKL_FAILURE; return MUNIT_OK; } - #+END_SRC + #+END_SRC -# -*- mode: org -*- -# vim: syntax=c + # -*- mode: org -*- + # vim: syntax=c diff --git a/src/qmckl_footer.org b/src/qmckl_footer.org index 53fab1b..5ed01c7 100644 --- a/src/qmckl_footer.org +++ b/src/qmckl_footer.org @@ -1,3 +1,8 @@ +* Acknowledgments + + [[https://trex-coe.eu/sites/default/files/inline-images/euflag.jpg]] + [[https://trex-coe.eu][TREX: Targeting Real Chemical Accuracy at the Exascale]] project has received funding from the European Union’s Horizon 2020 - Research and Innovation program - under grant agreement no. 952165. The content of this document does not represent the opinion of the European Union, and the European Union is not responsible for any use that might be made of such content. + * End of header files :noexport: #+BEGIN_SRC C :tangle qmckl.h diff --git a/src/qmckl_memory.org b/src/qmckl_memory.org index cf16b9e..7e3ca79 100644 --- a/src/qmckl_memory.org +++ b/src/qmckl_memory.org @@ -1,33 +1,33 @@ -* Memory management +** Memory management -We override the allocation functions to enable the possibility of -optimized libraries to fine-tune the memory allocation. + We override the allocation functions to enable the possibility of + optimized libraries to fine-tune the memory allocation. -2 files are produced: -- a source file : =qmckl_memory.c= -- a test file : =test_qmckl_memory.c= + 2 files are produced: + - a source file : =qmckl_memory.c= + - a test file : =test_qmckl_memory.c= -** Headers :noexport: - #+BEGIN_SRC C :tangle qmckl_memory.c +*** Headers :noexport: + #+BEGIN_SRC C :tangle qmckl_memory.c #include "qmckl.h" - #+END_SRC + #+END_SRC - #+BEGIN_SRC C :tangle test_qmckl_memory.c + #+BEGIN_SRC C :tangle test_qmckl_memory.c #include "qmckl.h" #include "munit.h" MunitResult test_qmckl_memory() { - #+END_SRC + #+END_SRC -** =qmckl_malloc= +*** =qmckl_malloc= - Memory allocation function, letting the library choose how the - memory will be allocated, and a pointer is returned to the user. + Memory allocation function, letting the library choose how the + memory will be allocated, and a pointer is returned to the user. - #+BEGIN_SRC C :tangle qmckl.h + #+BEGIN_SRC C :tangle qmckl.h void* qmckl_malloc(const qmckl_context ctx, const size_t size); - #+END_SRC + #+END_SRC - #+BEGIN_SRC f90 :tangle qmckl_f.f90 + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface type (c_ptr) function qmckl_malloc (context, size) bind(C) use, intrinsic :: iso_c_binding @@ -35,10 +35,10 @@ void* qmckl_malloc(const qmckl_context ctx, const size_t size); integer (c_int64_t), intent(in), value :: size end function qmckl_malloc end interface - #+END_SRC + #+END_SRC -*** Source - #+BEGIN_SRC C :tangle qmckl_memory.c +**** Source + #+BEGIN_SRC C :tangle qmckl_memory.c void* qmckl_malloc(const qmckl_context ctx, const size_t size) { if (ctx == (qmckl_context) 0) { /* Avoids unused parameter error */ @@ -47,10 +47,10 @@ void* qmckl_malloc(const qmckl_context ctx, const size_t size) { return malloc( (size_t) size ); } - #+END_SRC + #+END_SRC -*** Test :noexport: - #+BEGIN_SRC C :tangle test_qmckl_memory.c +**** Test :noexport: + #+BEGIN_SRC C :tangle test_qmckl_memory.c int *a; a = (int*) qmckl_malloc( (qmckl_context) 1, 3*sizeof(int)); a[0] = 1; @@ -59,43 +59,43 @@ a[2] = 3; munit_assert_int(a[0], ==, 1); munit_assert_int(a[1], ==, 2); munit_assert_int(a[2], ==, 3); + #+END_SRC + +*** =qmckl_free= + + #+BEGIN_SRC C :tangle qmckl.h +void qmckl_free(void *ptr); #+END_SRC -** =qmckl_free= - - #+BEGIN_SRC C :tangle qmckl.h -void qmckl_free(void *ptr); - #+END_SRC - - #+BEGIN_SRC f90 :tangle qmckl_f.f90 + #+BEGIN_SRC f90 :tangle qmckl_f.f90 interface subroutine qmckl_free (ptr) bind(C) use, intrinsic :: iso_c_binding type (c_ptr), intent(in), value :: ptr end subroutine qmckl_free end interface - #+END_SRC -*** Source - #+BEGIN_SRC C :tangle qmckl_memory.c + #+END_SRC +**** Source + #+BEGIN_SRC C :tangle qmckl_memory.c void qmckl_free(void *ptr) { free(ptr); } - #+END_SRC + #+END_SRC -*** Test :noexport: - #+BEGIN_SRC C :tangle test_qmckl_memory.c +**** Test :noexport: + #+BEGIN_SRC C :tangle test_qmckl_memory.c qmckl_free(a); - #+END_SRC + #+END_SRC -** End of files :noexport: +*** End of files :noexport: -*** Test - #+BEGIN_SRC C :comments org :tangle test_qmckl_memory.c +**** Test + #+BEGIN_SRC C :comments org :tangle test_qmckl_memory.c return MUNIT_OK; } - #+END_SRC + #+END_SRC -# -*- mode: org -*- -# vim: syntax=c + # -*- mode: org -*- + # vim: syntax=c diff --git a/src/test_qmckl.org b/src/test_qmckl.org index bcd0fce..1489768 100644 --- a/src/test_qmckl.org +++ b/src/test_qmckl.org @@ -1,18 +1,11 @@ -#+TITLE: QMCkl test +* QMCkl test :noexport: -#+HTML_HEAD: -#+HTML_HEAD: -#+HTML_HEAD: -#+HTML_HEAD: -#+HTML_HEAD: -#+HTML_HEAD: + This file is the main program of the unit tests. The tests rely on the + $\mu$unit framework, which is provided as a git submodule. -This file is the main program of the unit tests. The tests rely on the -$\mu$unit framework, which is provided as a git submodule. - -First, we use a script to find the list of all the produced test files: -#+NAME: test-files -#+BEGIN_SRC sh :exports none :results value + First, we use a script to find the list of all the produced test files: + #+NAME: test-files + #+BEGIN_SRC sh :exports none :results value grep BEGIN_SRC *.org | \ grep test_qmckl_ | \ rev | \ @@ -20,57 +13,57 @@ grep BEGIN_SRC *.org | \ rev | \ sort | \ uniq -#+END_SRC + #+END_SRC -#+RESULTS: test-files -| test_qmckl_ao.c | -| test_qmckl_context.c | -| test_qmckl_distance.c | -| test_qmckl_memory.c | + #+RESULTS: test-files + | test_qmckl_ao.c | + | test_qmckl_context.c | + | test_qmckl_distance.c | + | test_qmckl_memory.c | -We generate the function headers -#+BEGIN_SRC sh :var files=test-files :exports output :results raw + We generate the function headers + #+BEGIN_SRC sh :var files=test-files :exports output :results raw echo "#+NAME: headers" echo "#+BEGIN_SRC C :tangle no" for file in $files do - routine=${file%.c} - echo "MunitResult ${routine}();" + routine=${file%.c} + echo "MunitResult ${routine}();" done echo "#+END_SRC" -#+END_SRC + #+END_SRC -#+RESULTS: -#+NAME: headers -#+BEGIN_SRC C :tangle no + #+RESULTS: + #+NAME: headers + #+BEGIN_SRC C :tangle no MunitResult test_qmckl_ao(); MunitResult test_qmckl_context(); MunitResult test_qmckl_distance(); MunitResult test_qmckl_memory(); -#+END_SRC + #+END_SRC -and the required function calls: -#+BEGIN_SRC sh :var files=test-files :exports output :results raw + and the required function calls: + #+BEGIN_SRC sh :var files=test-files :exports output :results raw echo "#+NAME: calls" echo "#+BEGIN_SRC C :tangle no" for file in $files do - routine=${file%.c} - echo " { (char*) \"${routine}\", ${routine}, NULL,NULL,MUNIT_TEST_OPTION_NONE,NULL}," + routine=${file%.c} + echo " { (char*) \"${routine}\", ${routine}, NULL,NULL,MUNIT_TEST_OPTION_NONE,NULL}," done echo "#+END_SRC" -#+END_SRC - -#+RESULTS: -#+NAME: calls -#+BEGIN_SRC C :tangle no + #+END_SRC + + #+RESULTS: + #+NAME: calls + #+BEGIN_SRC C :tangle no { (char*) "test_qmckl_ao", test_qmckl_ao, NULL,NULL,MUNIT_TEST_OPTION_NONE,NULL}, { (char*) "test_qmckl_context", test_qmckl_context, NULL,NULL,MUNIT_TEST_OPTION_NONE,NULL}, { (char*) "test_qmckl_distance", test_qmckl_distance, NULL,NULL,MUNIT_TEST_OPTION_NONE,NULL}, { (char*) "test_qmckl_memory", test_qmckl_memory, NULL,NULL,MUNIT_TEST_OPTION_NONE,NULL}, -#+END_SRC + #+END_SRC -#+BEGIN_SRC C :comments link :noweb yes :tangle test_qmckl.c + #+BEGIN_SRC C :comments link :noweb yes :tangle test_qmckl.c #include "qmckl.h" #include "munit.h" <> @@ -78,15 +71,15 @@ echo "#+END_SRC" int main(int argc, char* argv[MUNIT_ARRAY_PARAM(argc + 1)]) { static MunitTest test_suite_tests[] = { -<> + <> { NULL, NULL, NULL, NULL, MUNIT_TEST_OPTION_NONE, NULL } }; - static const MunitSuite test_suite = + static const MunitSuite test_suite = { (char*) "", test_suite_tests, NULL, 1, MUNIT_SUITE_OPTION_NONE }; - return munit_suite_main(&test_suite, (void*) "µnit", argc, argv); -} -#+END_SRC + return munit_suite_main(&test_suite, (void*) "µnit", argc, argv); + } + #+END_SRC