
1, Before using Jumpshot, you need to know where the SLOG file is.
   typically they have the file extention, slog.  The SLOG file 
   should be generated by "utemerge".  If you would like
   to see the statistics of the job, you also need a "tsv" file.
   "utestat".  For further details, read ibm_doc/ute.man on
   how to generate the SLOG and tsv files in UTE environment.

2, To use Jumpshot, one needs to install the jumpshot first.
   To install jumpshot, one need to compile slog_api's java API
   slog_api.jar, and the actual GUI code, preview.jar and jumpshot.jar.  

   ---- In order to build Jumpshot, we need to build three jar files.
        The simplest way is to cd to directory GUI.  Update GUI_HOME 
        and SLOG_HOME in file GUI/Make.conf."OSname" to reflect where 
        these 2 directories are located. And type make.  On SGI, one 
        might need to do a gmake.  If everything goes well, there 
        should be 3 jar files generated in GUI/bin.  Check if 
        slog_api.jar, preview.jar and jumpshot.jar in GUI/bin are all 
        updated.
      
        If things do NOT go well.  One may need to build individual
        jar files separately.  One is the SLOG-API's java interface 
        and actual GUI codes.  slog_api/src-java/slog.jar which are 
        built from sources in slog_api/src-java,  GUI/bin/preview.jar 
        which are built from sources in GUI/src/GraphicPreview, and 
        GUI/bin/jumpshot.jar which are built from sources in GUI/src/main.
        So one needs to cd to the slog_api/src-java and build slog.jar
        by typing "make".  one may need to to set all the JAVA related
        environmental variable(s) so javac and jar are defined in your
        PATH before typing make.  slog.jar does NOT depend on Swing.
        Once slog.jar is built, one can proceed to build jumpshot.jar
        by cd'ing to the top level directory GUI ( i.e. cd ../../GUI ).
        Edit Make.conf."OSname" to define JAVA_HOME where JAVA resides.

        On AIX, JAVA_HOME should be set to point to /usr/jdk_base.
        Also be sure the "java -fullversion" return a build data later
        than or equal to 
        "JDK 1.1.6 IBM build a116-19990115 (JIT enabled: jitc)"

        Note: ignore the warning messages during compilation of 
        jumpshot.jar.

3, There are 2 ways to run jumpshot.

   a, using the supplied script in GUI/bin:
      If you have followed the instruction to build the 2 jar files,
      cd to GUI/bin and run Jumpshot by entering
      "jumpshot slog_filename", e.g.

      /homes/chan/jumpshot/GUI/bin> jumpshot ../logfiles/merge.slog

   b, run jumpshot directly using "java"
      Set the CLASSPATH in your local shell to where slog.jar, jumpshot.jar
      and swing.jar, GraphicPlotter and UTEStatsViewer are located.  And 
      you can invoke the jumpshot as 
      "java jumpshot slog_filename frame_number".

   For further details, Read ~GUI/README.slog

4, When Jumsphot is running, you will first see a small window
   titled "Jumpshot".   The following is extracted from the
   GUI/bin/jumpshot.help

------------------------------------------------------------------------------
***************
Jumpshot Window
***************
The first main window shows up when "jumpshot" is executed

In the top window menu bar, there are 4 pull-down menus.  They
are FILE, DISPLAY, SYSTEM and HELP menus.

FILE
 New Frame       - Open a new Jumpshot Window
 Select Logfile  - Opens up a window that allows you to select a logfile
                   to view.
 Exit            - Quit Jumpshot

DISPLAY
 Select type of display jumpshot should show.
 Currenyly, only the Time Lines display is usable.  Mountain display has been
 disabled.

SYSTEM
 - Select look and feel of choice. Certain look and feel may not be
   supported by the JVM that you are using.
 - Enable or disable tool tips. Tool tips are small descriptions that
   become visible when user places mouse over some region like a button,
   window, etc.

HELP
 Manual          - Opens a window containing this document
 About           - Gives a short description of Jumpshot


