Last Modification Date: 2/14/97 THE AUTHOR OF EMILY HAS MOVED FROM IU AND WILL NO LONGER BE SUPPORTING THE TOOL. IF YOU WANT THE SOURCE CODE, GET THE GZIPPED TAR FILE ugly.tar.gz NO WARRANTIES OR SUPPORT ARE PROVIDED WITH THE CODE OR THE TOOL!!!!! Intro: This is the README file for emily and hbin. emily is a sparse matrix visualization tool that runs either at a UN*X command line (standalone) or under matlab. hbin is a Matlab utility that allows Harwell-Boeing files to be read directly into Matlab matrices without need of .mat files. This version of emily and hbin are dated Jan 27, 1995. Architectures currently supported/tested on: emily has been run on SGI, SUN, DEC, and IBM RS/6000 computers in standalone mode. emily and hbin have been tested under matlab for IBM RS/6000, SGI, DEC, and SUN 4 computers. If you'd like support for other architectures, send mail to tloos@cs.indiana.edu and let me borrow an account long enough to get things running on your platform. Specifically, emily was compiled on a SGI Challenge running IRIX Release 5.2 (but has been tested on various SGI platforms running IRIX 5.2), a 32 bit executable runs on under IRIX 6.0, on a SUN SPARC 2 running SunOS 4.1.2 and 4.1.3_U1, and on an IBM RS/6000 running AIX Version 3.2. Files to be found here: USERS_GUIDE: a user's guide to emily. The users guide to hbin is just the help utility of Matlab -- install hbin and chbin into your Matlab path and type >> help hbin at the Matlab prompt. emily.rs6: standalone version of emily for the IBM RS/6000 emily.sgi: standalone version of emily for SGI computers emily.sun: standalone version of emily for SUN computers emily.alpha: standalone version of emily for Alpha-based DEC computers emily.dec: standalone version of emily for DEC (MIPS) computers emily.static.sun: standalone version of emily for SUNs compiled with static libraries (for those who don't have Motif available) emily.m: a Matlab script front end for emily emily.mexrs6: the emily CMEX (Matlab executable) file for RS/6000s emily.mexsg: the emily CMEX file for SGI computers (Matlab 4.2) emily.mex4: the emily CMEX file for SUN 4s. (Matlab 4.0) hbin.m: a Matlab script for hbin chbin.mexrs6: the hbin CMEX file for RS/6000s chbin.mexsg: the hbin CMEX file for SGIs chbin.mex4: the hbin CMEX file for SUN 4s. gre_115: a simple test matrix for emily and hbin emily_demo.m: a Matlab demo of emily that uses... demo.mat: a Matlab data file with several matrices for emily to display mydelsqdemo.m: a modified Matlab demo that uses emily that calls... mydsqshow.m: a helper file for mydsqdemo.m postscript/paper.ps.Z: a compressed Postscript version of the paper "Emily: A Visualization Tool for Large Sparse Matrices" by my advisor (R. Bramley) and me (T. Loos). WARNING: it's huge Caveats: 1. emily displays in compressed sparse row (CSR) format, even though the Harwell-Boeing files are in compressed sparse column (CSC) format. 2. emily and hbin STRONGLY BELIEVE in the 5 line Harwell-Boeing header format -- if a RHS is provided, ALL FIELDS of ALL 5 LINES must be supplied according to the 1992 H-B standard specified on pp. 10-11 of the "Users' Guide for the Harwell-Boeing Sparse Matrix Collection (Release I)" by Duff, Grimes, and Lewis. A Quick Walkthrough of Emily's Features: 1. Install the appropriate standalong emily binary into some directory in your UNIX PATH. Below, I assume you renamed it to emily along the way. 2. In standalone mode, at a UN*X prompt, type: % emily The default matrix (a dense matrix based on A_{ij} = i + j) will be presented. Try changing the scaling to "Linear" and testing out the various colormaps. Then, try changing the background color to gray and retry the various colormaps. I usually use either a gray background with either the spectral or sunrise colormaps or a black background with either the spectral or weather colormaps. Try clicking on the Zoom icon and dragging out a region of the window to create a zoom window. Zoom windows can be created from zoom windows or from the main window, so zooms can in turn be zoomed. For a sample matrix, you can also find, from the H-B collection, the small matrix "gre_115". This matrix (like any other H-B matrix) can be loaded into emily in two different ways: a. At the command line, by typing: % emily gre_115 b. While emily is running: 1. Go to the main menu and select the File Menu. 2. Choose New. 3. Go through the list of files presented (or through the directories, if the gre_115 file is in another directory) until gre_115 is found. 4. Finally, select the file with the File selection dialog and the gre_115 file will be read into emily. Try changing the scaling from linear to natural log and back again -- the very tiny entries at (2,2) and (15,15) show up quite clearly. Also, note that the smallest entry doesn't end up at the bottom of the color bar. This is because the process of expanding the matrix into the display required the use of smaller data values than were found in the input to interpolate from the minimum input value down to 0. (The short explanation for this phenomenon is that emily calculates the color displayed based on the area covered by the matrix value on the display matrix. If a small matrix value is split among 2 or more output pixels, it'll get reduced and could be smaller than any input value and consequently have the position of the smallest color value.) c. For examples of using emily in Matlab: 1. Install the emily.m and emily.mex??? files somewhere in your Matlab path. 2. Install the emily_demo.m and demo.mat files somehere in your Matlab path and run the emily_demo.m file by entering at the Matlab prompt: >> emily_demo This will show several pretty (in my eyes) matrices. Typing >> help emily_demo will give some information on generating these matrices. 3. To try a slightly updated version of an existing Matlab demo that uses emily, install the mydelsqdemo.m and mydsqshow.m files in your Matlab path and enter at the Matlab prompt: >> mydelsqdemo Good luck, tom loos tloos@cs.indiana.edu