From 917ff8f77725d81888046e4d244a27df3550265e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Del=20Pino?= <stephane.delpino44@gmail.com>
Date: Thu, 30 Nov 2023 18:03:31 +0100
Subject: [PATCH] Add a simple userdoc for parallel checker
---
doc/userdoc.org | 54 ++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 53 insertions(+), 1 deletion(-)
diff --git a/doc/userdoc.org b/doc/userdoc.org
index b80850ee5..b50768b07 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
--
GitLab