diff --git a/doc/userdoc.org b/doc/userdoc.org index b80850ee590d3416622539b6aa4e9b3b9665d092..b50768b072d372e1d462508343aaed9e2acff75b 100644 --- a/doc/userdoc.org +++ b/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