The numerical data in the Matrix Market file formats can be easily processed
using variants of fscanf() and fprintf()
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.
Reading a Matrix Market file can be broken into three basic steps:
use mm_read_banner() to process the 1st line of file
and identify the matrix type
use a type-specific function, such as
mm_read_mtx_crd_size()
to skip the optional comments and
process the matrix size information
use a variant of scanf() to read the numerical data,
one matrix entry per line
Saving a matrix from an internal data structure to a Matrix Market file is
a similar process:
use mm_write_banner()
to create the 1st line of
the Matrix Market file
(optional) add '%' delimited comments
use a type-specific function, such as
mm_write_mtx_crd_size()
to record the matrix size information
use a variant of printf() to write the numerical data,
one matrix entry per line
mm_read_banner - determine the type of matrix being represented in a
Matrix Market file
SYNPOSIS
#include <stdio.h>
#include "mmio.h"
int mm_read_banner(FILE *f, MM_typecode *t);
DESCRIPTION
mm_read_banner() processes the the first line of a Matrix Market file,
e.g.
%%MatrixMarket matrix coordinate real general
and returns the matrix characteristics.
File descriptor f is defined in "stdio.h" and is assumed
to have been opened for read access. The predefined descriptor
stdin can be used to read from the standard
input.
t points to an internal structure that describes the
matrix charateristics. This MM_typecode is
more efficient and convenient
than storing the explicit banner.
query functions, such as
mm_is_complex(t), are available to extract this information.
RETURN VALUES
mm_read_banner() returns 0 if succesful. Otherwise,
it returns one of the error codes below.
ERRORS
MM_PREMATURE_EOF if all items are not present on first line of file.
MM_NO_HEADER if the file does not begin with "%%MatrixMarket".
MM_UNSUPPORTED_TYPE if not recongizable description.
mm_read_mtx_crd_size - read the size information of a sparse matrix
(coordinate format) in a Matrix Market file
SYNPOSIS
#include <stdio.h>
#include "mmio.h"
int mm_read_mtx_crd_size(FILE *f, int *M, int *N, int *nz);
DESCRIPTION
After processing the Matrix Market banner,
mm_read_mtx_crd_size() reads
past the optional comments and initalizes size variables M
(number of rows), N (number of columns), and
nz(number of non-zeros).
It is assumed that the matrix being read is in coordinate format.
RETURN VALUES
mm_read_mtx_crd_size() return 0 is successful, otherwise
it returns one of the error codes below.
ERRORS
MM_PREMATURE_EOF if an end-of-file is encountered before processing
these three values.
mm_read_mtx_array_size - read the size information of a dense matrix
(array format) in a Matrix Market file
SYNPOSIS
#include <stdio.h>
#include "mmio.h"
int mm_read_mtx_array_size(FILE *f, int *M, int *N);
DESCRIPTION
After processing the Matrix Market banner,
mm_read_mtx_crd_size() reads
past the optional comments and initalizes matrix size variables
M (number of rows), N (number of columns).
It is assumed that the matrix being read is in array format.
RETURN VALUES
mm_read_mtx_array_size() return 0 is successful, otherwise
it returns one of the error codes below.
ERRORS
MM_PREMATURE_EOF if an end-of-file is encountered before reading
M and N.
mm_write_banner - record matrix type information in Matrix Market file
SYNPOSIS
#include <stdio.h>
#include "mmio.h"
int mm_write_banner(FILE *f, MM_typecode *t);
DESCRIPTION
mm_write_banner() prints the first line of a Matrix Market file,
which consists of the "%%MatrixMarket" token followed by an attribute
list,
e.g.
%%MatrixMarket matrix coordinate real general
File descriptor f is defined in "stdio.h" and is assumed
to have been opened for write access. The predefined descriptor
stdout can be used to read from the standard
output.
t points to an internal structure that describes the
matrix charateristics. This MM_typecode is
more efficient and convenient
than storing the explicit banner. Various
assign functions, such as
mm_set_complex(&t), can be used to set
these characterisitcs.
RETURN VALUES
mm_write_banner() returns 0 if succesful. Otherwise,
it returns MM_COULD_NOT_OPEN_WRITE_FILE.
mm_write_mtx_crd_size - write the size information of a dense matrix
(array format) to a Matrix Market file
SYNPOSIS
#include <stdio.h>
#include "mmio.h"
int mm_write_mtx_crd_size(FILE *f, int M, int N, int nz);
DESCRIPTION
Record the matrix dimensions M x N and
total number of nonzeros, nz to Matrix Market file.
Typically called after
mm_write_banner().
RETURN VALUES
mm_write_mtx_crd_size() returns 0 is successful, otherwise
MM_COULD_NOT_WRITE_FILE.
DIAGNOSTICS
This is a trivial function to write three integers to f
using fprintf().
It is included in the library only for the sake of completeness,
as a counterpart to mm_read_mtx_crd_size().
mm_write_mtx_array_size - write the size information of a dense matrix
(array format) to a Matrix Market file
SYNPOSIS
#include <stdio.h>
#include "mmio.h"
int mm_write_mtx_array_size(FILE *f, int M, int N);
DESCRIPTION
Record the matrix dimensions M x N
to Matrix Market file.
Typically called after
mm_write_banner().
RETURN VALUES
mm_write_mtx_array_size() returns 0 is successful, otherwise
MM_COULD_NOT_WRITE_FILE.
DIAGNOSTICS
This is a trivial function to write two integers to f
using fprintf().
It is included in the library only as a counterpart to
mm_read_mtx_array_size().
#include <stdio.h>
#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);
DESCRIPTION
MM_QUERY functions provide a boolean test on matrix typecodes
(MM_typecode) variables for a given storage property.
The functions return 0 if false, 1 otherwise. Note that these properties
refer only to the storage scheme, not the mathematical properties.
For example, a mathematically symmetric matrix stored with both upper
and lower triangular halves will evaluate mm_is_symmetric() false.
#include <stdio.h>
#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);
DESCRIPTION
MM_SET functions are used to encode the matrix charateristics to
a Matrix Market file, in conjunction with mm_write_banner(). To use properly, t first
must be initialized. For exmaple, the set a MM_typecode to
describe a complex, Hermititan, sparse matrix, one can write
mm_typecode_to_str converts a MM_typecode
to mnemonic string. This can be used as part of a diagnostics
and error reporting. (See "example_read.c"
for possible use.)
RETURN VALUES
mm_typecode_to_str() returns a new character string if
successful, or NULL if an error occured.
DIAGNOSTICS
mm_typecode_to_str uses strdup() internally, and
consequently the returned string must be freed to avoid memory leaks.
