Debian Codegraph @

include/deal.II/base/timer.h

raw
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 &section_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 &section_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 &section_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 &section_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