Document deal.II's mechanism for setting the number of threads

tests/main.cc

@@ -19,6 +19,8 @@ bool init_function() { return true; }
 
 int main(int argc, char *argv[])
 {
+  // Set the maximum number of threads used to the minimum of the number of
+  // cores reported by TBB and the environment variable DEAL_II_NUM_THREADS.
   dealii::Utilities::MPI::MPI_InitFinalize mpi_init(
       argc, argv, dealii::numbers::invalid_unsigned_int);
 

tests/test_hierarchy.cc

@@ -36,6 +36,15 @@
 #include "main.cc"
 #include "test_hierarchy_helpers.hpp"
 
+// In a lot of places in this file, we explicitly set the number of threads to
+// use since some of the tests cases don't work with multiple threads yet. This
+// works as follow: dealii::MultithreadInfo::set_thread_limit sets the number of
+// threads to the minimum its the argument and the environment variable
+// DEAL_II_NUM_THREADS. TBB is asked for the maximum nuber of cores if the
+// minimum is dealii::numbers::invalid_unsigned_int. Consequently,
+// MultithreadInfo::set_thread_limit(numbers::invalid_unsigned int) sets the
+// number of threads to the ones specified in the environment variable.
+
 namespace bdata = boost::unit_test::data;
 namespace tt = boost::test_tools;