By "Matlab (ASCII)" format, we mean an ASCII text file, each line of which contains either two, three, or four numbers. Lines are separated with the system-standard line separator, and numbers on each line are separated by one or more whitespace characters. Each line corresponds to a single stored entry of the sparse matrix. The first two numbers on the line are the column index and row index, respectively, of that entry. If the matrix is a pattern matrix, then there are only two numbers on the line. Otherwise, there may be one or two following numbers. If the matrix contains real numbers, then there is one number, which is the value of the matrix entry. If the matrix contains complex numbers, then there are two numbers, which are the real and complex components (respectively) of the matrix entry's value. In either case, each component is read in as a double-precision floating-point value, even if the actual precision is less or more. We use the C standard library routine strtod() to do this, so the way the routine rounds extra digits depends on the C standard and your system's implementation of strtod(). (If there is sufficient interest and we have sufficient time, we may allow in the future for storing values of arbitrary precision, and determine the precision dynamically from the values themselves.)
We call this format "Matlab (ASCII)" because the file can be read directly into Matlab as a two-, three-, or four-column matrix, and then converted by the spconvert() Matlab routine into a sparse matrix. Here is an example. Suppose your sparse matrix is stored in the file "matrix.mtl". Then the following Matlab commands will load the data and construct a Matlab sparse matrix in memory, without ever building an intermediate dense matrix:
>> load matrix.mtl; >> A = spconvert(matrix);
Here is an example of a sparse matrix stored in Matlab (ASCII) format:
2 1 -1.0000000000000000e+00 1 2 -1.0000000000000000e+00 2 2 4.0000000000000000e+00 3 3 4.0000000000000000e+00 4 4 4.0000000000000000e+00 3 2 -1.0000000000000000e+00 2 3 -1.0000000000000000e+00 4 3 -1.0000000000000000e+00 3 4 -1.0000000000000000e+00 1 1 4.0000000000000000e+00This is a 4x4 tridiagonal matrix (the 1-D discrete Laplacian) whose diagonal entries are all 4.0, and whose subdiagonal and superdiagonal entries are all -1.0. Note that the format does not require that the matrix entries be stored in any particular order. The SMC reads them in using an unordered coordinate storage internal format, and sorts them only on conversion to a sorted format, like compressed sparse row.
Our "Matlab (ASCII)" format differs from the "coordinate text file" format described on the Matrix Market web page, first because the coordinate text file format requires explicit storage of zero values when representing a pattern matrix, and second because our Matlab (ASCII) format does NOT store the matrix dimensions and number of nonzeros in the first line of the file. This means that if the lower right corner of the matrix contains no structural nonzeros, then our format will not represent the matrix dimensions correctly. The standard way to deal with that is to put a structural nonzero in the lower right corner of the matrix, and set its value to zero. Obviously this does not work for pattern matrices, which is why we recommend the MatrixMarket format over the Matlab (ASCII) format.
Our "Matlab (ASCII)" format also differs from PETSc's Matlab (ASCII) output format. Please see this explanation of the differences.