sreenatha/mmio/README.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>Matrix Market: C routines for Matrix Market I/O</TITLE>
<SCRIPT language="javascript"><!--
function enist(u){
  var q="'",c=":",d=".",a="&#64;",s="/",e="=",b=" ";
      i="ilto",t="a",m="ma",h="href",g="gov",n="nist";
  var x=u+a+n+d+g,l="<",g=">";
  document.write(l+t+b+h+e+q+m+i+c+x+q+g+x+l+s+t+g); }
//-->
</SCRIPT>
</HEAD>
<BODY BGCOLOR="#ffffff">

<CENTER>
<H3><IMG SRC="images/banner.gif" ALT="Matrix Market" BORDER=0 
         ISMAP USEMAP="#banner"></H3>
<MAP NAME="banner">
<AREA COORDS="  0  12 342 31" HREF="index.html" ALT="[ Home ]">
<AREA COORDS="344  12 395 31" HREF="search.html" ALT="[ Search ]">
<AREA COORDS="397  12 455 31" HREF="browse.html" ALT="[ Browse ]">
<AREA COORDS="457  12 535 31" HREF="resources.html" ALT="[ Resources ]">
</MAP>
</CENTER>

<center><H1>ANSI C library for Matrix Market I/O</H1></center>

<P>
The numerical data in the Matrix Market file formats can be easily processed
using variants of <b><TT>fscanf()</TT></b> and  <b><TT>fprintf()</TT></b> 
functions. 
The only non-trivial issue is to figure out what kind of matrix is
represented in a Matrix Market file.  Because of the wide range of
possibilities, it is impractical to have a single function handle
every case (furthermore, most applications will support only a subset
of these matrix types). Instead, we provide utilities that
identify and manage only the type and size information in MM files,  
leaving the actual reading and writing mechanisms to the driving 
application or higher-level I/O routines.  

<p>
Reading  a Matrix Market file can be broken into three basic steps:
<OL>
<li> use <a href="#mm_read_banner"><b><tt>mm_read_banner()</tt></b></a> to process the 1st line of file 
        and identify the matrix type
<li> use a type-specific function, such as 
    <a href="#mm_read_mtx_crd_size"><b><tt>mm_read_mtx_crd_size()</tt></b></a>
        to skip the optional comments and 
        process the matrix size information
<li> use a variant of <b><tt>scanf()</tt></b> to read the numerical data,
            one matrix entry per line
</OL>

<p>
Saving a matrix from an internal data structure to a Matrix Market file is 
        a similar process:
<OL>
<li> use <a href="#mm_write_banner"><b><tt>mm_write_banner()</tt></b></a> 
to create the 1st line of 
            the Matrix Market file 
<li> (optional) add '%' delimited comments
<li> use a type-specific function, such as 
<a href="#mm_write_mtx_crd_size"><b><tt>mm_write_mtx_crd_size()</tt></b></a>  
to record the matrix size information
<li> use a variant of  <b><tt> printf()</tt></b> to write the numerical data, 
            one matrix entry per line
</OL>
<hr>


<h3> Source code </h3>
<UL>
<li> examples:
    <UL>
    <li> <a href="mmio/c/example_read.c">example_read.c</a>
    <li> <a href="mmio/c/example_write.c">example_write.c</a>
    </uL>
<li> library routines:
    <UL> 
    <li> <a href="mmio/c/mmio.h">mmio.h</a>
    <li> <a href="mmio/c/mmio.c">mmio.c</a>
    </ul>
</UL>
<HR>

<h3>Documentation</h3>
<UL>
<tt>
<li> <a href="#mm_read_banner">mm_read_banner()</a>
<li> <a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>
<li> <a href="#mm_read_mtx_array_size">mm_read_mtx_array_size()</a>
<li> <a href="#mm_write_banner">mm_write_banner()</a>
<li> <a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>
<li> <a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>
</tt>
</UL>

<p>
<hr>

<!------------------------------------------------------------------>
<a name="mm_read_banner"><h2>mm_read_banner()</h2></a>


<h3>NAME</h3>
<p>
mm_read_banner - determine the type of matrix being represented in a 
            Matrix Market file

<h3>SYNPOSIS</h3>
<pre>
    #include &lt;stdio.h&gt
    #include "mmio.h"

    int mm_read_banner(FILE *f, MM_typecode *t);
</pre>

<h3>DESCRIPTION</h3>
<tt>mm_read_banner()</tt> processes the the first line of a Matrix Market file,
e.g. <br>

        <p>
        <center>
        <tt> %%MatrixMarket matrix coordinate real general</tt>
        </center>
<br>
and returns the matrix characteristics.  

File descriptor <b><em>f</em></b> is defined in "stdio.h" and is assumed
to have been opened for read access.  The predefined descriptor 
<b><em>stdin</em></b> can be used to read from the standard
input.

<b><em>t</em></b> points to an internal structure that describes the 
        matrix charateristics.   This <tt>MM_typecode</tt> is 
        more efficient and convenient
        than storing the explicit banner.
        <a href="#query">query functions</a>, such as 
        <tt>mm_is_complex(t)</tt>, are available to extract this information.

<h3>RETURN VALUES</h3>

    <tt>mm_read_banner()</tt> returns 0 if succesful. Otherwise,
    it returns one of the error codes below.
    
<h3> ERRORS </h3>

    <ul>
    <li> MM_PREMATURE_EOF if all items are not present on first line of file.
    <li> MM_NO_HEADER if the file does not begin with "%%MatrixMarket".
    <li> MM_UNSUPPORTED_TYPE  if not recongizable description.
    </ul>

