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