Demos-4/Notes/howTo-OpenMultipleReportFiles.txt
-----------------------------------------------

The ModelParameters class provides a built-in set
of methods to open, write to, and close to one
"report" file.  There are several parameters that 
affect how this works:

  outputDirName (oDN) = ./
  reportFileName (rFN) = report
  runNumber (rN) = 0

By default, the report file's base name is "report"
and appended to that is the (int) value of "runNumber"
e.g., "report.00" "report.01" and so on.
These are written to the outputDirName, by default
the working directory in which the program is run.

The above parameters are useful when you want to specify
the name and output dir used for the report file in systematic
ways, e.g., as is done by the Drone experiment-running tool.
For instance you can easily do multiple runs with the
same parameters but different RNG seeds like this:
   bin/batchrun.sh  iPFN=initParValues.xml S=1234567 rFN=report-X rN=0
   bin/batchrun.sh  iPFN=initParValues.xml S=3234567 rFN=report-X rN=1
   bin/batchrun.sh  iPFN=initParValues.xml S=5234567 rFN=report-X rN=2
This will run the model 3 times, with the same basic parameters
as specified in the file initParsValues.xml (see below) with
different RNG seeds, writing output to the files
report-X.00  report-X.01 and report-X.02 .

Assume the class that extends ModelParameters is Model.

The report file is opened by this method call
		startReportFile();
which should be made in the buildModel() method of Model,
after all the parts of the model have been constructed.
This will open the report file with the specified name
in the specified directory, and write out the current values of 
all parameters included in the ModelParameters, via calls
to  parametersMap.put() as in the method:
   addModelSpecificParameters ()
which should be defined in the Model class as well.

Actually, two report files will be opened:
   report.00
   report.xml.00
The first is intended for data written in some plain
ascii format, e.g., one row of data for each time step.
The second is intended for data written in xml format.
Thus the parameters and values are written to the top of
that file in an xml format that ModelParamters can process
as initial values, via the parameter 
    initialParametersFileName (iPFN)
eg, when the model is run like
   bin/batchrun.sh  iPFN=report.xml.00 T=100 nA=200  

In general, the section that specifies parameter values at the
start of a xml report file from such a model can be used
as a file of initial parameter values, as noted earlier in this file.
Eg, for a file named "initParValues.xml"  which has parameters
specified as follows:

<parameters>
        <rDebug>0</rDebug>
        <seed>1137785371949</seed>
        <stopT>100</stopT>
...
        <runNumber>0</runNumber>
        <saveRunEndState>0</saveRunEndState>
</parameters>

can then be used as an input parameter value file like this:
   bin/batchrun.sh  iPFN=initParValues.xml
Additional parameters can override the values in that initParValues.xml
file by including them on the end of the run command, eg
    bin/batchrun.sh  iPFN=initParValues.xml T=1000 muRate=0.01
and so on.

Data is typically written to the report files (plain and xml)
in the stepReport() method.
To write data to the ascii report file, you must first
format the data to be written to a line, e.g., with the
String class method:
   String s = String.format( "%5.0f  ", getTickCount() );
Append all the data you want to write at once to s, and then call:
   writeLineToPlaintextReportFile( s );
To write data to the xml report file, you must format the data
and write it via this method:
   	writeLineToReportFile ( s )
where in this case the String s must include any xml tags required.

There is an additional build-in parameter that can be used
in stepReport() to control how often data is written:
  reportFrequency (rF) = 1
E.g., you can use the modulus operator with that paramter
and the RePast getTickCount() value to have data written only
every N steps rather than every step.

The built in report file is closed by calls to 
    public void endReportFile ( )
in ModelParameters, which is usually done by methods like:
    processEndOfRun()

See Demos-4 projects like heatBugs3 to see examples of use
of the build in methods for opening, writing to, and closing the
standard "report" files.
   
=======================================================================
=======================================================================
How to set up additional "report" files with different base names:

