mirror of
https://github.com/TREX-CoE/qmckl.git
synced 2024-07-22 10:47:45 +02:00
| .gitignore | ||
| .nojekyll | ||
| qmckl_ao.html | ||
| qmckl_context.html | ||
| qmckl_distance.html | ||
| qmckl_memory.html | ||
| qmckl.html | ||
| README.html | ||
| test_qmckl.html | ||
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>QMCkl source code documentation</title>
<!-- 2020-10-28 Wed 23:57 -->
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta name="generator" content="Org-mode" />
<style type="text/css">
<!--/*--><![CDATA[/*><!--*/
.title { text-align: center; }
.todo { font-family: monospace; color: red; }
.done { color: green; }
.tag { background-color: #eee; font-family: monospace;
padding: 2px; font-size: 80%; font-weight: normal; }
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.right { margin-left: auto; margin-right: 0px; text-align: right; }
.left { margin-left: 0px; margin-right: auto; text-align: left; }
.center { margin-left: auto; margin-right: auto; text-align: center; }
.underline { text-decoration: underline; }
#postamble p, #preamble p { font-size: 90%; margin: .2em; }
p.verse { margin-left: 3%; }
pre {
border: 1px solid #ccc;
box-shadow: 3px 3px 3px #eee;
padding: 8pt;
font-family: monospace;
overflow: auto;
margin: 1.2em;
}
pre.src {
position: relative;
overflow: visible;
padding-top: 1.2em;
}
pre.src:before {
display: none;
position: absolute;
background-color: white;
top: -10px;
right: 10px;
padding: 3px;
border: 1px solid black;
}
pre.src:hover:before { display: inline;}
pre.src-sh:before { content: 'sh'; }
pre.src-bash:before { content: 'sh'; }
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
pre.src-R:before { content: 'R'; }
pre.src-perl:before { content: 'Perl'; }
pre.src-java:before { content: 'Java'; }
pre.src-sql:before { content: 'SQL'; }
table { border-collapse:collapse; }
caption.t-above { caption-side: top; }
caption.t-bottom { caption-side: bottom; }
td, th { vertical-align:top; }
th.right { text-align: center; }
th.left { text-align: center; }
th.center { text-align: center; }
td.right { text-align: right; }
td.left { text-align: left; }
td.center { text-align: center; }
dt { font-weight: bold; }
.footpara:nth-child(2) { display: inline; }
.footpara { display: block; }
.footdef { margin-bottom: 1em; }
.figure { padding: 1em; }
.figure p { text-align: center; }
.inlinetask {
padding: 10px;
border: 2px solid gray;
margin: 10px;
background: #ffffcc;
}
#org-div-home-and-up
{ text-align: right; font-size: 70%; white-space: nowrap; }
textarea { overflow-x: auto; }
.linenr { font-size: smaller }
.code-highlighted { background-color: #ffff00; }
.org-info-js_info-navigation { border-style: none; }
#org-info-js_console-label
{ font-size: 10px; font-weight: bold; white-space: nowrap; }
.org-info-js_search-highlight
{ background-color: #ffff00; color: #000000; font-weight: bold; }
/*]]>*/-->
</style>
<link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/htmlize.css"/>
<link rel="stylesheet" type="text/css" href="http://www.pirilampo.org/styles/readtheorg/css/readtheorg.css"/>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.4/js/bootstrap.min.js"></script>
<script type="text/javascript" src="http://www.pirilampo.org/styles/lib/js/jquery.stickytableheaders.js"></script>
<script type="text/javascript" src="http://www.pirilampo.org/styles/readtheorg/js/readtheorg.js"></script>
<script type="text/javascript">
/*
@licstart The following is the entire license notice for the
JavaScript code in this tag.
Copyright (C) 2012-2013 Free Software Foundation, Inc.
The JavaScript code in this tag is free software: you can
redistribute it and/or modify it under the terms of the GNU
General Public License (GNU GPL) as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version. The code is distributed WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU GPL for more details.
As additional permission under GNU GPL version 3 section 7, you
may distribute non-source (e.g., minimized or compacted) forms of
that code without the copy of the GNU GPL normally required by
section 4, provided you include this license notice and a URL
through which recipients can access the Corresponding Source.
@licend The above is the entire license notice
for the JavaScript code in this tag.
*/
<!--/*--><![CDATA[/*><!--*/
function CodeHighlightOn(elem, id)
{
var target = document.getElementById(id);
if(null != target) {
elem.cacheClassElem = elem.className;
elem.cacheClassTarget = target.className;
target.className = "code-highlighted";
elem.className = "code-highlighted";
}
}
function CodeHighlightOff(elem, id)
{
var target = document.getElementById(id);
if(elem.cacheClassElem)
elem.className = elem.cacheClassElem;
if(elem.cacheClassTarget)
target.className = elem.cacheClassTarget;
}
/*]]>*///-->
</script>
<script type="text/javascript" src="http://orgmode.org/mathjax/MathJax.js"></script>
<script type="text/javascript">
<!--/*--><![CDATA[/*><!--*/
MathJax.Hub.Config({
// Only one of the two following lines, depending on user settings
// First allows browser-native MathML display, second forces HTML/CSS
// config: ["MMLorHTML.js"], jax: ["input/TeX"],
jax: ["input/TeX", "output/HTML-CSS"],
extensions: ["tex2jax.js","TeX/AMSmath.js","TeX/AMSsymbols.js",
"TeX/noUndefined.js"],
tex2jax: {
inlineMath: [ ["\\(","\\)"] ],
displayMath: [ ['$$','$$'], ["\\[","\\]"], ["\\begin{displaymath}","\\end{displaymath}"] ],
skipTags: ["script","noscript","style","textarea","pre","code"],
ignoreClass: "tex2jax_ignore",
processEscapes: false,
processEnvironments: true,
preview: "TeX"
},
showProcessingMessages: true,
displayAlign: "center",
displayIndent: "2em",
"HTML-CSS": {
scale: 100,
availableFonts: ["STIX","TeX"],
preferredFont: "TeX",
webFont: "TeX",
imageFont: "TeX",
showMathMenu: true,
},
MMLorHTML: {
prefer: {
MSIE: "MML",
Firefox: "MML",
Opera: "HTML",
other: "HTML"
}
}
});
/*]]>*///-->
</script>
</head>
<body>
<div id="content">
<h1 class="title">QMCkl source code documentation</h1>
<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#sec-1">1. Introduction</a>
<ul>
<li><a href="#sec-1-1">1.1. Language used</a></li>
<li><a href="#sec-1-2">1.2. Source code editing</a></li>
<li><a href="#sec-1-3">1.3. Writing in Fortran</a></li>
<li><a href="#sec-1-4">1.4. Coding style</a></li>
</ul>
</li>
<li><a href="#sec-2">2. Design of the library</a>
<ul>
<li><a href="#sec-2-1">2.1. Naming conventions</a></li>
<li><a href="#sec-2-2">2.2. Application programming interface</a></li>
<li><a href="#sec-2-3">2.3. Global state</a></li>
<li><a href="#sec-2-4">2.4. Low-level functions</a></li>
<li><a href="#sec-2-5">2.5. High-level functions</a></li>
<li><a href="#sec-2-6">2.6. Numerical precision</a></li>
</ul>
</li>
<li><a href="#sec-3">3. Algorithms</a></li>
<li><a href="#sec-4">4. Rules for the API</a></li>
<li><a href="#sec-5">5. Documentation</a></li>
<li><a href="#sec-6">6. Acknowledgments</a></li>
</ul>
</div>
</div>
<div id="outline-container-sec-1" class="outline-2">
<h2 id="sec-1"><span class="section-number-2">1</span> Introduction</h2>
<div class="outline-text-2" id="text-1">
<p>
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 <i>pedagogical</i> presentation of the algorithms. We expect the
HPC experts to use this repository as a reference for re-writing
optimized libraries.
</p>
<p>
Literate programming is particularly adapted in this context.
Source files are written in <a href="https://karl-voit.at/2017/09/23/orgmode-as-markup-only/">org-mode</a> 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
<a href="http://www.howardism.org/Technical/Emacs/literate-programming-tutorial.html">this link</a>.
</p>
<p>
The code is extracted from the org files using Emacs as a command-line
tool in the <code>Makefile</code>, and then the produced files are compiled.
</p>
</div>
<div id="outline-container-sec-1-1" class="outline-3">
<h3 id="sec-1-1"><span class="section-number-3">1.1</span> Language used</h3>
<div class="outline-text-3" id="text-1-1">
<p>
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.
</p>
<p>
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.
</p>
<p>
The external dependencies should be kept as small as possible, so
external libraries should be used <i>only</i> if their used is strongly
justified.
</p>
</div>
</div>
<div id="outline-container-sec-1-2" class="outline-3">
<h3 id="sec-1-2"><span class="section-number-3">1.2</span> Source code editing</h3>
<div class="outline-text-3" id="text-1-2">
<p>
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
<a href="https://www.spacemacs.org">Spacemacs</a> which helps the transition for Vim users.
</p>
<p>
For users with a preference for Jupyter notebooks, the following
script can convert jupyter notebooks to org-mode files:
</p>
<div class="org-src-container">
<pre class="src src-"nb_to_org.sh"lang"nb_to_org.sh"switches"nb_to_org.sh"flags">"nb_to_org.sh"body
</pre>
</div>
<p>
And pandoc can convert multiple markdown formats into org-mode.
</p>
</div>
</div>
<div id="outline-container-sec-1-3" class="outline-3">
<h3 id="sec-1-3"><span class="section-number-3">1.3</span> Writing in Fortran</h3>
<div class="outline-text-3" id="text-1-3">
<p>
The Fortran source files should provide a C interface using
<code>iso_c_binding</code>. The name of the Fortran source files should end
with <code>_f.f90</code> 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 <code>_f</code>.
Fortran interface files should also be written in a file with a
<code>.fh</code> extension.
</p>
</div>
</div>
<div id="outline-container-sec-1-4" class="outline-3">
<h3 id="sec-1-4"><span class="section-number-3">1.4</span> Coding style</h3>
<div class="outline-text-3" id="text-1-4">
<p>
To improve readability, we maintain a consistent coding style in the library.
</p>
<ul class="org-ul">
<li>For C source files, we will use <span class="underline"><span class="underline">(decide on a coding style)</span></span>
</li>
<li>For Fortran source files, we will use <span class="underline"><span class="underline">(decide on a coding style)</span></span>
</li>
</ul>
<p>
Coding style can be automatically checked with <a href="https://clang.llvm.org/docs/ClangFormat.html">clang-format</a>.
</p>
</div>
</div>
</div>
<div id="outline-container-sec-2" class="outline-2">
<h2 id="sec-2"><span class="section-number-2">2</span> Design of the library</h2>
<div class="outline-text-2" id="text-2">
<p>
The proposed API should allow the library to:
</p>
<ul class="org-ul">
<li>deal with memory transfers between CPU and accelerators
</li>
<li>use different levels of floating-point precision
</li>
</ul>
<p>
We chose a multi-layered design with low-level and high-level
functions (see below).
</p>
</div>
<div id="outline-container-sec-2-1" class="outline-3">
<h3 id="sec-2-1"><span class="section-number-3">2.1</span> Naming conventions</h3>
<div class="outline-text-3" id="text-2-1">
<p>
Use <code>qmckl_</code> as a prefix for all exported functions and variables.
All exported header files should have a filename with the prefix
<code>qmckl_</code>.
</p>
<p>
If the name of the org-mode file is <code>xxx.org</code>, the name of the
produced C files should be <code>xxx.c</code> and <code>xxx.h</code> and the name of the
produced Fortran files should be <code>xxx.f90</code>
</p>
<p>
Arrays are in uppercase and scalars are in lowercase.
</p>
</div>
</div>
<div id="outline-container-sec-2-2" class="outline-3">
<h3 id="sec-2-2"><span class="section-number-3">2.2</span> Application programming interface</h3>
<div class="outline-text-3" id="text-2-2">
<p>
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:
</p>
<ul class="org-ul">
<li>32-bit and 64-bit floats and arrays (<code>real</code> and <code>double</code>)
</li>
<li>32-bit and 64-bit integers and arrays (<code>int32_t</code> and <code>int64_t</code>)
</li>
<li>Pointers should be represented as 64-bit integers (even on
32-bit architectures)
</li>
<li>ASCII strings are represented as a pointers to a character arrays
and terminated by a zero character (C convention).
</li>
</ul>
<p>
To facilitate the use in other languages than C, we provide some
bindings in other languages in other repositories.
</p>
</div>
</div>
<div id="outline-container-sec-2-3" class="outline-3">
<h3 id="sec-2-3"><span class="section-number-3">2.3</span> Global state</h3>
<div class="outline-text-3" id="text-2-3">
<p>
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
<code>context</code> variable, built by the library with the
<code>qmckl_context_create</code> function. The <code>context</code> contains the global
state of the library, and is used as the first argument of many
QMCkl functions.
</p>
<p>
Modifying the state is done by setters and getters, prefixed
by <code>qmckl_context_set_</code> an <code>qmckl_context_get_</code>.
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 <code>qmckl_context_update_</code> functions.
The context and its old versions can be destroyed with
<code>qmckl_context_destroy</code>.
</p>
</div>
</div>
<div id="outline-container-sec-2-4" class="outline-3">
<h3 id="sec-2-4"><span class="section-number-3">2.4</span> Low-level functions</h3>
<div class="outline-text-3" id="text-2-4">
<p>
Low-level functions are very simple functions which are leaves of the
function call tree (they don't call any other QMCkl function).
</p>
<p>
This functions are <i>pure</i>, and unaware of the QMCkl <code>context</code>. They are
not allowed to allocate/deallocate memory, and if they need
temporary memory it should be provided in input.
</p>
</div>
</div>
<div id="outline-container-sec-2-5" class="outline-3">
<h3 id="sec-2-5"><span class="section-number-3">2.5</span> High-level functions</h3>
<div class="outline-text-3" id="text-2-5">
<p>
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.
</p>
<p>
The high-level functions should be pure, unless the introduction of
non-purity is justified. All the side effects should be made in the
<code>context</code> variable.
</p>
</div>
</div>
<div id="outline-container-sec-2-6" class="outline-3">
<h3 id="sec-2-6"><span class="section-number-3">2.6</span> Numerical precision</h3>
<div class="outline-text-3" id="text-2-6">
<p>
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
<code>context</code> variable.
</p>
</div>
</div>
</div>
<div id="outline-container-sec-3" class="outline-2">
<h2 id="sec-3"><span class="section-number-2">3</span> Algorithms</h2>
<div class="outline-text-2" id="text-3">
<p>
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.
</p>
</div>
</div>
<div id="outline-container-sec-4" class="outline-2">
<h2 id="sec-4"><span class="section-number-2">4</span> Rules for the API</h2>
<div class="outline-text-2" id="text-4">
<ul class="org-ul">
<li><code>stdint</code> should be used for integers (<code>int32_t</code>, <code>int64_t</code>)
</li>
<li>integers used for counting should always be <code>int64_t</code>
</li>
<li>floats should be by default <code>double</code>, unless explicitly mentioned
</li>
<li>pointers are converted to <code>int64_t</code> to increase portability
</li>
</ul>
</div>
</div>
<div id="outline-container-sec-5" class="outline-2">
<h2 id="sec-5"><span class="section-number-2">5</span> Documentation</h2>
<div class="outline-text-2" id="text-5">
<ul class="org-ul">
<li><a href="./qmckl.html">Main QMCkl header file</a>
</li>
<li><a href="./qmckl_memory.html">Memory management</a>
</li>
<li><a href="./qmckl_context.html">Context</a>
</li>
<li><a href="./qmckl_distance.html">Distance</a>
</li>
<li><a href="./qmckl_ao.html">Atomic orbitals</a>
</li>
</ul>
</div>
</div>
<div id="outline-container-sec-6" class="outline-2">
<h2 id="sec-6"><span class="section-number-2">6</span> Acknowledgments</h2>
<div class="outline-text-2" id="text-6">
<p>
<img src="https://trex-coe.eu/sites/default/files/inline-images/euflag.jpg" alt="euflag.jpg" />
<a href="https://trex-coe.eu">TREX: Targeting Real Chemical Accuracy at the Exascale</a> 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.
</p>
</div>
</div>
</div>
<div id="postamble" class="status">
<p class="date">Created: 2020-10-28 Wed 23:57</p>
<p class="creator"><a href="http://www.gnu.org/software/emacs/">Emacs</a> 25.2.2 (<a href="http://orgmode.org">Org</a> mode 8.2.10)</p>
<p class="validation"><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>
</html>