Provides I/O functionality for MatrixMarket exchange file format. More...

#include <matrix_io_mtx.h>

Inheritance diagram for ug::MatrixIOMtx:

Public Member Functions
std::string	get_mat_file_name () const
	Retreive associated exchange file path and name. More...

size_t	get_num_cols () const
	Retrieves number of columns as specified in the exchange file. More...

size_t	get_num_lines () const
	Retrieves number of data lines as specified in the exchange file. More...

size_t	get_num_rows () const
	Retrieves number of rows as specified in the exchange file. More...

bool	is_sparse () const
	Tells whether the associated exchange file holds a sparse matrix. More...

	MatrixIOMtx ()
	Default constructor. More...

	MatrixIOMtx (std::string mFile, int openMode=MatrixIO::EXISTING)
	Constructor specifying matrix exchange file path. More...

template<typename matrix_type >
void	read_into (matrix_type &matrix)
	Reads data from associated exchange file into ug matrix. More...

void	set_mat_dims (size_t rows, size_t cols, size_t lines)
	Sets the size of the matrix and number of data lines. More...

void	set_mat_file_name (std::string mFile, int openMode=MatrixIO::EXISTING)
	Sets associated file to another one. More...

template<typename matrix_type >
void	write_from (matrix_type &matrix, std::string comment="%Generated with ug4.")
	Writes a ug matrix into the associated MatrixMarket exchange file. More...

	~MatrixIOMtx ()
	Destructor. More...

Private Member Functions
void	close_file ()

template<typename matrix_type >
std::vector< std::vector< size_t > >	determine_matrix_characteristics (const matrix_type &matrix)
	Determines characteristics of given matrix. More...

void	open_file (std::ios_base::openmode mode=std::ios_base::in)

void	query_matrix_characteristics ()
	Retreives matrix size and number non-zeros from exchange file. More...

void	query_matrix_type ()
	Parses banner of MatrixMarket file. More...

void	read_entry (size_t m, size_t n, CPUAlgebra::matrix_type::value_type *val)
	Reads and parses the next data line. More...

void	write_banner ()
	Writes the banner to the associated MatrixMarket file. More...

void	write_entry (size_t m, size_t n, CPUAlgebra::matrix_type::value_type val)
	Appends a data line to the associated file. More...

Private Member Functions inherited from ug::MatrixIO
std::string	get_mat_file_name () const
	Retreive associated exchange file path and name. More...

	MatrixIO ()
	Number of rows as specified in the matrix exchange file. More...

	MatrixIO (std::string mFile, int openMode=EXISTING)
	Constructor specifying matrix exchange file path. More...

void	set_mat_file_name (std::string mFile, int openMode=EXISTING)
	Sets associated file to another one. More...

	~MatrixIO ()
	Destructor. More...

Private Attributes
size_t	m_cols

size_t	m_firstDataLine
	Line number of the first data line (0 based) More...

size_t	m_lines

std::fstream	m_matFileStream

MatrixFileType	m_matFileType

MMTypeCode	m_mmTypeCode
	Characteristics of MatrixMarket matrix. More...

std::string *	m_pMatFileName

size_t	m_rows

Additional Inherited Members
Private Types inherited from ug::MatrixIO
enum	OpenMode { EXISTING = 1 , NEW = 2 }
	Specifies how file names pointing to non-existing files should be handeld. More...

Detailed Description

Provides I/O functionality for MatrixMarket exchange file format.

Given the path to a .mtx file it queries the therein stored matrix type and characteristics. With readInto(matrixType &matrix) an easy way of reading the represented matrix into a CPUAlgebra::matrix_type object is provided.

Note: So far, only real sparse matrices either symmetric or skew-symmetric or none of both are supported. Support for dense matrices (either really dense or just in array format) will come soon. Non-real (i.e. complex, integer or pattern) matrices and hermitian matrices might be supported in the future.

The specification of the MatrixMarket matrix exchange format can be found here: http://math.nist.gov/MatrixMarket/formats.html#MMformat

Note: Please include the generic MatrixIO header file (lib_algebra/common/matrixio/matrix_io.h) for usage and not the header file of this specific exchange file format.

Constructor & Destructor Documentation

◆ MatrixIOMtx() [1/2]

ug::MatrixIOMtx::MatrixIOMtx ( )

Default constructor.

◆ MatrixIOMtx() [2/2]

ug::MatrixIOMtx::MatrixIOMtx	(	std::string	mFile,
		int	openMode = `MatrixIO::EXISTING`
	)

Constructor specifying matrix exchange file path.

After successful call to MatrixIOMtx::set_mat_file_name it calls MatrixIOMtx::query_matrix_type and MatrixIOMtx::query_matrix_characteristics as long as openMode is MatrixIO::OpenMode::EXISTING.