<h3> EXAMPLES </h3>

    See <a href="mmio/c/example_read.c">example_read.c</a>.

<h3>SEE ALSO</h3>
    <a href="#mm_write_banner">mm_write_banner()</a>,
    <a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
    <a href="#mm_read_mtx_array_size">mm_read_array_crd_size()</a>,
    <a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
    <a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>
<br>
<br>
<hr>


<!----------------------------------------------------------------------->

<a name="mm_read_mtx_crd_size"><h2> mm_read_mtx_crd_size()</h2></a>

<h3>NAME</h3>
mm_read_mtx_crd_size - read the size information of a sparse matrix
        (coordinate format) in a Matrix Market file

<h3>SYNPOSIS</h3>
<pre>
    #include &lt;stdio.h&gt
    #include "mmio.h"

    int mm_read_mtx_crd_size(FILE *f, int *M, int *N, int *nz);
</pre>

<h3>DESCRIPTION</h3>
After processing the Matrix Market <a href="#mm_read_banner">banner</a>, 
<tt>mm_read_mtx_crd_size()</tt> reads 
past the optional comments and initalizes size variables <b><em>M</em></b> 
(number of rows), <b><em>N</em></b> (number of columns), and 
<b><em>nz</em></b>(number of non-zeros).
It is assumed that the matrix being read is in coordinate format.

<h3> RETURN VALUES</h3>

    <tt>mm_read_mtx_crd_size()</tt> return 0 is successful, otherwise
    it returns one of the error codes below.

<h3> ERRORS </h3>


    <ul>
    <li> MM_PREMATURE_EOF if an end-of-file is encountered before processing
            these three values.
    </ul>

<h3>SEE ALSO</h3>
    <a href="#mm_write_banner">mm_write_banner()</a>,
    <a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
    <a href="#mm_read_mtx_crd_size">mm_read_array_crd_size()</a>,
    <a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
    <a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>,


<br>
<br>
<hr>

<! ----------------------------------------------------------------------->

<a name="mm_read_mtx_array_size"><h2> mm_read_mtx_array_size()</h2></a>

<h3>NAME</h3>
mm_read_mtx_crd_size - read the size information of a dense matrix
        (array format) in a Matrix Market file

<h3>SYNPOSIS</h3>
<pre>
    #include &lt;stdio.h&gt
    #include "mmio.h"

    int mm_read_mtx_array_size(FILE *f, int *M, int *N);
</pre>

<h3>DESCRIPTION</h3>
After processing the Matrix Market <a href="#mm_read_banner">banner</a>, 
<tt>mm_read_mtx_crd_size()</tt> reads 
past the optional comments and initalizes matrix size variables 
<b><em>M</em></b> (number of rows), <b><em>N</em></b> (number of columns).
It is assumed that the matrix being read is in array format.

<h3> RETURN VALUES</h3>

    <tt>mm_read_mtx_array_size()</tt> return 0 is successful, otherwise
    it returns one of the error codes below.

<h3> ERRORS </h3>


    <ul>
    <li> MM_PREMATURE_EOF if an end-of-file is encountered before reading
            M and N.
    </ul>

<h3>SEE ALSO</h3>
    <a href="#mm_write_banner">mm_write_banner()</a>,
    <a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
    <a href="#mm_read_mtx_crd_size">mm_read_array_crd_size()</a>,
    <a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
    <a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>,


<br>
<br>
<hr>
<!------------------------------------------------------------------>
<a name="mm_write_banner"><h2>mm_write_banner()</h2></a>


<h3>NAME</h3>
<p>
mm_write_banner - record matrix type information in Matrix Market file

<h3>SYNPOSIS</h3>
<pre>
    #include &lt;stdio.h&gt
    #include "mmio.h"

    int mm_write_banner(FILE *f, MM_typecode *t);
</pre>

<h3>DESCRIPTION</h3>
<tt>mm_write_banner()</tt> prints the first line of a Matrix Market file,
which consists of the "%%MatrixMarket" token followed by an attribute
list, 
e.g. <br>

        <p>
        <center>
        <tt> %%MatrixMarket matrix coordinate real general</tt>
        </center>
<br>
<p>
File descriptor <b><em>f</em></b> is defined in "stdio.h" and is assumed
to have been opened for write access.  The predefined descriptor 
<b><em>stdout</em></b> can be used to read from the standard
output.

<b><em>t</em></b> points to an internal structure that describes the 
        matrix charateristics.   This <tt>MM_typecode</tt> is 
        more efficient and convenient
        than storing the explicit banner. Various 
        <a href="#query">assign functions</a>, such as 
        <tt>mm_set_complex(&t)</tt>, can be used to set
        these characterisitcs.

<h3>RETURN VALUES</h3>

    <tt>mm_write_banner()</tt> returns 0 if succesful. Otherwise,
    it returns MM_COULD_NOT_OPEN_WRITE_FILE.
    

<h3> EXAMPLES </h3>

    See <a href="mmio/c/example_write.c">example_write.c</a>.

<h3>SEE ALSO</h3>
    <a href="#mm_write_banner">mm_write_banner()</a>,
    <a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
    <a href="#mm_read_mtx_array_size">mm_read_array_crd_size()</a>,
    <a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
    <a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>
<br>
<br>
<hr>

<! ------------------------------------------------------------------->

<a name="mm_write_mtx_crd_size"><h2> mm_write_mtx_crd_size()</h2></a>

<h3>NAME</h3>
mm_write_mtx_crd_size - write the size information of a dense matrix
        (array format) to a Matrix Market file

