Update user documentation

Describe shortly checkpoint/resume use

.gitignore

@@ -24,3 +24,4 @@ GTAGS
 /doc/lisp/.fltk/
 /doc/*.msh
 /doc/*.vtu
+/doc/checkpoint.h5

cmake/PugsDoc.cmake

@@ -37,6 +37,7 @@ if (EMACS AND GNUPLOT_FOUND AND GMSH)
     COMMAND
     ${CMAKE_COMMAND} -E env
     PUGS=${PUGS_BINARY_DIR}/pugs
+    PUGS_CHECKPOINT=${PUGS_BINARY_DIR}/pugs_checkpoint
     HOME=${PUGS_SOURCE_DIR}/doc/lisp
     PUGS_SOURCE_DIR=${PUGS_SOURCE_DIR}
     PUGS_BINARY_DIR=${PUGS_BINARY_DIR}
@@ -51,6 +52,7 @@ if (EMACS AND GNUPLOT_FOUND AND GMSH)
     COMMAND
     ${CMAKE_COMMAND} -E env
     PUGS=${PUGS_BINARY_DIR}/pugs
+    PUGS_CHECKPOINT=${PUGS_BINARY_DIR}/pugs_checkpoint
     HOME=${PUGS_SOURCE_DIR}/doc/lisp
     PUGS_SOURCE_DIR=${PUGS_SOURCE_DIR}
     PUGS_BINARY_DIR=${PUGS_BINARY_DIR}
@@ -59,6 +61,7 @@ if (EMACS AND GNUPLOT_FOUND AND GMSH)
     "${PUGS_SOURCE_DIR}/doc/userdoc.org"
     "${PUGS_SOURCE_DIR}/doc/lisp/userdoc-html.el"
     pugs
+    pugs_checkpoint
     pugsdoc-dir
     pugsdoc-download-elpa
     ${ORG_GENERATOR_FILES}
@@ -77,6 +80,7 @@ if (EMACS AND GNUPLOT_FOUND AND GMSH)
       COMMAND
       ${CMAKE_COMMAND} -E env
       PUGS=${PUGS_BINARY_DIR}/pugs
+      PUGS_CHECKPOINT=${PUGS_BINARY_DIR}/pugs_checkpoint
       HOME=${PUGS_SOURCE_DIR}/doc/lisp
       PUGS_SOURCE_DIR=${PUGS_SOURCE_DIR}
       PUGS_BINARY_DIR=${PUGS_BINARY_DIR}
@@ -87,6 +91,7 @@ if (EMACS AND GNUPLOT_FOUND AND GMSH)
       "${PUGS_SOURCE_DIR}/tools/pgs-pygments.sh"
       "${PUGS_SOURCE_DIR}/tools/pgs-pygments.py"
       pugs
+      pugs_checkpoint
       pugsdoc-dir
       pugsdoc-download-elpa
       ${ORG_GENERATOR_FILES}

doc/lisp/build-doc-config.el

@@ -51,7 +51,7 @@
  '(org-latex-listings 'minted))
 
 (setq org-latex-minted-options
-      '(("linenos=true") ("breaklines")))
+      '(("linenos=true") ("breaklines") ("autogobble")))
 
 (defun org-export-output-file-name-modified (orig-fun extension &optional subtreep pub-dir)
   (unless pub-dir

doc/userdoc.org

@@ -32,6 +32,12 @@
 #+LATEX_HEADER_EXTRA: \usepackage{mathpazo}
 #+LATEX_HEADER_EXTRA: \usepackage{inconsolata}
 
+#+LATEX_HEADER_EXTRA:  %Patch accsupp to avoid copying line numbers when copying from listing
+#+LATEX_HEADER_EXTRA: \usepackage{accsupp}
+#+LATEX_HEADER_EXTRA: \newcommand\emptyaccsupp[1]{\BeginAccSupp{ActualText={}}#1\EndAccSupp{}}
+#+LATEX_HEADER_EXTRA: \let\theHFancyVerbLine\theFancyVerbLine
+#+LATEX_HEADER_EXTRA: \def\theFancyVerbLine{\rmfamily\tiny\emptyaccsupp{\arabic{FancyVerbLine}}}
+
 #+LATEX_HEADER_EXTRA: \BeforeBeginEnvironment{tabular}{\rowcolors[]{2}{orange!5}{orange!10}}
 #+LATEX_HEADER_EXTRA: \BeforeBeginEnvironment{minted}{\begin{mdframed}[linecolor=blue,backgroundcolor=blue!10]}
 #+LATEX_HEADER_EXTRA: \AfterEndEnvironment{minted}{\end{mdframed}}
@@ -2541,11 +2547,200 @@ to files for instance) as we will see below.
 
 **** ~core~ provided functions
 
-***** ~exit: Z -> void~
+***** execution control functions
+
+Here are functions that allow to control the execution of the
+script. These can stop the execution if some conditions are met or
+create checkpoint that may be used to stop and then resume the
+execution.
+
+****** ~exit: Z -> void~
 
 This function interrupts the execution of the script. The integer (~Z~)
 value is the code that is returned when ~pugs~ exits.
 
+#+NAME: exit-function
+#+BEGIN_SRC pugs :exports both :results output
+  for (let i:N, i = 1; i < 10; ++i) {
+    cout << "i = " << i << "\n";
+    if (i==3) {
+      exit(0);
+    }
+  }
+#+END_SRC
+The output shows that the execution is interrupted (in a clean way) if
+the condition (here ~i == 3~) is met.
+#+RESULTS: exit-function
+
+****** ~stop: void -> B~
+
+This is an interactive function that is used to notify the code to
+stop its execution. It returns ~true~ if one of the following stopping
+condition is met.
+- If a ~stop~ file is created *after* the beginning of the execution in
+  the *execution directory*. This file can be created using the ~touch~
+  command for instance
+  #+BEGIN_SRC shell :exports source
+    touch stop
+  #+END_SRC
+- If ~pugs~ was compiled using ~Slurm~ support (this can be checked using
+  the command ~./pugs -v~) then during batch execution the ~stop~ function
+  will also return ~true~ as soon as the remaining execution time is
+  less than $150s$.
+
+In the following example the function ~stop~ returns always ~false~ since
+none of the above conditions are satisfied.
+#+NAME: stop-function
+#+BEGIN_SRC pugs :exports both :results output
+  for (let i:N, i = 1; i <= 5; ++i) {
+    cout << "i = " << i << "\n";
+    if (stop()) {
+      exit(0);
+    }
+  }
+#+END_SRC
+The output shows that the execution reaches ~i == 5~.
+#+RESULTS: stop-function
+
+****** ~checkpoint: void -> void~
+
+This function creates a checkpoint that can be used as a starting
+point for another execution. This function can be placed anywhere in
+the script and possibly multiple times. The checkpoint storage file is
+~checkpoint.h5~ and it is created in the current execution directory.
+
+*This functionality requires ~pugs~ to be compiled with ~HDF5~ support*.
+
+The following example creates two checkpoints.
+#+NAME: checkpoint-function
+#+BEGIN_SRC pugs :exports both :results output
+  let n:N, n = 4;
+  cout << "n = " << n << "\n";
+  checkpoint();
+  let x:R^3, x = [1, 2, 3];
+  cout << "x = " << x << "\n";
+  checkpoint();
+#+END_SRC
+The output displays the creation of two checkpoints in the file ~checkpoint.h5~.
+#+RESULTS: checkpoint-function
+The command
+#+BEGIN_SRC shell :exports code
+  pugs_checkpoint --info checkpoint.h5
+#+END_SRC
+displays a simple execution state for each checkpoint stored in the
+file in order to help user to choose the appropriate resuming
+checkpoint.
+#+NAME: checkpoint-info
+#+BEGIN_SRC shell :exports results :results output
+  ${PUGS_CHECKPOINT} --no-color --info checkpoint.h5
+#+END_SRC
+#+RESULTS: checkpoint-info
+One can notice that the ~x~ variable does not appear in the first
+checkpoint since it was not created at this point. Also two pointers
+are defined:
+- ~last_checkpoint~ that displays the more recent checkpoint,
+  and
+- ~resuming_checkpoint~ that indicates which checkpoint will be used when
+  resuming.
+
+Proceeding with this example, one can change the resuming checkpoint
+with the command
+#+BEGIN_SRC shell :exports code
+  pugs_checkpoint --resume-from 0 checkpoint.h5
+#+END_SRC
+which displays
+#+NAME: checkpoint-resume-from
+#+BEGIN_SRC shell :exports results :results output
+  ${PUGS_CHECKPOINT} --no-color --resume-from 0 checkpoint.h5
+#+END_SRC
+#+RESULTS: checkpoint-resume-from
+Running again
+#+BEGIN_SRC shell :exports code
+  pugs_checkpoint --info checkpoint.h5
+#+END_SRC
+now prints
+#+NAME: checkpoint-info0
+#+BEGIN_SRC shell :exports results :results output
+  ${PUGS_CHECKPOINT} --no-color --info checkpoint.h5
+#+END_SRC
+#+RESULTS: checkpoint-info0
+One notices that ~resuming_checkpoint~ now points to ~checkpoint_0~.
+
+It is now possible to resume the execution using the command
+#+BEGIN_SRC shell :exports code
+  pugs --resume checkpoint.h5
+#+END_SRC
+The output is now
+#+NAME: checkpoint-resume0
+#+BEGIN_SRC shell :exports results :results output
+  ${PUGS} --no-exec-stat --no-preamble --no-color --threads=1 --resume checkpoint.h5
+#+END_SRC
+#+RESULTS: checkpoint-resume0
+Observe that the random seed is reset to the value that was stored at
+checkpoint 0.
+
+Also each checkpoint whose number is greater than the resuming
+checkpoint (here 0) are removed when the next checkpoint (here 1) is
+written.
+
+#+BEGIN_note
+One may have noticed that the script file that is used for resuming is
+actually stored in the ~checkpoint.h5~ file, the script is not a command
+line argument.
+
+By now, it is not possible to *simply* modify the script while
+resuming. This is done in purpose since it remains unclear if such a
+dangerous functionality should be make easy. Indeed allowing
+script modifications may lead to undefined behaviors.
+#+END_note
+
+#+BEGIN_warning
+The number of ~MPI~ ranks *cannot* be changed when resuming.
+
+This is not likely to change since it is a very specific
+functionality.  However, a post-processing tool rewriting checkpoints
+may be developed to achieve it, but it is not a priority.
+#+END_warning
+
+****** ~checkpoint_and_exit: void -> void~
+
+This is an advanced version of the ~checkpoint~ function that cause a
+clean ~exit~ of the code after writing a checkpoint.
+
+The use case for this function is batch execution and is generally
+triggered by the ~stop~ function.
+
+We give here a simple example.
+#+NAME: checkpoint-exit-function
+#+BEGIN_SRC pugs :exports both :results output
+  for (let i:N, i = 1; i<=10; ++i) {
+    cout << "i = " << i << "\n";
+    if (i==5) {
+      checkpoint_and_exit();
+    }
+  }
+#+END_SRC
+The output is
+#+RESULTS: checkpoint-exit-function
+
+Then one can resume the execution as previously by
+#+BEGIN_SRC shell :exports code
+  pugs --resume checkpoint.h5
+#+END_SRC
+It gives the output
+The output is now
+#+NAME: checkpoint-resume1
+#+BEGIN_SRC shell :exports results :results output
+  ${PUGS} --no-exec-stat --no-preamble --no-color --threads=1 --resume checkpoint.h5
+#+END_SRC
+#+RESULTS: checkpoint-resume1
+
+# Clean-up
+#+BEGIN_SRC shell :exports results :results none
+  /bin/rm -f checkpoint.h5
+#+END_SRC
+
+
 ***** ~getAvailableModules: void -> string~
 
 This function that is used in the preamble of this section is a