Teuchos  Trilinos Tools Package Version of the Day

A scopesafe timer wrapper class. More...
#include <Teuchos_TimeMonitor.hpp>
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 functions  
static RCP< Time >  getNewTimer (const std::string &name) 
Return a new timer with the given name.  
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) 
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) 
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) 
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) 
Print summary statistics for all timers on all (MPI) processes. 
A scopesafe timer wrapper class.
This class wraps a nonconst reference to a Teuchos::Time
timer object. The 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.
This class also keeps track of the set of all timers as class (not instance) data, and has a class method (summarize()
) for printing out global statistics (min, mean, and max over all MPI processes, in an MPI build). The summarize()
method works correctly even if some MPI processes have different timers than other processes.
Teuchos::Time
class internally. Definition at line 159 of file Teuchos_TimeMonitor.hpp.
Teuchos::TimeMonitor::TimeMonitor  (  Time &  timer, 
bool  reset = false 

) 
Constructor: starts the timer.
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 202 of file Teuchos_TimeMonitor.cpp.
Teuchos::TimeMonitor::~TimeMonitor  (  ) 
Destructor: stops the timer.
Definition at line 208 of file Teuchos_TimeMonitor.cpp.
Return a new timer with the given name.
This method wraps getNewCounter()
(inherited from the base class) for backwards compatibiity.
Definition at line 187 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()
.
Preconditions:
Definition at line 213 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 

)  [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.
Suppose there are processes in the communicator and unique timers in the global union. This method requires messages ( "reductions" and exactly 1 "broadcast") and perprocessor 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 time along the critical path (i.e., on the "slowest process" in the communicator).
The "Min" and "Max" 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 "Mean" is an arithmetic mean of all timings. It is not cumulative over call counts; it reports an average timing for a single invocation over all calls on all processes, not weighting any one process more than the others. Thus, the mean is not comparable with the min or max. To make it comparable, multiply the mean timing by the mean call count, and divide by the number of processes in the communicator. This makes the mean cumulative.
The mean for each timer equals 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.) Along with the mean timing comes the aritmetic mean of the call counts. 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.
All output arguments are returned redundantly on all processes in the communicator. That makes this method an allreduce.
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 (e.g., "Min", "Mean", or "Max") 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. 
Definition at line 689 of file Teuchos_TimeMonitor.cpp.
void Teuchos::TimeMonitor::computeGlobalTimerStatistics  (  stat_map_type &  statData, 
std::vector< std::string > &  statNames,  
const ECounterSetOp  setOp = Intersection 

)  [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:
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.MPI_COMM_WORLD
. Otherwise, the method will never finish, since it will be waiting forever for the nonparticipating 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 886 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 

)  [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 humanreadable tabular form.
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 min, average (arithmetic mean), and max of all timings over all processes in the communicator. If there is only one MPI process or if this is a nonMPI build of Trilinos, we only 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. 
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. Definition at line 715 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 

)  [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.
MPI_COMM_WORLD
. Otherwise, the method will never finish, since it will be waiting forever for the nonparticipating 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 870 of file Teuchos_TimeMonitor.cpp.