<h3>SYNPOSIS</h3>
<pre>
    #include &lt;stdio.h&gt
    #include "mmio.h"

    int mm_write_mtx_crd_size(FILE *f, int M, int N, int nz);
</pre>

<h3>DESCRIPTION</h3>

Record the matrix dimensions <b><em>M</em></b> x <b><em>N</em></b> and 
total number of nonzeros, <b><em>nz</em></b> to Matrix Market file.
Typically called after 
<a href="#mm_write_banner"><tt>mm_write_banner()</tt></a>.

<h3> RETURN VALUES</h3>

    <tt>mm_write_mtx_crd_size()</tt> returns 0 is successful, otherwise
    MM_COULD_NOT_WRITE_FILE.

<h3> DIAGNOSTICS </h3>

This is a trivial function to write three integers to <b><em>f</em></b>
using <tt>fprintf()</tt>.
It is included in the library only for the sake of completeness,
as a counterpart to <a href="#mm_read_mtx_crd_size">
<tt>mm_read_mtx_crd_size()</tt></a>.


<h3>SEE ALSO</h3>
    <a href="#mm_write_banner">mm_write_banner()</a>,
    <a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
    <a href="#mm_read_mtx_crd_size">mm_read_array_crd_size()</a>,
    <a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
    <a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>,


<br>
<br>
<hr>
<! ------------------------------------------------------------------->

<a name="mm_write_mtx_array_size"><h2> mm_write_mtx_array_size()</h2></a>

<h3>NAME</h3>
mm_write_mtx_array_size - write the size information of a dense matrix
        (array format) to a Matrix Market file

<h3>SYNPOSIS</h3>
<pre>
    #include &lt;stdio.h&gt
    #include "mmio.h"

    int mm_write_mtx_array_size(FILE *f, int M, int N);
</pre>

<h3>DESCRIPTION</h3>

Record the matrix dimensions <b><em>M</em></b> x <b><em>N</em></b>
to Matrix Market file.
Typically called after 
<a href="#mm_write_banner"><tt>mm_write_banner()</tt></a>.

<h3> RETURN VALUES</h3>

    <tt>mm_write_mtx_array_size()</tt> returns 0 is successful, otherwise
    MM_COULD_NOT_WRITE_FILE.

<h3>DIAGNOSTICS</h3>

This is a trivial function to write two integers to <b><em>f</em></b>
using <tt>fprintf()</tt>.
It is included in the library only as a counterpart to
<a href="#mm_read_mtx_array_size"><tt>mm_read_mtx_array_size()</tt></a>.


<h3>SEE ALSO</h3>
    <a href="#mm_write_banner">mm_write_banner()</a>,
    <a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
    <a href="#mm_read_mtx_crd_size">mm_read_array_crd_size()</a>,
    <a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
    <a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>,


<br>
<br>
<hr>
<! ------------------------------------------------------------------->

<a name="query"><h2> MM_IS</h2></a>

<h3>NAME</h3>


 mm_is_matrix,
 mm_is_sparse,
 mm_is_coordinate,
 mm_is_dense,
 mm_is_array,
 mm_is_complex,
 mm_is_real ,
 mm_is_pattern,
 mm_is_integer,
 mm_is_symmetric,
 mm_is_general,
 mm_is_skew,
 mm_is_hermitian -matrix type query functions

<h3>SYNPOSIS</h3>
<pre>
    #include &lt;stdio.h&gt
    #include "mmio.h"

    int mm_is_matrix(MM_typecode t);

    int mm_is_sparse(MM_typecode t);

    int mm_is_coordinate(MM_typecode t);

    int mm_is_dense(MM_typecode t);

    int mm_is_array(MM_typecode t);

    int mm_is_complex(MM_typecode t);

    int mm_is_real(MM_typecode t);

    int mm_is_pattern(MM_typecode t);

    int mm_is_integer(MM_typecode t);

    int mm_is_symmetric(MM_typecode t);

    int mm_is_general(MM_typecode t);

    int mm_is_skew(MM_typecode t);

    int mm_is_hermitian(MM_typecode t);


</pre>

<h3>DESCRIPTION</h3>
MM_QUERY functions provide a boolean test on matrix typecodes 
(<tt>MM_typecode</tt>) variables for a given storage property.
The functions return 0 if false, 1 otherwise.  Note that these properties
refer only to the <bf>storage</bf> scheme, not the mathematical properties.  
For example, a mathematically symmetric matrix stored with both upper
and lower triangular halves will evaluate <tt>mm_is_symmetric()</tt> false.


<h3> RETURN VALUES</h3>

    MM_QUERY functions return 1 if true, 0 if false.


<h3> DIAGNOSTICS </h3>

These functions are implemented as macros.  

<h3>SEE ALSO</h3>
    <a href="#mm_write_banner">mm_write_banner()</a>,
    <a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
    <a href="#mm_read_mtx_array_size">mm_read_array_crd_size()</a>,
    <a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
    <a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>,


<br>
<br>
<hr>
<! ------------------------------------------------------------------->


<a name="mm_set"><h2> MM_SET</h2></a>

<h3>NAME</h3>


 mm_set_matrix,
 mm_set_sparse,
 mm_set_coordinate,
 mm_set_dense,
 mm_set_array,
 mm_set_complex,
 mm_set_real    ,
 mm_set_pattern,
 mm_set_integer,
 mm_set_symmetric,
 mm_set_general,
 mm_set_skew,
 mm_set_hermitian,
 mm_clear_typecode,
 mm_initialize_typecode  --matrix type query functions

