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