Teuchos - Trilinos Tools Package Version of the Day
Static Public Member Functions
Teuchos::TimeMonitor Class Reference

A scope-safe timer wrapper class, that can compute global timer statistics. More...

#include <Teuchos_TimeMonitor.hpp>

Inheritance diagram for Teuchos::TimeMonitor:
Teuchos::PerformanceMonitorBase< Time >

List of all members.

Public Member Functions

Constructor/Destructor
 TimeMonitor (Time &timer, bool reset=false)
 Constructor: starts the timer.
 ~TimeMonitor ()
 Destructor: stops the timer.

Static Public Member Functions

static RCP< TimegetNewTimer (const std::string &name)
 Return a new timer with the given name (class method).
static void zeroOutTimers ()
 Reset all global timers to zero.
static void computeGlobalTimerStatistics (stat_map_type &statData, std::vector< std::string > &statNames, Ptr< const Comm< int > > comm, const ECounterSetOp setOp=Intersection, const std::string &filter="")
 Compute global timer statistics for all timers on the given communicator.
static void computeGlobalTimerStatistics (stat_map_type &statData, std::vector< std::string > &statNames, const ECounterSetOp setOp=Intersection, const std::string &filter="")
 Compute global timer statistics for all timers on all (MPI) processes.
static void summarize (Ptr< const Comm< int > > comm, std::ostream &out=std::cout, const bool alwaysWriteLocal=false, const bool writeGlobalStats=true, const bool writeZeroTimers=true, const ECounterSetOp setOp=Intersection, const std::string &filter="")
 Print summary statistics for all timers on the given communicator.
static void summarize (std::ostream &out=std::cout, const bool alwaysWriteLocal=false, const bool writeGlobalStats=true, const bool writeZeroTimers=true, const ECounterSetOp setOp=Intersection, const std::string &filter="")
 Print summary statistics for all timers on all (MPI) processes.
static void report (Ptr< const Comm< int > > comm, std::ostream &out, const std::string &filter, const RCP< ParameterList > &params=null)
 Report timer statistics to the given output stream.
static void report (Ptr< const Comm< int > > comm, std::ostream &out, const RCP< ParameterList > &params=null)
 Report timer statistics to the given output stream.
static void report (std::ostream &out, const std::string &filter, const RCP< ParameterList > &params=null)
 Report timer statistics to the given output stream.
static void report (std::ostream &out, const RCP< ParameterList > &params=null)
 Report timer statistics to the given output stream.
static RCP< const ParameterListgetValidReportParameters ()
 Default parameters (with validators) for report().

Detailed Description

A scope-safe timer wrapper class, that can compute global timer statistics.

An instance of the TimeMonitor class wraps a nonconst reference to a Time timer object. TimeMonitor's constructor starts the timer, and its destructor stops the timer. This ensures scope safety of timers, so that no matter how a scope is exited (whether the normal way or when an exception is thrown), a timer started in the scope is stopped when the scope is left.

TimeMonitor also has class methods that create or destroy timers and compute global timer statistics. If you create a timer using getNewCounter() (or the deprecated getNewTimer()), it will add that timer to the set of timers for which to compute global statistics. The summarize() and report() methods will print global statistics for these timers, like the minimum, mean, and maximum time over all processes in the communicator, for each timer. These methods work correctly even if some processes have different timers than other processes. You may also use computeGlobalTimerStatistics() to compute the same global statistics, if you wish to use them in your program or output them in a different format than that of these methods.

Warning:
This class must only be used to time functions that are called only within the main program. It may _not_ be used in pre-program setup or post-program teardown!
Examples:

TimeMonitor/cxx_main.cpp.

Definition at line 164 of file Teuchos_TimeMonitor.hpp.


Constructor & Destructor Documentation

Teuchos::TimeMonitor::TimeMonitor ( Time timer,
bool  reset = false 
)

Constructor: starts the timer.

Parameters:
timer[in/out] Reference to the timer to be wrapped. This constructor starts the timer, and the destructor stops the timer.
reset[in] If true, reset the timer before starting it. Default behavior is not to reset the timer.

Definition at line 209 of file Teuchos_TimeMonitor.cpp.

Teuchos::TimeMonitor::~TimeMonitor ( )

Destructor: stops the timer.

Definition at line 215 of file Teuchos_TimeMonitor.cpp.


Member Function Documentation

static RCP<Time> Teuchos::TimeMonitor::getNewTimer ( const std::string &  name) [inline, static]

Return a new timer with the given name (class method).

Call getNewCounter() or this method if you want to create a new named timer, and you would like TimeMonitor to track the timer for later computation of global statistics over processes.

