TREX/qmckl
1
0
Fork 0
mirror of https://github.com/TREX-CoE/qmckl.git synced 2025-01-03 10:06:09 +01:00
Code Issues Projects Releases Wiki Activity

Added make doc

Browse Source
This commit is contained in:
Anthony Scemama 2020-10-22 01:24:14 +02:00
parent 3286145e66
commit 9fde54922e
9 changed files with 278 additions and 208 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
src/.gitignore vendored
View File

@ -2,6 +2,7 @@
*.c
*.f90
*.h
*.html
*~
*.so
Makefile.generated

3
src/Makefile
View File

@ -21,6 +21,9 @@ libqmckl.so: Makefile.generated
test: Makefile.generated
$(MAKE) -f Makefile.generated test
doc:$(ORG_SOURCE_FILES)
./create_doc.sh $(ORG_SOURCE_FILES)
clean:
rm -f qmckl.h test_qmckl_* qmckl_*.f90 qmckl_*.c qmckl_*.o qmckl_*.h Makefile.generated libqmckl.so

51
src/README.org
View File

@ -1,6 +1,13 @@
* QMCkl source code
#+TITLE: QMCkl source code documentation
** Introduction
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/htmlize.css"/>
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/readtheorg.css"/>
#+HTML_HEAD: <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
#+HTML_HEAD: <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js"></script>
#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js"></script>
* Introduction
The ultimate goal of QMCkl is to provide a high-performance
implementation of the main kernels of QMC. In this particular
@ -10,7 +17,7 @@
optimized libraries.
Literate programming is particularly adapted in this context.
Source files are written in [[ottps://karl-voit.at/2017/09/23/orgmode-as-markup-only/][org-mode]] format, to provide useful
Source files are written in [[https://karl-voit.at/2017/09/23/orgmode-as-markup-only/][org-mode]] format, to provide useful
comments and LaTex formulas close to the code. There exists multiple
possibilities to convert org-mode files into different formats such as
HTML or pdf.
@ -20,7 +27,7 @@
The code is extracted from the org files using Emacs as a command-line
tool in the =Makefile=, and then the produced files are compiled.
*** Language used
** Language used
Fortran is one of the most common languages used by the community,
and is simple enough to make the algorithms readable. Hence we
@ -36,7 +43,7 @@
external libraries should be used /only/ if their used is strongly
justified.
*** Source code editing
** Source code editing
Any text editor can be used to edit org-mode files. For a better
user experience Emacs is recommended.
@ -62,13 +69,13 @@ rm ${nb}.md
And pandoc can convert multiple markdown formats into org-mode.
*** Writing in Fortran
** Writing in Fortran
The Fortran source files should provide a C interface using
iso-c-binding. The name of the Fortran source files should end
with =_f.f90= to be properly handled by the Makefile.
*** Coding style
** Coding style
# TODO: decide on a coding style
To improve readability, we maintain a consistent coding style in the library.
@ -78,7 +85,7 @@ 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
@ -87,7 +94,7 @@ rm ${nb}.md
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
@ -97,7 +104,7 @@ rm ${nb}.md
produced C files should be =xxx.c= and =xxx.h= and the name of the
produced Fortran files should be =xxx.f90=
*** 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
@ -116,7 +123,7 @@ rm ${nb}.md
# TODO : Link to repositories for bindings
*** 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
@ -137,7 +144,7 @@ rm ${nb}.md
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).
@ -146,7 +153,7 @@ rm ${nb}.md
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
@ -161,7 +168,7 @@ rm ${nb}.md
# 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
@ -170,7 +177,7 @@ rm ${nb}.md
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,
@ -180,21 +187,21 @@ rm ${nb}.md
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
** Documentation
* Documentation
- [[qmckl.org][Main QMCkl header file]]
- [[qmckl_memory.org][Memory management]]
- [[qmckl_context.org][Context]]
- [[qmckl_distance.org][Distance]]
- [[./qmckl.org][Main QMCkl header file]]
- [[./qmckl_memory.org][Memory management]]
- [[./qmckl_context.org][Context]]
- [[./qmckl_distance.org][Distance]]
** Acknowledgments
* 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.

22
src/create_doc.sh Executable file
View File

@ -0,0 +1,22 @@
#!/bin/bash
# Tangle org files
emacsclient -a "" \
--socket-name=org_to_code \
--eval "(require 'org)"
for INPUT in $@ ; do
echo $INPUT
emacsclient \
--no-wait \
--socket-name=org_to_code \
--eval "(find-file \"$INPUT\")" \
--eval "(org-html-export-to-html)"
done
emacsclient \
--no-wait \
--socket-name=org_to_code \
--eval '(kill-emacs)'

7
src/qmckl.org
View File

@ -2,6 +2,13 @@
# vim: syntax=c
#+TITLE: QMCkl C header
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/htmlize.css"/>
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/readtheorg.css"/>
#+HTML_HEAD: <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
#+HTML_HEAD: <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js"></script>
#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js"></script>
This file produces the =qmckl.h= header file, which is included in all
other C header files. It is the main entry point to the library.

10
src/qmckl_context.org
View File

@ -2,6 +2,14 @@
# vim: syntax=c
#+TITLE: Context
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/htmlize.css"/>
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/readtheorg.css"/>
#+HTML_HEAD: <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
#+HTML_HEAD: <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js"></script>
#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js"></script>
This file is written in C because it is more natural to express the context in
C than in Fortran.
@ -36,7 +44,7 @@ MunitResult test_qmckl_context() {
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.
A value of 0 for the context is equivalent to a =NULL= pointer.
*** Source
#+BEGIN_SRC C :comments link :tangle qmckl_context.c

9
src/qmckl_distance.org
View File

@ -2,6 +2,13 @@
# vim: syntax=c
#+TITLE: Computation of distances
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/htmlize.css"/>
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/readtheorg.css"/>
#+HTML_HEAD: <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
#+HTML_HEAD: <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js"></script>
#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js"></script>
Function for the computation of distances between particles.
3 files are produced:
@ -65,7 +72,7 @@ MunitResult test_qmckl_distance() {
Computes the matrix of the squared distances between all pairs of
points in two sets, one point within each set:
\[
C_{ij^2} = \sum_{k=1}^3 (A_{i,k}-B_{j,k})^2
C_{ij} = \sum_{k=1}^3 (A_{i,k}-B_{j,k})^2
\]
*** Arguments

34
src/qmckl_memory.org
View File

@ -2,6 +2,14 @@
# vim: syntax=c
#+TITLE: Memory management
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/htmlize.css"/>
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/readtheorg.css"/>
#+HTML_HEAD: <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
#+HTML_HEAD: <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js"></script>
#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js"></script>
We override the allocation functions to enable the possibility of
optimized libraries to fine-tune the memory allocation.
@ -10,34 +18,34 @@ optimized libraries to fine-tune the memory allocation.
- a source file : =qmckl_memory.c=
- a test file : =test_qmckl_memory.c=
*** Header
** Header
#+BEGIN_SRC C :comments link :tangle qmckl_memory.h
#ifndef QMCKL_MEMORY_H
#define QMCKL_MEMORY_H
#include "qmckl.h"
#+END_SRC
*** Source
** Source
#+BEGIN_SRC C :comments link :tangle qmckl_memory.c
#include <stdlib.h>
#include "qmckl_memory.h"
#+END_SRC
*** Test
** Test
#+BEGIN_SRC C :comments link :tangle test_qmckl_memory.c
#include "qmckl.h"
#include "munit.h"
MunitResult test_qmckl_memory() {
#+END_SRC
** =qmckl_malloc=
* =qmckl_malloc=
Analogous of =malloc, but passing a context and a signed 64-bit integers as argument.=
*** Header
** Header
#+BEGIN_SRC C :comments link :tangle qmckl_memory.h
void* qmckl_malloc(const qmckl_context ctx, const size_t size);
#+END_SRC
*** Source
** Source
#+BEGIN_SRC C :comments link :tangle qmckl_memory.c
void* qmckl_malloc(const qmckl_context ctx, const size_t size) {
if (ctx == (qmckl_context) 0) {
@ -49,7 +57,7 @@ void* qmckl_malloc(const qmckl_context ctx, const size_t size) {
#+END_SRC
*** Test
** Test
#+BEGIN_SRC C :comments link :tangle test_qmckl_memory.c
int *a;
a = (int*) qmckl_malloc( (qmckl_context) 1, 3*sizeof(int));
@ -61,33 +69,33 @@ void* qmckl_malloc(const qmckl_context ctx, const size_t size) {
munit_assert_int(a[2], ==, 3);
#+END_SRC
** =qmckl_free=
* =qmckl_free=
*** Header
** Header
#+BEGIN_SRC C :comments link :tangle qmckl_memory.h
void qmckl_free(void *ptr);
#+END_SRC
*** Source
** Source
#+BEGIN_SRC C :comments link :tangle qmckl_memory.c
void qmckl_free(void *ptr) {
free(ptr);
}
#+END_SRC
*** Test
** Test
#+BEGIN_SRC C :comments link :tangle test_qmckl_memory.c
qmckl_free(a);
#+END_SRC
* End of files
*** Header
** Header
#+BEGIN_SRC C :comments link :tangle qmckl_memory.h
#endif
#+END_SRC
*** Test
** Test
#+BEGIN_SRC C :comments link :tangle test_qmckl_memory.c
return MUNIT_OK;
}

7
src/test_qmckl.org
View File

@ -1,5 +1,12 @@
#+TITLE: QMCkl test
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/htmlize.css"/>
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/readtheorg.css"/>
#+HTML_HEAD: <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
#+HTML_HEAD: <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js"></script>
#+HTML_HEAD: <script type="text/javascript" src="http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js"></script>
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.