Verificarlo CI

1. Verificarlo probes
2. Fortran wrappers

1. Verificarlo probes

This file contains utility functions to enable the Verificarlo Continuous Integration system (VFC_CI), a tool for verifying the numerical accuracy and stability of scientific computations.

Verificarlo is a tool that uses Monte Carlo Arithmetic to detect numerical instabilities by randomly rounding floating-point operations. The VFC_CI system automates the process of testing numerical stability in a continuous integration environment.

This module is a wrapper around Verificarlo's vfc_probes system. The goal of these QMCkl probe functions is to simplify the use of vfc_probes, and to provide functions that can be called either with or without VFC_CI support by using preprocessor directives:

when VFC_CI is disabled, the functions will either return false (indicating no error) or perform a check based on a reference value
when VFC_CI is enabled, the functions will encapsulate calls to vfc_probe, enabling automatic numerical stability testing

Moreover, users don't need to worry about the life cycle of the probes data structure, as it is automatically created, dumped (written to output), and freed by this wrapper. This automation simplifies integration into existing codebases.

VFC_CI support can be enabled by using the following configure command, which uses the Verificarlo compiler wrappers:

QMCKL_DEVEL=1 ./configure --prefix=$PWD/_install --enable-silent-rules \
  --enable-maintainer-mode CC=verificarlo-f FC=verificarlo-f --host=x86_64

This wrapper also provides a Fortran interface (in its dedicated file), enabling numerical stability testing for Fortran code as well.

To learn more about Verificarlo CI and how to interpret its results: https://github.com/verificarlo/verificarlo/blob/master/doc/06-Postprocessing.md#verificarlo-ci

1.1. Automatically initialize the `vfc_probe` object if `VFC_CI` is defined

1.2. Standard probe, without check

if VFC_CI is defined, place a standard probe
if VFC_CI is undefined, return false (no error)

1.3. Probe with absolute check

if VFC_CI is defined, place a probe with an absolute check
if VFC_CI is undefined, perform an absolute check based on target value and accuracy

1.4. Probe with relative check

if VFC_CI is defined, place a probe with a relative check
if VFC_CI is undefined, perform a relative check based on target value and accuracy

1.5. Automatically delete and dump the vfc_probe object if `VFC_CI` is defined

2. Fortran wrappers

module qmckl_verificarlo_f
  interface
     logical(c_bool) function qmckl_probe &
          (testName, varName, val) &
          bind(C, name="qmckl_probe_f")

       use, intrinsic :: iso_c_binding
       import
       implicit none

       character(C_CHAR), dimension(*) :: testName
       character(C_CHAR), dimension(*) :: varName

       real(C_DOUBLE) :: val
     end function qmckl_probe

     logical(c_bool) function qmckl_probe_check &
          (testName, varName, val, expectedValue, accuracyTarget) &
          bind(C, name="qmckl_probe_check_f")

       use, intrinsic :: iso_c_binding
       import
       implicit none

       character(C_CHAR), dimension(*) :: testName
       character(C_CHAR), dimension(*) :: varName

       real(C_DOUBLE) :: val
       real(C_DOUBLE) :: expectedValue
       real(C_DOUBLE) :: accuracyTarget
     end function qmckl_probe_check

     logical(c_bool) function qmckl_probe_check_relative &
          (testName, varName, val, expectedValue, accuracyTarget) &
          bind(C, name="qmckl_probe_check_relative_f")

       use, intrinsic :: iso_c_binding
       import
       implicit none

       character(C_CHAR), dimension(*) :: testName
       character(C_CHAR), dimension(*) :: varName

       real(C_DOUBLE) :: val
       real(C_DOUBLE) :: expectedValue
       real(C_DOUBLE) :: accuracyTarget
     end function qmckl_probe_check_relative
  end interface
end module qmckl_verificarlo_f