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