From 33e713be50d5d8c1dcf3ad577f02728ed0cdabd0 Mon Sep 17 00:00:00 2001 From: Matthias Maier Date: Sun, 20 Feb 2022 11:32:06 -0600 Subject: [PATCH] Update documentation --- doc/developers/testsuite.html | 39 +++++++++++++++++++++++++++++++---- doc/users/testsuite.html | 13 ++++++------ 2 files changed, 41 insertions(+), 11 deletions(-) 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 @@
  • Restricting tests to build configurations
  • Restricting tests to feature configurations
  • Running tests with MPI
    • -
  • Tests with binary output
  • Tests with multiple comparison files
  • Changing condition for success
  • Adding new tests
    • @@ -475,7 +474,7 @@ category/test.output just category/test.output. In pseudo code: 
     category/test.[with_<string>(<=|>=|=|<|>)<on|off|version>.]*
-              [mpirun=<N|all>.][threads=<N|all>.][expect=<y>.][binary.][<debug|release>.](output|run_only)
+              [mpirun=<N|all>.][threads=<N|all>.][expect=<y>.][exclusive.][<debug|release>.](output|run_only)
    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

    Restricting tests to feature configurations

    - 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., 

     category/test.with_umfpack=on.output, or
@@ -543,7 +542,7 @@ category/test.with_umfpack=on.with_zlib=on.output
 
 
     
-    
    Running tests with MPI
    
+    
    Running tests with MPI or a specific thread pool size
    
     
    
       If a test should be run with MPI in parallel, the number of MPI
       processes N with which a program needs to be run for
@@ -553,6 +552,38 @@ category/test.mpirun=N.output
    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 + threads=N, where N is the number of + concurrent worker threads that should be initialized: +
    +category/test.threads=N.output
+
    + This is declaration is equivalent to setting the environment variable + DEAL_II_NUM_THREADS, or calling + MultithreadInfo::set_thread_limit() by hand. +

    + +

    + 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 .exclusive keyword: +

    +category/test.exclusive.output
+
    + This ensures that the test in question always runs "in serial" without + another test scheduled concurrently.

    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. + - 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.
    -- 2.39.5