87e435d861e2f82f52bdf1929125cb2dd134504b
[charm.git] / doc / projections / manual.tex
1 %\documentclass[10pt,dvips]{article}
2 \documentclass[10pt]{article}
3 \usepackage{../pplmanual}
4 \usepackage[pdftex]{graphicx}
5 \usepackage{subfigure}
6 %\usepackage[dvips]{graphicx}
7 %\usepackage[usenames,dvipsnames]{color}
8 %\usepackage[pdftex]{hyperref}
9 \usepackage{epsfig}
10 \input{../pplmanual}
11
12 \ifpdf
13 \DeclareGraphicsExtensions{.jpg,.pdf,.mps,.png}
14 \else
15 \DeclareGraphicsExtensions{.eps}
16 \fi
17
18
19 \title{\projections{} Manual}
20 \version{7.0}
21 \credits{
22 By Mike DeNardo, Sid Cammeresi, Theckla Louchios, Orion Lawlor, Gengbin Zheng,
23 Chee Wai Lee, Isaac Dooley, and Sindhura Bandhakavi
24 }
25
26 \begin{document}
27 \maketitle
28
29 \section{Introduction}
30
31 \projections{} is a performance analysis/visualization framework that
32 helps you understand and investigate performance-related problems in
33 your parallel (\charmpp{}) application. It is a framework with an
34 event tracing component with features that allow you to control the
35 amount of information generated and to a lesser degree the amount of
36 perturbation the tracing activities introduce into the application. It
37 also has a Java-based visualization and analysis component with
38 various views that will help present the performance information in a
39 visually useful manner.
40
41 Performance analysis with \projections{} typically involves 2 simple
42 steps:
43
44 \begin{enumerate}
45 \item 
46 Prepare your application code by linking with the appropriate trace
47 generation modules and executing it to generate trace data. (see
48 section \ref{sec::preparation})
49 \item
50 Using the Java-based tool to visually study various aspects of the
51 performance information to locate application execution performance
52 problems. (see section \ref{sec::visualization})
53 \end{enumerate}
54
55 \section{Preparing the \charmpp{} Application}
56 \label{sec::preparation}
57
58 The \charmpp{} runtime automatically records pertinent performance
59 data at performance-related events encountered by the runtime. These
60 events include the start and end of entry method execution, message
61 sends from entry methods and scheduler idle time. This means {\em
62 most} users will not need to manually insert code into their
63 applications in order to generate trace data. In scenarios where
64 special performance information not captured by the runtime is
65 required, an API (see section \ref{sec::api}) is available for
66 user-specific events with some support for visualization by the
67 Java-based tool. If greater control over tracing activities
68 (e.g. dynamically turning instrumentation on and off) is desired, the
69 API also allows users to insert code into their applications for such
70 purposes.
71
72 The automatic recording of events by the \projections{} framework
73 introduces the overhead of an if-statement for each runtime event,
74 even if no performance analysis traces are desired. Developers of
75 \charmpp{} applications who consider such an overhead to be
76 unacceptable (e.g. for a production application which requires the
77 absolute best performance) may recompile the \charmpp{} runtime with
78 the {\tt -{}-with-production} flag which removes the instrumentation
79 stubs.
80
81 To enable performance tracing of your application, users simply need
82 to link the appropriate trace data generation module(s) (also referred
83 to as {\em tracemode(s)}). (see section \ref{sec::trace modules})
84
85 \subsection{\projections{} API for \charmpp{} Applications}
86 \label{sec::api}
87
88 \subsubsection{Selective Tracing}
89 \label{sec::selective tracing}
90
91 \charmpp{} allows user to start/stop tracing the execution at certain
92 points in time on the local processor. Users are advised to make these
93 calls on all processors and at well-defined points in the application.
94
95 Users may choose to have instrumentation turned off at first (by
96 command line option {\tt +traceoff} - see section \ref{sec::general options}) if some period of time in middle of the
97 application\'s execution is of interest to the user.
98
99 Alternatively, users may start the application with instrumentation
100 turned on (default) and turn off tracing for specific sections of the
101 application.
102
103 Again, users are advised to be consistent as the {\tt +traceoff}
104 runtime option applies to all processors in the application.
105
106 \begin{itemize}
107 \item
108 {\tt void traceBegin()}
109
110 Enables the runtime to trace events (including all user events) on the local processor where {\tt traceBegin} is called.
111
112 \item
113 {\tt void traceEnd()}
114
115 Prevents the runtime from tracing events (including all user events) on the local processor where {\tt traceEnd} is called.
116
117 \end{itemize}
118
119 \subsubsection{User Events}
120 \label{sec::user events}
121
122 \projections{} has the ability to visualize traceable user
123 specified events. User events are usually displayed in the Timeline view as vertical bars above the entry methods. Alternatively the user event can be displayed as a vertical bar that vertically spans the timelines for all processors. Follow these following basic steps for creating user events in a charm++ program:
124
125 \begin{enumerate}
126 \item
127 Register an event with an identifying string and either specify or acquire
128 a globally unique event identifier. All user events that are not registered will be displayed in white.
129
130 \item
131 Use the event identifier to specify trace points in your code of interest to you.
132 \end{enumerate}
133
134 The functions available are as follows:
135
136 \begin{itemize}
137 \item
138 {\tt int traceRegisterUserEvent(char* EventDesc, int EventNum=-1) }
139
140 This function registers a user event by associating {\tt EventNum} to
141 {\tt EventDesc}. If {\tt EventNum} is not specified, a globally unique
142 event identifier is obtained from the runtime and returned. The string {\tt EventDesc} must either be a constant string, or it can be a dynamically allocated string that is {\bf NOT} freed by the program. If the {\tt EventDesc} contains a substring ``***'' then the Projections Timeline tool will draw the event vertically spanning all PE timelines.
143
144 {\tt EventNum} has to be the same on all processors. Therefore use one of the following methods to ensure the same value for any PEs generating the user events:
145
146 \begin{enumerate}
147 \item
148 Call {\tt traceRegisterUserEvent} on PE 0 in main::main without specifying
149 an event number, and store returned event number into a readonly variable.
150 \item
151 Call {\tt traceRegisterUserEvent} and specify the event number on
152 processor 0. Doing this on other processors would have no
153 effect. Afterwards, the event number can be used in the following user
154 event calls.
155 \end{enumerate}
156
157 Eg. {\tt traceRegisterUserEvent("Time Step Begin", 10);}
158
159 Eg. {\tt eventID = traceRegisterUserEvent(``Time Step Begin'');}
160
161 \end{itemize}
162
163
164
165 There are two main types of user events, bracketed and non bracketed. Non-bracketed user events mark a specific point in time. Bracketed user events span an arbitrary contiguous time range. Additionally, the user can supply a short user supplied text string that is recorded with the event in the log file. These strings should not contain newline characters, but they may contain simple html formatting tags such as \texttt{<br>}, \texttt{<b>}, \texttt{<i>}, \texttt{<font color=\#ff00ff>}, etc.
166
167 The calls for recording user events are the following:
168
169 \begin{itemize}
170
171
172 \item
173 {\tt void traceUserEvent(int EventNum) }
174
175 This function creates a user event that marks a specific point in time.
176
177 Eg. {\tt traceUserEvent(10);}
178
179 \item
180 {\tt void traceUserBracketEvent(int EventNum, double StartTime, double EndTime) }
181
182 This function records a user event spanning a time interval from {\tt StartTime} to {\tt EndTime}. Both {\tt StartTime} and {\tt EndTime} should be obtained from a call to {\tt CmiWallTimer()} at the appropriate point in the program.
183
184 Eg.
185 \begin{verbatim}
186    traceRegisterUserEvent("Critical Code", 20); // on PE 0
187    double critStart = CmiWallTimer();;  // start time
188    // do the critical code
189    traceUserBracketEvent(20, critStart,CmiWallTimer());
190 \end{verbatim}
191
192
193
194
195
196 \item
197 {\tt void traceUserSuppliedNote(char * note) }
198
199 This function records a user specified text string at the current time.
200
201
202
203
204 \item
205 {\tt void traceUserSuppliedBracketedNote(char *note, int EventNum, double StartTime, double EndTime)}
206
207 This function records a user event spanning a time interval from {\tt StartTime} to {\tt EndTime}. Both {\tt StartTime} and {\tt EndTime} should be obtained from a call to {\tt CmiWallTimer()} at the appropriate point in the program.
208
209 Additionally, a user supplied text string is recorded, and the  {\tt EventNum} is recorded. These events are therefore displayed with colors determined by the {\tt EventNum}, just as those generated with {\tt traceUserBracketEvent} are.
210
211 \end{itemize}
212
213
214 \subsubsection{Function-level Tracing for Adaptive MPI Applications}
215 \label{sec::AMPI functions}
216
217 Adaptive MPI (AMPI) is an implementation of the MPI interface on top
218 of \charmpp{}. As with standard MPI programs, the appropriate semantic
219 context for performance analysis is captured through the observation
220 of MPI calls within C/C++/Fortran functions. Unfortunately, AMPI's
221 implementation does not grant the runtime access to information about
222 user function calls. As a result, the tracing framework must provide
223 an explicit API for capturing this piece of performance information in
224 addition to MPI calls (which are known to the runtime).
225
226 The functions, similar to those used to capture user events, are as
227 follows:
228
229 \begin{itemize}
230 \item 
231 \begin{verbatim}
232 int _TRACE_REGISTER_FUNCTION_NAME(const char *name);
233 \end{verbatim}
234 This function registers an AMPI function {\tt name}. The tracing
235 framework assigns to function {\tt name} a unique id and returns
236 it. It is the user's responsibility to ensure that {\tt name} is
237 unique and consistent.
238
239 This registration function should be called near the start of the
240 application, just after {\tt MPI\_Init}.
241
242 \item
243 \begin{verbatim}
244 int _TRACE_REGISTER_FUNCTION_ID(const char *name, int idx);
245 \end{verbatim}
246 This function registers an AMPI function {\tt name} to be associated
247 explicitly to the id {\tt idx}. It is the user's responsibility to 
248 ensure that {\tt name} as well as {\tt idx} are unique and consistent.
249 The tracing framework returns {\tt idx}.
250
251 This is an alternative registration function and should be called near
252 the start of the application just after {\tt MPI\_Init}.
253
254 \item
255 \begin{verbatim}
256 void _TRACE_BEGIN_FUNCTION_NAME(const char *name);
257 \end{verbatim}
258 This function tells the tracing framework to record a begin event
259 associated with the registered function {\tt name}. If this were called
260 in a C/C++ environment with pre-processor support, the line number of
261 the function call will also be recorded.
262
263 \item
264 \begin{verbatim}
265 void _TRACE_BEGIN_FUNCTION_ID(int idx);
266 \end{verbatim}
267 This function tells the tracing framework to record a begin event
268 associated with the registered function indexed by {\tt idx}. If this were
269 called in a C/C++ environment with pre-processor support, the line number
270 of the function call will also be recorded.
271
272 \item
273 \begin{verbatim}
274 void _TRACE_END_FUNCTION_NAME(const char *name);
275 \end{verbatim}
276 This function tells the tracing framework to record a end event
277 associated with the registered function {\tt name}.
278
279 \item
280 \begin{verbatim}
281 void _TRACE_END_FUNCTION_ID(int idx);
282 \end{verbatim}
283 This function tells the tracing framework to record a end event
284 associated with the registered function indexed by {\tt idx}.
285
286 \end{itemize}
287
288 AMPI function events captured by the use of this API are recognized by
289 the visualization system and used for special AMPI-specific views in
290 addition to standard \charmpp{} entry methods.
291
292 %\subsubsection{Tracing POSE Parallel Discrete Event Simulation Abstractions}
293 %\label{sec::POSE}
294 %
295 %Parallel Object-oriented Simulation Environment (POSE) is a parallel
296 %discrete event simulator (PDES) implemented on top of
297 %\charmpp{}. Understanding the performance of simulations conducted
298 %using POSE requires not just the performance of POSE as the \charmpp{}
299 %runtime system sees it (through entry methods), but also requires the
300 %understanding of PDES progress and degree-of-parallelism in real time
301 %as well as virtual time.
302 %
303 %As a result, POSE provides its own performance data format that the
304 %\projections{} visualization tool understands when a POSE simulation
305 %is executed with the {\tt +dop\_pose} runtime option. No additional
306 %user intervention is required.
307
308 \subsection{\projections{} Tracing Modules at Application Link Time}
309 \label{sec::trace modules}
310
311 \projections{} tracing modules dictate the type of performance data,
312 data detail and data format each processor will record. They are also
313 refered to as ``tracemodes''. There are currently 2 tracemodes
314 available. Zero or more tracemodes may be specified at link-time. When
315 no tracemodes are specified, no trace data is generated.
316
317 \subsubsection{Tracemode {\tt projections}}
318
319 Link time option: {\tt -tracemode projections}
320
321 This tracemode generates detailed event log files that contain
322 information about all \charmpp{} events like entry method calls and
323 message packing during the execution of the program.  The data will be
324 used by \projections{} in visualization and analysis.
325
326 This tracemode will generate a single symbol table file and $p$ ASCII
327 log files for $p$ processors. The names of the log files will be
328 NAME.\#.log where NAME is the name of your executable and \# is the
329 processor \#. The name of the symbol table file is NAME.sts where NAME
330 is the name of your executable.
331
332 This is the main source of data expected by the performance
333 visualizer. Certain tools like timeline will not work without the
334 detailed data from this tracemode.
335
336 The following is a list of runtime options available under this tracemode:
337
338 \begin{itemize}
339 \item
340 {\tt +logsize NUM}: keep only NUM log entries in the memory of each
341 processor. The logs are emptied and flushed to disk when filled.
342 \item
343 {\tt +binary-trace}:  generate projections log in binary form.
344 \item
345 {\tt +gz-trace}:      generate gzip (if available) compressed log files.
346 \item
347 {\tt +checknested}: a debug option. Checks if events are improperly nested
348 while recorded and issue a warning immediately.
349
350 \item {\tt +trace-subdirs NUM}: divide the generated log files among
351   {\tt NUM} subdirectories of the trace root, each named {\tt
352     PROGNAME.projdir.K}
353 \end{itemize}
354
355 \subsubsection{Tracemode {\tt summary}}
356
357 Compile option: {\tt -tracemode summary}
358
359 In this tracemode, execution time across all entry points for each
360 processor is partitioned into a fixed number of equally sized
361 time-interval bins. These bins are globally resized whenever they are
362 all filled in order to accomodate longer execution times while keeping
363 the amount of space used constant.
364
365 Additional data like the total number of calls made to each entry
366 point is summarised within each processor.
367
368 This tracemode will generate a single symbol table file and $p$ ASCII
369 summary files for $p$ processors. The names of the summary files will
370 be NAME.\#.sum where NAME is the name of your executable and \# is the
371 processor \#. The name of the symbol table file is NAME.sum.sts where NAME
372 is the name of your executable.
373
374 This tracemode can be used to control the amount of output generated
375 in a run. It is typically used in scenarios where a quick look at the
376 overall utilization graph of the application is desired to identify
377 smaller regions of time for more detailed study. Attempting to
378 generate the same graph using the detailed logs of the prior tracemode
379 may be unnecessarily time consuming or impossible.
380
381 The following is a list of runtime options available under this tracemode:
382
383 \begin{itemize}
384 \item
385 {\tt +bincount NUM}:   use NUM time-interval bins. The bins are resized and compacted when filled.
386 \item
387 {\tt +binsize TIME}:   sets the initial time quantum each bin represents.
388 \item
389 {\tt +version}:        set summary version to generate.
390 %\item
391 %{\tt +epThreshold}: DOESNT DO ANYTHING YET. LEFT COMMENTED FOR DOC PURPOSES
392 %\item
393 %{\tt +epInterval}: DOESNT DO ANYTHING YET. LEFT COMMENTED FOR DOC PURPOSES
394 \item
395 {\tt +sumDetail}: Generates a additional set of files, one per processor,
396 that stores the time spent by each entry method associated with each 
397 time-bin. The names of ``summary detail'' files will be NAME.\#.sumd where
398 NAME is the name of your executable and \# is the processor \#.
399 \item
400 {\tt +sumOnly}: Generates an additional file that stores a single
401 utilization value per time-bin, averaged across all processors. This
402 file bears the name NAME.sum where NAME is the name of your
403 executable. This runtime option currently overrides the {\tt
404 +sumDetail} option.
405 \end{itemize}
406
407 \subsection{General Runtime Options}
408 \label{sec::general options}
409
410 The following is a list of runtime options available with the same
411 semantics for all tracemodes:
412
413 \begin{itemize}
414 \item
415 {\tt +traceroot DIR}: place all generated files in DIR.
416 \item
417 {\tt +traceoff}: trace generation is turned off when the application
418 is started. The user is expected to insert code to turn tracing on at
419 some point in the run.
420 \item
421 {\tt +traceWarn}: By default, warning messages from the framework are
422 not displayed. This option enables warning messages to be printed to
423 screen. However, on large numbers of processors, they can overwhelm
424 the terminal I/O system of the machine and result in unacceptable
425 perturbation of the application.
426 \end{itemize}
427
428 \section{Advanced Tracing Features}
429 \label{sec::advanced tracing features}
430
431 \subsection{End-of-run Analysis for Data Reduction}
432 \label{sec::data reduction}
433
434 As applications are scaled to thousands or hundreds of thousands of
435 processors, the amount of data generated becomes extremely large and
436 potentially unmanagable by the visualization tool. At the time of this
437 documentation, \projections{} is capable of handling data from 8000+
438 processors but with somewhat severe tool responsiveness issues. We
439 have developed an approach to mitigate this data size problem with
440 options to trim-off ``uninteresting'' processors' data by not writing
441 such data at the end of an application's execution.
442
443 This is currently done through heuristics to pick out interesting
444 extremal (i.e. poorly behaved) processors and at the same time using a
445 k-means clustering to pick out exemplar processors from equivalence
446 classes to form a representative subset of processor data. The analyst
447 is advised to also link in the summary module via {\tt +tracemode
448 summary} and enable the {\tt +sumDetail} option in order to retain
449 some profile data for processors whose data were dropped.
450
451 \begin{itemize}
452 \item
453 {\tt +extrema}: enables extremal processor identification analysis at
454 the end of the application's execution.
455 \item
456 {\tt +numClusters}: determines the number of clusters (equivalence
457 classes) to be used by the k-means clustering algorithm for
458 determining exemplar processors. Analysts should take advantage of
459 their knowledge of natural application decomposition to guess at a
460 good value for this.
461 \end{itemize}
462
463 This feature is still being developed and refined as part of our
464 research. It would be appreciated if users of this feature could
465 contact the developers if you have input or suggestions.
466
467 \newpage
468
469 \section{The \projections{} Performance Visualization Tool}
470 \label{sec::visualization}
471
472 The \projections{} Java-based visualization tool (henceforth refered
473 to as simply \projections{}) comes pre-built with the \charmpp{}
474 source release. It can be located at \\ {\tt
475 CHARM\_LOCATION/tools/projections} which will henceforth be refered to
476 as {\tt PROJECTIONS\_LOCATION}.
477
478 \subsection{Building \projections{}}
479
480 To rebuild \projections{} (optional) from the source:
481
482 \begin{enumerate}
483 \item[1)]
484    Make sure the JDK commands ``java'', ``javac'', ``ant'',  and ``jar''
485    are in your path  
486 \item[2)]
487    Make sure that your versions of java and javac are at least 1.5. Do this by running ``java -version'' and ``javac -version''. Also, make sure the environment variable JAVA\_HOME is not pointing at an old version of java.
488 \item[3)]
489    From {\tt PROJECTIONS\_LOCATION/}, type ``ant clean'' then ``ant''
490 \item[4)]
491    The following files are placed in `bin':
492
493       {\tt projections}           : Starts projections, for UNIX machines
494
495       {\tt projections.bat}       : Starts projections, for Windows machines
496
497       {\tt projections.jar}       : archive of all the java and image files
498 \end{enumerate}
499
500 \subsection{Visualization and Analysis using \projections{}}
501
502 \subsubsection{Starting Up}
503 \label{sec:startingUp}
504 From any location, type: \\
505 {\tt > PROJECTIONS\_LOCATION/bin/projections [NAME.sts]} \\
506 where {\tt PROJECTIONS\_LOCATION} is the path to the main projections
507 directory.
508
509 Available options to the visualization component of \projections{} include:
510
511 \begin{itemize}
512 \item
513 {\tt -h or --help}: displays help information about available options.
514 \item
515 {\tt -V or --version}: displays current \projections{} version number.
516 \item
517 {\tt -u or --use-version $<ver>$}: overrides the data interpretation
518 behavior of \projections{} to explicitly use $ver$ instead of the
519 current version. This is useful in scenarios where the latest version
520 of \projections{} is not backward-compatible with older log formats.
521 \item
522 {\tt -no-idle}: tells \projections{} to ignore idle time information
523 contained in the logs.
524 \item
525 {\tt -bgsize $<x> <y> <z>$}: tells \projections{} to compute
526 additional derived information by assuming a logical 3-D Torus
527 topology with the specified dimensionality and a processor-to-torus
528 placement policy that matches \charmpp's placement policy on the BG/L
529 class of machines. The presence of this option enables additional
530 communication visualization options (see later). Note that this option
531 is really meant to be used for logs generated from virtual-node mode
532 BG/L executions. The additional information derived from any other
533 logs would probably be misleading.
534 \item
535 {\tt -print\_usage}: tells \projections{} to also write to standard
536 output the detailed graph numbers when viewing Usage Profiles (see
537 later). This is useful for generating visuals that are better
538 expressed by tools such as gnuPlot than through screen captures of
539 \projections{} plots.
540 \end{itemize}
541
542 Supplying the optional {\tt NAME.sts} file in the command line will
543 cause \projections{} to load data from the file at startup. This shortcut
544 saves time selecting the desired dataset via the GUI's file dialog.
545
546 \begin{figure}[hbt]
547 \center
548 %\epsfig{figure=fig/front-with-summary.eps,height=4in}
549 \includegraphics[width=4.0in]{fig/front-with-summary}
550 \caption{\projections{} main window}
551 \label{mainwindow}
552 \end{figure}
553
554 When \projections{} is started, it will display a main window as shown
555 in figure \ref{mainwindow}. If summary (.sum) files are available in
556 the set of data, a low-resolution utilization graph (Summary Display)
557 will be displayed as shown. If summary files are not available, or if
558 \projections{} was started without supplying the optional {\tt
559 NAME.sts} file, the main window will show a blank screen.
560
561 %{\bf Menu Options}
562
563 \begin{itemize}
564 \item
565   {\bf File} contains 3 options. {\it Open File(s)} allows you to
566   explicitly load a data set. This happens if you had not specified a
567   {\tt NAME.sts} file in the command line when starting \projections{}
568   or if you wish to explicitly load a new dataset. It brings up a
569   dialog box that allows you to select the location of the dataset you
570   wish to study. Navigate to the directory containing your data and
571   select the .sts file.  Click on `Open'. If you have selected a valid
572   file, \projections{} will load in some preliminary data from the
573   files and then activate the rest of the options under the menu item
574   {\bf Tools}. {\it Close current data} currently works the same way
575   as {\it Close all data}. They unload all current \projections{} data
576   so one can load in a new set of data. They will also deactivate the
577   individual items provided in the {\bf Tools} menu option.
578 \item
579   {\bf Preferences} generally allows you to set foreground or background
580   colors and entry method color schemes. This is useful for configuring
581   the color schemes of \projections{} windows to be print-friendly.
582 \item
583   {\bf Tools} lists the set of available tools for analysis of generated
584   trace data. It will be described in great detail under section
585   \ref{sec::available tools}.
586 \end{itemize}
587
588 %{\bf Summary Display}
589
590 The Summary Display loaded on the Main Window displays basic processor
591 utilization data (averaged across all processors) over time
592 intervals. This is provided by the data generated by the summary
593 tracemode. This view offers no special features over and above the
594 {\bf Standard Graph Display} described in section \ref{sec::misc}. 
595 Please refer the appropriate section on information for using
596 its available features.
597
598 %{\bf Summary Display Performance Issues}
599
600 There should not be any serious performance issues involved in the
601 loading of summary data on the main window.
602
603 \subsubsection{Available Tools}
604 \label{sec::available tools}
605
606 The following tools and views become available to you after a dataset
607 has been loaded (with the exception of Multirun Analysis) and may be
608 accessed via the menu item Tools:
609
610 \begin{itemize}
611 \item 
612 The {\bf Graphs} view is where you can analyze your data by breaking it
613 into any number of intervals and look at what goes on in each of those
614 intervals.
615 \item
616 The {\bf Timelines} view lets you look at what a specific processor is
617 doing at each moment of the program. It is the most detailed view of a
618 parallel application \projections{} offers (and correspondingly, the
619 most resource-hungry).
620 \item
621 The {\bf Usage Profile} view lets you see percentage-wise what entry
622 methods each processor spends its time on during a specified time range.
623 It is particularly useful for identifying load imbalance and the probable
624 offending entry method.
625 \item
626 The {\bf Communication} view is a general tool that presents
627 communication properties contributed by each entry point across the
628 processors.
629 \item
630 The {\bf Log File Viewer} provides a human-readable, verbose
631 interpretation of a log file's entries.
632 \item
633 The {\bf Histograms} view presents entry point or communication
634 histogram information (ie. the frequency of occurrence of events given
635 an activity property like time bin size or message size on the
636 x-axis).
637 \item
638 The {\bf Overview} view gives user an overview of the utilization of
639 all processors during the execution. It is an extremely useful initial
640 tool to begin your performance analysis efforts with as it provides an
641 overall picture of application performance while being very
642 light-weight at the same time.
643 \item
644 The {\bf Animation} view animates the processor usage over a specified
645 range of time and a specified interval size.
646 \item
647 The {\bf Time Profile Graph} view is a more detailed presentation of
648 the {\bf Graphs} utilization view in that it presents the time
649 contribution by each entry point across the desired time
650 interval. While the {\bf Graphs} view can show the same data, it is
651 unable to stack the entry points, which proves useful in some cases.
652 \end{itemize}
653
654 \subsection{Performance Views}
655
656 \subsubsection{Graphs}
657 \label{sec::graph view}
658
659 %{\bf Introduction}
660
661 The Graphs window (see figure \ref{graph}) is where you can analyze your data by breaking it
662 into any number of intervals and look at what goes on in each of those
663 intervals.
664
665 %{\bf Dialog Box}
666
667 When the Graph Window first appears, a dialog box will also appear. It
668 will ask for the following information (Please refer to
669 \ref{sec::misc} for information on special features you can
670 use involving the various fields)::
671
672 \begin{itemize}
673 \item
674 Processor(s): Choose which processor(s) you wish to visualize graph 
675 information for.
676 \item
677 Start Time : Choose the starting time of interest. A time-based field.
678 \item
679 End Time : Choose the ending time of interest. A time-based field.
680 \item
681 Interval Size : Determine the size of an interval. The number of intervals
682 will also be determined by this value (End Time - Start Time divided by
683 Interval Size). A time-based field.
684 \end{itemize}
685
686 Standard \projections{} dialog options and buttons are also available
687 (see \ref{sec::misc} for details).
688
689 The following menu items are available:
690
691 \begin{itemize}
692 \item
693 {\bf File} contains 2 options: {\it Print Graph} uses Java's built-in 
694 print manager feature to render the tool's displays (usually to a printer 
695 or a file depending on the platform on which Java is supported). Note that
696 the current implementation of the renderer does not behave in exactly the
697 same fashion as the screen renderer, so you should expect the output to look
698 somewhat different. {\it Close} simply closes the Graph window.
699 \item
700 {\bf Tools} contains 2 options: {\it Set Interval Size} reloads the dialog
701 box so you could select a new time range over which to view Graph data.
702 {\it Timeline} is currently not implemented. Its intended as a convenient
703 way to load Timeline data (see section \ref{sec::timeline view}) over the 
704 same parameters as the current Graph view.
705 \end{itemize}
706
707 %{\bf Tool Performance }
708
709 The amount of time to analyze your data depends on several factors,
710 including the number of processors, number of entries, and number of
711 intervals you have selected.  A progress meter will show the amount of
712 data loaded so far. The meter will not, however, report rendering
713 progress which is determined mainly by the number of intervals selected.
714 As a rule of thumb, limit the number of intervals to 1,000 or less.
715
716 \begin{figure}[hbt]
717 \center
718 %\epsfig{figure=fig/graph.eps,height=4.3in}
719 \includegraphics[width=4.3in]{fig/graph}
720 \caption{Graph tool}
721 \label{graph}
722 \end{figure}
723
724 %{\bf Tool Features }
725
726 The Graph Window has 3 components in its display:
727 \begin{enumerate}
728 \item[1)]
729 {\bf Display Panel} (located : top-left area)
730    \begin{itemize}
731    \item[-]
732    Displays title, graph, and axes. To the left is a y-axis bar for
733    detailed information involving the number of messages sent or time
734    executed depending on the {\bf Control Panel} toggle selected (see 
735    below). To the right is a y-axis bar for average processor-utilization 
736    information. The x-axis may be based on time-interval or per-processor
737    information depending on the appropriate {\bf Control Panel} toggle.
738    \item[-]
739    Allows you to toggle display between a line graph and a bar graph.
740    \item[-]
741    Allows you to scale the graph along the X-axis.  You can either
742    enter a scale value $>=$ 1.0 in the text box, or you can use the
743    $<<$ and $>>$ buttons to increment/decrement the scale by .25.
744    Clicking on Reset sets the scale back to 1.0.  When the scale is
745    greater than 1.0, a scrollbar will appear along the bottom of the
746    graph to let you scroll back and forth.
747    \end{itemize}
748 \item[2)]
749 {\bf Legend Panel} (located : top-right area)
750    \begin{itemize}
751    \item[-]
752    Shows what information is currently being displayed on the graph and 
753    what color represents that information.
754    \item[-]
755    Click on the `Select Display Items' button to bring up a window to
756    add/remove items from the graph and to change the colors of the items:
757       \begin{itemize}
758       \item[*]
759       The {\bf Select Display Items} window shows a list of items that you
760       can display on the graph.  There are 3 main sections: System
761       Usage, System Msgs, and User Entries. The System Usage and System
762       Msgs are the same for all programs. The User Entries section
763       has program-specific items in it.
764       \item[*]
765       Click on the checkbox next to an item to have it displayed on the
766       graph.
767       \item[*]
768       Click on the colorbox next to an item to modify its color.
769       \item[*]
770       Click on `Select All' to choose all of the items
771       \item[*]
772       Click on `Clear All' to remove all of the items
773       \item[*]
774       Click on `Apply' to apply you choices/changes to the graph
775       \item[*]
776       Click on `Close' to exit
777       \end{itemize}
778    \end{itemize}
779 \item[3)]
780 {\bf Control Panel} (located : bottom area)
781    \begin{itemize}
782    \item[-]
783    Allows you to toggle what is displayed on the X-axis.  You can either
784    have the x-axis display the data by interval or by processor.
785    \item[-]
786    Allows you to toggle what is displayed on the Y-axis.  You can
787    either have the y-axis display the data by the number of msgs sent
788    or by the amount of time taken.
789    \item[-]
790    Allows you to change what data is being displayed by iterating
791    through the selections.  If you have selected an x-axis type of
792    `interval', that means you are looking at what goes on in each
793    interval for a specific processor.  Clicking on the $<<, <, >, >>$
794    buttons will change the processor you are looking at by either -5,
795    -1, +1, or +5.  Conversely, if you have an x-axis of `processor',
796    then the iterate buttons will change the value of the interval that
797    you are looking at for each processor.
798    \item[-]
799    Allows you to indicate which intervals/processors you want to
800    examine.  Instead of just looking at one processor or one interval,
801    the box and buttons on the right side of this panel let you choose
802    any number or processors/intervals to look at. This field behaves
803    like a processor field. Please refer to section \ref{sec::misc} 
804    for more information about the special features on using processor
805    fields.
806
807    Clicking on `Apply' updates the graph with your choices. Clicking
808    on `Select All' chooses the entire processor range.  When you
809    select more than one processor's worth of data to display, the
810    graph will show the desired information summed across all selected
811    processors. The exception to this is processor utilization data
812    which is always displayed as data averaged across all selected
813    processors.
814    \end{itemize}
815 \end{enumerate}
816
817 \subsubsection{Timelines}
818 \label{sec::timeline view}
819
820 %{\bf Introduction}
821
822 The Timeline window (see figure \ref{timeline}) lets you look at what
823 a specific processor is doing at each moment of the program.
824
825 \begin{figure}[htb]
826 \center
827 %\epsfig{figure=fig/timeline.eps,height=3.8in}
828 \includegraphics[width=3.8in]{fig/timeline}
829 \caption{Timeline Tool}
830 \label{timeline}
831 \end{figure}
832
833 %{\bf Dialog Box}
834
835 When opening a Timeline view, a dialog box appears. 
836 The box asks for the following information (Please refer to
837 \ref{sec::misc} for information on special features you can
838 use involving the various fields):
839
840 \begin{itemize}
841 \item
842 Processor(s): Choose which processor(s) you want to see in the timeline.
843 \item
844 Start Time  : Choose what time you want your timeline to start at.
845 A time-based field.
846 \item
847 End Time    : Choose what time you want your timeline to end at. A time-based
848 field.
849 \end{itemize}
850
851 Standard \projections{} dialog options and buttons are also available
852 (see \ref{sec::misc} for details).
853
854
855 The following menu options are available:
856
857 \begin{itemize}
858 \item {\bf File} contains 1 enabled option: 
859 {\it Close} simply closes the Timeline Window.
860 \item {\bf Tools} contains 1 option: {\it Modify Ranges} opens the initial 
861 dialog box thereby allowing you to select new set of processors or time duration
862 parameters.
863 \item {\bf Colors} contains options for loading, using, and modifying color schemes. {\it Change Colors} functions in
864 a manner similar to the button of the same name described under control 
865 panel information below. {\it Save Colors} allows you to save the current
866 color set to a file named ``color.map'' into the same directory where your
867 data logs are stored. Note that the directory must have write permissions
868 for you before this can work. We are currently working on a more flexible
869 scheme for storing saved color sets. {\it Restore Colors} allows you to
870 load any previously saved color sets described above. {\it Default Colors}
871 resets the current color set to the default set that \projections{} assigns
872 without user intervention.
873
874 Other color schemes are provided that can be used for some applications. The colors set as described above are the default coloring scheme. Other options for coloring the events are by event id (chare array index), user supplied parameter, or memory usage. In order to color by a user supplied parameter such as timestep, the C function  \texttt{traceUserSuppliedData(int value);} should be called within some entry methods. If such a method is called in an entry method, the entry method invocation can be colored by the parameter. The user supplied data can also be viewed in the tooltip that appears when the cursor hovers over an entry method invocation in the window. To color by memory usage, the C function \texttt{traceMemoryUsage();} should be called in all entry methods. The call records the current memory usage. Red indicates high memory usage, and green indicates low memory usage. The actual memory usage can also be viewed in the tooltips that appear when the cursor is over an event. The memory usage is only available in when using a Charm++ version that uses gnu memory.
875
876
877 \item {\bf Screenshot} contains 1 option: 
878 {\it Save as JPG or PNG} save the visible portion of the visualization
879 to an image file. You must choose a filename ending with a \texttt{.png}
880 or \texttt{.jpg} extension when choosing the location to save the image. The
881 appropriate filetype is chosen based on the chosen filename
882 extension. If the view is zoomed in, only the portion currently shown
883 on screen is saved.
884
885 \end{itemize}
886
887 The Timeline Window consists of two parts:
888 \begin{enumerate}
889 \item[1)]
890 {\bf Display Panel} (located: top area)
891
892 This is where the timelines are displayed and is the largest portion
893 of the window.  The time axis is displayed at the top 
894 of the panel.  The left side of the
895 panel shows the processor labels, each containing a processor number and
896 two strange numbers. These two numbers represent the percentage of the
897 loaded timeline during which work occurs. The first of the two numbers
898 is the ``non-idle'' time, i.e. the portion of the time in the timeline
899 not spent in idle regions. This contains both time for entry methods
900 as well as other uninstrumented time spent likely in the Charm++
901 runtime. The second number is the percentage of the time used by the
902 entry methods for the selected range.
903
904
905 The timeline itself consists of colored bars for each event.
906 Placing the cursor over any of these bars will display information 
907 about the event including:  the name, the begin time, the end
908 time, the total time, the time spent packing, the number of messages it
909 created, and which processor created the event. 
910
911 Left clicking on an event bar will cause a window to popup. This
912 window contains detailed information about the messages sent by the
913 clicked upon event.
914
915 Right clicking on an event bar will cause a line to be drawn to the
916 beginning of the event bar from the point where the message causing
917 the event originated. This option may not be applicable for threaded
918 events. If the message originated on a processor not currently
919 included in the visualization, the other processor will be loaded, and
920 then the message line will be drawn. A warning message will appear if
921 the message origination point is outside the time duration, and hence
922 no line will be drawn.
923
924 User events are displayed as bars above the ordinary
925 event bars in the display area. If the name of the user event contains a substring ``***'' then the bar will vertically span the whole screen.
926
927 Message pack times and send points can be displayed below the event
928 bars. The message sends are small white tick marks, while the message
929 pack times are small pink bars usually occurring immediatly after the
930 message send point. If zoomed in to a point where each microsecond
931 takes more than one pixel, the message send point and the following
932 packing time may appear disconnected. This is an inherent problem with
933 the granularity used for the logfiles.
934
935
936 \item[2)]
937 {\bf Control Panel} (located: bottom area)
938
939 The controls in this panel are obvious, but we mention one here anyway.
940
941    View User Event - Checking this box will bring up a new
942    window showing the string description, begin time, end time and
943    duration of all user events on each processor. You can access
944    information on user events on different processors by accessing the
945    numbered tabs near the top of the display.
946
947    \begin{figure}[htb]
948    \center
949 %\epsfig{figure=fig/userevent.eps,height=1.5in}
950    \includegraphics[height=1.5in]{fig/userevent}
951    \caption{User Event Window}
952    \label{userevent}
953    \end{figure}
954
955 \end{enumerate}
956
957 Various features appear when the user moves the mouse cursor over the
958 top axis. A vertical line will appear to highlight a specific
959 time. The exact time will be displayed at the bottom of the
960 window. Additionally a user can select a range by clicking while a
961 time is highlighted and dragging to the left or right of that
962 point. As a selection is being made, a vertical white line will mark
963 the beginning and end of the range. Between these lines, the
964 background color for the display will change to gray to better
965 distinguish the selection from the surrounding areas. After a
966 selection is made, its duration is displayed at the bottom. A user can
967 zoom into the selection by clicking the ``Zoom Selected'' button. To
968 release a selection, single-click anywhere along the axis. Clicking
969 ``Load Selected'' when a selection is active will cause the timeline
970 range to be reloaded. To zoom out, the ``<<'' or ``Reset'' button can be used.
971
972
973 To then zoom into the selected area via this interface, click on
974 either the ``Zoom Selected'' or the ``Load Selected'' buttons.  The
975 difference between these two buttons is that the "Load Selected" zooms
976 into the selected area and discards any events that are outside the
977 time range.  This is more efficient than ``Zoom Selected'' as the
978 latter draws all the events on a virtual canvas and then zooms into
979 the canvas. The disadvantage of using ``Load Selected'' is that it
980 becomes impossible to zoom back out without having to re-specify the
981 time range via the ``Select Ranges'' button.
982
983 Performance-wise, this is the most memory-intensive part of the
984 visualization tool. The load and zoom times are proportional to the
985 number of events displayed. The user should be aware of how event-intensive the application is
986 over the desired time-period before proceeding to use this view. If
987 \projections{} takes too long to load a timeline, cancel the load and
988 choose a smaller time range or fewer processors. We expect to add features to alleviate
989 this problem in future releases.
990
991 \subsubsection{Usage Profile}
992 \label{sec::usage profile}
993 The Usage Profile window (see figure \ref{usage profile}) lets you see
994 percentage-wise what each processor spends its time on during a
995 specified period.
996
997 When the window first comes up, a dialog box appears asking for the
998 processor(s) you want to look at as well as the time range you want to
999 look at.  This dialog functions in exactly the same way as for the Timeline
1000 tool (see section \ref{sec::timeline view}).
1001
1002 \begin{figure}[htb]
1003 \center
1004 %\epsfig{figure=fig/usageprofile.eps,height=4in}
1005 \includegraphics[width=4.0in]{fig/usageprofile}
1006 \caption{Usage Profile}
1007 \label{usage profile}
1008 \end{figure}
1009
1010 The following menu options are available in this view:
1011
1012 \begin{itemize}
1013 \item {\bf File} has 2 options: {\it Select Processors} reloads the dialog
1014 box for the view and allows you to select a new processor and time range
1015 for this view. {\it Print Profile} currently does nothing. This will be
1016 addressed in a later release of \projections{}.
1017 \end{itemize}
1018
1019 The following components are supported in this view:
1020
1021 \begin{itemize}
1022 \item[1)] 
1023 {\bf Main Display} (located: top area) 
1024 The left axis of the display shows a scale from 0\% to 100\%.  The
1025 main part of the display shows the statistics.  Each processor is
1026 represented by a vertical bar with the leftmost bar representing the
1027 statistics averaged across all processors. The bottom of the bar
1028 always shows the time spent in each entry method (distinguished by the
1029 entry method's assigned color) . Above that is always reported the
1030 message pack time (in black), message unpack time (in orange) and idle
1031 time (in white). Above this, if the information exists, are colored
1032 bars representing communication CPU overheads contributed by each
1033 entry method (again, distinguished by the same set of colors
1034 representing entry methods). Finally the black area on top represents
1035 time overheads that the \charmpp{} runtime cannot account for.
1036
1037 If you mouse-over a portion of the bar (with the exception of the
1038 black area on top), a pop-up window will appear telling you the name
1039 of the item, what percent of the usage it has, and the processor it is
1040 on.
1041
1042 \item[2)]
1043 {\bf Control Panel} (located: bottom area)
1044 The panellets you adjust the scales in both the X and Y directions.
1045 The X direction is useful if you are looking at a large number of
1046 processors. The Y direction is useful if there are small-percentage
1047 items for a processor. The ``Reset'' button allows you to reset the 
1048 X and Y scales.
1049
1050 The ``Pie Chart'' button generates a pie chart representation (see
1051 figure \ref{piechart}) of the same information using averaged
1052 statistics but without idle time and communication CPU overheads.
1053
1054 \begin{figure}[htb]
1055 \center
1056 %\epsfig{figure=fig/piechart.eps,height=1in}
1057 \includegraphics[width=1.8in]{fig/piechart}
1058 \caption{Pie Chart representation of average usage}
1059 \label{piechart}
1060 \end{figure}
1061
1062 The ``Change Colors'' button lists all entry methods displayed on the
1063 main display and their assigned colors. It allows you to change those
1064 assigned colors to aid in highlighting entry methods.
1065
1066 The resource consumption of this view is moderate. Load times and
1067 visualization times should be relatively fast, but dismissing the tool
1068 may result in a very slight delay while \projections{} reclaims memory
1069 through Java's garbage collection system.
1070
1071 \end{itemize}
1072
1073 \subsubsection{Communication}
1074 \label{sec::communication}
1075
1076 The communication tool (see figure \ref{communication}) visualizes
1077 communication properties on each processor over a user-specified time
1078 range.
1079
1080 The dialog box of the tool allows you to specify the time period
1081 within which to load communication characteristics information. This
1082 dialog box is exactly the same as that of the Timeline tool (see
1083 section \ref{sec::timeline view}).
1084
1085 The main component employs the standard capabilities provided by
1086 \projections{}' standard graph (see \ref{sec::misc}).
1087
1088 The control panel allows you to switch between the following
1089 communication characteristics:
1090
1091 \begin{itemize}
1092 \item[-] Number of Messages Sent by entry methods (initial default view);
1093 \item[-] Number of Bytes Sent by entry methods;
1094 \item[-] Number of Messages Received by entry methods;
1095 \item[-] Number of Bytes Received by entry methods;
1096 \item[-] Number of Messages Sent externally (physically) by entry methods;
1097 \item[-] Number of Bytes Sent externally (physically) by entry methods;
1098 \item[-] and Number of hops messages travelled before being received
1099 by an entry methods. This is available when the runtime option {\tt -bgsize}
1100 (See section \ref{sec:startingUp}) is supplied.
1101 \end{itemize}
1102
1103 \begin{figure}[htb]
1104 \center
1105 %\epsfig{figure=fig/commhistogram.eps,height=4in}
1106 \includegraphics[width=4.0in]{fig/apoa1_512_CommProcessorProfile}
1107 \caption{Communication View}
1108 \label{communication}
1109 \end{figure}
1110
1111 This view uses memory proportional to the number of processors selected.
1112
1113 \subsubsection{Communication vs Time}
1114
1115 The communication over time tool (see figure \ref{communication-time})
1116 visualizes communication properties over all processors and displayed
1117 over a user-specified time range on the x-axis.
1118
1119 The dialog box of the tool allows you to specify the time period
1120 within which to load communication characteristics information. This
1121 dialog box is exactly the same as that of the Communication tool (see
1122 section \ref{sec::communication}).
1123
1124 The main component employs the standard capabilities provided by
1125 \projections{}' standard graph (see \ref{sec::misc}).
1126
1127 The control panel allows you to switch between the following
1128 communication characteristics:
1129
1130 \begin{itemize}
1131 \item[-] Number of Messages Sent by entry methods (initial default view);
1132 \item[-] Number of Bytes Sent by entry methods;
1133 \item[-] Number of Messages Received by entry methods;
1134 \item[-] Number of Bytes Received by entry methods;
1135 \item[-] Number of Messages Sent externally (physically) by entry methods;
1136 \item[-] Number of Bytes Sent externally (physically) by entry methods;
1137 \item[-] and Number of hops messages travelled before being received
1138 by an entry methods (available only on trace logs generated on the
1139 Bluegene machine).
1140 \end{itemize}
1141
1142 \begin{figure}[htb]
1143 \center
1144 %\epsfig{figure=fig/commhistogram.eps,height=4in}
1145 \includegraphics[width=4.0in]{fig/apoa1_512_CommTimeProfile}
1146 \caption{Communication View over Time}
1147 \label{communication-time}
1148 \end{figure}
1149
1150 This view has no known problems loading any range or volume of data.
1151
1152 \subsubsection{View Log Files}
1153
1154 This window (see figure \ref{viewlog}) lets you see a translation of a
1155 log file from a bunch of numbers to a verbose version.  A dialog box
1156 asks which processor you want to look at.  After choosing and pressing
1157 OK, the translated version appears. Note that this is {\it not} a
1158 standard processor field. This tool will only load {\it exactly} one
1159 processor's data.
1160
1161 \begin{figure}[htb]
1162 \center
1163 %\epsfig{figure=fig/viewlog.eps,height=4in}
1164 \includegraphics[width=2.5in]{fig/viewlog}
1165 \caption{Log File View}
1166 \label{viewlog}
1167 \end{figure}
1168
1169 Each line has:
1170 \begin{itemize}
1171 \item[-] a line number (starting at 0)
1172 \item[-] the time the event occurred at
1173 \item[-] a description of what happened.
1174 \end{itemize}
1175
1176 This tool has the following menu options:
1177
1178 \begin{itemize}
1179 \item {\bf File} has 2 options: {\it Open File} reloads the dialog box
1180 and allows the user to select a new processor's data to be loaded.
1181 {\it Close} closes the current window.
1182 \item {\bf Help} has 2 options: {\it Index} currently does not do anything.
1183 This will be addressed in a later release of \projections{}. {\it About}
1184 currently does not do anything. This will also be addressed in a later
1185 release of \projections{}.
1186 \end{itemize}
1187
1188 The tool has 2 buttons. ``Open File'' reloads the dialog box (described 
1189 above) and allows the user to select a new processor's data to be loaded.
1190 ``Close Window'' closes the current window.
1191
1192 \subsubsection{Histograms}
1193
1194 This module (see figure \ref{histogram}) allows you to examine the
1195 performance property distribution of all your entry points (EP). It
1196 gives a histogram of different number of EP's that have the following
1197 properties falling in different property bins:
1198
1199 The dialog box for this view asks the following information from the
1200 user. (Please refer to \ref{sec::misc} for information on special
1201 features you can use involving the various fields):
1202
1203 \begin{itemize}
1204 \item
1205 Processor(s): Choose which processor(s) you wish to visualize histogram
1206 information for.
1207 \item
1208 Start Time: Choose the starting time of interest. A time-based field.
1209 \item
1210 End Time: Choose the ending time of interest. A time-based field.
1211 \item
1212 Number of Bins: Select the number of property bins to fit frequency data
1213 under. A simple numeric field.
1214 \item
1215 Size of Bin: Determine (in units - microseconds or bytes) how large each
1216 bin should be. A simple numeric field.
1217 \item
1218 Starting Bin Size: Determine (in units - microseconds or bytes) how
1219 far to offset the data. This is useful for ignoring data that is too
1220 small to be considered significant, but could overwhelm other data
1221 because of the sheer numbers of occurrences. A simple numeric field.
1222 \end{itemize}
1223
1224 The dialog box reports the selection of bins as specified by the user
1225 by displaying the minimum bin size (in units - microseconds or bytes)
1226 to the maximum bin size. ``units'' refer to microseconds for time-based
1227 histograms or bytes for histograms representing message sizes.
1228
1229 Standard graph features can be employed for the main display of this
1230 view (see section \ref{sec::misc}). 
1231
1232 The following menu items are available in this tool:
1233
1234 \begin{itemize}
1235 \item {\bf File} offers 3 options: {\it Select Entry Points} currently
1236 does nothing. It is intended to behave similarly to the button ``Select
1237 Entries'' described below. This will be fixed in a later release of
1238 \projections{}. {\it Set Range} reloads the dialog box and allows the
1239 user to load data based on new parameters. {\it Close} closes the current
1240 tool window.
1241 \item {\bf View} provides 1 option: {\it Show Longest EPs} currently
1242 does nothing. It is intended to behave similarly to the button 
1243 ``Out-of-Range EPs'' and will be fixed in a later release of \projections{}.
1244 \end{itemize}
1245
1246 The following options are available in the control panel in the form
1247 of toggle buttons:
1248
1249 \begin{itemize}
1250 \item[-] Entry method execution time (How long did that entry method ran 
1251 for?)
1252 \item[-] Entry method creation message size (How large was the message
1253 that caused the entry method's execution?)
1254 \end{itemize}
1255
1256 \begin{figure}[htb]
1257 \center
1258 %\epsfig{figure=fig/histogram.eps,height=4in}
1259 \includegraphics[width=4.0in]{fig/histogram}
1260 \caption{Histogram view}
1261 \label{histogram}
1262 \end{figure}
1263
1264 The use of the tool is somewhat counterintuitive. The dialog box is
1265 created immediately and when the tool window is created, it is
1266 defaulted to a time-based histogram. You may change this histogram to
1267 a message-size-based histogram by selecting the ``Message Size'' radio
1268 button which would then update the graph using the same parameters
1269 provided in the dialog box. This issue will be fixed in upcoming
1270 editions of \projections{}.
1271
1272 The following features are, as of this writing, not implemented. They
1273 will be ready in a later release of \projections{}.
1274
1275 The ``Select Entries'' button is intended to bring up a color
1276 selection and filtering window that allows you to filter away entry
1277 methods from the count. This offers more control over the analysis
1278 (e.g. when you already know EP 5 takes 20-30ms and you want to know if
1279 there are other entry points also takes 20-30ms).
1280
1281 The ``Out-of-Range EPs'' button is intended to bring up a table
1282 detailing all the entry methods that fall into the overflow (last)
1283 bin. This list will, by default, be listed in descending order of time
1284 taken by the entry methods.
1285
1286 The performance of this view is affected by the number of bins the
1287 user wishes to analyze. We recommend the user limits the analysis to
1288 1,000 bins or less.
1289
1290 \subsubsection{Overview}
1291
1292 Overview (see figure \ref{overview}) gives users an overview of the
1293 utilization of all processors during the execution over a
1294 user-specified time range.
1295
1296 The dialog box of the tool allows you to specify the time period
1297 within which to load overview information. This dialog box is exactly
1298 the same as that of the Timeline tool (see section \ref{sec::timeline
1299 view}).
1300
1301 \begin{figure}[!ht]
1302   \centering
1303   \subfigure[Overview]{
1304     \includegraphics[width=3in]{fig/apoa1_512_overview}
1305     \label{overview}
1306   } 
1307   \subfigure[Overview with dominant Entry Method colors]{
1308     \includegraphics[width=3in]{fig/apoa1_512_overviewEPColored}
1309     \label{overview-ep}
1310   }
1311   \caption{Different Overview presentation forms.}
1312   \label{overview forms}
1313 \end{figure}
1314
1315 %\begin{figure}[htb]
1316 %\center
1317 %\epsfig{figure=fig/overview.eps,height=4in}
1318 %\includegraphics[width=4.0in]{fig/apoa1_512_overview}
1319 %\caption{Overview}
1320 %\label{overview}
1321 %\end{figure}
1322 %
1323 %\begin{figure}[htb]
1324 %\center
1325 %\epsfig{figure=fig/overview.eps,height=4in}
1326 %\includegraphics[width=4.0in]{fig/apoa1_512_overviewEPColored}
1327 %\caption{Overview with dominant Entry Method colors}
1328 %\label{overview-ep}
1329 %\end{figure}
1330
1331 This tool provides support for the following menu options:
1332
1333 \begin{itemize}
1334 \item {\bf File} provides 1 option: {\it Close} closes the current tool.
1335 \item {\bf Modify} provides 1 option: {\it Set Range} reloads the
1336 dialog box and allows the user to specify new parameters for rendering
1337 new overview information.
1338 \end{itemize}
1339
1340 The view currently hard codes the number of intervals to 7,000
1341 independent of the time-range desired.
1342
1343 Each processor has a row of colored bars in the display, different
1344 colors indicating different utilization at that time (White
1345 representing 100% utilization, shades of red representing other
1346 utilization (100% < utilization < 0%) and the background color
1347 representing 0% utilization. Moving a mouse over the graph will invoke
1348 a display of the processor usage of the specific processor at the
1349 specific time in the status bar below the graph. Vertical and
1350 horizontal zoom is enabled by two zooming bars to the right and lower
1351 of the graph. Panning is possible by clicking on any part of the
1352 display and dragging the mouse.
1353
1354 The ``by EP colors'' radio button provides more detail by replacing
1355 the utilization colors with the colors of the most significant entry
1356 method execution time in that time-interval on that processor
1357 represented by the cells (as illustrated in figure
1358 \ref{overview-ep}). 
1359 %Be warned that this particular view is very likely
1360 %a major visualization resource hog.
1361
1362 The Overview tool uses memory proportional to the number of processors
1363 selected. If an out-of-memory error is encountered, try again by
1364 skipping processors (e.g. {\tt 0-8191:2} instead of {\tt
1365 0-8191}). This should show the general application structure almost as
1366 well as using the full processor range.
1367
1368 \subsubsection{Animations}
1369
1370 This window (see figure \ref{animation}) animates the processor usage
1371 over a specified range of time and a specified interval size.
1372
1373 The dialog box to load animation information is exactly the same as
1374 that of the Graph tool (see section \ref{sec::graph view}).
1375
1376 \begin{figure}[htb]
1377 \center
1378 %\epsfig{figure=fig/animation.eps,height=3in}
1379 \includegraphics[width=2.5in]{fig/animation}
1380 \caption{Animation View}
1381 \label{animation}
1382 \end{figure}
1383
1384 A color temperature bar serves as a legend for displaying different
1385 processor utilizations as the animation progresses. Each time interval
1386 will have its data rendered as a frame. A frame displays in text on
1387 the top of the display the currently represented execution time of the
1388 application and what the size of an interval is.
1389
1390 Each selected processor is laid out in a 2-D plot as close to a square
1391 as possible. The view employs a color temperature ranging from blue
1392 (cool - low utilization) to bright red (hot - high utilization) to
1393 represent utilization.
1394
1395 You may manually update the frames by using the ``$<<$'' or ``$>>$''
1396 buttons to visualize the preceding or next frames respectively. The
1397 ``Auto'' button toggles automatic animation given the desired refresh
1398 rate.
1399
1400 The ``Frame Refresh Delay'' field allows you to select the real time
1401 delay between frames. It is a time-based field (see section
1402 \ref{sec::misc} for special features in using time-based
1403 fields).
1404
1405 The ``Set Ranges'' button allows you to set new parameters for this
1406 view via the dialog box.
1407
1408 This view has no known performance issues.
1409
1410 \subsubsection{Time Profile Graph}
1411
1412 The Time Profile view (see figure \ref{time profile}) is a
1413 visualization of the amount of time contributed by each entry method
1414 summed across all processors and displayed by user-adjustable time
1415 intervals.
1416
1417 Time Profile's dialog box is exactly the same as that of the Graph
1418 tool (see section \ref{sec::graph view}).
1419
1420 \begin{figure}[htb]
1421 \center
1422 %\epsfig{figure=fig/timeprofile.eps,height=4in}
1423 \includegraphics[width=4.0in]{fig/timeprofile}
1424 \caption{Time Profile Graph View}
1425 \label{time profile}
1426 \end{figure}
1427
1428 Standard graph features can be employed for the main display of this
1429 view (see section \ref{sec::misc}).
1430
1431 Under the tool options, one may:
1432
1433 \begin{itemize}
1434 \item[-] Filter the set of entry methods to be displayed on the graph via
1435 the ``Select Entry Points'' button. One may also modify the color set used
1436 for the entry methods via this option.
1437 \item[-] use the ``Select New Range'' button to reload the dialog box
1438 for the tool and set new parameters for visualization (eg. different
1439 time range, different set of processors or different interval sizes).
1440 \item[-] store the current set of entry method colors to disk (to the
1441 same directory where the trace logs are stored). This is done via the
1442 ``Save Entry Colors'' button.
1443 \item[-] load the stored set of entry method colors (if it exists)
1444 from disk (from the same directory where the trace logs are
1445 stored). This is done via the ``Load Entry Colors'' button.
1446 \end{itemize}
1447
1448 Time Profile also reacts to the presence of data about AMPI
1449 functions (See section \ref{sec::AMPI functions}). When such data is
1450 detected, an extra tabbed window displays a graph similar to entry
1451 method profiles, but for AMPI functions only.
1452
1453 This tool's performance is tied to the number of intervals desired by
1454 the user. We recommend that the user stick to visualizing 1,000
1455 intervals or less.
1456
1457 \subsubsection{User Events Profile}
1458
1459 The User Events view is essentially a usage profile (See section
1460 \ref{sec::usage profile}) of bracketed user events (if any) that were
1461 recorded over a specified time range. The x-axis holds bars of data
1462 associated with each processor while the y-axis represents the time
1463 spent by each user event. Each user event is assigned a color.
1464
1465 \begin{figure}[htb]
1466 \center
1467 \includegraphics[width=4.0in]{fig/apoa1_128_userEventsView}
1468 \caption{User Events Profile View}
1469 \label{user event profile}
1470 \end{figure}
1471
1472 It is important to note that user-events can be arbitrarily
1473 nested. The view currently displays information based on raw data
1474 without regard to the way the events are nested. Memory usage is
1475 proportional to the number of processors to be displayed.
1476
1477 \input{View_Outlier}
1478
1479 \subsubsection{Multirun Analysis}
1480
1481 \subsubsection{Function Tool}
1482 \label{sec::function tool}
1483 The Function Tool view presents a graph that is a usage profile (See
1484 section \ref{sec::usage profile}) of AMPI function information. This
1485 view allows the analyst to choose to display the time spent by each
1486 function or the number of calls made over the selected time range.
1487
1488 In the case of AMPI functions, the events are properly nested. The
1489 information displayed is currently that of {\em inclusive time}
1490 (i.e. if function B's calls are nested within function A's, the time
1491 spent in function B contribute to both function B's and function A's
1492 displayed performance information). There are plans to implement the
1493 presentation of AMPI function information based on {\em exclusive
1494 time} (i.e. time within functions are computed by subtracting the
1495 measured time spent minus the time spent by any calls to nested
1496 functions).
1497
1498 %\subsubsection{POSE Analysis}
1499
1500 \subsubsection{AMPI Usage Profile}
1501
1502 The AMPI Usage Profile view presents a graph similar to Function
1503 Tool's (See section \ref{sec::function tool}) with several
1504 modifications:
1505
1506 \begin{enumerate}
1507 \item In it's per-processor mode, displayed via the tabbed window
1508 ``Per Processor'', the information displayed includes the time spent
1509 by other events outside of AMPI. This is displayed as a white bar
1510 marked ``Others'' when moused-over. This allows the analyst to compare
1511 the time spent by events within AMPI functions along with other
1512 recorded events. In contrast, Function Tool shows only AMPI function
1513 events.
1514 \item In it's per-function mode, displayed via the tabbed window ``Per
1515 Function'', the information is displayed with each bar on the x-axis
1516 showing the percentage utilization for a different AMPI function.
1517 \end{enumerate}
1518
1519 \input{View_NoiseMiner}
1520
1521 \subsection{Miscellaneous features}
1522 \label{sec::misc}
1523
1524 \subsubsection{Standard Graph Display Interface} 
1525
1526 A standard graph display (an example of which can be found with the
1527 Main Summary Graph - figure \ref{mainwindow}) has the following
1528 features:
1529
1530 \begin{itemize}
1531 \item[-] {\bf Graph types} can be selected between ``Line Graph'' which
1532 connects each data point with a colored line representing the
1533 appropriate data entry. This information may be ``stacked'' or
1534 ``unstacked'' (controlled by the checkbox to the right). A ``stacked''
1535 graph places one data point set (Y values) on top of another. An
1536 ``unstacked'' graph simply uses the data point's Y value to directly
1537 determine the point's position; ``Bar Graph'' (the default) which
1538 draws a colored bar for each data entry and the value of the data
1539 point determines its height or starting position (depending on whether
1540 the bar graph is ``stacked'' or ``unstacked''). A ``Bar Graph''
1541 displayed in ``unstacked'' mode draws its bars in a tallest to
1542 shortest order so that the large Y values do not cover over the small
1543 Y values; ``Area Graph'' is similar to a ``Line Graph'' except that the
1544 area under the lines for a particular Y data point set is also colored
1545 by the data's appropriate color. ``Area Graph''s are always stacked.
1546 \item[-] {\bf x-scale} allows the user to scale the X-Axis. This can be
1547 done by directly entering a scaling factor in the text field (simple
1548 numeric field - see below) or by using the ``$<<$'' or ``$>>$'' buttons
1549 to increase or decrease the scale by 0.25 each time. The ``Reset'' button
1550 changes the scale factor back to 1.0. A scrollbar automatically appears
1551 if the scale factor causes the canvas to be larger than the window.
1552 \item {\bf y-scale} allows the user to scale the Y-Axis. This functions 
1553 similarly to the {\bf x-scale} feature where the buttons and fields are
1554 concerned.
1555 \end{itemize}
1556
1557 \subsubsection{Standard Dialog Features}
1558
1559 \begin{figure}[htb]
1560 \center
1561 %\epsfig{figure=fig/standard_dialog.eps,height=4in}
1562 \includegraphics[width=2.5in]{fig/standard_dialog}
1563 \caption{An example Dialog with standard fields}
1564 \label{standard dialog}
1565 \end{figure}
1566
1567 Figure \ref{standard dialog} shows a sample dialog box with standard
1568 features. The following are standard features that can be employed in
1569 such a dialog box:
1570
1571 \begin{itemize}
1572 \item[-] {\bf Moving from field to field} via the tab key causes the
1573 dialog box update the last field input by the user. It also performs a
1574 consistency check. Whenever it finds an inconsistency, it will move
1575 mouse focus onto the offending field, disabling the ``OK'' button so
1576 as to force the user to fix the inconsistency. Examples of
1577 inconsistency includes: input that violates a field's format; input
1578 whose value violates constraints (eg. start time larger than end
1579 time); or out-of-range stand-alone values.
1580 \item[-] {\bf Available buttons} include ``OK'' which confirms the
1581 user's choice of parameters. This button is only activated if the
1582 dialog box considers the parameters' input to be
1583 consistent. ``Update'' causes the dialog box to update the last field
1584 input by the user and perform a consistency check. This is similar in
1585 behavior to the user tabbing between fields. ``Cancel'' closes the
1586 dialog box without modifying any parameters if the tool has already
1587 been loaded or aborts the tool's load attempt otherwise.
1588 \item[-] {\bf Parameter History} allows the user to quickly access
1589 information for all tools for a set of frequently needed time
1590 periods. An example of such a use is the desire by the analyst to view
1591 a particular phase or timestep of a computation without having to
1592 memorize or write on a piece of paper when exactly the phase or
1593 timestep occurred.
1594
1595 It consists of a pull-down text box and 2 buttons. ``Add to History
1596 List'' adds the current time range to the pull-down list to the left
1597 of the button. The dialog box maintains up to 5 entries, replacing
1598 older entries with newer ones. ``Remove Selected History'' removes the
1599 currently selected entry in the history list. ``Save History to Disk''
1600 stores current history information to the file ``ranges.hst'' in the
1601 same directory where your logs are stored. Note that you will need
1602 write access to that directory to successfully store history
1603 information. A more flexible scheme is currently being developed and
1604 will be released in a later version of \projections{}. Clicking on the
1605 pull-down list allows the user to select one out of up to 5 possible
1606 time ranges. You can do so by moving the mouse up or down the
1607 list. Clicking on any one item changes the start and end times on the
1608 dialog box.
1609 \end{itemize}
1610
1611 \subsubsection{Data Fields}
1612
1613 Throughout \projections{} tools and dialog boxes (see sample figure
1614 \ref{standard dialog}), data entry fields are provided. Unless
1615 otherwise specified, these can be of the following standard field with
1616 some format requirements:
1617
1618 \begin{itemize}
1619 \item[-] {\bf Simple numeric fields}: An example can be found in
1620 figure \ref{standard dialog} for ``Number of Bins:''. This field expects
1621 a single number.
1622 \item[-] {\bf Time-Based Field}: An example can be found in figure
1623 \ref{standard dialog} for ``Start Time:''. This field expects a single
1624 simple or floating point number followed by a time-scale modifier. The
1625 following modifiers are supported: {\it none} - this is the default
1626 and means the input number represents time in microseconds. A whole
1627 number is expected; {\it The characters ``us''} - the input number
1628 represents time in microseconds. A whole number is expected; {\it The
1629 characters ``ms''} - the input number represents time in
1630 milliseconds. This can be a whole number or floating point number; or
1631 {\it The character ``s''} - the input number represents time in
1632 seconds. This can be a whole number or floating point number.
1633 \item[-] {\bf Processor-Based Field}: An example can be found in
1634 figure \ref{standard dialog} for ``Processors:''. This field expects a
1635 single whole number; a list of whole numbers; a range; or a mixed list
1636 of whole numbers and ranges. Here are some examples which makes the
1637 format clearer:
1638
1639    eg: Want to see processors 1,3,5,7:  Enter {\tt 1,3,5,7}
1640
1641    eg: Want to see processors 1,2,3,4:  Enter {\tt 1-4}
1642
1643    eg: Want to see processors 1,2,3,7:  Enter {\tt 1-3,7}
1644
1645    eg: Want to see processors 1,3,4,5,7,8: Enter {\tt 1,3-5,7-8}
1646
1647 Ranges also allow skip-factors. Here are some examples:
1648
1649    eg: Want to see processors 3,6,9,12,15: Enter {\tt 3-15:3}
1650
1651    eg: Want to see processors 1,3,6,9,11,14: Enter {\tt 1,3-9:3,11,14}
1652
1653 This feature is extremely flexible. It will normalize your input to a
1654 canonical form, tolerating duplication of entries as well as
1655 out-of-order entries (ie. {\tt 4,6,3} is the same as {\tt 3-4,6}).
1656 \end{itemize}
1657
1658 \section{Known Issues}
1659 \label{sec::known issues}
1660
1661 This section lists known issues and bugs with the \projections{}
1662 framework that we have not resolved at this time.
1663
1664 \begin{itemize}
1665 \item
1666 \charmpp{} scheduler idle time is known to be incorrectly recorded on
1667 the BG/L machine at IBM TJ Watson.
1668 \item
1669 End-of-Run analysis techniques (while tracing applications) are
1670 currently known to hang for applications that make multiple calls to
1671 traceBegin() and traceEnd() on the same processor through multiple
1672 \charmpp{} objects.
1673 \end{itemize}
1674
1675 \end{document}