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