Also there are LOGFILE panel and Read button.

LOGFILE
 Contains name of loaded logfile

READ
 Read in the logfile for processin
------------------------------------------------------------------------------

5,  Click the FILE pull down menu to select the file.
    Once the file is selected by double clicking on filename
    or clicking the OPEN button.  The "View & Frame Selector"
    window will pop up.   Again extract from the GUI/bin/jumpshot.help


------------------------------------------------------------------------------
****************************
View & Frame Selector Window
****************************
After the READ button in the Jumpshot window has been pressed, the window
titled "View & Frame Selector" will show up.

In this window, you have a Graphical Frame Preview Selector which has
two pull-down menus, FILE and GRAPH.  The Graphical Preview contains
a simple graph of event count versus the duration of the whole logfile.

Read the description of various options in GUI/src/GraphicPreview/README

File
 View Statistics - Open the UTE statistics viewer
 Close           - Close the View & Frame Window

Graph
 Type  - Graphical preview's display type
   Bar   - ( default ), cummulative Histograms
   Line  - curves

 Rescale - rescaling of Y-axis
   On    - automatic rescaling of y-axis
   Off   - retains the current scale of the y-axis

Data Sets
 All     - display all data sets
 None    - clears all data sets in the graph

Zoom
 In      - magnify the view around selected view point
 Out     - demagnify the view around selected view point
 Reset   - reset the magnification to the orginal scale

Legend
 Display - display the legend for each data set.
 Hide    - hide the Legend dialog box


In the Graphical Preview, there is a Red Line which marks the middle of
the frame to be displayed and also marks the view point to be used as
a reference point during zoom in and out.

In this window, there are 2 sets of radio buttons to define the properties
of the frame to be displayed.  One is titled as "Connectivity Options"
which currently only allow "Disconnected States", and the other one is
titled as "View Options" which currently allows 3 possible views -
Application View, Thread View and Processor View.

Application View: MPI rank ID is used as Y axis label in the displayed
                  frame later.

Thread View     : MPI rank ID and logic thread ID, i.e. local thread ID,
                  are used as the Y axis label in the displayed frame.
                  Currently the 2 integers are encoded as one in the Y
                  axis label through the equation :
                  thread_Y_label = rank_ID * 1000 + logic_thread_ID.

Processor View  : Node ID and local cpu ID are used as the Y axis label
                  in the displayed frame.  Currently the 2 integers are
                  encoded as one in the Y axis label through the equation:
                  processor_Y_label = node_ID * 1000 + local_CPU_ID.

Below these, there are buttons and textfield that allow user to manuelly
select frame to display.  It is particularly important when the number
of the pixels in the Graphical Preview is less than the number of
frames available in the logfile.  In this case, the frame buttons are used
to fine tune the frame of logfile that user wishes to view.

The PREVIOUS frame button decrements the frame index.
The NEXT     frame button increments the frame index.
The only way to display a frame is to click on the display button.
Then a Time Line Window with the properties selected will pop up

Also the textfield next to "Current frame =" under the Frame Information
panel allows one to directly type in a frame index to view.  The Red
Line Marker in the Graphical Preview and the Frame Buttons will be updated
according.  The frame index should be between 0 and ( Number of frames - 1 ).

The only way to display a frame is to click on the display button.
Then a Time Line Window with the properties selected will pop up.

The "View Statistics" option in under the FILE pull-down menu will
invoke the statistical viewer to process the *.tsv file.  Read the
~/ibm_doc/README.viewstat for further detail.
------------------------------------------------------------------------------

6,  After the display button is clicked, the display button turns
    dark grey.  This indicates that the code is working to convert
    the raw data into a displayable graphical format.  It takes
    about 30 seconds for a Time Lines Window to pop up.  There
    are many operations allowed in the Time Lines Windows.  Here
    is the extract from the GUI/bin/jumpshot.help

------------------------------------------------------------------------------
*****************
Time Lines Window
*****************

