*** Last Update: November 2007 by Isaac Dooley

TO COMPILE PROJECTIONS:
----------------------

1) Make sure the JDK commands "java", "javac" and "jar" 
   are in your path. You should use at least java version 1.5, 
   and your java and javac should be of the same version.

2) Type "ant"

   Ant is a java tool similar to make which is available on most platforms.

3) The following files will be located in 'bin':

      projections           : Starts projections, for UNIX machines
      projections.bat       : Starts projections, for Windows machines
      projections.jar       : archive of all the java and image files 

   
TO RUN PROJECTIONS:
------------------

1.) From any location, type
	> PROJECTIONS_LOCATION/bin/projections

where PROJECTIONS_LOCATION is the path to the main projections
directory.  

HOW TO USE PROJECTIONS:
-----------------------
Projections is a visualization tool to help you understand and analyze what it
happening in your parallel (Charm++) program.  To use Projections, you first
have to make sure your program is compiled with the Projections tracemode.
Usually, this means adding '-tracemode projections' to your compile options.
When you run your program compiled with this tracemode, a log file will be
created for each processor.  An additional state file will also be created.  The
names of the log files will be NAME.#.log, where NAME is the name of your
executable and # is the processor #.  The name of the state file is NAME.sts.

If your environment is set up correctly, as described in the previous section,
all you have to do to start Projections is type 'projections' at the prompt.

When Projections starts, you will see the main window with a title and 
six buttons:

   1. Open File
   2. Graphs
   3. Timelines
   4. Usage Profile
   5. Animations
   6. View Log Files
   
Clicking on any of the buttons will bring up the appropriate next window, as 
described in the following sections.  Initially, only the Open File button
will be active.

1. Open File
------------
   Clicking on the Open File button brings up a dialog box to let you select
   the location of the data you want to look at.  Navigate to the directory 
   containing your data and select the *.sts file.  Click on 'OK'.  If you
   have selected a valid file, Projections will load in some preliminary data
   from the files and then activate the rest of the buttons in the main window.
   If your file is invalid, you will be shown an error dialog.

2. Graphs
---------
   The Graphs window is where you can analyze your data by breaking it into
   any number of intervals and look at what goes on in each of those intervals.

   When the Graph Window first appears, a dialog box will also appear, asking
   you what interval settings you want to use.  It will show you the total
   amount of time your program run took (in microseconds) and ask you to enter
   either the interval size you want or the number of intervals you want.
   Entering a number in either box will recalculate the other number, so you
   will know both items. Click on 'OK' when you are satisifed with your choice.
   Your data will then be analyzed. 
   
   The amount of time to analyze your data depends on several factors, including
   the number of processors, number of entries, and number of intervals you have
   selected.  Although a progress meter has not been implemented at this time,
   you can look at the console window to see which log file is being analyzed.
   Even for large amounts of data, this step should not take more than a few
   minutes, though.

   The Graph Window has 3 components in its display:
   1) Display Panel: 
      - Largest Component in top/left corner
      - Displays title, graph, and axes
      - Allows you to toggle display between a line graph and a bar graph
      - Allows you to scale the graph along the X-axis.  You can either enter
        a scale value >= 1.0 in the text box, or you can use the << and >>
        buttons to increment/decrement the scale by .25.  Clicking on Reset
        sets the scale back to 1.0.  When the scale is greater than 1.0, a
        scrollbar will appear along the bottom of the graph to let you
        scroll back and forth.
        
   2) Legend Panel:
      - Top right side of the display
      - Shows what is currently being displayed on the graph and what color it
        is.
      - Click on the 'Select Display Items' button to bring up a window to
        add/remove items from the graph and to change the colors of the items.
        * The Select Display Items window shows a list of items that you can
          display on the graph.  There are 3 main sections:
            System Usage, System Msgs, and User Entries
          The System Usage and System Msgs are the same for all programs.  The
          User Entries section has program-specific items in it.
        * Click on the checkbox next to an item to have it displayed on the
          graph.
        * Click on the colorbox next to an item to modify its color.
        * Click on 'Select All' to choose all of the items
        * Click on 'Clear All' to remove all of the items
        * Click on 'Apply' to apply you choices/changes to the graph
        * Click on 'Close' to exit 

   3) Control Panel:
      - Bottom of the display
      - Allows you to toggle what is displayed on the X-axis.  You can either
        have the x-axis display the data by interval or by processor.
      - Allows you to toggle what is displayed on the Y-axis.  You can either
        have the y-axis display the data by the number of msgs sent or
        by the amount of time taken.
      - Allows you to change what data is being displayed by iterating through
        the selections.  If you have selected an x-axis type of 'interval', 
        that means you are looking at what goes on in each interval for a
        specific processor.  Clicking on the <<, <, >, >> buttons will change
        the processor you are looking at by either -5, -1, +1, or +5.
        Conversely, if you have an x-axis of 'processor', then the iterate
        buttons will change the value of the interval that you are looking at
        for each processor.
      - Allows you to indicate which intervals/processors you want to examine.
        Instead of just looking at one processor or one interval, the box and
        buttons on the right side of this panel let you choose any number or
        processors/intervals to look at.  Just enter the number(s) in the box.
        If you want to look at multiple items, separate them with commas.  If
        your selections include a range of items, you can separate those with 
        a dash.  
        
        ex: Want to see processors 1,3,5,7:  Enter 1,3,5,7
        ex: Want to see processors 1,2,3,4:  Enter 1-4
        ex: Want to see processors 1,2,3,7:  Enter 1-3,7 

        Clicking on 'Apply' updates the graph with your choices.
        Clicking on 'Select All' chooses the entire range.  When you select more
        than one set of data to display, the graph will show the TOTAL amount of
        the data for all of those items, EXCEPT for the processor usage, which
        shows the average amount.
   

