| 1 |
// ------------------------------------------------------------------------ |
| 2 |
// |
| 3 |
// SPDX-License-Identifier: LGPL-2.1-or-later |
| 4 |
// Copyright (C) 1998 - 2023 by the deal.II authors |
| 5 |
// |
| 6 |
// This file is part of the deal.II library. |
| 7 |
// |
| 8 |
// Part of the source code is dual licensed under Apache-2.0 WITH |
| 9 |
// LLVM-exception OR LGPL-2.1-or-later. Detailed license information |
| 10 |
// governing the source code and code contributions can be found in |
| 11 |
// LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. |
| 12 |
// |
| 13 |
// ------------------------------------------------------------------------ |
| 14 |
|
| 15 |
#ifndef dealii_timer_h |
| 16 |
#define dealii_timer_h |
| 17 |
|
| 18 |
#include <deal.II/base/config.h> |
| 19 |
|
| 20 |
#include <deal.II/base/conditional_ostream.h> |
| 21 |
#include <deal.II/base/mpi.h> |
| 22 |
#include <deal.II/base/mutex.h> |
| 23 |
|
| 24 |
#include <chrono> |
| 25 |
#include <list> |
| 26 |
#include <map> |
| 27 |
#include <string> |
| 28 |
|
| 29 |
DEAL_II_NAMESPACE_OPEN |
| 30 |
|
| 31 |
/** |
| 32 |
* A clock, compatible with the <code>std::chrono</code> notion of a clock, |
| 33 |
* whose now() method returns a time point indicating the amount of CPU time |
| 34 |
* that the current process has used. |
| 35 |
*/ |
| 36 |
struct CPUClock |
| 37 |
{ |
| 38 |
/** |
| 39 |
* Duration type. Windows measures CPU times, by default, in multiples of |
| 40 |
* 1/64th of a second and POSIX uses microseconds, so go with microseconds |
| 41 |
* for uniformity. |
| 42 |
*/ |
| 43 |
using duration = std::chrono::microseconds; |
| 44 |
|
| 45 |
/** |
| 46 |
* Signed integral type used to store the value returned by count(). |
| 47 |
*/ |
| 48 |
using rep = duration::rep; |
| 49 |
|
| 50 |
/** |
| 51 |
* Ratio representing the length of a period (in seconds). |
| 52 |
*/ |
| 53 |
using period = duration::period; |
| 54 |
|
| 55 |
/** |
| 56 |
* Time point type. |
| 57 |
*/ |
| 58 |
using time_point = std::chrono::time_point<CPUClock, duration>; |
| 59 |
|
| 60 |
/** |
| 61 |
* Boolean indicating that the clock monotonically increases. |
| 62 |
*/ |
| 63 |
static const bool is_steady = true; |
| 64 |
|
| 65 |
/** |
| 66 |
* Return the amount of CPU time that the current process has |
| 67 |
* used. Unfortunately, this requires platform-specific calls, so this |
| 68 |
* function returns 0 on platforms that are neither Windows nor POSIX. |
| 69 |
*/ |
| 70 |
static time_point |
| 71 |
now() noexcept; |
| 72 |
}; |
| 73 |
|
| 74 |
/** |
| 75 |
* The Timer class provides a way to measure both the amount of wall time |
| 76 |
* (i.e., the amount of time elapsed on a wall clock) and the amount of CPU |
| 77 |
* time that certain sections of an application have used. This class also |
| 78 |
* offers facilities for synchronizing the elapsed time across an MPI |
| 79 |
* communicator. |
| 80 |
* |
| 81 |
* <h3>Usage</h3> |
| 82 |
* |
| 83 |
* The Timer class can be started and stopped several times. It stores both |
| 84 |
* the amount of time elapsed over the last start-stop cycle, or <em>lap</em>, |
| 85 |
* as well as the total time elapsed over all laps. Here is an example: |
| 86 |
* |
| 87 |
* @code |
| 88 |
* Timer timer; // creating a timer also starts it |
| 89 |
* |
| 90 |
* // do some complicated computations here |
| 91 |
* // ... |
| 92 |
* |
| 93 |
* timer.stop(); |
| 94 |
* |
| 95 |
* std::cout << "Elapsed CPU time: " << timer.cpu_time() << " seconds.\n"; |
| 96 |
* std::cout << "Elapsed wall time: " << timer.wall_time() << " seconds.\n"; |
| 97 |
* |
| 98 |
* // reset timer for the next thing it shall do |
| 99 |
* timer.reset(); |
| 100 |
* @endcode |
| 101 |
* |
| 102 |
* Alternatively, you can also restart the timer instead of resetting it. The |
| 103 |
* times between successive calls to start() and stop() (i.e., the laps) will |
| 104 |
* then be accumulated. The usage of this class is also explained in the |
| 105 |
* step-28 tutorial program. |
| 106 |
* |
| 107 |
* @note The TimerOutput (combined with TimerOutput::Scope) class provide a |
| 108 |
* convenient way to time multiple named sections and summarize the output. |
| 109 |
* |
| 110 |
* @note Implementation of this class is system dependent. In particular, CPU |
| 111 |
* times are accumulated from summing across all threads and will usually |
| 112 |
* exceed the wall times. |
| 113 |
* |
| 114 |
* @ingroup utilities |
| 115 |
*/ |
| 116 |
class Timer |
| 117 |
{ |
| 118 |
public: |
| 119 |
/** |
| 120 |
* Constructor. Sets the accumulated times at zero and calls Timer::start(). |
| 121 |
*/ |
| 122 |
Timer(); |
| 123 |
|
| 124 |
/** |
| 125 |
* Constructor specifying that CPU times should be summed over the given |
| 126 |
* communicator. If @p sync_lap_times is <code>true</code> then the Timer |
| 127 |
* will set the elapsed wall and CPU times over the last lap to their |
| 128 |
* maximum values across the provided communicator. This synchronization is |
| 129 |
* only performed if Timer::stop() is called before the timer is queried for |
| 130 |
* time duration values. |
| 131 |
* |
| 132 |
* This constructor calls Timer::start(). |
| 133 |
* |
| 134 |
* @note The timer is stopped before the synchronization over the |
| 135 |
* communicator occurs; the extra cost of the synchronization is not |
| 136 |
* measured. |
| 137 |
*/ |
| 138 |
Timer(const MPI_Comm mpi_communicator, const bool sync_lap_times = false); |
| 139 |
|
| 140 |
/** |
| 141 |
* Return a reference to the data structure containing basic statistics on |
| 142 |
* the last lap's wall time measured across all MPI processes in the given |
| 143 |
* communicator. This structure does not contain meaningful values until |
| 144 |
* Timer::stop() has been called. |
| 145 |
*/ |
| 146 |
const Utilities::MPI::MinMaxAvg & |
| 147 |
get_last_lap_wall_time_data() const; |
| 148 |
|
| 149 |
/** |
| 150 |
* Return a reference to the data structure containing basic statistics on |
| 151 |
* the accumulated wall time measured across all MPI processes in the given |
| 152 |
* communicator. This structure does not contain meaningful values until |
| 153 |
* Timer::stop() has been called. |
| 154 |
*/ |
| 155 |
const Utilities::MPI::MinMaxAvg & |
| 156 |
get_accumulated_wall_time_data() const; |
| 157 |
|
| 158 |
/** |
| 159 |
* Print the data returned by Timer::get_last_lap_wall_time_data() to the |
| 160 |
* given stream. |
| 161 |
*/ |
| 162 |
template <typename StreamType> |
| 163 |
void |
| 164 |
print_last_lap_wall_time_data(StreamType &stream) const; |
| 165 |
|
| 166 |
/** |
| 167 |
* Print the data returned by Timer::get_accumulated_wall_time_data() to the |
| 168 |
* given stream. |
| 169 |
*/ |
| 170 |
template <typename StreamType> |
| 171 |
void |
| 172 |
print_accumulated_wall_time_data(StreamType &stream) const; |
| 173 |
|
| 174 |
/** |
| 175 |
* Begin measuring a new lap. If <code>sync_lap_times</code> is |
| 176 |
* <code>true</code> then an MPI barrier is used to ensure that all |
| 177 |
* processes begin the lap at the same wall time. |
| 178 |
*/ |
| 179 |
void |
| 180 |
start(); |
| 181 |
|
| 182 |
/** |
| 183 |
* Stop the timer. This updates the lap times and accumulated times. If |
| 184 |
* <code>sync_lap_times</code> is <code>true</code> then the lap times are |
| 185 |
* synchronized over all processors in the communicator (i.e., the lap times |
| 186 |
* are set to the maximum lap time). |
| 187 |
* |
| 188 |
* Return the accumulated CPU time in seconds. |
| 189 |
*/ |
| 190 |
double |
| 191 |
stop(); |
| 192 |
|
| 193 |
/** |
| 194 |
* Stop the timer, if it is running, and reset all measured values to their |
| 195 |
* default states. |
| 196 |
*/ |
| 197 |
void |
| 198 |
reset(); |
| 199 |
|
| 200 |
/** |
| 201 |
* Equivalent to calling Timer::reset() followed by calling Timer::start(). |
| 202 |
*/ |
| 203 |
void |
| 204 |
restart(); |
| 205 |
|
| 206 |
/** |
| 207 |
* Return the current accumulated wall time (including the current lap, if |
| 208 |
* the timer is running) in seconds without stopping the timer. |
| 209 |
*/ |
| 210 |
double |
| 211 |
wall_time() const; |
| 212 |
|
| 213 |
/** |
| 214 |
* Return the wall time of the last lap in seconds. The timer is not stopped |
| 215 |
* by this function. |
| 216 |
*/ |
| 217 |
double |
| 218 |
last_wall_time() const; |
| 219 |
|
| 220 |
/** |
| 221 |
* Return the accumulated CPU time (including the current lap, if the timer |
| 222 |
* is running) in seconds without stopping the timer. |
| 223 |
* |
| 224 |
* If an MPI communicator is provided to the constructor then the returned |
| 225 |
* value is the sum of all accumulated CPU times over all processors in the |
| 226 |
* communicator. |
| 227 |
*/ |
| 228 |
double |
| 229 |
cpu_time() const; |
| 230 |
|
| 231 |
/** |
| 232 |
* Return the CPU time of the last lap in seconds. The timer is not stopped |
| 233 |
* by this function. |
| 234 |
*/ |
| 235 |
double |
| 236 |
last_cpu_time() const; |
| 237 |
|
| 238 |
private: |
| 239 |
/** |
| 240 |
* The Timer class stores timing information for two different clocks: a |
| 241 |
* wall clock and a CPU usage clock. Since the logic for handling both |
| 242 |
* clocks is, in most places, identical, we collect the relevant |
| 243 |
* measurements for each clock into this <code>struct</code>. |
| 244 |
* |
| 245 |
* @tparam clock_type_ The type of the clock whose measurements are being |
| 246 |
* stored. This class should conform to the usual clock interface expected |
| 247 |
* by <code>std::chrono</code> (i.e., the correct alias and a static |
| 248 |
* <code>now()</code> method). |
| 249 |
*/ |
| 250 |
template <class clock_type_> |
| 251 |
struct ClockMeasurements |
| 252 |
{ |
| 253 |
/** |
| 254 |
* Store the clock type. |
| 255 |
*/ |
| 256 |
using clock_type = clock_type_; |
| 257 |
|
| 258 |
/** |
| 259 |
* The time point type of the provided clock. |
| 260 |
*/ |
| 261 |
using time_point_type = typename clock_type::time_point; |
| 262 |
|
| 263 |
/** |
| 264 |
* The duration type of the provided clock. |
| 265 |
*/ |
| 266 |
using duration_type = typename clock_type::duration; |
| 267 |
|
| 268 |
/** |
| 269 |
* The time point corresponding to the start of the current lap. This is |
| 270 |
* obtained by calling <code>clock_type::now()</code>. |
| 271 |
*/ |
| 272 |
time_point_type current_lap_start_time; |
| 273 |
|
| 274 |
/** |
| 275 |
* The accumulated time over several laps. |
| 276 |
*/ |
| 277 |
duration_type accumulated_time; |
| 278 |
|
| 279 |
/** |
| 280 |
* The duration of the last lap. |
| 281 |
*/ |
| 282 |
duration_type last_lap_time; |
| 283 |
|
| 284 |
/** |
| 285 |
* Constructor. Sets <code>current_lap_start_time</code> to the current |
| 286 |
* clock time and the durations to zero. |
| 287 |
*/ |
| 288 |
ClockMeasurements(); |
| 289 |
|
| 290 |
/** |
| 291 |
* Reset the clock by setting <code>current_lap_start_time</code> to the |
| 292 |
* current clock time and the durations to zero. |
| 293 |
*/ |
| 294 |
void |
| 295 |
reset(); |
| 296 |
}; |
| 297 |
|
| 298 |
/** |
| 299 |
* Alias for the wall clock. |
| 300 |
*/ |
| 301 |
using wall_clock_type = std::chrono::steady_clock; |
| 302 |
|
| 303 |
/** |
| 304 |
* Alias for the CPU clock. |
| 305 |
*/ |
| 306 |
using cpu_clock_type = CPUClock; |
| 307 |
|
| 308 |
/** |
| 309 |
* Collection of wall time measurements. |
| 310 |
*/ |
| 311 |
ClockMeasurements<wall_clock_type> wall_times; |
| 312 |
|
| 313 |
/** |
| 314 |
* Collection of CPU time measurements. |
| 315 |
*/ |
| 316 |
ClockMeasurements<cpu_clock_type> cpu_times; |
| 317 |
|
| 318 |
/** |
| 319 |
* Whether or not the timer is presently running. |
| 320 |
*/ |
| 321 |
bool running; |
| 322 |
|
| 323 |
/** |
| 324 |
* The communicator over which various time values are synchronized and |
| 325 |
* combined: see the documentation of the relevant constructor for |
| 326 |
* additional information. |
| 327 |
*/ |
| 328 |
MPI_Comm mpi_communicator; |
| 329 |
|
| 330 |
/** |
| 331 |
* Store whether or not the wall time and CPU time are synchronized across |
| 332 |
* the communicator in Timer::start() and Timer::stop(). |
| 333 |
*/ |
| 334 |
bool sync_lap_times; |
| 335 |
|
| 336 |
/** |
| 337 |
* A structure for parallel wall time measurement that includes the minimum, |
| 338 |
* maximum, and average over all processors known to the MPI communicator of |
| 339 |
* the last lap time. |
| 340 |
*/ |
| 341 |
Utilities::MPI::MinMaxAvg last_lap_wall_time_data; |
| 342 |
|
| 343 |
/** |
| 344 |
* A structure for parallel wall time measurement that includes the minimum |
| 345 |
* time recorded among all processes, the maximum time as well as the |
| 346 |
* average time defined as the sum of all individual times divided by the |
| 347 |
* number of MPI processes in the MPI_Comm for the total run time. |
| 348 |
*/ |
| 349 |
Utilities::MPI::MinMaxAvg accumulated_wall_time_data; |
| 350 |
}; |
| 351 |
|
| 352 |
|
| 353 |
|
| 354 |
// TODO: The following class is not thread-safe |
| 355 |
/** |
| 356 |
* This class can be used to generate formatted output from time measurements |
| 357 |
* of different subsections in a program. It is possible to create several |
| 358 |
* sections that perform certain aspects of the program. A section can be |
| 359 |
* entered several times. By changing the options in OutputFrequency and |
| 360 |
* OutputType, the user can choose whether output should be generated every |
| 361 |
* time a section is joined or just in the end of the program. Moreover, it is |
| 362 |
* possible to show CPU times, wall times, or both. |
| 363 |
* |
| 364 |
* The class is used in a substantial number of tutorial programs that collect |
| 365 |
* timing data. step-77 is an example of a relatively simple sequential program |
| 366 |
* that uses it. step-40 and several others mentioned below use it for parallel |
| 367 |
* computations. |
| 368 |
* |
| 369 |
* |
| 370 |
* <h3>Usage</h3> |
| 371 |
* |
| 372 |
* Use of this class could be as follows: |
| 373 |
* @code |
| 374 |
* TimerOutput timer (std::cout, TimerOutput::summary, |
| 375 |
* TimerOutput::wall_times); |
| 376 |
* |
| 377 |
* timer.enter_subsection ("Setup dof system"); |
| 378 |
* setup_dofs(); |
| 379 |
* timer.leave_subsection(); |
| 380 |
* |
| 381 |
* timer.enter_subsection ("Assemble"); |
| 382 |
* assemble_system_1(); |
| 383 |
* timer.leave_subsection(); |
| 384 |
* |
| 385 |
* timer.enter_subsection ("Solve"); |
| 386 |
* solve_system_1(); |
| 387 |
* timer.leave_subsection(); |
| 388 |
* |
| 389 |
* timer.enter_subsection ("Assemble"); |
| 390 |
* assemble_system_2(); |
| 391 |
* timer.leave_subsection(); |
| 392 |
* |
| 393 |
* timer.enter_subsection ("Solve"); |
| 394 |
* solve_system_2(); |
| 395 |
* timer.leave_subsection(); |
| 396 |
* |
| 397 |
* // do something else... |
| 398 |
* @endcode |
| 399 |
* When run, this program will return an output like this: |
| 400 |
* @code |
| 401 |
* +---------------------------------------------+------------+------------+ |
| 402 |
* | Total wallclock time elapsed since start | 88.8s | | |
| 403 |
* | | | | |
| 404 |
* | Section | no. calls | wall time | % of total | |
| 405 |
* +---------------------------------+-----------+------------+------------+ |
| 406 |
* | Assemble | 2 | 19.7s | 22% | |
| 407 |
* | Solve | 2 | 3.03s | 3.4% | |
| 408 |
* | Setup dof system | 1 | 3.97s | 4.5% | |
| 409 |
* +---------------------------------+-----------+------------+------------+ |
| 410 |
* @endcode |
| 411 |
* The output will see that we entered the assembly and solve section twice, |
| 412 |
* and reports how much time we spent there. Moreover, the class measures the |
| 413 |
* total time spent from start to termination of the TimerOutput object. In |
| 414 |
* this case, we did a lot of other stuff, so that the time proportions of the |
| 415 |
* functions we measured are far away from 100 percent. |
| 416 |
* |
| 417 |
* |
| 418 |
* <h3>Using scoped timers</h3> |
| 419 |
* |
| 420 |
* The scheme above where you have to have calls to |
| 421 |
* TimerOutput::enter_subsection() and TimerOutput::leave_subsection() is |
| 422 |
* awkward if the sections in between these calls contain <code>return</code> |
| 423 |
* statements or may throw exceptions. In that case, it is easy to forget that |
| 424 |
* one nevertheless needs to leave the section somehow, somewhere. An easier |
| 425 |
* approach is to use "scoped" sections. This is a variable that when you |
| 426 |
* create it enters a section, and leaves the section when you destroy it. If |
| 427 |
* this is a variable local to a particular scope (a code block between curly |
| 428 |
* braces) and you leave this scope due to a <code>return</code> statements or |
| 429 |
* an exception, then the variable is destroyed and the timed section is left |
| 430 |
* automatically. Consequently, we could have written the code piece above as |
| 431 |
* follows, with exactly the same result but now exception-safe: |
| 432 |
* @code |
| 433 |
* TimerOutput timer (std::cout, TimerOutput::summary, |
| 434 |
* TimerOutput::wall_times); |
| 435 |
* |
| 436 |
* { |
| 437 |
* TimerOutput::Scope timer_section(timer, "Setup dof system"); |
| 438 |
* setup_dofs(); |
| 439 |
* } |
| 440 |
* |
| 441 |
* { |
| 442 |
* TimerOutput::Scope timer_section(timer, "Assemble"); |
| 443 |
* assemble_system_1(); |
| 444 |
* } |
| 445 |
* |
| 446 |
* { |
| 447 |
* TimerOutput::Scope timer_section(timer, "Solve"); |
| 448 |
* solve_system_1(); |
| 449 |
* } |
| 450 |
* |
| 451 |
* { |
| 452 |
* TimerOutput::Scope timer_section(timer, "Assemble"); |
| 453 |
* assemble_system_2(); |
| 454 |
* } |
| 455 |
* |
| 456 |
* { |
| 457 |
* TimerOutput::Scope timer_section(timer, "Solve"); |
| 458 |
* solve_system_2(); |
| 459 |
* } |
| 460 |
* |
| 461 |
* // do something else... |
| 462 |
* @endcode |
| 463 |
* |
| 464 |
* |
| 465 |
* <h3>Usage in parallel programs using MPI</h3> |
| 466 |
* |
| 467 |
* In a parallel program built on MPI, using the class in a way such as the |
| 468 |
* one shown above would result in a situation where each process times the |
| 469 |
* corresponding sections and then outputs the resulting timing information at |
| 470 |
* the end. This is annoying since you'd get a lot of output -- one set of |
| 471 |
* timing information from each processor. |
| 472 |
* |
| 473 |
* This can be avoided by only letting one processor generate screen output, |
| 474 |
* typically by using an object of type ConditionalOStream instead of |
| 475 |
* <code>std::cout</code> to write to screen (see, for example, step-17, |
| 476 |
* step-18, step-32 and step-40, all of which use this method). |
| 477 |
* |
| 478 |
* This way, only a single processor outputs timing information, typically the |
| 479 |
* first process in the MPI universe. However, if you take the above code |
| 480 |
* snippet as an example, imagine what would happen if |
| 481 |
* <code>setup_dofs()</code> is fast on processor zero and slow on at least |
| 482 |
* one of the other processors; and if the first thing |
| 483 |
* <code>assemble_system_1()</code> does is something that requires all |
| 484 |
* processors to communicate. In this case, on processor zero, the timing |
| 485 |
* section with name <code>"Setup dof system"</code> will yield a short run |
| 486 |
* time on processor zero, whereas the section <code> "Assemble"</code> will |
| 487 |
* take a long time: not because <code>assemble_system_1()</code> takes a |
| 488 |
* particularly long time, but because on the processor on which we time (or, |
| 489 |
* rather, the one on which we generate output) happens to have to wait for a |
| 490 |
* long time till the other processor is finally done with |
| 491 |
* <code>setup_dofs()</code> and starts to participate in |
| 492 |
* <code>assemble_system_1()</code>. In other words, the timing that is |
| 493 |
* reported is unreliable because it reflects run times from other processors. |
| 494 |
* Furthermore, the run time of this section on processor zero has nothing to |
| 495 |
* do with the run time of the section on other processors but instead with |
| 496 |
* the run time of <i>the previous section</i> on another processor. |
| 497 |
* |
| 498 |
* The first way to avoid this is to introduce a barrier into the parallel |
| 499 |
* code just before we start and stop timing sections. This ensures that all |
| 500 |
* processes are at the same place and the timing information then reflects |
| 501 |
* the maximal run time across all processors. To achieve this, you need to |
| 502 |
* initialize the TimerOutput object with an MPI communicator object, for |
| 503 |
* example as in the following code: |
| 504 |
* @code |
| 505 |
* TimerOutput timer (MPI_COMM_WORLD, |
| 506 |
* pcout, |
| 507 |
* TimerOutput::summary, |
| 508 |
* TimerOutput::wall_times); |
| 509 |
* @endcode |
| 510 |
* Here, <code>pcout</code> is an object of type ConditionalOStream that makes |
| 511 |
* sure that we only generate output on a single processor. See the step-32, |
| 512 |
* step-40, and step-42 tutorial programs for this kind of usage of this class. |
| 513 |
* |
| 514 |
* The second variant to cope with this issue is print more information about |
| 515 |
* the recorded times to be able to understand this kind of imbalances without |
| 516 |
* actually adding the barriers. While this approach is still affected by |
| 517 |
* imbalances between different MPI processes, its output is not the arbitrary |
| 518 |
* time of rank 0, but the minimum, average and maximum of the MPI results, |
| 519 |
* using information from Utilities::MPI::MinMaxAvg. As the data is also |
| 520 |
* equipped with the rank id where the minimum and maximum are attained, this |
| 521 |
* approach allows to identify on which ranks certain slowdowns occur. In case |
| 522 |
* some imbalance between the MPI ranks from one section to the next can be |
| 523 |
* tolerated, this strategy can hence be advantageous over the barrier variant |
| 524 |
* as it does not synchronize the program in places where it is not necessary, |
| 525 |
* and rather tries to display the imbalance observed in various phases. In |
| 526 |
* order to use this variant initialize the output object without any native |
| 527 |
* print settings and without communicator, |
| 528 |
* @code |
| 529 |
* TimerOutput timer (pcout, |
| 530 |
* TimerOutput::never, |
| 531 |
* TimerOutput::wall_times); |
| 532 |
* @endcode |
| 533 |
* and then call |
| 534 |
* @code |
| 535 |
* timer.print_wall_time_statistics(MPI_COMM_WORLD); |
| 536 |
* @endcode |
| 537 |
* where appropriate. Here, the output is written to the <code>pcout</code> |
| 538 |
* object of type ConditionalOStream passed to the constructor, making sure |
| 539 |
* the information is only printed once. See step-67 for an example usage of |
| 540 |
* this variant. Besides the basic minimum, average, and maximum of times over |
| 541 |
* all MPI ranks, the TimerOutput::print_wall_time_statistics() function also |
| 542 |
* takes a second argument to specify output of quantiles, e.g., the time |
| 543 |
* taken by the 10\% of the slowest and fastest ranks, respectively, to get |
| 544 |
* additional insight into the statistical distribution. |
| 545 |
* |
| 546 |
* @ingroup utilities |
| 547 |
*/ |
| 548 |
class TimerOutput |
| 549 |
{ |
| 550 |
public: |
| 551 |
/** |
| 552 |
* Helper class to enter/exit sections in TimerOutput be constructing a |
| 553 |
* simple scope-based object. The purpose of this class is explained in the |
| 554 |
* documentation of TimerOutput. |
| 555 |
*/ |
| 556 |
class Scope |
| 557 |
{ |
| 558 |
public: |
| 559 |
/** |
| 560 |
* Enter the given section in the timer. Exit automatically when calling |
| 561 |
* stop() or destructor runs. |
| 562 |
*/ |
| 563 |
Scope(dealii::TimerOutput &timer_, const std::string §ion_name); |
| 564 |
|
| 565 |
/** |
| 566 |
* Destructor calls stop() |
| 567 |
*/ |
| 568 |
~Scope(); |
| 569 |
|
| 570 |
/** |
| 571 |
* In case you want to exit the scope before the destructor is executed, |
| 572 |
* call this function. |
| 573 |
*/ |
| 574 |
void |
| 575 |
stop(); |
| 576 |
|
| 577 |
private: |
| 578 |
/** |
| 579 |
* Reference to the TimerOutput object |
| 580 |
*/ |
| 581 |
dealii::TimerOutput &timer; |
| 582 |
|
| 583 |
/** |
| 584 |
* Name of the section we need to exit |
| 585 |
*/ |
| 586 |
const std::string section_name; |
| 587 |
|
| 588 |
/** |
| 589 |
* Do we still need to exit the section we are in? |
| 590 |
*/ |
| 591 |
bool in; |
| 592 |
}; |
| 593 |
|
| 594 |
/** |
| 595 |
* An enumeration data type that describes whether to generate output every |
| 596 |
* time we exit a section, just in the end, both, or never. |
| 597 |
*/ |
| 598 |
enum OutputFrequency |
| 599 |
{ |
| 600 |
/** |
| 601 |
* Generate output after every call. |
| 602 |
*/ |
| 603 |
every_call, |
| 604 |
/** |
| 605 |
* Generate output in summary at the end. |
| 606 |
*/ |
| 607 |
summary, |
| 608 |
/** |
| 609 |
* Generate output both after every call and in summary at the end. |
| 610 |
*/ |
| 611 |
every_call_and_summary, |
| 612 |
/** |
| 613 |
* Never generate any output. |
| 614 |
*/ |
| 615 |
never |
| 616 |
}; |
| 617 |
|
| 618 |
/** |
| 619 |
* An enumeration data type that describes the type of data to return |
| 620 |
* when fetching the data from the timer. |
| 621 |
*/ |
| 622 |
enum OutputData |
| 623 |
{ |
| 624 |
/** |
| 625 |
* Output CPU times. |
| 626 |
*/ |
| 627 |
total_cpu_time, |
| 628 |
/** |
| 629 |
* Output wall clock times. |
| 630 |
*/ |
| 631 |
total_wall_time, |
| 632 |
/** |
| 633 |
* Output number of calls. |
| 634 |
*/ |
| 635 |
n_calls |
| 636 |
}; |
| 637 |
|
| 638 |
/** |
| 639 |
* An enumeration data type that describes whether to show CPU times, wall |
| 640 |
* times, or both CPU and wall times whenever we generate output. |
| 641 |
*/ |
| 642 |
enum OutputType |
| 643 |
{ |
| 644 |
/** |
| 645 |
* Output CPU times. |
| 646 |
*/ |
| 647 |
cpu_times, |
| 648 |
/** |
| 649 |
* Output wall clock times. |
| 650 |
*/ |
| 651 |
wall_times, |
| 652 |
/** |
| 653 |
* Output both CPU and wall clock times in separate tables. |
| 654 |
*/ |
| 655 |
cpu_and_wall_times, |
| 656 |
/** |
| 657 |
* Output both CPU and wall clock times in a single table. |
| 658 |
*/ |
| 659 |
cpu_and_wall_times_grouped |
| 660 |
}; |
| 661 |
|
| 662 |
/** |
| 663 |
* Constructor. |
| 664 |
* |
| 665 |
* @param stream The stream (of type std::ostream) to which output is |
| 666 |
* written. |
| 667 |
* @param output_frequency A variable indicating when output is to be |
| 668 |
* written to the given stream. |
| 669 |
* @param output_type A variable indicating what kind of timing the output |
| 670 |
* should represent (CPU or wall time). |
| 671 |
*/ |
| 672 |
TimerOutput(std::ostream &stream, |
| 673 |
const OutputFrequency output_frequency, |
| 674 |
const OutputType output_type); |
| 675 |
|
| 676 |
/** |
| 677 |
* Constructor. |
| 678 |
* |
| 679 |
* @param stream The stream (of type ConditionalOstream) to which output is |
| 680 |
* written. |
| 681 |
* @param output_frequency A variable indicating when output is to be |
| 682 |
* written to the given stream. |
| 683 |
* @param output_type A variable indicating what kind of timing the output |
| 684 |
* should represent (CPU or wall time). |
| 685 |
*/ |
| 686 |
TimerOutput(ConditionalOStream &stream, |
| 687 |
const OutputFrequency output_frequency, |
| 688 |
const OutputType output_type); |
| 689 |
|
| 690 |
/** |
| 691 |
* Constructor that takes an MPI communicator as input. A timer constructed |
| 692 |
* this way will sum up the CPU times over all processors in the MPI network |
| 693 |
* for calculating the CPU time, or take the maximum over all processors, |
| 694 |
* depending on the value of @p output_type . See the documentation of this |
| 695 |
* class for the rationale for this constructor and an example. |
| 696 |
* |
| 697 |
* @param mpi_comm An MPI communicator across which we should accumulate or |
| 698 |
* otherwise synchronize the timing information we produce on every MPI |
| 699 |
* process. |
| 700 |
* @param stream The stream (of type std::ostream) to which output is |
| 701 |
* written. |
| 702 |
* @param output_frequency A variable indicating when output is to be |
| 703 |
* written to the given stream. |
| 704 |
* @param output_type A variable indicating what kind of timing the output |
| 705 |
* should represent (CPU or wall time). In this parallel context, when this |
| 706 |
* argument selects CPU time, then times are accumulated over all processes |
| 707 |
* participating in the MPI communicator. If this argument selects wall |
| 708 |
* time, then reported times are the maximum over all processors' run times |
| 709 |
* for this section. (The latter is computed by placing an |
| 710 |
* <code>MPI_Barrier</code> call before starting and stopping the timer for |
| 711 |
* each section. |
| 712 |
*/ |
| 713 |
TimerOutput(const MPI_Comm mpi_comm, |
| 714 |
std::ostream &stream, |
| 715 |
const OutputFrequency output_frequency, |
| 716 |
const OutputType output_type); |
| 717 |
|
| 718 |
/** |
| 719 |
* Constructor that takes an MPI communicator as input. A timer constructed |
| 720 |
* this way will sum up the CPU times over all processors in the MPI network |
| 721 |
* for calculating the CPU time, or take the maximum over all processors, |
| 722 |
* depending on the value of @p output_type . See the documentation of this |
| 723 |
* class for the rationale for this constructor and an example. |
| 724 |
* |
| 725 |
* @param mpi_comm An MPI communicator across which we should accumulate or |
| 726 |
* otherwise synchronize the timing information we produce on every MPI |
| 727 |
* process. |
| 728 |
* @param stream The stream (of type ConditionalOstream) to which output is |
| 729 |
* written. |
| 730 |
* @param output_frequency A variable indicating when output is to be |
| 731 |
* written to the given stream. |
| 732 |
* @param output_type A variable indicating what kind of timing the output |
| 733 |
* should represent (CPU or wall time). In this parallel context, when this |
| 734 |
* argument selects CPU time, then times are accumulated over all processes |
| 735 |
* participating in the MPI communicator. If this argument selects wall |
| 736 |
* time, then reported times are the maximum over all processors' run times |
| 737 |
* for this section. (The latter is computed by placing an |
| 738 |
* <code>MPI_Barrier</code> call before starting and stopping the timer for |
| 739 |
* each section.) |
| 740 |
*/ |
| 741 |
TimerOutput(const MPI_Comm mpi_comm, |
| 742 |
ConditionalOStream &stream, |
| 743 |
const OutputFrequency output_frequency, |
| 744 |
const OutputType output_type); |
| 745 |
|
| 746 |
/** |
| 747 |
* Destructor. Calls print_summary() in case the option for writing the |
| 748 |
* summary output is set. |
| 749 |
*/ |
| 750 |
~TimerOutput(); |
| 751 |
|
| 752 |
/** |
| 753 |
* Open a section by given a string name of it. In case the name already |
| 754 |
* exists, that section is entered once again and times are accumulated. |
| 755 |
*/ |
| 756 |
void |
| 757 |
enter_subsection(const std::string §ion_name); |
| 758 |
|
| 759 |
/** |
| 760 |
* Leave a section. If no name is given, the last section that was entered |
| 761 |
* is left. |
| 762 |
*/ |
| 763 |
void |
| 764 |
leave_subsection(const std::string §ion_name = ""); |
| 765 |
|
| 766 |
/** |
| 767 |
* Get a map with the collected data of the specified type for each subsection |
| 768 |
*/ |
| 769 |
std::map<std::string, double> |
| 770 |
get_summary_data(const OutputData kind) const; |
| 771 |
|
| 772 |
/** |
| 773 |
* Print a formatted table that summarizes the time consumed in the various |
| 774 |
* sections. |
| 775 |
*/ |
| 776 |
void |
| 777 |
print_summary() const; |
| 778 |
|
| 779 |
/** |
| 780 |
* Print a formatted table that summarizes the wall time consumed in the |
| 781 |
* various sections, using statistics in terms of the minimum, average, and |
| 782 |
* maximum of times in the various sections and the MPI ranks where the |
| 783 |
* minimum and maximum are attained. Note that this call only provides |
| 784 |
* useful information when the TimerOutput object is constructed without an |
| 785 |
* MPI_Comm argument, to let individual sections run without being disturbed |
| 786 |
* by barriers. |
| 787 |
* |
| 788 |
* The optional argument `quantile` allows to add two additional columns to |
| 789 |
* the output in terms of the distribution of run times. If quantile = 0.1, |
| 790 |
* the value and rank of the 10% lowest data is printed as well as the value |
| 791 |
* and rank at 90% of the distribution function, in addition to the minimum |
| 792 |
* and the maximum. The value of `quantile` needs to be between 0 (no |
| 793 |
* quantiles are printed besides the minimum and maximum) and 0.5 (when the |
| 794 |
* median is given). |
| 795 |
*/ |
| 796 |
void |
| 797 |
print_wall_time_statistics(const MPI_Comm mpi_comm, |
| 798 |
const double print_quantile = 0.) const; |
| 799 |
|
| 800 |
/** |
| 801 |
* By calling this function, all output can be disabled. This function |
| 802 |
* together with enable_output() can be useful if one wants to control the |
| 803 |
* output in a flexible way without putting a lot of <tt>if</tt> clauses in |
| 804 |
* the program. |
| 805 |
*/ |
| 806 |
void |
| 807 |
disable_output(); |
| 808 |
|
| 809 |
/** |
| 810 |
* This function re-enables output of this class if it was previously |
| 811 |
* disabled with disable_output(). This function together with |
| 812 |
* disable_output() can be useful if one wants to control the output in a |
| 813 |
* flexible way without putting a lot of <tt>if</tt> clauses in the program. |
| 814 |
*/ |
| 815 |
void |
| 816 |
enable_output(); |
| 817 |
|
| 818 |
/** |
| 819 |
* Resets the recorded timing information. |
| 820 |
*/ |
| 821 |
void |
| 822 |
reset(); |
| 823 |
|
| 824 |
private: |
| 825 |
/** |
| 826 |
* When to output information to the output stream. |
| 827 |
*/ |
| 828 |
OutputFrequency output_frequency; |
| 829 |
|
| 830 |
/** |
| 831 |
* Whether to show CPU times, wall times, or both CPU and wall times. |
| 832 |
*/ |
| 833 |
OutputType output_type; |
| 834 |
|
| 835 |
|
| 836 |
/** |
| 837 |
* A timer object for the overall run time. If we are using MPI, this timer |
| 838 |
* also accumulates over all MPI processes. |
| 839 |
*/ |
| 840 |
Timer timer_all; |
| 841 |
|
| 842 |
/** |
| 843 |
* A structure that groups all information that we collect about each of the |
| 844 |
* sections. |
| 845 |
*/ |
| 846 |
struct Section |
| 847 |
{ |
| 848 |
Timer timer; |
| 849 |
double total_cpu_time; |
| 850 |
double total_wall_time; |
| 851 |
unsigned int n_calls; |
| 852 |
}; |
| 853 |
|
| 854 |
/** |
| 855 |
* A list of all the sections and their information. |
| 856 |
*/ |
| 857 |
std::map<std::string, Section> sections; |
| 858 |
|
| 859 |
/** |
| 860 |
* The stream object to which we are to output. |
| 861 |
*/ |
| 862 |
ConditionalOStream out_stream; |
| 863 |
|
| 864 |
/** |
| 865 |
* A boolean variable that sets whether output of this class is currently on |
| 866 |
* or off. |
| 867 |
*/ |
| 868 |
bool output_is_enabled; |
| 869 |
|
| 870 |
/** |
| 871 |
* A list of the sections that have been entered and not exited. The list is |
| 872 |
* kept in the order in which sections have been entered, but elements may |
| 873 |
* be removed in the middle if an argument is given to the leave_subsection() |
| 874 |
* function. |
| 875 |
*/ |
| 876 |
std::list<std::string> active_sections; |
| 877 |
|
| 878 |
/** |
| 879 |
* mpi communicator |
| 880 |
*/ |
| 881 |
MPI_Comm mpi_communicator; |
| 882 |
|
| 883 |
/** |
| 884 |
* A lock that makes sure that this class gives reasonable results even when |
| 885 |
* used with several threads. |
| 886 |
*/ |
| 887 |
Threads::Mutex mutex; |
| 888 |
}; |
| 889 |
|
| 890 |
|
| 891 |
|
| 892 |
/* ---------------- inline functions ----------------- */ |
| 893 |
|
| 894 |
|
| 895 |
inline void |
| 896 |
Timer::restart() |
| 897 |
{ |
| 898 |
reset(); |
| 899 |
start(); |
| 900 |
} |
| 901 |
|
| 902 |
|
| 903 |
|
| 904 |
inline const Utilities::MPI::MinMaxAvg & |
| 905 |
Timer::get_last_lap_wall_time_data() const |
| 906 |
{ |
| 907 |
return last_lap_wall_time_data; |
| 908 |
} |
| 909 |
|
| 910 |
|
| 911 |
|
| 912 |
inline const Utilities::MPI::MinMaxAvg & |
| 913 |
Timer::get_accumulated_wall_time_data() const |
| 914 |
{ |
| 915 |
return accumulated_wall_time_data; |
| 916 |
} |
| 917 |
|
| 918 |
|
| 919 |
|
| 920 |
template <typename StreamType> |
| 921 |
inline void |
| 922 |
Timer::print_last_lap_wall_time_data(StreamType &stream) const |
| 923 |
{ |
| 924 |
const Utilities::MPI::MinMaxAvg &statistic = get_last_lap_wall_time_data(); |
| 925 |
stream << statistic.max << " wall," |
| 926 |
<< " max @" << statistic.max_index << ", min=" << statistic.min << " @" |
| 927 |
<< statistic.min_index << ", avg=" << statistic.avg << std::endl; |
| 928 |
} |
| 929 |
|
| 930 |
|
| 931 |
|
| 932 |
template <typename StreamType> |
| 933 |
inline void |
| 934 |
Timer::print_accumulated_wall_time_data(StreamType &stream) const |
| 935 |
{ |
| 936 |
const Utilities::MPI::MinMaxAvg &statistic = get_accumulated_wall_time_data(); |
| 937 |
stream << statistic.max << " wall," |
| 938 |
<< " max @" << statistic.max_index << ", min=" << statistic.min << " @" |
| 939 |
<< statistic.min_index << ", avg=" << statistic.avg << std::endl; |
| 940 |
} |
| 941 |
|
| 942 |
|
| 943 |
|
| 944 |
inline TimerOutput::Scope::Scope(dealii::TimerOutput &timer_, |
| 945 |
const std::string §ion_name_) |
| 946 |
: timer(timer_) |
| 947 |
, section_name(section_name_) |
| 948 |
, in(true) |
| 949 |
{ |
| 950 |
timer.enter_subsection(section_name); |
| 951 |
} |
| 952 |
|
| 953 |
|
| 954 |
|
| 955 |
inline void |
| 956 |
TimerOutput::Scope::stop() |
| 957 |
{ |
| 958 |
if (!in) |
| 959 |
return; |
| 960 |
in = false; |
| 961 |
|
| 962 |
timer.leave_subsection(section_name); |
| 963 |
} |
| 964 |
|
| 965 |
|
| 966 |
DEAL_II_NAMESPACE_CLOSE |
| 967 |
|
| 968 |
#endif |