This method wraps getNewCounter() (inherited from the base class) for backwards compatibiity.

Definition at line 193 of file Teuchos_TimeMonitor.hpp.

void Teuchos::TimeMonitor::zeroOutTimers ( ) [static]

Reset all global timers to zero.

This method only affects Time objects created by getNewCounter() or getNewTimer().

Precondition:
None of the timers must currently be running.

Definition at line 220 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::computeGlobalTimerStatistics ( stat_map_type statData,
std::vector< std::string > &  statNames,
Ptr< const Comm< int > >  comm,
const ECounterSetOp  setOp = Intersection,
const std::string &  filter = "" 
) [static]

Compute global timer statistics for all timers on the given communicator.

The typical use case for Time and TimeMonitor is that all processes in a communicator create the same set of timers, and then want to report summary statistics. This method supports that typical use case. For each timer in the set, this method computes a list of global statistics. "Global" means "for all processes in the communicator." "Statistic" means the result of a reduction over the timing and call count values. Thus, each statistic includes both a timing and a call count. The current list of computed statistics includes the minimum and maximum timing (and the corresponding call count for each) and the arithmetic mean (timing and call count). This list may expand in the future.

Different processes may have different sets of timers. This method gives you two options for reconciling the sets. If setOp is Intersection, it computes the intersection (the common subset) of timers on all processes in the communicator. Otherwise, if setOp is Union, this method computes the union of timers on all processes in the communicator. Intersection is the default, since it means that all reported timers exist on all participating processes. For setOp=Union, timers that do not exist on some processes will be given a zero timing and call count, so that statistics make sense.

Note:
This method must called as a collective by all processes in the communicator.

All output arguments are returned redundantly on all processes in the communicator. That makes this method an all-reduce.

Statistics collected

The "MinOverProcs" and "MaxOverProcs" timings are cumulative: the reported timing is for all calls. Along with the min resp. max timing comes the call count of the process who had the min resp. max. (If more than one process had the min resp. max timing, then the call count on the process with the smallest rank is reported.)

The "MeanOverProcs" equals the sum of the processes' cumulative timings, divided by the number of processes. Thus, it is cumulative over all calls, and is comparable with the "MinOverProcs" and "MaxOverProcs" timings. This differs from the "MeanOverCallCounts" (see below). This does not weight the mean by call counts.

The "MeanOverCallCounts" is an arithmetic mean of all timings. It is not cumulative. It reports the mean timing for a single invocation over all calls on all processes, not weighting any one process more than the others. For each timer, this is the sum of the cumulative timing over all processes, divided by the sum of the call counts over all processes for that timing. (We compute it a bit differently to help prevent overflow.) The "MeanOverCallCounts" is not comparable with the min, max, or "MeanOverProcs".

We report with both versions of the mean timing the mean call count over processes. This may be fractional, which is one reason why we report call counts as double rather than int. It has no particular connection to the mean timing.

Performance

This operation requires interprocess communication. Suppose there are $P$ processes in the given communicator, and $N$ unique timers in the global union of all processes' timers. Then, this method requires $O(\log P)$ messages ( $O(1)$ "reductions" and exactly 1 "broadcast") and $O(N)$ per-processor storage (in the worst case) when computing either the intersection or the union of timers (the algorithm is similar in either case). The whole algorithm takes at worst $O(N (\log N) (\log P))$ time along the critical path (i.e., on the "slowest process" in the communicator). The $N \log N$ term comes from sorting the timers by label at each stage of the reduction in order to compute their union or intersection.

Parameters:
statData[out] On output: Global timer statistics, stored as a map with key timer name, and with value the ordered list of statistics for that timer. The statNames output has the same order as the ordered list of statistics for each timer. Each entry of the statistics list is a (timing, call count) pair, the meaning of which depends on the particular statistic (see above).
statNames[out] On output: Each value in the statData map is a vector. That vector v has the same number of entries as statNames. statNames[k] is the name of the statistic (see above) stored as v[k]. Always refer to statNames for the number and names of statistics.
comm[in] Communicator whose process(es) will participate in the gathering of timer statistics. This is a Ptr and not an RCP, because RCP would suggest that TimeMonitor were keeping the communicator around after return of this method. Ptr suggests instead that TimeMonitor will only reference the communicator during this method. If you have an RCP, you can turn it into a Ptr by calling its ptr() method:
   RCP<const Comm<int> > myComm = ...;
   TimeMonitor::computeGlobalTimerStatistics (statData, statNames, myComm.ptr());
