Printer¶
MRCPP comes with a printer class to handle standard output:
#include "MRCPP/Printer"
The main purpose of this class is to provide (or suppress) any internal printing
in MRCPP routines that might be useful for debugging. Also, it provides a sane
printing environment for parallel computations that can also be used by the
host program. By using the printing routines of this class, as opposed to the
standard std::cout
, only the master thread in a OpenMP region will provide
any output while all other threads remain silent. Similarly, when running a
host program in MPI parallel, the mrcpp::Printer
provides three different
options for handling printed output (see examples below):
Only master rank prints to screen (stdout)
All ranks prints to screen (stdout)
All ranks prints to individual files
If you want only the master rank to print to an output file, this can be
achieved by redirecting the output from the first option to a file
(./program >file.out
).
-
class Printer¶
Convenience class to handle printed output.
The
Printer
singleton class holds the current state of the print environment. Allmrcpp::print
functions, as well as theprintln
andprintout
macros, take an integer print level as first argument. When the globalmrcpp::Printer
is initialized with a given print level, only print statements with a lower print level will be displayed. All internal printing in MRCPP is at print level 10 or higher, so there is some flexibility left (levels 0 through 9) for adjusting the print volume within the host program.Public Static Functions
-
static void init(int level = 0, int rank = 0, int size = 1, const char *file = nullptr)¶
Initialize print environment.
Only print statements with lower printlevel than level will be displayed. If a file name is given, each process will print to a separate file called {file}-{rank}.out. If no file name is given, only processes which initialize the printer with rank=0 will print to screen. By default, all ranks initialize with rank=0, i.e. all ranks print to screen by default.
- Parameters:
level – [in] Desired print level of output
rank – [in] MPI rank of current process
size – [in] Total number of MPI processes
file – [in] File name for printed output, will get “-{rank}.out” extension
-
static inline void setScientific()¶
Use scientific floating point notation, e.g. 1.0e-2.
-
static inline void setFixed()¶
Use fixed floating point notation, e.g. 0.01.
-
static inline int setWidth(int i)¶
Set new line width for printed output.
- Parameters:
i – [in] New width (number of characters)
- Returns:
Old width (number of characters)
-
static inline int setPrecision(int i)¶
Set new precision for floating point output.
- Parameters:
i – [in] New precision (digits after comma)
- Returns:
Old precision (digits after comma)
-
static inline int setPrintLevel(int i)¶
Set new print level.
- Parameters:
i – [in] New print level
- Returns:
Old print level
-
static inline int getWidth()¶
- Returns:
Current line width (number of characters)
-
static inline int getPrecision()¶
- Returns:
Current precision for floating point output (digits after comma)
-
static inline int getPrintLevel()¶
- Returns:
Current print level
-
static void init(int level = 0, int rank = 0, int size = 1, const char *file = nullptr)¶
Functions¶
Some convenience functions for printing output is provided within the
mrcpp::print
namespace. These functions use the data of the
mrcpp::Printer
class to provide pretty output of a few standard data types.
-
void mrcpp::print::environment(int level)¶
Print information about MRCPP version and build configuration.
- Parameters:
level – [in] Activation level for print statement
-
void mrcpp::print::separator(int level, const char &c, int newlines = 0)¶
Print a full line of a single character.
- Parameters:
level – [in] Activation level for print statement
c – [in] Character to fill the line
newlines – [in] Number of extra newlines
-
void mrcpp::print::header(int level, const std::string &txt, int newlines = 0, const char &c = '=')¶
Print a text header.
- Parameters:
level – [in] Activation level for print statement
txt – [in] Header text
newlines – [in] Number of extra newlines
c – [in] Character to fill the first line
Print a footer with elapsed wall time.
- Parameters:
level – [in] Activation level for print statement
t – [in] Timer to be evaluated
newlines – [in] Number of extra newlines
c – [in] Character to fill the last line
-
template<int D>
void mrcpp::print::tree(int level, const std::string &txt, const MWTree<D> &tree, const Timer &timer)¶ Print tree parameters (nodes, memory) and wall time.
- Parameters:
level – [in] Activation level for print statement
txt – [in] Text string
tree – [in] Tree to be printed
timer – [in] Timer to be evaluated
-
void mrcpp::print::tree(int level, const std::string &txt, int n, int m, double t)¶
Print tree parameters (nodes, memory) and wall time.
- Parameters:
level – [in] Activation level for print statement
txt – [in] Text string
n – [in] Number of tree nodes
m – [in] Memory usage (kB)
t – [in] Wall time (sec)
-
void mrcpp::print::time(int level, const std::string &txt, const Timer &timer)¶
Print elapsed time from Timer.
- Parameters:
level – [in] Activation level for print statement
txt – [in] Text string
timer – [in] Timer to be evaluated
-
void mrcpp::print::memory(int level, const std::string &txt)¶
Print the current memory usage of this process, obtained from system.
- Parameters:
level – [in] Activation level for print statement
txt – [in] Text string
Macros¶
The following macros should replace the regular calls to std::cout
:
-
println(level, STR)¶
Print text at the given print level, with newline.
-
printout(level, STR)¶
Print text at the given print level, without newline.
The following macros will print a message along with information on where you
are in the code (file name, line number and function name). Only macros that
end with _ABORT
will kill the program, all other will continue to run after
the message is printed:
-
MSG_INFO(STR)¶
Print info message.
-
MSG_WARN(STR)¶
Print warning message.
-
MSG_ERROR(STR)¶
Print error message, no abort.
-
MSG_ABORT(STR)¶
Print error message and abort.
-
INVALID_ARG_ABORT¶
You have passed an invalid argument to a function.
-
NOT_IMPLEMENTED_ABORT¶
You have reached a point in the code that is not yet implemented.
-
NOT_REACHED_ABORT¶
You have reached a point that should not be reached, bug or inconsistency.
-
NEEDS_TESTING¶
You have reached an experimental part of the code, results cannot be trusted.
-
NEEDS_FIX(STR)¶
You have hit a known bug that is yet to be fixed, results cannot be trusted.
Examples¶
Using the print level to adjust the amount of output:
int level = 10;
mrcpp::Printer::init(level); // Initialize printer with printlevel 10
println( 0, "This is printlevel 0"); // This will be displayed at printlevel 10
println(10, "This is printlevel 10"); // This will be displayed at printlevel 10
println(11, "This is printlevel 11"); // This will NOT be displayed at printlevel 10
Using headers and footers to get pretty output:
using namespace mrcpp;
Timer timer; // Start timer
project(prec, tree, func); // Project function
double integral = tree.integrate(); // Integrate function
timer.stop(); // Stop timer
print::header(0, "Projecting analytic function");
print::tree(0, "Projected function", tree, timer);
print::value(0, "Integrated function", integral, "(au)");
print::footer(0, timer);
This will produce the following output:
============================================================
Projecting analytic function
------------------------------------------------------------
Projected function 520 nds 16 MB 0.09 sec
Integrated function (au) 9.999999999992e-01
------------------------------------------------------------
Wall time: 9.32703e-02 sec
============================================================
As mentioned above, when running in MPI parallel there are three different ways
of handling printed output (master to stdout, all to stdout or all to files).
These can be chosen by adding appropriate arguments to init
. The default
setting will in a parallel environment have all MPI ranks printing to screen,
but by adding MPI info to the printer, we can separate the output of the
different ranks:
int level = 10;
int wrank, wsize;
MPI_Comm_rank(MPI_COMM_WORLD, &wrank); // Get my rank
MPI_Comm_size(MPI_COMM_WORLD, &wsize); // Get total number of ranks
// All ranks will print to screen
mrcpp::Printer::init(level);
// Only master rank will print to screen
mrcpp::Printer::init(level, wrank, wsize);
// All ranks will print to separate files called filename-<rank>.out
mrcpp::Printer::init(level, wrank, wsize, "filename");