<h3>SYNPOSIS</h3>
<pre>
    #include &lt;stdio.h&gt
    #include "mmio.h"

    int mm_set_matrix(MM_typecode &t);

    int mm_set_sparse(MM_typecode &t);

    int mm_set_coordinate(MM_typecode &t);

    int mm_set_dense(MM_typecode &t);

    int mm_set_array(MM_typecode &t);

    int mm_set_complex(MM_typecode &t);

    int mm_set_real(MM_typecode &t);

    int mm_set_pattern(MM_typecode &t);

    int mm_set_integer(MM_typecode &t);

    int mm_set_symmetric(MM_typecode &t);

    int mm_set_general(MM_typecode &t);

    int mm_set_skew(MM_typecode &t);

    int mm_set_hermitian(MM_typecode &t);

    int mm_clear_typecode(MM_typecode &t);

    int mm_initialize_typecode(MM_typecode &t);

</pre>

<h3>DESCRIPTION</h3>
MM_SET functions are used to encode the matrix charateristics to
a Matrix Market file, in conjunction with <a href="#mm_write_banner">
<tt>mm_write_banner()</tt></a>.  To use properly, <em><b>t</b></em> first
must be initialized.  For exmaple, the set a <tt>MM_typecode</tt> to
describe a complex, Hermititan, sparse matrix, one can write
<pre>
    
    mm_initialize_typecode(&t);
    mm_set_matrix(&t);
    mm_set_complex(&t);
    mm_set_coordinate(&t);
    mm_set_hermitian(&t);

</pre>

<em><b>t</b></em> can then be used as an argument to 
<tt>mm_write_banner()</tt></a>.
<h3> RETURN VALUES</h3>

    MM_SET functions return void.


<h3> DIAGNOSTICS </h3>

These functions are implemented as macros.  

<h3>SEE ALSO</h3>
    <a href="#mm_write_banner">mm_write_banner()</a>,
    <a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
    <a href="#mm_read_mtx_array_size">mm_read_array_crd_size()</a>,
    <a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
    <a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>,


<br>
<br>
<hr>
<! ------------------------------------------------------------------->

<a name="mm_typecode_to_str"><h2> mm_typecode_to_str()</h2></a>

<h3>NAME</h3>
mm_typecode_to_str - convert a typecode to a descriptive string

<h3>SYNPOSIS</h3>
<pre>
    #include &lt;stdio.h&gt
    #include "mmio.h"

    char *mm_typecode_to_str(MM_typecode t);
</pre>

<h3>DESCRIPTION</h3>

<tt>mm_typecode_to_str</tt> converts a <tt>MM_typecode </tt>
to mnemonic string.  This can be used as part of a diagnostics
and error reporting.  (See "<a href="mmio/c/example_read.c">example_read.c</a>"
for possible use.)

<h3> RETURN VALUES</h3>

    <tt>mm_typecode_to_str()</tt> returns a new character string if
    successful, or NULL if an error occured.

<h3> DIAGNOSTICS </h3>
<tt>mm_typecode_to_str</tt> uses <tt>strdup()</tt> internally, and
consequently the returned string must be freed to avoid memory leaks.

<h3>SEE ALSO</h3>
    <a href="#mm_write_banner">mm_write_banner()</a>,
    <a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
    <a href="#mm_read_mtx_crd_size">mm_read_array_crd_size()</a>,
    <a href="#mm_typecode_to_str">mm_typecode_to_str()</a>,
    <a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>,

<P><HR>
<CENTER><FONT SIZE=-2>
The Matrix Market is a service of the
<A HREF="/mcsd/">Mathematical and Computational Sciences Division</A> / 
<A HREF="http://www.itl.nist.gov/">Information Technology Laboratory</A> / 
<A HREF="http://www.nist.gov/">National Institute of Standards and Technology</A>
</FONT></CENTER>

<P>
[ <A HREF="index.html">Home</A> ]
[ <A HREF="search.html">Search</A> ]
[ <A HREF="browse.html">Browse</A> ]
[ <A HREF="resources.html">Resources</A> ]

<P>
Last change in this page : <I>May 2, 2000</I>.
[ <SCRIPT language="javascript"><!-- 
enist('matrixmarket');
// --></SCRIPT>
<noscript>matrixmarket</noscript><noscript>&#64;</noscript><noscript>nist.gov</noscript>
].
</P>  