Parameters

[in]	mFile	Full path and name of matrix exchange file.
[in]	openMode	how to deal with non-existing files (a value of MatrixIO::OpenMode)

References ug::MatrixIO::EXISTING, PROFILE_FUNC, query_matrix_characteristics(), query_matrix_type(), and set_mat_file_name().

◆ ~MatrixIOMtx()

ug::MatrixIOMtx::~MatrixIOMtx ( )

Destructor.

The destructor calls MatrixIOMtx::close_file to make sure, that write operations to the associated exchange file are flushed and terminated correctly.

References close_file(), and m_pMatFileName.

Member Function Documentation

◆ close_file()

void ug::MatrixIOMtx::close_file ( )

private

References m_matFileStream.

Referenced by query_matrix_characteristics(), query_matrix_type(), read_into(), write_banner(), write_from(), and ~MatrixIOMtx().

◆ determine_matrix_characteristics()

template<typename matrix_type >

std::vector< std::vector<size_t> > ug::MatrixIOMtx::determine_matrix_characteristics ( const matrix_type & matrix )

inlineprivate

Determines characteristics of given matrix.

Symmetries of the given matrix are determined and saved.

Parameters

[in] matrix Matrix of CPUAlgebra::matrix_type to analyse

Returns: 2D vector with coordinates of non-zero entries of the given matrix with column indices as first and row indices as second dimension.

Exceptions

std::runtime_error if the matrix was determined to be symmetric and skew-symmetric at the same time

References ug::MMTypeCode::COORDINATE, ug::MMTypeCode::GENERAL, m_mmTypeCode, PROFILE_FUNC, ug::MMTypeCode::REAL, ug::MMTypeCode::set_algebraic_type(), ug::MMTypeCode::set_class_type(), set_mat_dims(), ug::MMTypeCode::set_numeric_type(), ug::MMTypeCode::SKEW, ug::MMTypeCode::SYMMETRIC, and UG_ASSERT.

Referenced by write_from().

◆ get_mat_file_name()

std::string ug::MatrixIOMtx::get_mat_file_name ( ) const

Retreive associated exchange file path and name.

Returns: String representation of exchange file with full path as set by constructor or MatrixIOMtx::set_mat_file_name.

References m_pMatFileName.

◆ get_num_cols()

size_t ug::MatrixIOMtx::get_num_cols ( ) const

Retrieves number of columns as specified in the exchange file.

Returns: Number of columns as size_t

References m_cols.

◆ get_num_lines()

size_t ug::MatrixIOMtx::get_num_lines ( ) const

Retrieves number of data lines as specified in the exchange file.

Returns: Number of data lines as size_t

References m_lines.

◆ get_num_rows()

size_t ug::MatrixIOMtx::get_num_rows ( ) const

Retrieves number of rows as specified in the exchange file.

Returns: Number of rows as size_t

References m_rows.

◆ is_sparse()

bool ug::MatrixIOMtx::is_sparse ( ) const

Tells whether the associated exchange file holds a sparse matrix.

Returns: true if it is in coordinate format, false otherwise

References ug::MMTypeCode::is_sparse(), and m_mmTypeCode.

Referenced by read_entry().

◆ open_file()

void ug::MatrixIOMtx::open_file ( std::ios_base::openmode mode = std::ios_base::in )

private

References m_matFileStream, m_pMatFileName, and UG_ASSERT.

Referenced by query_matrix_characteristics(), query_matrix_type(), read_into(), write_banner(), and write_from().

◆ query_matrix_characteristics()

void ug::MatrixIOMtx::query_matrix_characteristics ( )

private

Retreives matrix size and number non-zeros from exchange file.

The first non-empty line after the comments (lines starting with %) consists of three values for the coordinate format:

nRows nCols nLines

nRows: Number of rows of the described matrix
nCols: Number of columns of the described matrix
nLines: Number of data lines. For types symmetric, skew-symmetric and hermitian, this is not equal to the number of non-zero elements.

Exceptions

std::runtime_error	if the file stream ended unexpectetly (e.g. the exchange file does not contain data lines)
UGError	if the exchange file does not describe a coordinate/sparse matrix (as only sparse matrices are supported yet)

References close_file(), ug::MMTypeCode::is_sparse(), m_firstDataLine, m_matFileStream, m_mmTypeCode, open_file(), PROFILE_FUNC, set_mat_dims(), ug::vrl::split(), UG_ASSERT, and UG_THROW.

Referenced by MatrixIOMtx().

◆ query_matrix_type()

void ug::MatrixIOMtx::query_matrix_type ( )

private

Parses banner of MatrixMarket file.

The banner is the first line of a MatrixMarket file with the syntax:

%MatrixMarket matrix [format] [numeric] [type]

