Fixed documentation.
[charm.git] / examples / bigsim / tools / rewritelog / README
1 NOTE: the instructions below represent a rapidly changing experimental
2       setup. Contact idooley2@uiuc.edu for the latest status. I am 
3       currently adding support for PAPI performance counters, so the 
4       format of the CYCLE_ACCURATE_TIMES file has recently changed
5
6
7 Building / Compiling :
8   
9   Install GSL, the GNU Scientific Library. This is required 
10   to perform least square curve fitting. Make sure the local
11   makefile points to your copy of gsl. Currently this is 
12   in the variable "LIBS"
13
14   Build charm/bigemulator
15
16   Modify the file interpolatelog.C to match your particular tastes.
17     OUTPUTDIR         specifies a directory for the new logfiles
18
19     CYCLE_TIMES_FILE  specifies the file which contains accurate 
20                       timing information
21
22     time_factor       specifies a multiplier used to scale any times 
23                       that are not replaced by times approximated
24                       from available cycle-accurate times
25
26   Make the interpolation tool: 
27     > make
28
29 Modifying Application:
30
31   Insert startTraceBigSim() call before a compute kernel. Add an 
32   endTraceBigSim() call after the kernel. Currently the first call
33   takes no parameters, and the second takes a name for the event
34   that is being bracketed, followed by between 0 and 20 parameters 
35   describing the computation. 
36
37   You will find the definitions of these functions in traceBigSim/
38
39   startTraceBigSim();
40   // Some serial computational kernel goes here
41   endTraceBigSim("EventName",param1,param2,param3);
42
43   Thes calls will time and produce output(to STDOUT) that lists 
44   the time, parameters, and possibly some performance counters
45   for the code executed between the calls. 
46
47   A sample output file: traceBigSim/sample_namd_timings.txt
48
49   Run the application, in serial or parallel to produce a good
50   set of samples of the timings. These timings will be used 
51   to predict the performance for the events appearing in a
52   bgTrace log files. Put all of these timings in the file
53   reference by CYCLE_TIMES_FILE in interpolatelog.C. You can 
54   grep out only the lines containing TRACEBIGSIM, and can 
55   concatenate them all together into one big file.
56
57  
58 Running The interpolation tool:
59   
60   Run a parallel version of the application to generate the bgTrace* 
61   and param* files.
62
63   Run the interpolation tool from a directory containing the bgTrace*,
64   param*, and CYCLE_TIMES_FILE files. If you want these files to be 
65   located elsewhere, you should be able to modify interpolatelog.C
66   and EventInterpolator.C easily.
67
68   A new set of bgTrace files will be produced.