Diffpack Documentation

Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Search  

MultipleReporter Class Reference

automatic generation of 7 report formats in simulators. More...

#include <MultipleReporter.h>

Inheritance diagram for MultipleReporter::

HandleId List of all members.

Public Methods

 MultipleReporter ()
 ~MultipleReporter ()
virtual bool ok () const
virtual void open ()
virtual void open (const String &filename)
virtual MultipleReporter& header (const String &title, const String &author, bool fullpage=true, bool singlefile=true, const char *purpose=NULL)
virtual MultipleReporter& trailer ()
virtual String getSectionRef ()
virtual MultipleReporter& section (const String &txt)
virtual MultipleReporter& subsection (const String &txt)
virtual MultipleReporter& section (const String &txt, const String &label)
virtual MultipleReporter& subsection (const String &txt, const String &label)
virtual MultipleReporter& subsubsection (const String &txt)
virtual MultipleReporter& subsubsection (const String &txt, const String &label)
virtual MultipleReporter& multipleLoopSection (int run_no, const char *heading=NULL)
virtual MultipleReporter& multipleLoopSection (int run_no, MenuSystem &menu, const char *heading=NULL)
virtual MultipleReporter& pagebreak ()
virtual MultipleReporter& linebreak ()
virtual MultipleReporter& eject (int n=1)
virtual MultipleReporter& drawline ()
virtual MultipleReporter& putLabel (const String &label)
virtual MultipleReporter& putReference (const String &label)
virtual MultipleReporter& putReference (const String &label, const String &document)
virtual MultipleReporter& flush ()
virtual MultipleReporter& beginGroup (TextStyle style)
virtual MultipleReporter& endGroup ()
virtual String getGroup (const String &txt, TextStyle style)
virtual String cellpad (const String &s)
virtual String adaptString (const String &txt)
virtual MultipleReporter& insert (const String &txt)
virtual MultipleReporter& put (const String &txt)
virtual MultipleReporter& putmathline (const String &txt)
virtual MultipleReporter& centerline (const String &txt)
virtual MultipleReporter& insertDocument (const String &basename)
virtual MultipleReporter& insertVerbatim (const String &file)
virtual MultipleReporter& put (ArrayGenSimple(String) &tb)
virtual MultipleReporter& put (ArrayGenSimple(real) &tb)
virtual MultipleReporter& put (ArrayGenSimple(real) &tb, const String &cell_format)
virtual MultipleReporter& put (ArrayGenSimple(real) &tb, ArrayGenSimple(String) &cell_format)
virtual MultipleReporter& beginCenter ()
virtual MultipleReporter& endCenter ()
virtual MultipleReporter& beginTabular (int ncols, const String &col_format)
virtual MultipleReporter& endTabular ()
virtual MultipleReporter& beginTable (int ncols, const String &col_format)
virtual MultipleReporter& endTable (const String &caption, const String &label)
virtual MultipleReporter& beginItemize ()
virtual MultipleReporter& endItemize ()
virtual MultipleReporter& beginEnumerate ()
virtual MultipleReporter& endEnumerate ()
virtual MultipleReporter& beginFigure (const String &psfilename, real cmWidth=10.0)
virtual MultipleReporter& endFigure (const String &caption, const String &label)
virtual MultipleReporter& beginDispmath ()
virtual MultipleReporter& endDispmath ()
virtual String makeLabelRef (const String &label)
virtual String getCurrPlotDir ()
virtual MultipleReporter& figure (const String &psfilename, const String &caption, const String &label, real cmWidth=10.0)
virtual MultipleReporter& figure (const Strings &psfilename, const Strings &caption, const String &common_caption, const Strings &label, real cmWidth=10.0)
virtual MultipleReporter& setFigureCollectMode (bool mode)
virtual MultipleReporter& dumpMultipleFigures ()
virtual MultipleReporter& dumpPlotCmd (const StringList &command)
virtual MultipleReporter& displaymath (const String &txt)
virtual void specialTextASCII (const String &txt)
virtual void specialTextLaTeX (const String &txt)
virtual void specialTextHTML (const String &txt)
virtual void process (bool postscript=true)
virtual void print (bool postscript=true)
virtual void preview (bool postscript=true)
virtual void setSummaryTableLineLength (int max_chars)
virtual void putSummaryTable (ArrayGenSimple(String) &table)
virtual void putSummaryHeading (const String &title, const String &author, const Strings &headings, bool fullpage=true, bool singlefile=true)
virtual void putSummary4oneSim (const Strings &results, int icomb)
virtual void endSummary ()