setOp[in] If Intersection, compute statistics for the intersection of all created timers over all processes in the communicator. If Union, compute statistics for the union of all created timers over all processes in the communicator.
filter[in] Filter for timer labels. If filter is not empty, this method will only compute statistics for timers whose labels begin with this string.

Definition at line 754 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::computeGlobalTimerStatistics ( stat_map_type statData,
std::vector< std::string > &  statNames,
const ECounterSetOp  setOp = Intersection,
const std::string &  filter = "" 
) [static]

Compute global timer statistics for all timers on all (MPI) processes.

This is an overload of the above computeGlobalTimerStatistics() method for when the caller does not want to provide a communicator explicitly. This method "does the right thing" in that case. Specifically:

  • If Trilinos was not built with MPI support, this method assumes a serial "communicator" containing one process.
  • If Trilinos was built with MPI support and MPI has been initialized (via MPI_Init() or one of the wrappers in Epetra or Teuchos), this method uses MPI_COMM_WORLD as the communicator. This is the most common case.
  • If Trilinos was built with MPI support and MPI has not been initialized, this method will use a "serial" communicator (that does not actually use MPI). This may produce output on all the MPI processes if you are running with Trilinos as an MPI job with more than one process. Thus, if you intend to use this method in parallel, you should first initialize MPI. (We cannot initialize MPI for you, because we have no way to know whether you intend to run an MPI-enabled build serially.)
Warning:
If you call this method when MPI is running, you must call it on all processes in MPI_COMM_WORLD. Otherwise, the method will never finish, since it will be waiting forever for the non-participating processes. If you want to use computeGlobalTimerStatistics() on a subcommunicator, please use the overloaded version above that takes a communicator as an input argument.

Definition at line 958 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::summarize ( Ptr< const Comm< int > >  comm,
std::ostream &  out = std::cout,
const bool  alwaysWriteLocal = false,
const bool  writeGlobalStats = true,
const bool  writeZeroTimers = true,
const ECounterSetOp  setOp = Intersection,
const std::string &  filter = "" 
) [static]

Print summary statistics for all timers on the given communicator.