3. Timelines
------------
   The Timelines window lets you look at what a specific processor is doing at
   each moment of the program.
   
   When the Timelines window first appears, a dialog box appears along with it.
   The box asks for the following information:

   - Processor(s):  Choose which processor(s) you want to see a timeline for.
                    To enter multiple values, separate them with a comma or a
                    dash (for ranges).  (See the Graphs section for examples)
   - Begin Time  : Choose what time you want your timeline to start at.
   - End Time    : Choose what time you want your timeline to end at.
   - Length      : Choose the length of your timeline.
   
   The dialog box tells you what the valid processor choices are as well as what
   the valid time ranges are.

   Instead of entering a BeginTime, you can have the dialog box choose a
   BeginTime for you based on the occurrence of a specific entry.  To do this,
   you go to the bottom portion of the dialog box and select an entry to find an
   occurrence of.  Then, you choose the processor you want to find an occurrence
   on, and which occurrence you want to find (N).  Click on 'Search for Begin
   Time'.  The dialog box will display a message telling you if your occurrence
   was found and when it was found.  If valid, the time is automatically entered
   as the begin time.
   
   When you are satisifed with your time and processor ranges, click on 'OK'.
   Projections will then get the Timeline data for you.  The time for this step
   depends on the number of items in your time range and the number of
   processors you have chosen.  
  
   The Timeline Window consists of two parts:
  
   1) Display Panel:  
      This is where the timelines are displayed and is the largest portion of
      the window.  The time axes are displayed at the top and the bottom of the
      panel, and the units are microseconds.  The left side of the panel shows
      the processor labels.  Underneath each label is a percentage telling you
      what amount of the total time in your timeline was actually spent working
      on this program.  The timeline itself consists of colored bars for each
      work item.  Placing the cursor over one of these bars will bring up a
      pop-up window telling you the name of that item, the begin time, the end
      time, and the total time.  It will also tell you what amount of time was
      spent packing, how many messages were created during this work item, and
      which processor created this item.  If you click on the item, a window
      will appear telling you similar information to the pop-up window.  This
      window will also list all of the messages created during this work item,
      and it will tell you what time they were sent at and to which entry.

   2) Control Panel:  
      - At the bottom of the window
      Checkboxes:
      - Display Pack Times
        Lets you toggle display of Time spent packing
      - Display Message Creations
        Lets you toggle display of message creations. These are represented 
        by little vertical lines at the time a message was created.
      - Lets you toggle display of idle time
      Buttons:
      - Select Ranges
        Brings up the initial dialog box
      - Change Colors
        Lets you change colors for the work items
      - Scale
        Enter a scale >= 1.0 in the box, or click on the << and >> buttons to
        adjust the scale by 0.25 increments.  Click on Reset to set the scale
        back to 1.0
  


4. Usage Profile:
-----------------
   The Usage Profile window lets you see percentage-wise what each processor
   spends its time on during a specified period.
   
   When the window first comes up, a dialog box appears asking for the
   processor(s) you want to look at as well as the time range you want to look
   at.  This is similar to the dialog for the Timelines.
   
   The bottom portion of the Usage Profile window lets you adjust the scales in
   both the X and Y directions.  The X direction is useful if you are looking at
   a large number of processors.  The Y direction is useful if there are
   small-percentage items for a processor.
   
   The left side of the display shows a scale from 0% to 100%.  The main part of
   the display shows the statistics.  Each processor is represented by a
   vertical bar.  The top of the bar always shows the overhead time.  Below that
   is always (if exists) the idle time and then the message packing/unpacking
   times.  The rest of the bar is ordered from the bottom with the largest
   percentage items being closest to the bottom.  If you place the cursor over a
   portion of the bar, a pop-up window will appear telling you the name of the
   item, what percent of the usage it has, and the processor it is on.
   

5. Animations:
--------------
   This window animates the processor usage by displaying
   different colors for different amount of usage.

   The left box allows you to select the real time between frames;
   the right box the processor time between frames.
   

6. View Log Files:
------------------
   This window lets you see a translation of a log file from a bunch of numbers
   to an English version.  A dialog box asks which processor you want to look
   at.  After choosing and pressing OK, the translated version appears.  
   
   Each line has:
   - a line number (starting at 0)
   - the time the event occurred at
   - a description of what happened.