Public Attributes

Handle(Reporter) full_latex
Handle(Reporter) full_ascii
Handle(Reporter) full_html
Handle(Reporter) sum_latex
Handle(Reporter) sum_ascii
Handle(Reporter) sum_html
Os sum_data

Protected Attributes

String filename
int max_char_pr_summary_line
bool open_files
String purpose
bool figure_collect_mode
StringList psfilename_list
StringList caption_list
StringList label_list
real max_cmWidth
int psfilename_counter
ArrayGenSimple(String) summary_page
int i_summary_column
Strings summary_heading

Detailed Description

automatic generation of 7 report formats in simulators.

NAME: MultipleReporter - automatic generation of 7 report formats in simulators

DESCRIPTION:

Class "MultipleReporter" is an extension of class "Reporter". Instead of generating one report in a specified format, class "MultipleReporter" generates three report formats automatically: ASCII, `\`LaTeX`\` and HTML. The interface is identical to class "Reporter" (with the exception of a couple of additional features). The purpose of generating three formats simultaneously is to produce a professionally typeset report in `\`LaTeX`\` and at the same time allow the user to investigate simulation results using tools like Mosaic and Unix text manipulation programs (perl, awk, sed, grep).

This type of reports are normally generated when the menu system is used for executing a large number of simulations (the so called "multiple loop" feature). Therefore the reports tend to be very long, and it may be very difficult to extract the most important information. To solve this practical problem, class "MultipleReporter" is equipped with an additional feature, namely the generation of a summary report. The summary is essentially compact tables where each column corresponds to a single execution of the simulator (or in other words, one single input parameter combination). The summary is also written in various formats: ASCII, `\`LaTeX, HTML and table. The latter format is aimed at input files for post-processing procedures like curve fitting in statistical software etc.

The normal use of class "MultipleReporter" thus results in seven reports: Three so called full reports and four summary reports. The user will study the summaries for general trends and look up in the full reports to investigate the details of particularly interesting runs. `\`LaTeX`\` summary reports are the easiest to read on paper, HTML reports are useful for moving around in the report -- using Mosaic one can find an interesting run in the summary, click on that table column and then move directly into the full report for more information, including figures, on that particular execution.

The example in class "CDFEM2" presented in Report NO:97-11, "Diffpack Tools for Automatic Generation of Result Reports" by A.M. Bruaset, should be sufficient to see how the "MultipleReporter" is used in a practical problem. Together with the documentation of all the member functions (this documentation is given in class "Reporter" and the cited document), this is a good starting point for developing automatic report generation in other applications.

In case one has a class hierarchy with the simulator as base class, it may be advantageous to let the items in the summary report differ among the subclasses. The simulator base class can then declare virtual functions "defineSummaryHeading" and "resultSummary". The former adds names of the subclass' result or input items to the summary, and the latter adds the class' results to the summary. In "openReport" in the simulator class, one writes the header of the "MultipleReporter", defines some general summary items and then calls the virtual function "defineSummaryHeading" such that the subclass can add its names of the table headings. In "resultReport" one reports the general results, e.g., convergence and efficiency of equation solvers, and calls "resultSummary" so that the simulator in question can report its special results.

"MultipleReporter" is in a sense a "Reporter", but it also has six reporters. We have decided not to derive it from "Reporter". If you tend to mix "Reporter" and "MultipleReporter" in programs and should desire writing functions that could work for both classes, stick to "MultipleReporter" since it is the most general class of the two.

If one has a mathematical model and its numerical solution implemented as a class X, it is a Diffpack standard to derive a class ReportX where the "MultipleReporter" details are implemented. There is a convenient script "MkReport" that can be run to automatically generate a definition of the new class. Just write "MkReport X". The file "ReportX.cpp" will contain several examples on how to write to the report, how to let other classes write to the report and how to produce and include plots in the report.

Constructor & Destructor Documentation

MultipleReporter::MultipleReporter ( )
 

The constructor takes no argument and opens reports with filenames based on the casename (in other words, this constructor just call "open", see below). This is sufficient initialization of the full reports.

MultipleReporter::~MultipleReporter ( )
 

Member Function Documentation

String MultipleReporter::adaptString ( const String & txt ) [virtual]
 

MultipleReporter & MultipleReporter::beginCenter ( ) [virtual]
 

MultipleReporter & MultipleReporter::beginDispmath ( ) [virtual]
 

MultipleReporter & MultipleReporter::beginEnumerate ( ) [virtual]
 

MultipleReporter & MultipleReporter::beginFigure ( const String & psfilename,
real cmWidth = 10.0 ) [virtual]
 

MultipleReporter & MultipleReporter::beginGroup ( TextStyle style ) [virtual]
 

MultipleReporter & MultipleReporter::beginItemize ( ) [virtual]
 

MultipleReporter & MultipleReporter::beginTable ( int ncols,
const String & col_format ) [virtual]
 

MultipleReporter & MultipleReporter::beginTabular ( int ncols,
const String & col_format ) [virtual]
 

String MultipleReporter::cellpad ( const String & s ) [virtual]
 

MultipleReporter & MultipleReporter::centerline ( const String & txt ) [virtual]
 

MultipleReporter & MultipleReporter::displaymath ( const String & txt ) [virtual]
 

MultipleReporter & MultipleReporter::drawline ( ) [virtual]
 

MultipleReporter & MultipleReporter::dumpMultipleFigures ( ) [virtual]
 

see "setFigureCollectMode".

MultipleReporter & MultipleReporter::dumpPlotCmd ( const StringList & command ) [virtual]
 

this functions lists the various commands used to create a plot. The list is typeset using the "beginItemize" and "endItemize" functions. The argument to the function is a list of command strings. It is assumed that the first item in this list is some kind of heading for the plot commands, e.g., ``plot of the "p" field:''. The plot commands written by this function will only appear in the HTML file.

MultipleReporter & MultipleReporter::eject ( int n = 1 ) [virtual]
 

MultipleReporter & MultipleReporter::endCenter ( ) [virtual]
 

MultipleReporter & MultipleReporter::endDispmath ( ) [virtual]
 

MultipleReporter & MultipleReporter::endEnumerate ( ) [virtual]
 

MultipleReporter & MultipleReporter::endFigure ( const String & caption,
const String & label ) [virtual]
 

MultipleReporter & MultipleReporter::endGroup ( ) [virtual]
 

MultipleReporter & MultipleReporter::endItemize ( ) [virtual]
 

void MultipleReporter::endSummary ( ) [virtual]
 

MultipleReporter & MultipleReporter::endTable ( const String & caption,
const String & label ) [virtual]
 

MultipleReporter & MultipleReporter::endTabular ( ) [virtual]
 

MultipleReporter & MultipleReporter::figure ( const Strings & psfilename,
const Strings & caption,
const String & common_caption,
const Strings & label,
real cmWidth = 10.0 ) [virtual]
 

MultipleReporter & MultipleReporter::figure ( const String & psfilename,
const String & caption,
const String & label,
real cmWidth = 10.0 ) [virtual]
 

MultipleReporter & MultipleReporter::flush ( ) [virtual]
 

String MultipleReporter::getCurrPlotDir ( ) [virtual]
 

String MultipleReporter::getGroup ( const String & txt,
TextStyle style ) [virtual]
 

String MultipleReporter::getSectionRef ( ) [virtual]
 

MultipleReporter & MultipleReporter::header ( const String & title,
const String & author,
bool fullpage = true,
bool singlefile = true,
const char * purpose = NULL ) [virtual]
 

this function has an optional argument "purpose" that behaves differently from the same argument in "Reporter header". If "purpose" is a "NULL" pointer, no purpose comment is written in the reports. However, "MultipleReporter header" treats a non-"NULL" pointer that points to an empty string """" also as a "NULL" pointer when calling the relvant "Reporter header" functions. That is, when calling "MultipleReporter header", "purpose" can either be "NULL" or "s.c_str()", where "s" is an empty string, in order to avoid a comment in the header about the purpose of the report. By default no such comment will be generated.

MultipleReporter & MultipleReporter::insert ( const String & txt ) [virtual]
 

MultipleReporter & MultipleReporter::insertDocument ( const String & basename ) [virtual]
 

MultipleReporter & MultipleReporter::insertVerbatim ( const String & file ) [virtual]
 

MultipleReporter & MultipleReporter::linebreak ( ) [virtual]
 

String MultipleReporter::makeLabelRef ( const String & label ) [virtual]
 

MultipleReporter & MultipleReporter::multipleLoopSection ( int run_no,
MenuSystem & menu,
const char * heading = NULL ) [virtual]
 

See documentation of one of the overloaded functions.

MultipleReporter & MultipleReporter::multipleLoopSection ( int run_no,
const char * heading = NULL ) [virtual]
 

a version of "section" aimed at multiple loops under the menu system. This is the normal "section"-type function to be used in the "resultReport" functions in simulators. The overloaded function that also takes a "MenuSystem" argument will add a subsection containing the menu items that have been varied in the multiple loop. This is convenient for stand-alone solvers, but not when solvers are combined into a simulator for a system of PDEs. In those cases one should remove the "MenuSystem" argument from the call and instead add a call to "MenuSystem writeExtendedResults4multipleAnswers" in the "resultReport" of the administiring class, before the "writeExtendedResults" of each simulator is called.

bool MultipleReporter::ok ( ) const [virtual]
 

void MultipleReporter::open ( const String & filename ) [virtual]
 

See documentation of one of the overloaded functions.

void MultipleReporter::open ( ) [virtual]
 

opens the files associated with a report. This function must be called explicitly by the programmer, thus providing full control of the handling of reporter files in a simulator. If the class utilizing "MultipleReporter" is used in a wider context, it may be advantegous to use another "MultipleReporter" object and just let the class write to this object instead of using its own "MultipleReporter". Avoiding the automatic call to "open" then makes it possible for the class to avoid generating empty report files. There are two versions of "open", the one without arguments opens files with the current casename as filename stem, the other version takes a filename as argument.

MultipleReporter & MultipleReporter::pagebreak ( ) [virtual]
 

void MultipleReporter::preview ( bool postscript = true ) [virtual]
 

void MultipleReporter::print ( bool postscript = true ) [virtual]
 

void MultipleReporter::process ( bool postscript = true ) [virtual]
 

MultipleReporter & MultipleReporter::put ( ArrayGenSimple(real) & tb,
ArrayGenSimple(String) & cell_format ) [virtual]
 

MultipleReporter & MultipleReporter::put ( ArrayGenSimple(real) & tb,
const String & cell_format ) [virtual]
 

MultipleReporter & MultipleReporter::put ( ArrayGenSimple(real) & tb ) [virtual]
 

MultipleReporter & MultipleReporter::put ( ArrayGenSimple(String) & tb ) [virtual]
 

MultipleReporter & MultipleReporter::put ( const String & txt ) [virtual]
 

MultipleReporter & MultipleReporter::putLabel ( const String & label ) [virtual]
 

MultipleReporter & MultipleReporter::putReference ( const String & label,
const String & document ) [virtual]
 

MultipleReporter & MultipleReporter::putReference ( const String & label ) [virtual]
 

void MultipleReporter::putSummary4oneSim ( const Strings & results,
int icomb ) [virtual]
 

adds the results from one simulation to the summary tables. The "icomb" parameter reflects the so called run number, i.e., the current input data combination number, or equivalently, the current iteration number in the multiple loop.

void MultipleReporter::putSummaryHeading ( const String & title,
const String & author,
const Strings & headings,
bool fullpage = true,
bool singlefile = true ) [virtual]
 

opens summary reports. A title for each result item in the summary report must be given to the constructor. Summary reports are used for compact summary of results from multiple executions by the menu system.

void MultipleReporter::putSummaryTable ( ArrayGenSimple(String) & table ) [virtual]
 

MultipleReporter & MultipleReporter::putmathline ( const String & txt ) [virtual]
 

MultipleReporter & MultipleReporter::section ( const String & txt,
const String & label ) [virtual]
 

MultipleReporter & MultipleReporter::section ( const String & txt ) [virtual]
 

MultipleReporter & MultipleReporter::setFigureCollectMode ( bool mode ) [virtual]
 

if the argument is true, calls to figure (the version with one PostScript file and one caption) may result in a collection of several PostScript files in one figure environment. For `\`LaTeX`\` this saves a lot of pages, while for HTML it has no visible effect because the collect mode is ignored and figures are put where they are defined. One can dump the buffer of figures by calling "dumpMultipleFigures", but this dump is also performed when "figure" decides that there are enough figures in one environment (that is, one page).

void MultipleReporter::setSummaryTableLineLength ( int max_chars ) [virtual]
 

sets the number of characters in each line in the summary tables. If the summary tables tend to be too wide or too narrow, try to alter the parameter to this function.

void MultipleReporter::specialTextASCII ( const String & txt ) [virtual]
 

void MultipleReporter::specialTextHTML ( const String & txt ) [virtual]
 

writes the text argument only to the HTML report. This is well suited for making hyperlinks to other documents -- this is information that should be ignored in ASCII and `\`LaTeX`\` reports. Similar functions "specialTextLaTeX" and "specialTextASCII" are included for the other two formats as well. Here is an example on using "specialTextHTML" to insert a link to an mpeg movie in a document (note that the movie itself can be generated after the program is finished, as long as it is done before the report is loaded in an HTML browser). 

     // given a MultipleReporter rep
     // and a String movie1file, containing the name of the mpeg file

     rep.specialTextHTML 
       (aform("\n\n<P><P>Movie 1 is shown <A HREF=\"%s\">here.</A><P><P>\n\n",

           movie1file.c_str()));

void MultipleReporter::specialTextLaTeX ( const String & txt ) [virtual]
 

MultipleReporter & MultipleReporter::subsection ( const String & txt,
const String & label ) [virtual]
 

MultipleReporter & MultipleReporter::subsection ( const String & txt ) [virtual]
 

MultipleReporter & MultipleReporter::subsubsection ( const String & txt,
const String & label ) [virtual]
 

MultipleReporter & MultipleReporter::subsubsection ( const String & txt ) [virtual]
 

MultipleReporter & MultipleReporter::trailer ( ) [virtual]
 

Member Data Documentation

StringList MultipleReporter::caption_list [protected]
 

bool MultipleReporter::figure_collect_mode [protected]
 

String MultipleReporter::filename [protected]
 

Handle(Reporter) MultipleReporter::full_ascii
 

Handle(Reporter) MultipleReporter::full_html
 

Handle(Reporter) MultipleReporter::full_latex
 

int MultipleReporter::i_summary_column [protected]
 

StringList MultipleReporter::label_list [protected]
 

int MultipleReporter::max_char_pr_summary_line [protected]
 

real MultipleReporter::max_cmWidth [protected]
 

bool MultipleReporter::open_files [protected]
 

int MultipleReporter::psfilename_counter [protected]
 

StringList MultipleReporter::psfilename_list [protected]
 

String MultipleReporter::purpose [protected]
 

Handle(Reporter) MultipleReporter::sum_ascii
 

Os MultipleReporter::sum_data
 

Handle(Reporter) MultipleReporter::sum_html
 

Handle(Reporter) MultipleReporter::sum_latex
 

Strings MultipleReporter::summary_heading [protected]
 

ArrayGenSimple(String) MultipleReporter::summary_page [protected]
 

The documentation for this class was generated from the following file:
Copyright © 2003 inuTech GmbH. All rights reserved.