Matrix Market

[ Home ] [ Search ] [ Browse ] [ Resources ]

ANSI C library for Matrix Market I/O

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:

  1. use mm_read_banner() to process the 1st line of file and identify the matrix type
  2. use a type-specific function, such as mm_read_mtx_crd_size() to skip the optional comments and process the matrix size information
  3. 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:

  1. use mm_write_banner() to create the 1st line of the Matrix Market file
  2. (optional) add '%' delimited comments
  3. use a type-specific function, such as mm_write_mtx_crd_size() to record the matrix size information
  4. use a variant of printf() to write the numerical data, one matrix entry per line

Source code


Documentation


mm_read_banner()

NAME

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

EXAMPLES

See example_read.c.

SEE ALSO

mm_write_banner(), mm_read_mtx_crd_size(), mm_read_array_crd_size(), mm_write_mtx_crd_size(), mm_write_mtx_array_size()


mm_read_mtx_crd_size()

NAME

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

SEE ALSO

mm_write_banner(), mm_read_mtx_crd_size(), mm_read_array_crd_size(), mm_write_mtx_crd_size(), mm_write_mtx_array_size(),


mm_read_mtx_array_size()

NAME

mm_read_mtx_crd_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

SEE ALSO

mm_write_banner(), mm_read_mtx_crd_size(), mm_read_array_crd_size(), mm_write_mtx_crd_size(), mm_write_mtx_array_size(),


mm_write_banner()

NAME

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.

EXAMPLES

See example_write.c.

SEE ALSO

mm_write_banner(), mm_read_mtx_crd_size(), mm_read_array_crd_size(), mm_write_mtx_crd_size(), mm_write_mtx_array_size()


mm_write_mtx_crd_size()

NAME

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().

SEE ALSO

mm_write_banner(), mm_read_mtx_crd_size(), mm_read_array_crd_size(), mm_write_mtx_crd_size(), mm_write_mtx_array_size(),


mm_write_mtx_array_size()

NAME

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().

SEE ALSO

mm_write_banner(), mm_read_mtx_crd_size(), mm_read_array_crd_size(), mm_write_mtx_crd_size(), mm_write_mtx_array_size(),


MM_IS

NAME

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

SYNPOSIS

	#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.

RETURN VALUES

MM_QUERY functions return 1 if true, 0 if false.

DIAGNOSTICS

These functions are implemented as macros.

SEE ALSO

mm_write_banner(), mm_read_mtx_crd_size(), mm_read_array_crd_size(), mm_write_mtx_crd_size(), mm_write_mtx_array_size(),


MM_SET

NAME

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

SYNPOSIS

	#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_initialize_typecode(&t);
	mm_set_matrix(&t);
	mm_set_complex(&t);
	mm_set_coordinate(&t);
	mm_set_hermitian(&t);

t can then be used as an argument to mm_write_banner().

RETURN VALUES

MM_SET functions return void.

DIAGNOSTICS

These functions are implemented as macros.

SEE ALSO

mm_write_banner(), mm_read_mtx_crd_size(), mm_read_array_crd_size(), mm_write_mtx_crd_size(), mm_write_mtx_array_size(),


mm_typecode_to_str()

NAME

mm_typecode_to_str - convert a typecode to a descriptive string

SYNPOSIS

	#include <stdio.h>
	#include "mmio.h"

	char *mm_typecode_to_str(MM_typecode t);

DESCRIPTION

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.

SEE ALSO

mm_write_banner(), mm_read_mtx_crd_size(), mm_read_array_crd_size(), mm_typecode_to_str(), mm_write_mtx_array_size(),


The Matrix Market is a service of the Mathematical and Computational Sciences Division / Information Technology Laboratory / National Institute of Standards and Technology

[ Home ] [ Search ] [ Browse ] [ Resources ]

Last change in this page : May 2, 2000. [ ].