format: Either coordinate or array, representing a sparse or dense matrix respectively
numeric: Either real, complex, integer or pattern, representing the numerical type of the values
type: Either general, symmetric, skew-symmetric or hermitian, representing the algebraic type of the matrix

Exceptions

std::runtime_error	if the banner starts not with `%MatrixMarket`
std::runtime_error	if the second word of the banner is not `matrix`
UGError	if the `format` identifier is invalid
UGError	if the `numeric` identifier is invalid
UGError	if the `type` identifier is invalid

References close_file(), m_matFileStream, m_mmTypeCode, MM_BANNER_STR, MM_MTX_STR, open_file(), PROFILE_FUNC, s, ug::MMTypeCode::set_algebraic_type(), ug::MMTypeCode::set_class_type(), ug::MMTypeCode::set_numeric_type(), and UG_ASSERT.

Referenced by MatrixIOMtx().

◆ read_entry()

void ug::MatrixIOMtx::read_entry	(	size_t *	m,
		size_t *	n,
		CPUAlgebra::matrix_type::value_type *	val
	)

private

Reads and parses the next data line.

Note: This function does not open the filestream by itself, but requires it to be already open.

Parameters

[out]	m	pointer to store the row index to (1 based)
[out]	n	pointer to store the column index to (1 based)
[out]	val	pointer to store the value to

Exceptions

std::runtime_error	if the filestream is not open
std::runtime_error	if the matrix is sparse but there were less or more than 3 elements in the line
ug::UGError	if the exchange file does not describe a coordinate/sparse matrix (as only sparse matrices are supported yet)

References is_sparse(), m_matFileStream, PROFILE_FUNC, ug::vrl::split(), UG_ASSERT, and UG_THROW.

Referenced by read_into().

◆ read_into()

template<typename matrix_type >

void ug::MatrixIOMtx::read_into ( matrix_type & matrix )

inline

Reads data from associated exchange file into ug matrix.

The given ug-matrix is first resized. Each data line of the underlying exchange file is read separately and independently. If the matrix is (skew-)symmetric as defined in the exchange file, this is considered during writing the values to the correct positions.

Note: This function does not take care about memory alignement of the given ug-matrix (e.g. SparseMatrix::defragment ).

Parameters

[in,out] matrix Matrix of CPUAlgebra::matrix_type to read into

Exceptions

std::runtime_error	if one of `m_rows`, `m_cols` or `m_lines` is not positive.
UGError	if exchange file's matrix is not in coordinate format (as only sparse matrices are supported yet)

References close_file(), ug::MMTypeCode::is_skew_symmetric(), ug::MMTypeCode::is_sparse(), ug::MMTypeCode::is_symmetric(), m_cols, m_firstDataLine, m_lines, m_matFileStream, m_mmTypeCode, m_rows, open_file(), PROFILE_FUNC, read_entry(), UG_ASSERT, and UG_THROW.

◆ set_mat_dims()

void ug::MatrixIOMtx::set_mat_dims	(	size_t	rows,
		size_t	cols,
		size_t	lines
	)

Sets the size of the matrix and number of data lines.

In case of reading from a matrix exchange file, this function is called by MatrixIOMtx::query_matrix_characteristics.

Parameters

[in]	rows	Number of rows of the matrix
[in]	cols	Number of columns of the matrix
[in]	lines	Number of data lines in the exchange file

Exceptions

std::runtime_error	if `rows` is not positive
std::runtime_error	if `cols` is not positive
std::runtime_error	if `lines` is not positive

References m_cols, m_lines, m_rows, PROFILE_FUNC, and UG_ASSERT.

Referenced by determine_matrix_characteristics(), and query_matrix_characteristics().

◆ set_mat_file_name()

void ug::MatrixIOMtx::set_mat_file_name	(	std::string	mFile,
		int	openMode = `MatrixIO::EXISTING`
	)

Sets associated file to another one.

Note: It does not check, whether the given file is a MatrixMarket exchange file. Only it's existance is verified.

Parameters

[in]	mFile	Full path and name of matrix exchange file.
[in]	openMode	how to deal with non-existing files

Exceptions

std::runtime_error	if exchange file is not found and `openMode=MatrixIO::OpenMode::Existing`.
UGError	if `openMode` is non of MatrixIO::OpenMode

References ug::MatrixIO::EXISTING, ug::FileExists(), m_pMatFileName, ug::MatrixIO::NEW, PROFILE_FUNC, UG_ASSERT, and UG_THROW.

Referenced by MatrixIOMtx().

◆ write_banner()

void ug::MatrixIOMtx::write_banner ( )

private

Writes the banner to the associated MatrixMarket file.

Note: Any existing content of the associated file will be delted.