Zoom Operations:
---------------
IN, OUT          - These buttons are used to zoom in and out horizontally
                   Zooming out of the frame __before__ zooming in will
                   produce unreasonable result.

RESET            - Reset the time range of the displayed frame to the
                   default range.

Miscellaneous Operations:
------------------------
PRINT            - Clicking on this button will bring up the 'Print Dialog'
                   window where you will be able to choose printer-related
                   options, and print display of this window.
                   It is NOT working yet.

OPTIONS          - Clicking on this button will bring up the 'Options' window


Hidden Operations:
-----------------
Y-axis LABEL     - Double Clicking on label will bring up 'Adjust Process'
                   window.

SCROLL BAR       - Use to move forward or backward in time.
                   Usually, one scrolls by dragging the scroll bar by
                   clicking on the empty space in the direction where
                   one wants scroll bar to move to.  Clicking on the
                   arrows in the scroll bar will only move scroll bar
                   1 pixel at a time.

KEYBOARD KEYS

Z or z           - Set the center of the Zoom operation. 
                   Lock Zoom at point where mouse is positioned

T or t           - Set a time marker at point where mouse is positioned

MOUSE BUTTON     - Clicking of any mouse button on a specific state instance
                   on display will bring up 'State Info' Window which displays
                   information on that state instance. Clicking on this window
                   will dispose it.
                 - Clicking of any mouse button on the circle at origin of a
                   message will open up a window containing information on that
                   message. Clicking on this window will dispose it.

**************
Options Window
**************

LINE DISPLAY     - Turn off/on zoom lock line and elapsed time line. These are
                   vertical lines that you see in Display Window.

DISPLAY OPTIONS  - Add/Cut time lines or mountain ranges to/from display window
                   Again Mountains range is NOT usable.

ZOOM & TIME      - Zoom Factor: Length of display is multiplied by this value
                   when you zoom in. Lenght of display is divided by this value
                   when you zoom out.
                   From and To are starting and ending times in viewport
                   respectively.
                   To change these values edit and press enter.

NESTING          - Nest Factor: Measure of difference between heights of
                   successive nested levels. Larger the value larger the
                   difference. To change value edit and press enter.
                   DO OPTIMAL NESTING: Calculates most appropriate nest factor
                   and implements it.

*********************
Adjust Process Window
*********************

This window contains options used to manipulate processes.

SCROLLBAR        - This scrollbar is used to move current process forward and
                   backward in time.

FORWARD/BACKWARD - This button is used to determine direction in which current
                   process is to be moved

RESET            - This causes the process to take up its original position in
                   time.

DISPLAY          - This checkbox controls display status of selected process.
                   A process can be selected from 'AVAILABLE' list.

SWAP             - This causes selected process to be swapped with current
                   process.

DELETE           - Selected process is deleted. Deleted process is removed from
                   'AVAILABLE' list and placed in 'DELETED' list.

INSERT           - Causes selected process from 'DELETED' list to be placed
                   just above selected process from 'AVAILABLE' list.


*****************
State Definitions
*****************

Intially below Display Window, process states region contains buttons for
each state and messages. This region can be attached to any of the 4 sides of
Display Window. It can also be torn away from Display Window and made to form
its own window.

ALL STATES ON    - Turn on all possible states

ALL STATES OFF   - Turn off all possible states

[State]          - Clicking on button for any state will show histogram
                   window for that state.

checkbox         - Use this to enable/disable this state's display.

**********************
state histogram Window
**********************

This window contains information on associated state. The histogram
given is the plot of number of state instances (y-axis) versus duration in
seconds (x-axis).
------------------------------------------------------------------------------

7, One can have several Time Lines windows displayed simultaneously
   as long as the JVM has enough memory.  This feature allows one
   to compare the different frame with identical views or identical
   frame with different views.

8, For further details of code, read the READMEs in the slog_api,
   slog_api/src, GUI, GUI/src, GUI/src/GraphicPreview and GUI/src/main.




