The Emily Users' Guide (date of last modification: 2/26/94)

	This guide is broken down into five parts:  what emily is, how to
run emily, the different types of windows emily uses, the different 
display areas, and emily's menu options.  If you have any suggestions
or complaints about this document, please contact tloos@cs.indiana.edu.

0. What is emily?

   emily is a tool for visualizing sparse matrices using either UN*X or Matlab.
The UN*X version accepts input in Harwell-Boeing (HB) sparse matrix format.
The Matlab version of emily can be used with HB matrix files, or to look at
ether sparse or dense Matlab matrices.

1. How to Run emily 

The UN*X command line usage is:  

   % emily [hb_file_name] 

   where "hb_file_name" is a file containing a sparse matrix specified in 
HB format. This file must use the five line header specified 
in the 1992 "Users's Guide for the Harwell-Boeing Sparse Matrix Collection
(Release I)."  The HB file is read and the sparse matrix is displayed.   If 
no filename is specified, a dense matrix based on $a_{ij} = i + j$ will be 
calculated and displayed.

The Matlab version of emily is executed as: 

    >> emily(M)  

   where M is a matrix. 

   If M is a string matrix, it is interpreted as a filename.  The file, 
which must contain a sparse matrix in HB format, is read in and the sparse 
matrix is displayed.

   If M is a sparse or dense matrix, its values are displayed. 

   Both versions use the same user interface and display layout.

2. Window Types

   emily has two types of windows: the main window and zoom windows.  The
main window is created on invocation of emily. Zoom windows are created by 
performing a zoom operation, described in Section 3.2.

   Generally, a zoom window and the main window are the same.  But, there
are some important differences, which will be pointed out as they come up.

3. Display Areas

   emily has several display areas and various new windows can be
created to help focus in on submatrices and to give some additional information
about specific points in the matrix.


3.1. Main Display Area

   The main display area shows the (sub)matrix of interest using the selected 
colormap and background color. Zero values are displayed using the background 
color.

   The matrix is displayed with the upper left corner as matrix coordinate
(0,0) and the lower right corner as matrix coordinate (NR,NC), where NR is
the number of rows in the input matrix and NC is the number of columns 
in the input matrix.  In other words, the matrix is displayed as if it were 
in CSR (Compressed Sparse Row) format, even though the Harwell-Boeing format
is CSC (Compressed Sparse Column).

   If the input matrix consists of solely two values (usually 0 and 1), then
emily renders the matrix as a bitmap, using the colormap values corresponding 
to the smallest and largest values therein.  Otherwise, emily tries to 
approximate that matrix value's contribution to the displayed value by 
calculating the area in the display matrix one input matrix value covers 
and distributing the input value over that area in the display matrix.

   emily is currently configured to have the window try to conform to the 
matrix.  On resizing or selecting a submatrix, the displayed matrix will 
keep the selected aspect ratio (ratio of rows to columns) at the expense 
of wasting potentially usable display space.  All windows, however, are 
initially square, so the easiest way to find the delineation between used 
and wasted space is to select a new background color.  This has the side 
effect of only repainting the matrix's background, not the whole window's. 

   Clicking on a point in the main display window will pop up a small 
subwindow with some information about the point selected.  This subwindow 
will not be created if the user is in the middle of a zoom operation.

3.2. Status Areas and Zooming

   A matrix status position indicator which displays the current position of 
the mouse in matrix (row, column) coordinates starting with (0,0) is just 
below the menu bar on emily's left.  This can be handy for determining and 
selecting areas of interest.

   Just below the position indicator is the zoom icon, which controls 
zoom operations.   A zoom operation is emily's method of allowing user's to 
focus on a submatrix of the current matrix on display.

   To execute a zoom operation:

   1. Click on the zoom icon with the first mouse button.
   2. Move the mouse to the main display area.
   3. Click on the starting point of interest in the main display area, 
        again with the first mouse button.
   4. Drag the mouse until the area of interest has been selected.

   A new window will be created with the submatrix of interest.  This process
can be repeated either on the main window or any zoom window until there are
a total of 9 zoom windows open.  The zoom windows are independent of each 
other.  They will be all be closed if either a new matrix is read in or the 
main window is closed, terminating emily.

   Underneath the zoom icon is the color bar with the maximum and minimum 
values of the compression matrix on the top and bottom, respectively, of the 
color bar. The color bar's color values change with the selected colormap; 
the maximum and minimum values change with the submatrix of interest.

   Beneath the color bar, the maximum and minimum values of the input 
