qmckl/src

QMCkl source code documentation

• Introduction
  • Language used
  • Source code editing
  • Writing in Fortran
  • Coding style
  • Design of the library
    • Naming conventions
    • Application programming interface
    • Global state
    • Low-level functions
    • High-level functions
    • Numerical precision
  • Algorithms
  • Rules for the API
• Documentation

Introduction

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.

Literate programming is particularly adapted in this context. Source files are written in 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. For a tutorial on literate programming with org-mode, follow this link.

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

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, so external libraries should be used only if their used is strongly justified.

Source code editing

Any text editor can be used to edit org-mode files. For a better user experience Emacs is recommended. For users hating Emacs, it is good to know that Emacs can behave like Vim when switched into ``Evil'' mode. There also exists Spacemacs which helps the transition for Vim users.

For users with a preference for Jupyter notebooks, the following script can convert jupyter notebooks to org-mode files:

#!/bin/bash
# $ nb_to_org.sh notebook.ipynb
# produces the org-mode file notebook.org

set -e

nb=$(basename $1 .ipynb)
jupyter nbconvert --to markdown ${nb}.ipynb --output ${nb}.md
pandoc ${nb}.md -o ${nb}.org
rm ${nb}.md

And pandoc can convert multiple markdown formats into org-mode.

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. The names of the functions defined in fortran should be the same as those exposed in the API suffixed by _f. Fortran interface files should also be written in a file with a .fh extension.

For more guidelines on using Fortran to generate a C interface, see this link

Coding style

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.

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

We chose a multi-layered design with low-level and high-level functions (see below).

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_.

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.

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:

• 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.

To facilitate the use in other languages than C, we provide some bindings in other languages in other repositories.

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.

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 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

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.

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.

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.

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