If writeGlobalStatus=true, this method computes the same statistics as computeGlobalTimerStatistics(), using the same collective algorithm. (writeGlobalStatus=false means that only the process with rank 0 in the communicator reports its timers' data.) It then reports the results to the given output stream on the process with rank 0 in the given communicator. Output follows a human-readable tabular form.

Parameters:
comm[in] Communicator whose process(es) will participate in the gathering of timer statistics. This is a Ptr and not an RCP, because RCP would suggest that TimeMonitor were keeping the communicator around after return of this method. Ptr suggests instead that TimeMonitor will only reference the communicator during this method. If you have an RCP, you can turn it into a Ptr by calling its ptr() method:
   RCP<const Comm<int> > myComm = ...;
   TimeMonitor::summarize (myComm.ptr());
out[out] Output stream to which to write. This will only be used on the process with rank 0 in the communicator.
alwaysWriteLocal[in] If true, the process with Rank 0 in the communicator will write its local timings to the given output stream. Defaults to false, since the global statistics are more meaningful. If the local set of timers differs from the global set of timers (either the union or the intersection, depending on setOp), Proc 0 will create corresponding local timer data (not corresponding timers) with zero elapsed times and call counts, just to pad the table of output.
writeGlobalStats[in] If true (the default), compute and display the statistics that computeGlobalTimerStatistics() computes. If there is only one MPI process or if this is a non-MPI build of Trilinos, only compute and show the "global" timings, without the "statistics" that would be all the same anyway.
writeZeroTimers[in] If false, do not display results for timers that have never been called (numCalls() == 0). If true, display results for all timers, regardless of their call count. Note that setOp and writeGlobalStats might reintroduce timers with zero call counts.
setOp[in] If Intersection, compute and display the intersection of all created timers over all processes in the communicator. If Union, compute and display the union of all created timers over all processes in the communicator.
filter[in] Filter for timer labels. If filter is not empty, this method will only print timers whose labels begin with this string.
Note:
If writeGlobalStats is true, this method must be called as a collective by all processes in the communicator. This method will only perform communication if writeGlobalStats is true.
Examples:
TimeMonitor/cxx_main.cpp.

Definition at line 783 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::summarize ( std::ostream &  out = std::cout,
const bool  alwaysWriteLocal = false,
const bool  writeGlobalStats = true,
const bool  writeZeroTimers = true,
const ECounterSetOp  setOp = Intersection,
const std::string &  filter = "" 
) [static]

Print summary statistics for all timers on all (MPI) processes.

This is an overload of the above summarize() method for when the caller does not want to provide a communicator explicitly. This method "does the right thing" in that case. For an explanation of what that means, see the documentation of the overload of computeGlobalTimerStatistics() that does not require a communicator argument.

Warning:
If you call this method when MPI is running, you must call it on all processes in MPI_COMM_WORLD. Otherwise, the method will never finish, since it will be waiting forever for the non-participating processes. If you want to use summarize() on a subcommunicator, please use the overloaded version above that takes a communicator as an input argument.

Definition at line 941 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::report ( Ptr< const Comm< int > >  comm,
std::ostream &  out,
const std::string &  filter,
const RCP< ParameterList > &  params = null 
) [static]

Report timer statistics to the given output stream.

This is like summarize(), but gives you more control over the output format. To get the default parameters, either call getValidReportParameters(), or call this method with params nonnull but empty (it will fill in default parameters).

Parameters:
comm[in] Communicator whose process(es) will participate in the gathering of timer statistics. This is a Ptr and not an RCP, because RCP would suggest that TimeMonitor were keeping the communicator around after return of this method. Ptr suggests instead that TimeMonitor will only reference the communicator during this method. If you have an RCP, you can turn it into a Ptr by calling its ptr() method:
   RCP<const Comm<int> > myComm = ...;
   TimeMonitor::report (myComm.ptr (), ...);
out[out] Output stream to which to write. This will only be used on the process with rank 0 in the communicator.
filter[in] Filter for timer labels. If filter is not empty, this method will only print timers whose labels begin with this string.
params[in/out] Parameters to control output format and which statistics to generate. If null, we use default parameters if this method was not yet called with params nonnull, otherwise we use the previous set of parameters. If nonnull, we read the given parameters, filling in defaults, and use the resulting parameters for all subsequent calls to report() (until new parameters are set).

Supported parameters

Here is the current set of supported parameters:

  • "Report format": "Table" (default), "YAML"
  • "YAML style": "spacious" (default), "compact"
  • "How to merge timer sets": "Intersection" (default), "Union"
  • "alwaysWriteLocal": true, false (default)
  • "writeGlobalStats": true (default), false
  • "writeZeroTimers": true (default), false

This method currently supports two different output formats. "Table" format is the same tabular format which summarize() uses. It displays times and call counts in a table that is easy for humans to read, but hard to parse. "YAML" format uses a standard, structured, human-readable output format called YAML. YAML stands for YAML Ain't Markup Language.

"YAML style" refers to two variants of YAML output that report() can generate. The "compact" mode attempts to put as much data on each line as possible. It may be more readable when there are a small number of timers. The "spacious" mode prefers one line per datum whenever possible. Both modes have the same schema, that is, their output has the same hierarchical structure and thus the same parse tree.

(In technical terms: compact mode uses YAML's so-called "flow style" for sequences and mappings whenever possible, except at the outermost level where it would hinder readability. Spacious mode does not use "flow style" for lists or mappings. For an explanation of YAML's flow style, see Chapter 7 of the YAML 1.2 spec.)

"How to merge timer sets" refers to the set operation by which processors should combine their sets of timers in order to compute global timer statistics. This corresponds to the setOp argument of summarize().

The remaining Boolean parameters are the same as the eponymous arguments of summarize(), to whose documentation one should refer. There are some wrinkles: in particular, YAML output ignores the "alwaysWriteLocal" parameter and assumes "writeGlobalStats" is true.

Definition at line 1407 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::report ( Ptr< const Comm< int > >  comm,
std::ostream &  out,
const RCP< ParameterList > &  params = null 
) [static]

Report timer statistics to the given output stream.

This is like the 4-argument version of report(), but with a default filter.

Definition at line 1430 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::report ( std::ostream &  out,
const std::string &  filter,
const RCP< ParameterList > &  params = null 
) [static]

Report timer statistics to the given output stream.

This is like the 4-argument version of report(), but with a default communicator.

Definition at line 1438 of file Teuchos_TimeMonitor.cpp.

void Teuchos::TimeMonitor::report ( std::ostream &  out,
const RCP< ParameterList > &  params = null 
) [static]

Report timer statistics to the given output stream.

This is like the 4-argument version of report(), but with a default communicator and a default filter.

Definition at line 1447 of file Teuchos_TimeMonitor.cpp.

RCP< const ParameterList > Teuchos::TimeMonitor::getValidReportParameters ( ) [static]

Default parameters (with validators) for report().

Definition at line 1341 of file Teuchos_TimeMonitor.cpp.


The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines