Design
The domain of quantum chemistry needs a library in which the main kernels of Quantum Monte Carlo methods are implemented. In the library proposed in this project, we expose the main algorithms in a simple language and provide a standard API and tests to enable the development of high-performance QMCkl implementations taking advantage of modern hardware.
The ultimate goal of QMCkl is to provide a high-performance implementation of the main kernels of QMC. In this particular repository, we focus on the definition of the API and the tests, and on a pedagogical presentation of the algorithms. We expect the HPC experts to use this repository as a reference for re-writing optimized libraries.
The proposed API should allow the library to:
- take care of 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).
Fortran is one of the most common languages used by the community, and is simple enough to make the algorithms readable. Hence we propose in this pedagogical implementation of QMCkl to use Fortran to express the algorithms. For specific internal functions where the C language is more natural, C is used.
As Fortran modules generate compiler-dependent files, the use of modules is restricted to the internal use of the library, otherwise the compliance with C is violated.
The external dependencies should be kept as small as possible.
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
- 32-bit and 64-bit integers and arrays
- Pointers should be represented as 64-bit integers (even on 32-bit architectures)
- ASCII strings are represented as a pointers to character arrays and terminated by a zero character (C convention).
To facilitate the use in other languages than C, we provide some bindings in other languages in other repositories.
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 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.
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.
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.
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.
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.
High quality documentation is absolutely mandatory. The priority is to provide reference documentation for each function. The documentation should be written inside the source files to help keeping the documentation consistent with the code.
Org-mode markup syntax is recommended, as among other advantages it natively supports LaTex for equations.
Use qmckl_ as a prefix for all exported functions and variables.
All exported header files should have a filename with the prefix
qmckl_.
To improve readability, we maintain a consistent coding style in the library.
- For C source files, we will use __(decide on a coding style)__
- For Fortran source files, we will use __(decide on a coding style)__
Coding style can be automatically checked with clang-format.
- The discipline and method architecture for reusable libraries
- Org-Mode Is One of the Most Reasonable Markup Languages to Use for Text
The TREX team welcomes new contributions to enhance the functionality of the library. Much emphasis is placed on ensuring the stability of the existing functions, library consistency, and fixing any reported bugs. Potential contributors are encouraged to gain familiarity with the library by investigating and fixing known problems listed in the issue tracker.
Adding large amounts of new code is difficult because it leads to differences in the maturity of different parts of the library. To maintain stability, any new functionality is encouraged as packages, built on top of GSL and maintained independently by the author, as in other free software projects (such as the Perl CPAN archive and TeX CTAN archive, etc).
This document was greatly inspired by the design principles exposed in the documentation of the GNU Scientific Library.
The development of this library is supported by the TREX center of Excellence.
