2022-09-28 18:04:21 +02:00
<?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 >
2022-11-16 22:57:35 +01:00
<!-- 2022 - 11 - 16 Wed 21:57 -->
2022-09-28 18:04:21 +02:00
< meta http-equiv = "Content-Type" content = "text/html;charset=utf-8" / >
< meta name = "viewport" content = "width=device-width, initial-scale=1" / >
< title > Introduction< / title >
< meta name = "generator" content = "Org mode" / >
< meta name = "author" content = "TREX CoE" / >
< style type = "text/css" >
<!-- /* --> <![CDATA[/*> <!-- */
.title { text-align: center;
margin-bottom: .2em; }
.subtitle { text-align: center;
font-size: medium;
font-weight: bold;
margin-top:0; }
.todo { font-family: monospace; color: red; }
.done { font-family: monospace; color: green; }
.priority { font-family: monospace; color: orange; }
.tag { background-color: #eee; font-family: monospace;
padding: 2px; font-size: 80%; font-weight: normal; }
.timestamp { color: #bebebe; }
.timestamp-kwd { color: #5f9ea0; }
.org-right { margin-left: auto; margin-right: 0px; text-align: right; }
.org-left { margin-left: 0px; margin-right: auto; text-align: left; }
.org-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;}
/* Languages per Org manual */
pre.src-asymptote:before { content: 'Asymptote'; }
pre.src-awk:before { content: 'Awk'; }
pre.src-C:before { content: 'C'; }
/* pre.src-C++ doesn't work in CSS */
pre.src-clojure:before { content: 'Clojure'; }
pre.src-css:before { content: 'CSS'; }
pre.src-D:before { content: 'D'; }
pre.src-ditaa:before { content: 'ditaa'; }
pre.src-dot:before { content: 'Graphviz'; }
pre.src-calc:before { content: 'Emacs Calc'; }
pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
pre.src-fortran:before { content: 'Fortran'; }
pre.src-gnuplot:before { content: 'gnuplot'; }
pre.src-haskell:before { content: 'Haskell'; }
pre.src-hledger:before { content: 'hledger'; }
pre.src-java:before { content: 'Java'; }
pre.src-js:before { content: 'Javascript'; }
pre.src-latex:before { content: 'LaTeX'; }
pre.src-ledger:before { content: 'Ledger'; }
pre.src-lisp:before { content: 'Lisp'; }
pre.src-lilypond:before { content: 'Lilypond'; }
pre.src-lua:before { content: 'Lua'; }
pre.src-matlab:before { content: 'MATLAB'; }
pre.src-mscgen:before { content: 'Mscgen'; }
pre.src-ocaml:before { content: 'Objective Caml'; }
pre.src-octave:before { content: 'Octave'; }
pre.src-org:before { content: 'Org mode'; }
pre.src-oz:before { content: 'OZ'; }
pre.src-plantuml:before { content: 'Plantuml'; }
pre.src-processing:before { content: 'Processing.js'; }
pre.src-python:before { content: 'Python'; }
pre.src-R:before { content: 'R'; }
pre.src-ruby:before { content: 'Ruby'; }
pre.src-sass:before { content: 'Sass'; }
pre.src-scheme:before { content: 'Scheme'; }
pre.src-screen:before { content: 'Gnu Screen'; }
pre.src-sed:before { content: 'Sed'; }
pre.src-sh:before { content: 'shell'; }
pre.src-sql:before { content: 'SQL'; }
pre.src-sqlite:before { content: 'SQLite'; }
/* additional languages in org.el's org-babel-load-languages alist */
pre.src-forth:before { content: 'Forth'; }
pre.src-io:before { content: 'IO'; }
pre.src-J:before { content: 'J'; }
pre.src-makefile:before { content: 'Makefile'; }
pre.src-maxima:before { content: 'Maxima'; }
pre.src-perl:before { content: 'Perl'; }
pre.src-picolisp:before { content: 'Pico Lisp'; }
pre.src-scala:before { content: 'Scala'; }
pre.src-shell:before { content: 'Shell Script'; }
pre.src-ebnf2ps:before { content: 'ebfn2ps'; }
/* additional language identifiers per "defun org-babel-execute"
in ob-*.el */
pre.src-cpp:before { content: 'C++'; }
pre.src-abc:before { content: 'ABC'; }
pre.src-coq:before { content: 'Coq'; }
pre.src-groovy:before { content: 'Groovy'; }
/* additional language identifiers from org-babel-shell-names in
ob-shell.el: ob-shell is the only babel language using a lambda to put
the execution function name together. */
pre.src-bash:before { content: 'bash'; }
pre.src-csh:before { content: 'csh'; }
pre.src-ash:before { content: 'ash'; }
pre.src-dash:before { content: 'dash'; }
pre.src-ksh:before { content: 'ksh'; }
pre.src-mksh:before { content: 'mksh'; }
pre.src-posh:before { content: 'posh'; }
/* Additional Emacs modes also supported by the LaTeX listings package */
pre.src-ada:before { content: 'Ada'; }
pre.src-asm:before { content: 'Assembler'; }
pre.src-caml:before { content: 'Caml'; }
pre.src-delphi:before { content: 'Delphi'; }
pre.src-html:before { content: 'HTML'; }
pre.src-idl:before { content: 'IDL'; }
pre.src-mercury:before { content: 'Mercury'; }
pre.src-metapost:before { content: 'MetaPost'; }
pre.src-modula-2:before { content: 'Modula-2'; }
pre.src-pascal:before { content: 'Pascal'; }
pre.src-ps:before { content: 'PostScript'; }
pre.src-prolog:before { content: 'Prolog'; }
pre.src-simula:before { content: 'Simula'; }
pre.src-tcl:before { content: 'tcl'; }
pre.src-tex:before { content: 'TeX'; }
pre.src-plain-tex:before { content: 'Plain TeX'; }
pre.src-verilog:before { content: 'Verilog'; }
pre.src-vhdl:before { content: 'VHDL'; }
pre.src-xml:before { content: 'XML'; }
pre.src-nxml:before { content: 'XML'; }
/* add a generic configuration mode; LaTeX export needs an additional
(add-to-list 'org-latex-listings-langs '(conf " ")) in .emacs */
pre.src-conf:before { content: 'Configuration File'; }
table { border-collapse:collapse; }
caption.t-above { caption-side: top; }
caption.t-bottom { caption-side: bottom; }
td, th { vertical-align:top; }
th.org-right { text-align: center; }
th.org-left { text-align: center; }
th.org-center { text-align: center; }
td.org-right { text-align: right; }
td.org-left { text-align: left; }
td.org-center { text-align: center; }
dt { font-weight: bold; }
.footpara { display: inline; }
.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; }
.org-svg { width: 90%; }
/*]]>*/-->
< / style >
< link rel = "stylesheet" title = "Standard" href = "qmckl.css" type = "text/css" / >
< script type = "text/javascript" src = "org-info.js" >
/**
*
* @source: org-info.js
*
* @licstart The following is the entire license notice for the
* JavaScript code in org-info.js.
*
* Copyright (C) 2012-2019 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 org-info.js.
*
*/
< / script >
< script type = "text/javascript" >
/*
@licstart The following is the entire license notice for the
JavaScript code in this tag.
Copyright (C) 2012-2019 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[/*> <!-- */
org_html_manager.set("TOC_DEPTH", "4");
org_html_manager.set("LINK_HOME", "index.html");
org_html_manager.set("LINK_UP", "");
org_html_manager.set("LOCAL_TOC", "1");
org_html_manager.set("VIEW_BUTTONS", "0");
org_html_manager.set("MOUSE_HINT", "underline");
org_html_manager.set("FIXED_TOC", "0");
org_html_manager.set("TOC", "1");
org_html_manager.set("VIEW", "info");
org_html_manager.setup(); // activate after the parameters are set
/*]]>*///-->
< / script >
< script type = "text/javascript" >
/*
@licstart The following is the entire license notice for the
JavaScript code in this tag.
Copyright (C) 2012-2019 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/x-mathjax-config" >
MathJax.Hub.Config({
displayAlign: "center",
displayIndent: "0em",
"HTML-CSS": { scale: 100,
linebreaks: { automatic: "false" },
webFont: "TeX"
},
SVG: {scale: 100,
linebreaks: { automatic: "false" },
font: "TeX"},
NativeMML: {scale: 100},
TeX: { equationNumbers: {autoNumber: "AMS"},
MultLineWidth: "85%",
TagSide: "right",
TagIndent: ".8em"
}
});
< / script >
< script type = "text/javascript"
src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS_HTML">< / script >
< / head >
< body >
< div id = "org-div-home-and-up" >
< a accesskey = "h" href = "" > UP < / a >
|
< a accesskey = "H" href = "index.html" > HOME < / a >
< / div > < div id = "content" >
< h1 class = "title" > Introduction< / h1 >
< div id = "table-of-contents" >
< h2 > Table of Contents< / h2 >
< div id = "text-table-of-contents" >
< ul >
2022-11-16 22:57:35 +01:00
< li > < a href = "#org18e0045" > 1. Installing QMCkl< / a >
2022-09-28 18:04:21 +02:00
< ul >
2022-11-16 22:57:35 +01:00
< li > < a href = "#org9aef809" > 1.1. Installing from the released tarball (for end users)< / a > < / li >
< li > < a href = "#org3b18f7a" > 1.2. Installing from the source repository (for developers)< / a > < / li >
2022-09-28 18:04:21 +02:00
< / ul >
< / li >
2022-11-16 22:57:35 +01:00
< li > < a href = "#org798a1a0" > 2. Using QMCkl< / a > < / li >
< li > < a href = "#orge39d16b" > 3. Developing in QMCkl< / a >
2022-09-28 18:04:21 +02:00
< ul >
2022-11-16 22:57:35 +01:00
< li > < a href = "#org5facb59" > 3.1. Literate programming< / a > < / li >
< li > < a href = "#orgf758240" > 3.2. Source code editing< / a > < / li >
< li > < a href = "#org4fea233" > 3.3. Choice of the programming language< / a > < / li >
< li > < a href = "#orgfdd1ccd" > 3.4. Coding rules< / a > < / li >
< li > < a href = "#orga22da4b" > 3.5. Design of the library< / a > < / li >
< li > < a href = "#orgc871a0a" > 3.6. Naming conventions< / a > < / li >
< li > < a href = "#org08610a0" > 3.7. Application programming interface< / a > < / li >
< li > < a href = "#org039f4ce" > 3.8. Global state< / a > < / li >
< li > < a href = "#orgb7c3566" > 3.9. Headers< / a > < / li >
< li > < a href = "#orgb5fc43c" > 3.10. Low-level functions< / a > < / li >
< li > < a href = "#orgd60e73f" > 3.11. High-level functions< / a > < / li >
< li > < a href = "#org285bf72" > 3.12. Numerical precision< / a > < / li >
< li > < a href = "#org5ab4f3b" > 3.13. Algorithms< / a > < / li >
2022-09-28 18:04:21 +02:00
< / ul >
< / li >
< / ul >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-org18e0045" class = "outline-2" >
< h2 id = "org18e0045" > < span class = "section-number-2" > 1< / span > Installing QMCkl< / h2 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-2" id = "text-1" >
< p >
The latest version fo QMCkl can be downloaded
< a href = "https://github.com/TREX-CoE/qmckl/releases/latest" > here< / a > , and the source code is accessible on the
< a href = "https://github.com/TREX-CoE/qmckl" > GitHub repository< / a > .
< / p >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-org9aef809" class = "outline-3" >
< h3 id = "org9aef809" > < span class = "section-number-3" > 1.1< / span > Installing from the released tarball (for end users)< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-1-1" >
< p >
QMCkl is built with GNU Autotools, so the usual
< code > configure ; make ; make check ; make install< / code > scheme will be used.
< / p >
< p >
As usual, the C compiler can be specified with the < code > CC< / code > variable
and the Fortran compiler with the < code > FC< / code > variable. The compiler
options are defined using < code > CFLAGS< / code > and < code > FCFLAGS< / code > .
< / p >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-org3b18f7a" class = "outline-3" >
< h3 id = "org3b18f7a" > < span class = "section-number-3" > 1.2< / span > Installing from the source repository (for developers)< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-1-2" >
< p >
To compile from the source repository, additional dependencies are
required to generated the source files:
< / p >
< ul class = "org-ul" >
< li > Emacs > = 26< / li >
< li > Autotools< / li >
< li > Python3< / li >
< / ul >
< p >
When the repository is downloaded, the Makefile is not yet
generated, as well as the configure script. < code > ./autogen.sh< / code > has
to be executed first.
< / p >
< / div >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-org798a1a0" class = "outline-2" >
< h2 id = "org798a1a0" > < span class = "section-number-2" > 2< / span > Using QMCkl< / h2 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-2" id = "text-2" >
< p >
The < code > qmckl.h< / code > header file installed in the < code > ${prefix}/include< / code > directory
has to be included in C codes when QMCkl functions are used:
< / p >
< div class = "org-src-container" >
< pre class = "src src-c" > < span style = "color: #483d8b;" > #include< / span > < span style = "color: #8b2252;" > "qmckl.h"< / span >
< / pre >
< / div >
< p >
In Fortran programs, the < code > qmckl_f.f90< / code > installed in
< code > ${prefix}/share/qmckl/fortran< / code > interface file should be copied in the source
code using the library, and the Fortran codes should use the < code > qmckl< / code > module as
< / p >
< div class = "org-src-container" >
< pre class = "src src-f90" > < span style = "color: #a020f0;" > use< / span > < span style = "color: #0000ff;" > qmckl< / span >
< / pre >
< / div >
< p >
Both files are located in the < code > include/< / code > directory.
< / p >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-orge39d16b" class = "outline-2" >
< h2 id = "orge39d16b" > < span class = "section-number-2" > 3< / span > Developing in QMCkl< / h2 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-2" id = "text-3" >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-org5facb59" class = "outline-3" >
< h3 id = "org5facb59" > < span class = "section-number-3" > 3.1< / span > Literate programming< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-3-1" >
< p >
In a traditional source code, most of the lines of source files of a program
are code, scripts, Makefiles, and only a few lines are comments explaining
parts of the code that are non-trivial to understand. The documentation of
the prorgam is usually written in a separate directory, and is often outdated
compared to the code.
< / p >
< p >
Literate programming is a different approach to programming,
where the program is considered as a publishable-quality document. Most of
the lines of the source files are text, mathematical formulas, tables,
figures, < i > etc< / i > , and the lines of code are just the translation in a computer
language of the ideas and algorithms expressed in the text. More importantly,
the "document" is structured like a text document with sections, subsections,
a bibliography, a table of contents < i > etc< / i > , and the place where pieces of code
appear are the places where they should belong for the reader to understand
the logic of the program, not the places where the compiler expects to find
them. Both the publishable-quality document and the binary executable are
produced from the same source files.
< / p >
< p >
Literate programming is particularly well adapted in this context, as the
central part of this project is the documentation of an API. The
implementation of the algorithms is just an expression of the algorithms in a
language that can be compiled, so that the correctness of the algorithms can
be tested.
< / p >
< p >
We have chosen to write the source files in < a href = "https://karl-voit.at/2017/09/23/orgmode-as-markup-only/" > org-mode< / a > format,
as any text editor can be used to edit org-mode files. To
produce the documentation, there exists multiple possibilities to convert
org-mode files into different formats such as HTML or PDF. The source code is
easily extracted from the org-mode files invoking the Emacs text editor from
the command-line in the < code > Makefile< / code > , and then the produced files are compiled.
Moreover, within the Emacs text editor the source code blocks can be executed
interactively, in the same spirit as Jupyter notebooks.
< / p >
< p >
Note that Emacs is not needed for end users because the distributed
tarball contains the generated source code.
< / p >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-orgf758240" class = "outline-3" >
< h3 id = "orgf758240" > < span class = "section-number-3" > 3.2< / span > Source code editing< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-3-2" >
< p >
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 >
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.
< / p >
< p >
In the < code > tools/init.el< / code > file, we provide a minimal Emacs configuration
file for vim users. This file should be copied into < code > .emacs.d/init.el< / code > .
< / p >
< p >
For users with a preference for Jupyter notebooks, we also provide the
< code > tools/nb_to_org.sh< / code > script can convert jupyter notebooks into org-mode
files.
< / p >
< p >
Note that pandoc can be used to convert multiple markdown formats into
org-mode.
< / p >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-org4fea233" class = "outline-3" >
< h3 id = "org4fea233" > < span class = "section-number-3" > 3.3< / span > Choice of the programming language< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-3-3" >
< p >
Most of the codes of the < a href = "https://trex-coe.eu" > TREX CoE< / a > are written in Fortran with some
scripts in Bash and Python. Outside of the CoE, Fortran is also
important in QMC codes (Casino, Amolqc), and other important
languages used by the community are C and C++ (QMCPack, QWalk),
Julia and Rust are gaining in popularity. We want QMCkl to be
compatible with all of these languages, so the QMCkl API has to be
compatible with the C language since libraries with a C-compatible
API can be used in every other language.
< / p >
< p >
High-performance versions of QMCkl, with the same API, can be
rewritten by HPC experts. These optimized libraries will be tuned
for specific architectures, among which we can cite x86 based
processors, and GPU accelerators. Nowadays, the most efficient
software tools to take advantage of low-level features
(intrinsics, prefetching, aligned or pinned memory allocation,
… ) are for C++ developers. It is highly probable that optimized
implementations will be written in C++, but as the API is
C-compatible this doesn't pose any problem for linking the library
in other languages.
< / p >
< p >
Fortran is one of the most common languages used by the community,
and is simple enough to make the algorithms readable both by
experts in QMC, and experts in HPC. Hence we propose in this
pedagogical implementation of QMCkl to use Fortran to express the
QMC algorithms. However, for internal functions related to system
programming, the C language is more natural than Fortran.
< / p >
< p >
As QMCkl appears like a C library, for each Fortran function there
is an < code > iso_c_binding< / code > interface to make the Fortran function
callable from C. It is this C interface which is exposed to the
user. As a consequence, the Fortran users of the library never
call directly the Fortran routines, but call instead the C binding
function and an < code > iso_c_binding< / code > is still required:
< / p >
< pre class = "example" >
ISO_C_BINDING ISO_C_BINDING
Fortran ---------------> C ---------------> Fortran
< / pre >
< p >
The name of the Fortran source files should end with < code > _f.f90< / code > to
be properly handled by the < code > Makefile< / code > and to avoid collision of
object files (< code > *.o< / code > ) with the compiled C source files. The names
of the functions defined in Fortran should be the same as those
exposed in the API suffixed by < code > _f< / code > .
< / p >
< p >
For more guidelines on using Fortran to generate a C interface, see
< a href = "http://fortranwiki.org/fortran/show/Generating+C+Interfaces" > this link< / a > .
< / p >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-orgfdd1ccd" class = "outline-3" >
< h3 id = "orgfdd1ccd" > < span class = "section-number-3" > 3.4< / span > Coding rules< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-3-4" >
< p >
The authors should follow the recommendations of the C99
< a href = "https://wiki.sei.cmu.edu/confluence/display/c/SEI+CERT+C+Coding+Standard" > SEI+CERT C Coding Standard< / a > .
< / p >
< p >
Compliance can be checked with < code > cppcheck< / code > as:
< / p >
< div class = "org-src-container" >
< pre class = "src src-bash" > cppcheck --addon=cert --enable=all *.c & > cppcheck.out
# < span style = "color: #b22222;" > or< / span >
make cppcheck ; cat cppcheck.out
< / pre >
< / div >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-orga22da4b" class = "outline-3" >
< h3 id = "orga22da4b" > < span class = "section-number-3" > 3.5< / span > Design of the library< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-3-5" >
< p >
The proposed API should allow the library to: deal with memory transfers
between CPU and accelerators, and to use different levels of floating-point
precision. We chose a multi-layered design with low-level and high-level
functions (see below).
< / p >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-orgc871a0a" class = "outline-3" >
< h3 id = "orgc871a0a" > < span class = "section-number-3" > 3.6< / span > Naming conventions< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-3-6" >
< p >
To avoid namespace collisions, we use < code > qmckl_< / code > as a prefix for all exported
functions and variables. All exported header files should have a file name
prefixed with < 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 file should be < code > xxx.f90< / code > .
< / p >
< p >
In the names of the variables and functions, only the singular
form is allowed.
< / p >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-org08610a0" class = "outline-3" >
< h3 id = "org08610a0" > < span class = "section-number-3" > 3.7< / span > Application programming interface< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-3-7" >
< p >
In the C language, the number of bits used by the integer types can change
from one architecture to another one. To circumvent this problem, we choose to
use the integer types defined in < code > < stdint.h> < / code > where the number of bits used for
the integers are fixed.
< / p >
< p >
To ensure that the library will be easily usable in < i > any< / i > other language
than C, we restrict the data types in the interfaces to the following:
< / p >
< ul class = "org-ul" >
< li > 32-bit and 64-bit integers, scalars and and arrays (< code > int32_t< / code > and < code > int64_t< / code > )< / li >
< li > 32-bit and 64-bit floats, scalars and and arrays (< code > float< / code > and < code > double< / code > )< / li >
< li > Pointers are always casted into 64-bit integers, even on legacy 32-bit architectures< / li >
< li > ASCII strings are represented as a pointers to character arrays
and terminated by a < code > '\0'< / code > character (C convention).< / li >
< li > Complex numbers can be represented by an array of 2 floats.< / li >
< li > Boolean variables are stored as integers, < code > 1< / code > for < code > true< / code > and < code > 0< / code > for < code > false< / code > < / li >
< li > Floating point variables should be by default < code > double< / code > unless explicitly mentioned< / li >
< li > integers used for counting should always be < code > int64_t< / code > < / li >
< / ul >
< p >
To facilitate the use in other languages than C, we will provide some
bindings in other languages in other repositories.
< / p >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-org039f4ce" class = "outline-3" >
< h3 id = "org039f4ce" > < span class = "section-number-3" > 3.8< / span > Global state< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-3-8" >
< 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 < a href = "./qmckl_context.html" > < code > context< / code > < / a > variable, built by the library with the
2022-11-16 22:57:35 +01:00
< code > qmckl_context_create< / code > function. The < a id = "orgc5de3fd" > =context=< / a > contains the global
2022-09-28 18:04:21 +02:00
state of the library, and is used as the first argument of many
QMCkl functions.
< / p >
< p >
The internal structure of the context is not specified, to give a
maximum of freedom to the different implementations. Modifying
the state is done by setters and getters, prefixed by
< code > qmckl_set_< / code > an < code > qmckl_get_< / code > .
< / p >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-orgb7c3566" class = "outline-3" >
< h3 id = "orgb7c3566" > < span class = "section-number-3" > 3.9< / span > Headers< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-3-9" >
< p >
A single < code > qmckl.h< / code > header to be distributed by the library
is built by concatenating some of the produced header files.
To facilitate building the < code > qmckl.h< / code > file, we separate types from
function declarations in headers. Types should be defined in header
files suffixed by < code > _type.h< / code > , and functions in files suffixed by
< code > _func.h< / code > .
As these files will be concatenated in a single file, they should
not be guarded by < code > #ifndef *_H< / code > , and they should not include other
produced headers.
< / p >
< p >
Some particular types that are not exported need to be known by the
context, and there are some functions to update instances of these
types contained inside the context. For example, a
< code > qmckl_numprec_struct< / code > is present in the context, and the function
< code > qmckl_set_numprec_range< / code > takes a context as a parameter, and set a
value in the < code > qmckl_numprec_struct< / code > contained in the context.
Because of these intricate dependencies, a private header is
created, containing the < code > qmckl_numprec_struct< / code > . This header is
included in the private header file which defines the type of the
context. Header files for private types are suffixed by < code > _private_type.h< / code >
and header files for private functions are suffixed by < code > _private_func.h< / code > .
Fortran interfaces should also be written in the < code > *fh_func.f90< / code > file,
and the types definitions should be written in the < code > *fh_type.f90< / code > file.
< / p >
< table border = "2" cellspacing = "0" cellpadding = "6" rules = "groups" frame = "hsides" >
< colgroup >
< col class = "org-left" / >
< col class = "org-left" / >
< col class = "org-left" / >
< / colgroup >
< thead >
< tr >
< th scope = "col" class = "org-left" > File< / th >
< th scope = "col" class = "org-left" > Scope< / th >
< th scope = "col" class = "org-left" > Description< / th >
< / tr >
< / thead >
< tbody >
< tr >
< td class = "org-left" > < code > *_type.h< / code > < / td >
< td class = "org-left" > Public< / td >
< td class = "org-left" > Type definitions< / td >
< / tr >
< tr >
< td class = "org-left" > < code > *_func.h< / code > < / td >
< td class = "org-left" > Public< / td >
< td class = "org-left" > Function definitions< / td >
< / tr >
< tr >
< td class = "org-left" > < code > *_private_type.h< / code > < / td >
< td class = "org-left" > Private< / td >
< td class = "org-left" > Type definitions< / td >
< / tr >
< tr >
< td class = "org-left" > < code > *_private_func.h< / code > < / td >
< td class = "org-left" > Private< / td >
< td class = "org-left" > Function definitions< / td >
< / tr >
< tr >
< td class = "org-left" > < code > *fh_type.f90< / code > < / td >
< td class = "org-left" > Public< / td >
< td class = "org-left" > Fortran type definitions< / td >
< / tr >
< tr >
< td class = "org-left" > < code > *fh_func.f90< / code > < / td >
< td class = "org-left" > Public< / td >
< td class = "org-left" > Fortran function definitions< / td >
< / tr >
< / tbody >
< / table >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-orgb5fc43c" class = "outline-3" >
< h3 id = "orgb5fc43c" > < span class = "section-number-3" > 3.10< / span > Low-level functions< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-3-10" >
< 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 >
These functions are < i > pure< / i > , and unaware of the QMCkl
2022-11-16 22:57:35 +01:00
< a href = "#orgc5de3fd" > < code > context< / code > < / a > . They are not allowed to allocate/deallocate memory, and
2022-09-28 18:04:21 +02:00
if they need temporary memory it should be provided in input.
< / p >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-orgd60e73f" class = "outline-3" >
< h3 id = "orgd60e73f" > < span class = "section-number-3" > 3.11< / span > High-level functions< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-3-11" >
< 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 >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-org285bf72" class = "outline-3" >
< h3 id = "org285bf72" > < span class = "section-number-3" > 3.12< / span > Numerical precision< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-3-12" >
< p >
The minimal 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
2022-11-16 22:57:35 +01:00
specified in the < a href = "#orgc5de3fd" > < code > context< / code > < / a > variable.
2022-09-28 18:04:21 +02:00
< / p >
< p >
In order to automatize numerical accuracy tests, QMCkl uses
< a href = "https://github.com/verificarlo/verificarlo" > Verificarlo< / a > and its CI functionality. You can read Verificarlo CI's
documentation at the < a href = "https://github.com/verificarlo/verificarlo/blob/master/doc/06-Postprocessing.md#verificarlo-ci" > following link< / a > . Reading it is advised to
understand the remainder of this section.
< / p >
< p >
To enable support for Verificarlo CI tests when building the
library, use the following configure command :
< / p >
< div class = "org-src-container" >
< pre class = "src src-bash" > ./configure < span style = "color: #a0522d;" > CC< / span > =verificarlo-f < span style = "color: #a0522d;" > FC< / span > =verificarlo-f --host=x86_64 --enable-vfc_ci
< / pre >
< / div >
< p >
Note that this does require an install of Verificarlo < b > with
Fortran support< / b > . Enabling the support for CI will define the
< code > VFC_CI< / code > preprocessor variable which use will be explained now.
< / p >
< p >
As explained in the documentation, Verificarlo CI uses a probes
system to export variables from test programs to the tools itself.
To make tests easier to use, QMCkl has its own interface to the
probes system. To make the system very easy to use, these functions
are always defined, but will behave differently depending on the
< code > VFC_CI< / code > preprocessor variable. There are 3 functions at your
disposal. When the CI is enabled, they will place a < code > vfc_ci< / code > probe
as if calling < code > vfc_probes< / code > directly. Otherwise, they will either do
nothing or perform a check on the tested value and return its result
as a boolean that you are free to use or ignore.
Here are these 3 functions :
< / p >
< ul class = "org-ul" >
< li > < code > qmckl_probe< / code > : place a normal probe witout any check. Won't do anything when < code > vfc_ci< / code > is disabled (false is returned).< / li >
< li > < code > qmckl_probe_check< / code > : place a probe with an absolute check. If < code > vfc_ci< / code > is disabled, this will return the result of an absolute check (|val - ref| < accuracy target ?). If the check fails, true is returned (false otherwise).< / li >
< li > < code > qmckl_probe_check_relative< / code > : place a probe with a relative check. If < code > vfc_ci< / code > is disabled, this will return the result of a relative check (|val - ref| / ref < accuracy target?). If the check fails, true is returned (false otherwise).< / li >
< / ul >
< p >
If you need more detail on these functions or their Fortran
interfaces, have a look at the < code > tools/qmckl_probes< / code > files.
< / p >
< p >
Finally, if you need to add a QMCkl kernel to the CI tests
or modify an existing one, you should pay attention to the
following points :
< / p >
< ul class = "org-ul" >
< li > you should add the new kernel to the < code > vfc_tests_config.json< / code > file, which controls the backends and repetitions for each executable. More details can be found in the < code > vfc_ci< / code > documentation.< / li >
< li > in order to call the < code > qmckl_probes< / code > functions from Fortran, import the < code > qmckl_probes_f< / code > module.< / li >
< li > if your tests include some asserts that rely on accurate FP values, you should probably wrap them inside a < code > #ifndef VFC_CI< / code > statement, as the asserts would otherwise risk to fail when executed with the different Verificarlo backends.< / li >
< / ul >
< / div >
< / div >
2022-11-16 22:57:35 +01:00
< div id = "outline-container-org5ab4f3b" class = "outline-3" >
< h3 id = "org5ab4f3b" > < span class = "section-number-3" > 3.13< / span > Algorithms< / h3 >
2022-09-28 18:04:21 +02:00
< div class = "outline-text-3" id = "text-3-13" >
< 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 >
< / div >
< div id = "postamble" class = "status" >
< p class = "author" > Author: TREX CoE< / p >
2022-11-16 22:57:35 +01:00
< p class = "date" > Created: 2022-11-16 Wed 21:57< / p >
2022-09-28 18:04:21 +02:00
< p class = "validation" > < a href = "http://validator.w3.org/check?uri=referer" > Validate< / a > < / p >
< / div >
< / body >
< / html >