diff --git a/org/qmckl.org b/org/qmckl.org index 2533b05..6113a89 100644 --- a/org/qmckl.org +++ b/org/qmckl.org @@ -256,6 +256,64 @@ cppcheck --addon=cert --enable=all *.c &> cppcheck.out functions will use the precision specified in the =context= variable. + In order to automatize numerical accuracy tests, QMCkl uses + [[https://github.com/verificarlo/verificarlo][Verificarlo]] and + its CI functionality. You can read Verificarlo CI's documentation + at the [[https://github.com/verificarlo/verificarlo/blob/master/doc/06-Postprocessing.md#verificarlo-ci][following link]]. + Reading it is advised to understand the remainder of this section. + + To enable support for Verificarlo CI tests when building the + library, use the following configure command : + + #+begin_src bash + QMCKL_DEVEL=1 ./configure --prefix=$PWD/_install --enable-silent-rules --enable-maintainer-mode CC=verificarlo-f FC=verificarlo-f --host=x86_64 --enable-vfc_ci + #+end_src + + Note that this does require an install of Verificarlo *with + Fortran support*. Enabling the support for CI will define the + ~VFC_CI~ preprocessor variable which use will be explained now. + + 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 + ~VFC_CI~ preprocessor variable. There are 3 functions at your + disposal. When the CI is enabled, they will place a ~vfc_ci~ probe + as if calling ~vfc_probes~ 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 : + + - ~qmckl_probe~ : place a normal probe witout any check. Won't do + anything when ~vfc_ci~ is disabled. + - ~qmckl_probe_check~ : place a probe with a relative check. If + ~vfc_ci~ is disabled, this will return the result of a relative + check (|val - ref| / ref < accuracy target?). + - ~qmckl_probe_check~ : place a probe with an absolute check. If + ~vfc_ci~ is disabled, this will return the result of an absolute + check (|val - ref| < accuracy target ?) + + If you need more details on these functions or their Fortran + interfaces, have a look at the ~tools/qmckl_probes~ files. + + 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 : + + - you should add the new kernel to the ~vfc_tests_config.json~ file, + which controls the backends and repetitions for each executable. More + details can be found in the ~vfc_ci~ documentation. + + - in order to call the ~qmckl_probes~ functions from Fortran, import + the ~qmckl_probes_f~ module. All Fortran functions are appended with + the ~_f~ suffix. + + - if your tests include some asserts that rely on accurate FP values, + you should probably wrap them inside a ~#ifndef VFC_CI~ statement, as + the asserts would otherwise risk to fail when executed with the + different Verificarlo backends. + ** Algorithms Reducing the scaling of an algorithm usually implies also reducing