Sometimes it is useful to have multiple report files, with
different kinds of data, generated from the same model.
As mentioned above, the new ModelParameters class provides some
methods that makes it easy to have multiple report files, with different
base names.   To do this, you will use the
following methods provied by the ModelParameters class:

   public PrintWriter startReportFile ( String baseName )
   public PrintWriter startPlainTextReportFile ( String baseName )
   public void writeParametersToReportFile( PrintWriter rfile ) 
   public void writeParametersToPlainTextReportFile( PrintWriter rfile ) 
   public void writeLineToReportFile ( String line, PrintWriter rfile )
   public void writeBufferToReportFile ( String buffer, PrintWriter rfile )
           the above does NOT write a newline.
   public void endReportFile ( PrintWriter rfile ) 
   public void endPlainTextReportFile ( PrintWriter rfile ) 
      
To use these, one would:
  - define a String parameter/variable that gives the base name for the report files.
    Eg, this would typically be a parameter added for a specific model,
    in the Model class that extends ModelParameters.
  - define one or two PrintWriter variables in the Model class, 
    one for the new report in plain text format, 
    one for xml format (if you are using that).
    Thse are used below in place "rfile" (one for plain ascii and one
    for xml if you are doing xml). 
  - use these method (in buildModel() usually) to open the report file(s):
        public PrintWriter startReportFile ( String baseName )
        public PrintWriter startPlainTextReportFile ( String baseName )
    Those automatically call the methods to write parameters to the
    start of those files.
  - custom write any comments to the head of these report files using 
         writeLineToReportFile ( String line, PrintWriter rfile )
    and formatting (xml or plain text) as desired.
   - Then write data to the files using
        public void writeLineToReportFile ( String line, PrintWriter rfile )
        public void writeBufferToReportFile ( String buffer, PrintWriter rfile )
     e.g.,in the stepReport() method or some other method that is
     called when you want to write data to these files.
   - In some method like processEndRun(), call
          endReportFile ( PrintWriter rfile )
          public void endPlainTextReportFile ( PrintWriter rfile ) 
     to cleanly close these report, where the "rfile" variables are
     those you defined for these report files.


For instance, in the ~rlr/Courses/530/Src/AntPheromones2 project 
this could be done as follows:

So we:
- add this to the top of Model.java if its not there:
     import java.io.*;
- define  
      public String pherReportFileName = "pherReport"; 
      public PrintWriter pherReportFile, pherPlainTextReportFile;  
    and add getters/setters for the string variable.
    and add pherReport to ParametersMap alias pRFN
    and add pherReport to getInitParam for the GUI 

    Lets also add a variable to control the frequency of writing this info:
       public int pherReportFrequency = 1;
    plus getter/setter, add to ParametersMap, to getInitParam.
    Use it in Model-stepReport() method.

- In buildModel(), add lines like:

     if ( pherReportFile != null )
        endReportFile (  pherReportFile );
     if ( pherPlainTextReportFile != null )
        endPlainTextReportFile (  pherPlainTextReportFile );
     pherReportFile = startReportFile( pherReportFileName );
     pherPlainTextReportFile = startPlainTextReportFile( pherReportFileName );

- in stepReport(), do this to write all values in pherSpace
  every pherReportFrequency steps:

     if ( getTickCount() % pherReportFrequency == 0 ) {
        double v;
        s = String.format( "# step %5.0f", getTickCount() );
        writeLineToReportFile( s, pherPlainTextReportFile );
        for ( int x = 0; x < sizeX; ++x ) {
           s = "";
           for ( int y = 0; y < sizeY; ++y ) {
              v = pSpace.getValueAt( x, y );
              s += String.format( " %5.0f", v );
           }
           writeLineToReportFile( s, pherPlainTextReportFile );
        }
        writeLineToReportFile( "# endstep", pherPlainTextReportFile );
     }

- in processEndOfRun(), call:
        endReportFile( pherReportFile );
        endPlainTextReportFile( pherPlainTextReportFile );

We could test it like this:
   bin/batchrun.sh dK=0.1 rFN=report-d.1 T=5 D=3 

Or try with set pherReportName, and frequency:
  bin/batchrun.sh dK=0.1 rFN=report-d.1 pRFN=pherReport-X pRF=10  T=50 D=1 

-----------------------------------------------------------------------