</BODY>
</HTML>
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2	<HTML>
3	<HEAD>
4	<TITLE>Matrix Market: C routines for Matrix Market I/O</TITLE>
5	<SCRIPT language="javascript"><!--
6	function enist(u){
7	var q="'",c=":",d=".",a="@",s="/",e="=",b=" ";
8	i="ilto",t="a",m="ma",h="href",g="gov",n="nist";
9	var x=u+a+n+d+g,l="<",g=">";
10	document.write(l+t+b+h+e+q+m+i+c+x+q+g+x+l+s+t+g); }
11	//-->
12	</SCRIPT>
13	</HEAD>
14	<BODY BGCOLOR="#ffffff">
15
16	<CENTER>
17	<H3><IMG SRC="images/banner.gif" ALT="Matrix Market" BORDER=0
18	ISMAP USEMAP="#banner"></H3>
19	<MAP NAME="banner">
20	<AREA COORDS=" 0 12 342 31" HREF="index.html" ALT="[ Home ]">
21	<AREA COORDS="344 12 395 31" HREF="search.html" ALT="[ Search ]">
22	<AREA COORDS="397 12 455 31" HREF="browse.html" ALT="[ Browse ]">
23	<AREA COORDS="457 12 535 31" HREF="resources.html" ALT="[ Resources ]">
24	</MAP>
25	</CENTER>
26
27	<center><H1>ANSI C library for Matrix Market I/O</H1></center>
28
29	<P>
30	The numerical data in the Matrix Market file formats can be easily processed
31	using variants of <b><TT>fscanf()</TT></b> and <b><TT>fprintf()</TT></b>
32	functions.
33	The only non-trivial issue is to figure out what kind of matrix is
34	represented in a Matrix Market file. Because of the wide range of
35	possibilities, it is impractical to have a single function handle
36	every case (furthermore, most applications will support only a subset
37	of these matrix types). Instead, we provide utilities that
38	identify and manage only the type and size information in MM files,
39	leaving the actual reading and writing mechanisms to the driving
40	application or higher-level I/O routines.
41
42	<p>
43	Reading a Matrix Market file can be broken into three basic steps:
44	<OL>
45	<li> use <a href="#mm_read_banner"><b><tt>mm_read_banner()</tt></b></a> to process the 1st line of file
46	and identify the matrix type
47	<li> use a type-specific function, such as
48	<a href="#mm_read_mtx_crd_size"><b><tt>mm_read_mtx_crd_size()</tt></b></a>
49	to skip the optional comments and
50	process the matrix size information
51	<li> use a variant of <b><tt>scanf()</tt></b> to read the numerical data,
52	one matrix entry per line
53	</OL>
54
55	<p>
56	Saving a matrix from an internal data structure to a Matrix Market file is
57	a similar process:
58	<OL>
59	<li> use <a href="#mm_write_banner"><b><tt>mm_write_banner()</tt></b></a>
60	to create the 1st line of
61	the Matrix Market file
62	<li> (optional) add '%' delimited comments
63	<li> use a type-specific function, such as
64	<a href="#mm_write_mtx_crd_size"><b><tt>mm_write_mtx_crd_size()</tt></b></a>
65	to record the matrix size information
66	<li> use a variant of <b><tt> printf()</tt></b> to write the numerical data,
67	one matrix entry per line
68	</OL>
69	<hr>
70
71
72	<h3> Source code </h3>
73	<UL>
74	<li> examples:
75	<UL>
76	<li> <a href="mmio/c/example_read.c">example_read.c</a>
77	<li> <a href="mmio/c/example_write.c">example_write.c</a>
78	</uL>
79	<li> library routines:
80	<UL>
81	<li> <a href="mmio/c/mmio.h">mmio.h</a>
82	<li> <a href="mmio/c/mmio.c">mmio.c</a>
83	</ul>
84	</UL>
85	<HR>
86
87	<h3>Documentation</h3>
88	<UL>
89	<tt>
90	<li> <a href="#mm_read_banner">mm_read_banner()</a>
91	<li> <a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>
92	<li> <a href="#mm_read_mtx_array_size">mm_read_mtx_array_size()</a>
93	<li> <a href="#mm_write_banner">mm_write_banner()</a>
94	<li> <a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>
95	<li> <a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>
96	</tt>
97	</UL>
98
99	<p>
100	<hr>
101
102	<!------------------------------------------------------------------>
103	<a name="mm_read_banner"><h2>mm_read_banner()</h2></a>
104
105
106	<h3>NAME</h3>
107	<p>
108	mm_read_banner - determine the type of matrix being represented in a
109	Matrix Market file
110
111	<h3>SYNPOSIS</h3>
112	<pre>
113	#include <stdio.h&gt
114	#include "mmio.h"
115
116	int mm_read_banner(FILE f, MM_typecode t);
117	</pre>
118
119	<h3>DESCRIPTION</h3>
120	<tt>mm_read_banner()</tt> processes the the first line of a Matrix Market file,
121	e.g. <br>
122
123	<p>
124	<center>
125	<tt> %%MatrixMarket matrix coordinate real general</tt>
126	</center>
127	<br>
128	and returns the matrix characteristics.
129
130	File descriptor <b><em>f</em></b> is defined in "stdio.h" and is assumed
131	to have been opened for read access. The predefined descriptor
132	<b><em>stdin</em></b> can be used to read from the standard
133	input.
134
135	<b><em>t</em></b> points to an internal structure that describes the
136	matrix charateristics. This <tt>MM_typecode</tt> is
137	more efficient and convenient
138	than storing the explicit banner.
139	<a href="#query">query functions</a>, such as
140	<tt>mm_is_complex(t)</tt>, are available to extract this information.
141
142	<h3>RETURN VALUES</h3>
143
144	<tt>mm_read_banner()</tt> returns 0 if succesful. Otherwise,
145	it returns one of the error codes below.
146
147	<h3> ERRORS </h3>
148
149	<ul>
150	<li> MM_PREMATURE_EOF if all items are not present on first line of file.
151	<li> MM_NO_HEADER if the file does not begin with "%%MatrixMarket".
152	<li> MM_UNSUPPORTED_TYPE if not recongizable description.
153	</ul>
154
155	<h3> EXAMPLES </h3>
156
157	See <a href="mmio/c/example_read.c">example_read.c</a>.
158
159	<h3>SEE ALSO</h3>
160	<a href="#mm_write_banner">mm_write_banner()</a>,
161	<a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
162	<a href="#mm_read_mtx_array_size">mm_read_array_crd_size()</a>,
163	<a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
164	<a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>
165	<br>
166	<br>
167	<hr>
168
169
170	<!----------------------------------------------------------------------->
171
172	<a name="mm_read_mtx_crd_size"><h2> mm_read_mtx_crd_size()</h2></a>
173
174	<h3>NAME</h3>
175	mm_read_mtx_crd_size - read the size information of a sparse matrix
176	(coordinate format) in a Matrix Market file
177
178	<h3>SYNPOSIS</h3>
179	<pre>
180	#include <stdio.h&gt
181	#include "mmio.h"
182
183	int mm_read_mtx_crd_size(FILE f, int M, int N, int nz);
184	</pre>
185
186	<h3>DESCRIPTION</h3>
187	After processing the Matrix Market <a href="#mm_read_banner">banner</a>,
188	<tt>mm_read_mtx_crd_size()</tt> reads
189	past the optional comments and initalizes size variables <b><em>M</em></b>
190	(number of rows), <b><em>N</em></b> (number of columns), and
191	<b><em>nz</em></b>(number of non-zeros).
192	It is assumed that the matrix being read is in coordinate format.
193
194	<h3> RETURN VALUES</h3>
195
196	<tt>mm_read_mtx_crd_size()</tt> return 0 is successful, otherwise
197	it returns one of the error codes below.
198
199	<h3> ERRORS </h3>
200
201
202	<ul>
203	<li> MM_PREMATURE_EOF if an end-of-file is encountered before processing
204	these three values.
205	</ul>
206
207	<h3>SEE ALSO</h3>
208	<a href="#mm_write_banner">mm_write_banner()</a>,
209	<a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
210	<a href="#mm_read_mtx_crd_size">mm_read_array_crd_size()</a>,
211	<a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
212	<a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>,
213
214
215	<br>
216	<br>
217	<hr>
218
219	<! ----------------------------------------------------------------------->
220
221	<a name="mm_read_mtx_array_size"><h2> mm_read_mtx_array_size()</h2></a>
222
223	<h3>NAME</h3>
224	mm_read_mtx_crd_size - read the size information of a dense matrix
225	(array format) in a Matrix Market file
226
227	<h3>SYNPOSIS</h3>
228	<pre>
229	#include <stdio.h&gt
230	#include "mmio.h"
231
232	int mm_read_mtx_array_size(FILE f, int M, int *N);
233	</pre>
234
235	<h3>DESCRIPTION</h3>
236	After processing the Matrix Market <a href="#mm_read_banner">banner</a>,
237	<tt>mm_read_mtx_crd_size()</tt> reads
238	past the optional comments and initalizes matrix size variables
239	<b><em>M</em></b> (number of rows), <b><em>N</em></b> (number of columns).
240	It is assumed that the matrix being read is in array format.
241
242	<h3> RETURN VALUES</h3>
243
244	<tt>mm_read_mtx_array_size()</tt> return 0 is successful, otherwise
245	it returns one of the error codes below.
246
247	<h3> ERRORS </h3>
248
249
250	<ul>
251	<li> MM_PREMATURE_EOF if an end-of-file is encountered before reading
252	M and N.
253	</ul>
254
255	<h3>SEE ALSO</h3>
256	<a href="#mm_write_banner">mm_write_banner()</a>,
257	<a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
258	<a href="#mm_read_mtx_crd_size">mm_read_array_crd_size()</a>,
259	<a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
260	<a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>,
261
262
263	<br>
264	<br>
265	<hr>
266	<!------------------------------------------------------------------>
267	<a name="mm_write_banner"><h2>mm_write_banner()</h2></a>
268
269
270	<h3>NAME</h3>
271	<p>
272	mm_write_banner - record matrix type information in Matrix Market file
273
274	<h3>SYNPOSIS</h3>
275	<pre>
276	#include <stdio.h&gt
277	#include "mmio.h"
278
279	int mm_write_banner(FILE f, MM_typecode t);
280	</pre>
281
282	<h3>DESCRIPTION</h3>
283	<tt>mm_write_banner()</tt> prints the first line of a Matrix Market file,
284	which consists of the "%%MatrixMarket" token followed by an attribute
285	list,
286	e.g. <br>
287
288	<p>
289	<center>
290	<tt> %%MatrixMarket matrix coordinate real general</tt>
291	</center>
292	<br>
293	<p>
294	File descriptor <b><em>f</em></b> is defined in "stdio.h" and is assumed
295	to have been opened for write access. The predefined descriptor
296	<b><em>stdout</em></b> can be used to read from the standard
297	output.
298
299	<b><em>t</em></b> points to an internal structure that describes the
300	matrix charateristics. This <tt>MM_typecode</tt> is
301	more efficient and convenient
302	than storing the explicit banner. Various
303	<a href="#query">assign functions</a>, such as
304	<tt>mm_set_complex(&t)</tt>, can be used to set
305	these characterisitcs.
306
307	<h3>RETURN VALUES</h3>
308
309	<tt>mm_write_banner()</tt> returns 0 if succesful. Otherwise,
310	it returns MM_COULD_NOT_OPEN_WRITE_FILE.
311
312
313	<h3> EXAMPLES </h3>
314
315	See <a href="mmio/c/example_write.c">example_write.c</a>.
316
317	<h3>SEE ALSO</h3>
318	<a href="#mm_write_banner">mm_write_banner()</a>,
319	<a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
320	<a href="#mm_read_mtx_array_size">mm_read_array_crd_size()</a>,
321	<a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
322	<a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>
323	<br>
324	<br>
325	<hr>
326
327	<! ------------------------------------------------------------------->
328
329	<a name="mm_write_mtx_crd_size"><h2> mm_write_mtx_crd_size()</h2></a>
330
331	<h3>NAME</h3>
332	mm_write_mtx_crd_size - write the size information of a dense matrix
333	(array format) to a Matrix Market file
334
335	<h3>SYNPOSIS</h3>
336	<pre>
337	#include <stdio.h&gt
338	#include "mmio.h"
339
340	int mm_write_mtx_crd_size(FILE *f, int M, int N, int nz);
341	</pre>
342
343	<h3>DESCRIPTION</h3>
344
345	Record the matrix dimensions <b><em>M</em></b> x <b><em>N</em></b> and
346	total number of nonzeros, <b><em>nz</em></b> to Matrix Market file.
347	Typically called after
348	<a href="#mm_write_banner"><tt>mm_write_banner()</tt></a>.
349
350	<h3> RETURN VALUES</h3>
351
352	<tt>mm_write_mtx_crd_size()</tt> returns 0 is successful, otherwise
353	MM_COULD_NOT_WRITE_FILE.
354
355	<h3> DIAGNOSTICS </h3>
356
357	This is a trivial function to write three integers to <b><em>f</em></b>
358	using <tt>fprintf()</tt>.
359	It is included in the library only for the sake of completeness,
360	as a counterpart to <a href="#mm_read_mtx_crd_size">
361	<tt>mm_read_mtx_crd_size()</tt></a>.
362
363
364	<h3>SEE ALSO</h3>
365	<a href="#mm_write_banner">mm_write_banner()</a>,
366	<a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
367	<a href="#mm_read_mtx_crd_size">mm_read_array_crd_size()</a>,
368	<a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
369	<a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>,
370
371
372	<br>
373	<br>
374	<hr>
375	<! ------------------------------------------------------------------->
376
377	<a name="mm_write_mtx_array_size"><h2> mm_write_mtx_array_size()</h2></a>
378
379	<h3>NAME</h3>
380	mm_write_mtx_array_size - write the size information of a dense matrix
381	(array format) to a Matrix Market file
382
383	<h3>SYNPOSIS</h3>
384	<pre>
385	#include <stdio.h&gt
386	#include "mmio.h"
387
388	int mm_write_mtx_array_size(FILE *f, int M, int N);
389	</pre>
390
391	<h3>DESCRIPTION</h3>
392
393	Record the matrix dimensions <b><em>M</em></b> x <b><em>N</em></b>
394	to Matrix Market file.
395	Typically called after
396	<a href="#mm_write_banner"><tt>mm_write_banner()</tt></a>.
397
398	<h3> RETURN VALUES</h3>
399
400	<tt>mm_write_mtx_array_size()</tt> returns 0 is successful, otherwise
401	MM_COULD_NOT_WRITE_FILE.
402
403	<h3>DIAGNOSTICS</h3>
404
405	This is a trivial function to write two integers to <b><em>f</em></b>
406	using <tt>fprintf()</tt>.
407	It is included in the library only as a counterpart to
408	<a href="#mm_read_mtx_array_size"><tt>mm_read_mtx_array_size()</tt></a>.
409
410
411	<h3>SEE ALSO</h3>
412	<a href="#mm_write_banner">mm_write_banner()</a>,
413	<a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
414	<a href="#mm_read_mtx_crd_size">mm_read_array_crd_size()</a>,
415	<a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
416	<a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>,
417
418
419	<br>
420	<br>
421	<hr>
422	<! ------------------------------------------------------------------->
423
424	<a name="query"><h2> MM_IS</h2></a>
425
426	<h3>NAME</h3>
427
428
429	mm_is_matrix,
430	mm_is_sparse,
431	mm_is_coordinate,
432	mm_is_dense,
433	mm_is_array,
434	mm_is_complex,
435	mm_is_real ,
436	mm_is_pattern,
437	mm_is_integer,
438	mm_is_symmetric,
439	mm_is_general,
440	mm_is_skew,
441	mm_is_hermitian -matrix type query functions
442
443	<h3>SYNPOSIS</h3>
444	<pre>
445	#include <stdio.h&gt
446	#include "mmio.h"
447
448	int mm_is_matrix(MM_typecode t);
449
450	int mm_is_sparse(MM_typecode t);
451
452	int mm_is_coordinate(MM_typecode t);
453
454	int mm_is_dense(MM_typecode t);
455
456	int mm_is_array(MM_typecode t);
457
458	int mm_is_complex(MM_typecode t);
459
460	int mm_is_real(MM_typecode t);
461
462	int mm_is_pattern(MM_typecode t);
463
464	int mm_is_integer(MM_typecode t);
465
466	int mm_is_symmetric(MM_typecode t);
467
468	int mm_is_general(MM_typecode t);
469
470	int mm_is_skew(MM_typecode t);
471
472	int mm_is_hermitian(MM_typecode t);
473
474
475	</pre>
476
477	<h3>DESCRIPTION</h3>
478	MM_QUERY functions provide a boolean test on matrix typecodes
479	(<tt>MM_typecode</tt>) variables for a given storage property.
480	The functions return 0 if false, 1 otherwise. Note that these properties
481	refer only to the <bf>storage</bf> scheme, not the mathematical properties.
482	For example, a mathematically symmetric matrix stored with both upper
483	and lower triangular halves will evaluate <tt>mm_is_symmetric()</tt> false.
484
485
486	<h3> RETURN VALUES</h3>
487
488	MM_QUERY functions return 1 if true, 0 if false.
489
490
491	<h3> DIAGNOSTICS </h3>
492
493	These functions are implemented as macros.
494
495	<h3>SEE ALSO</h3>
496	<a href="#mm_write_banner">mm_write_banner()</a>,
497	<a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
498	<a href="#mm_read_mtx_array_size">mm_read_array_crd_size()</a>,
499	<a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
500	<a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>,
501
502
503	<br>
504	<br>
505	<hr>
506	<! ------------------------------------------------------------------->
507
508
509	<a name="mm_set"><h2> MM_SET</h2></a>
510
511	<h3>NAME</h3>
512
513
514	mm_set_matrix,
515	mm_set_sparse,
516	mm_set_coordinate,
517	mm_set_dense,
518	mm_set_array,
519	mm_set_complex,
520	mm_set_real ,
521	mm_set_pattern,
522	mm_set_integer,
523	mm_set_symmetric,
524	mm_set_general,
525	mm_set_skew,
526	mm_set_hermitian,
527	mm_clear_typecode,
528	mm_initialize_typecode --matrix type query functions
529
530	<h3>SYNPOSIS</h3>
531	<pre>
532	#include <stdio.h&gt
533	#include "mmio.h"
534
535	int mm_set_matrix(MM_typecode &t);
536
537	int mm_set_sparse(MM_typecode &t);
538
539	int mm_set_coordinate(MM_typecode &t);
540
541	int mm_set_dense(MM_typecode &t);
542
543	int mm_set_array(MM_typecode &t);
544
545	int mm_set_complex(MM_typecode &t);
546
547	int mm_set_real(MM_typecode &t);
548
549	int mm_set_pattern(MM_typecode &t);
550
551	int mm_set_integer(MM_typecode &t);
552
553	int mm_set_symmetric(MM_typecode &t);
554
555	int mm_set_general(MM_typecode &t);
556
557	int mm_set_skew(MM_typecode &t);
558
559	int mm_set_hermitian(MM_typecode &t);
560
561	int mm_clear_typecode(MM_typecode &t);
562
563	int mm_initialize_typecode(MM_typecode &t);
564
565	</pre>
566
567	<h3>DESCRIPTION</h3>
568	MM_SET functions are used to encode the matrix charateristics to
569	a Matrix Market file, in conjunction with <a href="#mm_write_banner">
570	<tt>mm_write_banner()</tt></a>. To use properly, <em><b>t</b></em> first
571	must be initialized. For exmaple, the set a <tt>MM_typecode</tt> to
572	describe a complex, Hermititan, sparse matrix, one can write
573	<pre>
574
575	mm_initialize_typecode(&t);
576	mm_set_matrix(&t);
577	mm_set_complex(&t);
578	mm_set_coordinate(&t);
579	mm_set_hermitian(&t);
580
581	</pre>
582
583	<em><b>t</b></em> can then be used as an argument to
584	<tt>mm_write_banner()</tt></a>.
585	<h3> RETURN VALUES</h3>
586
587	MM_SET functions return void.
588
589
590	<h3> DIAGNOSTICS </h3>
591
592	These functions are implemented as macros.
593
594	<h3>SEE ALSO</h3>
595	<a href="#mm_write_banner">mm_write_banner()</a>,
596	<a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
597	<a href="#mm_read_mtx_array_size">mm_read_array_crd_size()</a>,
598	<a href="#mm_write_mtx_crd_size">mm_write_mtx_crd_size()</a>,
599	<a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>,
600
601
602	<br>
603	<br>
604	<hr>
605	<! ------------------------------------------------------------------->
606
607	<a name="mm_typecode_to_str"><h2> mm_typecode_to_str()</h2></a>
608
609	<h3>NAME</h3>
610	mm_typecode_to_str - convert a typecode to a descriptive string
611
612	<h3>SYNPOSIS</h3>
613	<pre>
614	#include <stdio.h&gt
615	#include "mmio.h"
616
617	char *mm_typecode_to_str(MM_typecode t);
618	</pre>
619
620	<h3>DESCRIPTION</h3>
621
622	<tt>mm_typecode_to_str</tt> converts a <tt>MM_typecode </tt>
623	to mnemonic string. This can be used as part of a diagnostics
624	and error reporting. (See "<a href="mmio/c/example_read.c">example_read.c</a>"
625	for possible use.)
626
627	<h3> RETURN VALUES</h3>
628
629	<tt>mm_typecode_to_str()</tt> returns a new character string if
630	successful, or NULL if an error occured.
631
632	<h3> DIAGNOSTICS </h3>
633	<tt>mm_typecode_to_str</tt> uses <tt>strdup()</tt> internally, and
634	consequently the returned string must be freed to avoid memory leaks.
635
636	<h3>SEE ALSO</h3>
637	<a href="#mm_write_banner">mm_write_banner()</a>,
638	<a href="#mm_read_mtx_crd_size">mm_read_mtx_crd_size()</a>,
639	<a href="#mm_read_mtx_crd_size">mm_read_array_crd_size()</a>,
640	<a href="#mm_typecode_to_str">mm_typecode_to_str()</a>,
641	<a href="#mm_write_mtx_array_size">mm_write_mtx_array_size()</a>,
642
643	<P><HR>
644	<CENTER><FONT SIZE=-2>
645	The Matrix Market is a service of the
646	<A HREF="/mcsd/">Mathematical and Computational Sciences Division</A> /
647	<A HREF="http://www.itl.nist.gov/">Information Technology Laboratory</A> /
648	<A HREF="http://www.nist.gov/">National Institute of Standards and Technology</A>
649	</FONT></CENTER>
650
651	<P>
652	[ <A HREF="index.html">Home</A> ]
653	[ <A HREF="search.html">Search</A> ]
654	[ <A HREF="browse.html">Browse</A> ]
655	[ <A HREF="resources.html">Resources</A> ]
656
657	<P>
658	Last change in this page : <I>May 2, 2000</I>.
659	[ <SCRIPT language="javascript"><!--
660	enist('matrixmarket');
661	// --></SCRIPT>
662	<noscript>matrixmarket</noscript><noscript>@</noscript><noscript>nist.gov</noscript>
663	].
664	</P>
665
666	</BODY>
667	</HTML>