submatrix and the corresponding display window coordinates are displayed.  
This allows easy identification of extreme values.

   There is a small text status area at the bottom of the window which displays
the coordinates of the (sub)matrix displayed in that window and the 
total size of the matrix. Also, for a sparse matrix, the number of non-zero
entries is printed.

4. Menu Options

   At the top of the main window is a menu bar controlling five menus:  File, 
Colors, Background, Scaling, and Help.  

4.1. The File Menu

   From the main window, the File Menu allows:

   o reading of a new file by selecting the ``New'' option.  This
      also closes all open zoom windows.
   o clearing or redrawing the main window by selecting the 
     ``Clear'' or ``Refresh'' options, respectively. 
   o choosing the scaling strategy by selecting the ``Scaling'' option.
   o leaving emily by selecting the ``Quit'' option.
   o printing the (sub)matrix of interest by selecting the ``Print'' option.
     The Print option allows output either directly to a printer or a
     file.

   From a zoom window, only the ``Print'' and ``Quit'' options can be selected 
from the File Menu.  The ``Print'' option prints the submatrix in the zoom 
window and the ``Quit'' option closes only that zoom window.  That is, if a 
window is created by zooming on a zoom window, and the original zoom window is 
closed, the child zoom window will remain open. 

4.2: The Colors Menu

   The Colors Menu allows selection of a colormap.  A colormap is the palette
of colors that emily chooses from to display the matrix.  Selecting a new colormap from the Colors Menu changes emily's appearance instantaneously. The 
selected colormap is common for all windows, so changing the colormap
on ANY window changes it for ALL windows.  The default colormap is the 
``Spectral'' colormap, which roughly follows the colors of the spectrum, from
violet to red.

   Most of the colormaps have hopefully intuitive names, but ``Pete's'' 
colormap and the ``Weather'' colormap are representative not of the colormap, 
but of the origin of the colormap.  ``Pete's'' colormap goes roughly around
2/3rds the HSV color cone, from black, through purple, red, orange, and 
yellow, to white.  The ``Weather'' colormap goes from green through yellow
to red and provides very nice constrast to a black background for all 
input values.

4.3: The Background Menu

   The Background Menu allows selection of the display matrix's
background color. The background color is the color that is used to represent 
a non-fill (or zero) entry in the input sparse matrix.  A new background color
causes the whole display matrix to be recalculated to insert the new 
background color.  This implies that selecting a new background color will 
take some time -- up to a  minute or two in some cases.  

   The ``Natural'' background color is the color of the entry in the
selected colormap corresponding to the minimum compressed matrix value.  
For example, for the ``Spectral'' colormap, the Natural background color is 
violet.  The default background color is black.

   Changing the background only affects the background of the selected window.
However, all of the windows zoomed from that window will inherit the selected 
background color, unless changed in the child window.

4.4: The Scaling Menu

   The Scaling Menu allows selection of the scaling strategy.  The scaling 
strategy is a function applied to the value v of each entry in the compression 
matrix C that determines the displayed color of v.   The compression matrix 
is a dense matrix of the same size as the display area of the window with 
real valued entries that correspond to the input value(s) that overlap that 
portion of the screen.  For now, the important fact is that the value
corresponds to one or more input matrix value(s).

   To scale C, four menu options are available:

   1. Linear:  The matrix values are scaled within the range of the 
               current colors linearly. 
   2. Absolute Linear:  The absolute values of the matrix values are 
               scaled linearly.
   3. Abs. Natural Log: The absolute values of the matrix values are scaled 
               logarithmically using natural logarithms.  If the minimum
               absolute value of the matrix is 0, then the next largest 
               value is used. 
   4. Abs. Log Base 10: The same formula is used as for the natural log 
               scaling, but the logarithm used is the base 10 logarithm .

   NOTE: Only the linear scaling doesn't use the absolute value (magnitude)
	 of the entries -- the other 3 scaling strategies use absolute values.
	 
4.5: The Help Menu

   The ``Help'' option on the far right hand side of the menu bar provides 
a quick reference to emily's features.  Help is not available from a zoom 
window.

5:  Error Messages, etc.

   The DISPLAY variable has to be set to a proper X display.  If not, emily
should tell you to set your DISPLAY properly.

   Any stray Xlib errors that are non-fatal can be ignored (on some systems, 
one or two are noticed once in awhile.)  Similarly, any messages of the form 
"CWresize: not mapped, so exiting" can be ignored -- they're internally 
generated by emily and usually arise from iconified or otherwise unavailable 
windows.
	
That's it -- good luck!

tom
tloos@cs.indiana.edu