


             USING THE MATRIX CAPTURE FACILITY


Any call to AZ_solve will check to see if the file "AZ_write_matrix_now" 
exists in the current working directory.  If this file exists and
you are running on 1 processor, then the files

  - AZ_capture_matrix.dat
  - AZ_capture_rhs.dat
  - AZ_capture_partition.dat (VBR only)

  will be appended with the current matrix in (i,j,val) format, the
  current RHS and the current partition information.  The existence
  of "AZ_write_matrix_now" is check each time.  Thus, capturing can
  be turned on and off at will during the run of a simulation.

This facility provides a dynamic way of turning capture on and off.



                   DATA FILE FORMAT

Capture data files can be easily read by packages such as matlab.
The file AZ_capture_matrix.dat stores the entries of the matrix in 
row, column, value format, commonly called coordinate format.  Each
entry occupies a line in the file.  The format of the line is
generated by the following C statement:

   fprintf(AZ_capture_matrix,"%d %d %22.16e\n", i, j, value);

Each captured matrix in preceded by the line

Start of VBR matrix
or
Start of MSR matrix

Thus, it is possible to search for the start of a matrix by searching
for this string.



                    SAMPLE SCENARIO

Suppose you want to capture an instance of a linear system that was 
causing trouble for Aztec.  If you run your simulation one time and 
know when the trouble will begin, you can re-run the simulation and, 
just prior to reachin the trouble spot again in a separate window, 
type the following

cat > AZ_write_matrix_now
Ctrl-D

in the current working directory of your simulation.

Aztec will see this file and dump out the current matrix, rhs and
partition information (partition information is only dumped if your
matrix is in VBR format) the next time AZ_solve is called.

You may turn the capture facility on and off as needed by creating or
deleting AZ_write_matrix_now.  The capture facility will always append
to any existing capture data files.  Thus, you must delete old capture 
files if you want to start fresh.


             IMPORTING CAPTURE DATA FILES

Once you have captured one or more instances of Aztec input, it is
possible to use the data in a variety of ways.  The most common is
probably MATLAB but it is also possible to write a simple C or Fortran
wrapper routine to read the data.  For example, see the routine
read_captured_matrix.c in this directory.

To read matrices into MATLAB, edit the file AZ_capture_matrix.dat and
write the matrix of interest to a new file, using a .dat (e.g.  mat.dat) 
file extension.  DO NOT include the header line or the dimension information.  
MATLAB will figure this information out on its own.  Once this file is 
created, issue the following commands in MATLAB:

>> load mat.dat       <- Loads a nnz-by-3 array mat with nnz rows of (i,j,val)
>> A=spconvert(mat);  <- Converts mat to a sparse matrix, stored in A.
                         DON'T FORGET THE SEMI-COLON (SUPPRESSES OUTPUT)
>> spy(A)             <- Graphs the nonzero pattern of the matrix.
                         (Not required but is a good sanity check.)

To read right-hand-side vectors, edit the file AZ_capture_rhs.dat 
and write the right-hand-side of interest to a file, e.g. b.dat.  Do
not include header or dimension information.  Once this file is
created, issue the following command in MATLAB:

>> load b.dat         <- Loads a 1D array b with the right-hand-side.
                         There is no need to convert to anything else.


Questions/Comments can be sent to:

Mike Heroux
Dept 9222, SNL
(320) 845-7695
mheroux@cs.sandia.gov