References close_file(), ug::MMTypeCode::is_general(), ug::MMTypeCode::is_skew_symmetric(), ug::MMTypeCode::is_symmetric(), m_matFileStream, m_mmTypeCode, MM_BANNER_STR, MM_COORDINATE_STR, MM_GENERAL_STR, MM_MTX_STR, MM_REAL_STR, MM_SKEW_STR, MM_SYMMETRIC_STR, and open_file().

Referenced by write_from().

◆ write_entry()

void ug::MatrixIOMtx::write_entry	(	size_t	m,
		size_t	n,
		CPUAlgebra::matrix_type::value_type	val
	)

private

Appends a data line to the associated file.

The value is formatted to scientific notation with 13 digits of precision.

Parameters

[out]	m	row index (1 based)
[out]	n	column index (1 based)
[out]	val	value at [row,col]

Exceptions

std::runtime_error	if the filestream is not open
std::runtime_error	if either the specified row or column index is not positive

References m_matFileStream, PROFILE_FUNC, and UG_ASSERT.

Referenced by write_from().

◆ write_from()

template<typename matrix_type >

void ug::MatrixIOMtx::write_from	(	matrix_type &	matrix,
		std::string	comment = `"%Generated with ug4."`
	)

inline

Writes a ug matrix into the associated MatrixMarket exchange file.

From this analysis the MatrixMarket exchange file banner is constructed and the characteristics and data lines written to that file consecutively.

A comment is added right after the banner. The default comment is Generated with ug4.. To suppress the comment line completely, pass an empty string as the comment parameter to this function.

Note: Please make sure, the lines of the given comment are not longer than 1025 characters and all liness start with a %.

Todo:: Implement validity check for the comment.

The resulting MatrixMarket exchange file is in line with the specifications.

Parameters

[in]	matrix	Matrix of CPUAlgebra::matrix_type to read from
[in]	comment	Optional comment to be put atop of the MatrixMarket matrix exchange file.

References close_file(), determine_matrix_characteristics(), m_cols, m_lines, m_matFileStream, m_rows, open_file(), PROFILE_FUNC, UG_WARNING, write_banner(), and write_entry().

Referenced by ug::SaveMatrixToMTX().

Member Data Documentation

◆ m_cols

size_t ug::MatrixIOMtx::m_cols

private

Referenced by get_num_cols(), read_into(), set_mat_dims(), and write_from().

◆ m_firstDataLine

size_t ug::MatrixIOMtx::m_firstDataLine

private

Line number of the first data line (0 based)

Referenced by query_matrix_characteristics(), and read_into().

◆ m_lines

size_t ug::MatrixIOMtx::m_lines

private

Referenced by get_num_lines(), read_into(), set_mat_dims(), and write_from().

◆ m_matFileStream

std::fstream ug::MatrixIOMtx::m_matFileStream

private

Referenced by close_file(), open_file(), query_matrix_characteristics(), query_matrix_type(), read_entry(), read_into(), write_banner(), write_entry(), and write_from().

◆ m_matFileType

MatrixFileType ug::MatrixIOMtx::m_matFileType

private

◆ m_mmTypeCode

MMTypeCode ug::MatrixIOMtx::m_mmTypeCode

private

Characteristics of MatrixMarket matrix.

Referenced by determine_matrix_characteristics(), is_sparse(), query_matrix_characteristics(), query_matrix_type(), read_into(), and write_banner().

◆ m_pMatFileName

std::string* ug::MatrixIOMtx::m_pMatFileName

private

Referenced by get_mat_file_name(), open_file(), set_mat_file_name(), and ~MatrixIOMtx().

◆ m_rows

size_t ug::MatrixIOMtx::m_rows

private

Referenced by get_num_rows(), read_into(), set_mat_dims(), and write_from().

The documentation for this class was generated from the following files:

ugbase/lib_algebra/common/matrixio/matrix_io_mtx.h
ugbase/lib_algebra/common/matrixio/matrix_io_mtx.cpp

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ MatrixIOMtx() [1/2]

◆ MatrixIOMtx() [2/2]

◆ ~MatrixIOMtx()

Member Function Documentation

◆ close_file()

◆ determine_matrix_characteristics()

◆ get_mat_file_name()

◆ get_num_cols()

◆ get_num_lines()

◆ get_num_rows()

◆ is_sparse()

◆ open_file()

◆ query_matrix_characteristics()

◆ query_matrix_type()

◆ read_entry()

◆ read_into()

◆ set_mat_dims()

◆ set_mat_file_name()

◆ write_banner()

◆ write_entry()

◆ write_from()

Member Data Documentation

◆ m_cols

◆ m_firstDataLine

◆ m_lines

◆ m_matFileStream

◆ m_matFileType

◆ m_mmTypeCode

◆ m_pMatFileName

◆ m_rows