Add a simple userdoc for parallel checker

doc/userdoc.org

@@ -2667,6 +2667,58 @@ Gets the abstract syntax tree associated to a user function into a
 Saves the AST of the script into the file (whose name is given as
 argument) using the dot format.
 
+***** Parallel checker utilities
+
+Developing parallel applications, it is generally useful to be able to
+check that results are reproducible bit-to-bit, whichever the number
+of processes or threads are. Such a mechanism is provided by ~pugs~.
+
+It works as follows. One first runs the code to build a reference (by
+now the reference cannot be build using ~MPI~ parallelism), then a
+second run will compare the obtained results and reference ones. If
+ghost value differs, a warning is printed, stating that the data is
+not synchronized (this may not be a mistake) and if non-ghost value
+differs the execution stops indicating an error.
+
+Parallel checking points can be placed directly in the source code
+(see developer documentation), but for convenience, one can also check
+parallelism directly in the scripting language.
+
+The provided functions are
+- ~parallel_check: Vh*string -> void~
+- ~parallel_check: item_array*string -> void~
+- ~parallel_check: item_value*string -> void~
+- ~parallel_check: sub_item_array*string -> void~
+- ~parallel_check: sub_item_value*string -> void~
+
+They allow to check parallelism for ~Vh~ functions, ~item_value~,
+~item_array~, ~sub_item_value~ or ~sub_item_arrays~ variables. These types
+are discussed below when describing the ~mesh~ and ~schemes~ module (see
+sections [[mesh]] and [[scheme]]). The second argument is just a string that is just
+used as a tag to ease the reading of the output.
+
+To create the reference, one launches the code as
+#+BEGIN_SRC shell :exports source
+./pugs example.pgs --parallel-checker-file="/tmp/my-ref.h5"
+#+END_SRC
+Observe that the option ~--parallel-checker-file="/tmp/my-ref.h5"~ is
+not mandatory. If not specified, the reference is created in the
+current directory in the file ~parallel_checker.h5~. Also observe that
+this command runs the code in sequential (in the sense that there is
+no message passing). In that case parallel checker runs in write mode
+automatically. To force the read mode (for comparison), one can use
+the ~--parallel-checker-mode=read~ option
+#+BEGIN_SRC shell :exports source
+./pugs example.pgs \
+  --parallel-checker-file="/tmp/my-ref.h5" \
+  --parallel-checker-mode=read
+#+END_SRC
+Running the code in parallel automatically triggers the
+read/comparison mode.
+#+BEGIN_SRC shell :exports source
+mpirun -n 3 pugs example.pgs --parallel-checker-file="/tmp/my-ref.h5"
+#+END_SRC
+
 *** The ~math~ module
 
 The ~math~ module is a small utility module that provides a set of
@@ -2765,7 +2817,7 @@ mathematically ${x^y}^z = x^{(y^z)}$, many softwares treat it (by mistake)
 as ${(x^y)}^z$. Thus, using the ~pow~ function avoids any confusion.
 #+END_note
 
-*** The ~mesh~ module
+*** The ~mesh~ module<<mesh>>
 
 This is an important module. It provides mesh utility tools.
 #+NAME: get-module-info-mesh