From: Matthias Maier <tamiko@43-1.org>
Date: Sun, 20 Feb 2022 17:32:06 +0000 (-0600)
Subject: Update documentation
X-Git-Tag: v9.4.0-rc1~458^2~3
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=33e713be50d5d8c1dcf3ad577f02728ed0cdabd0;p=dealii.git

Update documentation
---

diff --git a/doc/developers/testsuite.html b/doc/developers/testsuite.html
index 74e7d708cb..93c37f0ef0 100644
--- a/doc/developers/testsuite.html
+++ b/doc/developers/testsuite.html
@@ -52,7 +52,6 @@
           <li><a href="#restrictbuild">Restricting tests to build configurations</a></li>
           <li><a href="#restrictfeature">Restricting tests to feature configurations</a></li>
           <li><a href="#mpi">Running tests with MPI</a></li>
-          <li><a href="#binary">Tests with binary output</a></li>
           <li><a href="#variants">Tests with multiple comparison files</a></li>
           <li><a href="#expect">Changing condition for success</a></li>
           <li><a href="#layoutaddtests">Adding new tests</a></li>
@@ -475,7 +474,7 @@ category/test.output
       just <code>category/test.output</code>. In pseudo code:
 <pre>
 category/test.[with_&lt;string&gt;(&lt;=|&gt;=|=|&lt;|&gt;)&lt;on|off|version&gt;.]*
-              [mpirun=&lt;N|all&gt;.][threads=&lt;N|all&gt;.][expect=&lt;y&gt;.][binary.][&lt;debug|release&gt;.](output|run_only)
+              [mpirun=&lt;N|all&gt;.][threads=&lt;N|all&gt;.][expect=&lt;y&gt;.][exclusive.][&lt;debug|release&gt;.](output|run_only)
 </pre>
       Normally, a test will be set up so that it runs twice, once in debug and
       once in release configuration.
@@ -500,7 +499,7 @@ category/test.release.output
     <a name="restrictfeature"></a>
     <h3>Restricting tests to feature configurations</h3>
     <p>
-      In a similar vain as for build configurations, it is possible to restrict
+      In a similar vein as for build configurations, it is possible to restrict
       tests to specific feature configurations, e.g.,
 <pre>
 category/test.with_umfpack=on.output, or
@@ -543,7 +542,7 @@ category/test.with_umfpack=on.with_zlib=on.output
 
 
     <a name="mpi"></a>
-    <h3>Running tests with MPI</h3>
+    <h3>Running tests with MPI or a specific thread pool size</h3>
     <p>
       If a test should be run with MPI in parallel, the number of MPI
       processes <code>N</code> with which a program needs to be run for
@@ -553,6 +552,38 @@ category/test.mpirun=N.output
 </pre>
       It is quite typical for an MPI-enabled test to have multiple output
       files for different numbers of MPI processes.
+
+      Similarly, the thread pool size of a test can be specified by using
+      <code>threads=N</code>, where <code>N</code> is the number of
+      concurrent worker threads that should be initialized:
+<pre>
+category/test.threads=N.output
+</pre>
+      This is declaration is equivalent to setting the environment variable
+      <code>DEAL_II_NUM_THREADS</code>, or calling
+      <code>MultithreadInfo::set_thread_limit()</code> by hand.
+    </p>
+
+    <p>
+      In order to account for the increased computational workload of MPI
+      parallel code the testsuite will add a processing weight to
+      individual MPI tests equal to half of the number of MPI ranks that
+      ensures that the machine the testsuite runs on is at most
+      overcommitted by a factor of 2. Thread concurrency is not accounted
+      for.
+
+      This behavior is modified for performance tests. Here, the
+      processing weight is taken directly to be the product of the number
+      of MPI ranks times the number of threads.
+
+      Particularly sensitive timing tests that have to be run
+      exclusively without any other test running concurrently can be
+      annotated with the <code>.exclusive</code> keyword:
+<pre>
+category/test.exclusive.output
+</pre>
+       This ensures that the test in question always runs "in serial" without
+       another test scheduled concurrently.
     </p>
 
     <a name="variants"></a>
diff --git a/doc/users/testsuite.html b/doc/users/testsuite.html
index ccc40b6819..149e5a17ef 100644
--- a/doc/users/testsuite.html
+++ b/doc/users/testsuite.html
@@ -322,13 +322,12 @@ TEST_MPI_RANK_LIMIT
     dropped. The special value 0 enforces no limit. Defaults to 0.
 
 TEST_THREAD_LIMIT
-  - Specifies the maximal number of worker threads that can should be
-    used by the threading backend. If a test variant configures a larger
-    number of threads (via .threads=N. in the output file) than this limit
-    the test will be dropped. Note that individual tests might exceed this
-    limit by calling MultithreadInfo::set_thread_limit(), or by manually
-    creating additional threads. The special value 0 enforces no limit.
-    Defaults to 0.</pre>
+  - Specifies the maximal number of worker threads that can be used by the
+    threading backend. If a test variant configures a larger number of threads
+    (via .threads=N. in the output file) than this limit the test will be
+    dropped. Note that individual tests might exceed this limit by calling
+    MultithreadInfo::set_thread_limit(), or by manually creating additional
+    threads. The special value 0 enforces no limit. Defaults to 0.</pre>
     <hr />
     <div class="right">
       <a href="http://validator.w3.org/check?uri=referer" target="_top">