Sierra Toolkit
Version of the Day
|
Output logging is responsible for connecting program's output streams (sierra::out(), sierra::pout(), any std::ostream) to output log files (a disk file, stdout, etc). More...
![]() |
Output logging is responsible for connecting program's output streams (sierra::out(), sierra::pout(), any std::ostream) to output log files (a disk file, stdout, etc).
Output streams are std::ostream's that the developer's write logging information to within the source code. Developers register the program's output stream using the register_ostream() functions. Log streams are files or streams which are the destinations of those output streams.
Log files each have a name and an std::ostream, and optionally a file path and std::ofstream. Developers create log files using the create_log_file() or register_log_ostream() functions. The create_log_file() function opens an std::ofstream to a file with the specified path and inserts it into the log stream map using the name as the key. The register_log_ostream() function registers a log stream using the the name as the key.
The output streams are bound to log files passing a description string to the bind_output_streams() function or by getting the streambuf's using the get_ostream_tee_streambuf() function and adding and removing streams. By binding output streams to log streams, the developer can control the destination of the data written to by any output stream. Multiple log files may be bound to the same output stream and may be bound to multiple output streams. Other registered output streams may also be destinations.
This binding feature provides the developer with a great deal of output logging control with very little programming effort.
For example, if the developer creates a normal output stream, a diagnostic output stream and a single log file, he can configure the normal output stream to go to the log file and the diagnostic output stream to go to the bit bucket. If dire circumstances should arise, the diagnostic output stream could be bound to the output stream, and from that point forward, the diagnostic data would be properly interleaved with the normal output log.
Another example for use with parallel systems, is to create a normal log file and a per-processor log file. Processor zero's (0) normal output stream writes to the normal log file and to its per-processor log file. The remaining processors each write to there per-processor log file and diagnostic streams write to the per-processor log file. This provides detailed, interleaved diagnostic for each processor for the developer to examine and normal looking output for the analyst to view.
This output logging scheme in tandem with the diagnostic writer selectable output provides the developer with significant detailed output control with minimal coding and processing overhead.
The program's output streams must be named and registered to participate in the output log binding. For general parallel use, three streams are created, a regular output stream, out; a per-processor output stream, pout; and a diagnostic output stream, dout. These can be static objects as long as they are not written to prior to main(). These three streams are registered with the output logging system at the start of the program execution.
For example, the output streams header which would be included wherever output logging is desired.
The corresponding implementation file.
And the registration in main().
The output description is defined as a white space separated string of command phrases. There are two types of command phrases, log file creation and output stream direction.
The log file creation phrase consists of a name, and equal sign (=) and a file path. The file path is opened and the log file stream is registered with the log streams.
The output stream phrase consists of a name, a greater than sign (>) and a output stream selector. The selector is a list of log streams or output streams which may be prefixed with a plus sign (+) or a minus sign (-). No prefix removes all current log and output streams from the named output stream before adding the new log or output stream. A plus prefix adds the new log or output stream to the named output stream and a minus prefix removes the log or output stream from the named output stream. Note that quotes must be used when meta-characters are included as part of a file path.
The following are examples of output stream descriptions:
logfile="sierra.log" out>logfile+pout pout>null dout>out"
out>pout pout>null dout>out"
logfile="sierra.log" plogfile="debug.log.4.0" out>logfile+pout pout>plogfile dout>out"
plogfile="debug.log.4.1" out>pout pout>plogfile dout>out"
tlogfile="testoutput.txt" tout>tlogfile
pout>-plogfile
pout>+plogfile
The following is an example of a regular output log file when running on multiple processors:
The following is an example of a regular output log file and a per-processor log file when running on multiple processors:
This section describes how to control the output logging for a sierra application and how to enable diagnostic and timer output. It also describes the use of log control to remove excess output caused by many time steps.
To get the latest command line options for a sierra application, type
The sierra applications have three command line arguments which control the log output:
The -o option defines the location and filename of the log file. The –pout option directs per-processor output to a specified set of files or standard output stream. And the –dout option directs the diagnostic writer output to a specified set of files or standard output stream.
For example:
Complementary to the output log is the diagnostic writer output. This output is enabled by a variety of command line options. The diagnostic writers allow more detailed information to be displayed during the execution. This extended log information is written to the diagnostic stream which is defined by the –dout command line option.
The diagnostic writer output can also be controlled from the input deck using:
where option-list is a command separated list of options specific for that diagnostic writer.
It is also possible to control the output of diagnostics based on time step or simulation time. When the simulation is within the specified interval, the diagnostic writer has the specified options enabled. Note that the definition of step and time is based on the regions current step and time which may not be consistent across all regions.
where name is the specific diagnostic writer, n and m are steps values, s and t are simulation times, and option-list is a comma separated list of options specific for that diagnostic writer. Here is an example list of options available to the adagio application:
There are many timers embedded within the application to assist in determining application performance. The –timer command line option activates these timers.
The input deck may also use the Enable Timer line command in the Sierra command block can be used to enable timers. Also, the Print Timer Information line command causes the timers to be printed at the specified step interval.
where timer-list is a comma separated list of timers and interval is the number steps between timer output. Accumulated displays the values since that start of the application and Checkpointed displays the values since the last interval.
Sample timers are listed below:
Since explicit codes run many time steps, only occasional output to the log file is necessary. The log control feature allows the output to appear in the log file on specified intervals or on error. The Log line command in the Sierra command block is used to specify the output interval.
When the last interval is reached or an error condition arises the output is written to the log file.