Common functionality of a coordinate-format sparse matrix or graph data reader. More...

#include <Teuchos_MatrixMarket_CoordDataReader.hpp>

Inheritance diagram for Teuchos::MatrixMarket::CoordDataReaderBase< Callback, Ordinal >:

Public Member Functions
	CoordDataReaderBase (const Teuchos::RCP< Callback > &adder)
	Constructor with "adder" argument. More...

	CoordDataReaderBase ()
	No-argument constructor. More...

virtual	~CoordDataReaderBase ()
	Virtual destructor for safety and happy compilers. More...

void	setAdder (const Teuchos::RCP< Callback > &adder)
	Set the Adder object. More...

virtual std::pair< bool, std::vector< size_t > >	read (std::istream &in, const size_t startingLineNumber, const bool tolerant, const bool debug=false)
	Read in all the data from the given input stream. More...

std::pair< Teuchos::Tuple < Ordinal, 3 >, bool >	readDimensions (std::istream &in, size_t &lineNumber, const bool tolerant=false)
	Read (numRows, numCols, numNonzeros). More...

Protected Member Functions
virtual bool	readLine (const std::string &theLine, const size_t lineNumber, const bool tolerant)=0
	Read in the data from a single line of the input stream. More...

Protected Attributes
Teuchos::RCP< Callback >	adder_
	Closure that knows how to add entries to the sparse graph or matrix. More...

Detailed Description

template<class Callback, class Ordinal>
class Teuchos::MatrixMarket::CoordDataReaderBase< Callback, Ordinal >

Common functionality of a coordinate-format sparse matrix or graph data reader.

This class provides common functionality for reading coordinate-format sparse matrix or graph data from a Matrix Market file. In particular, this class does not depend on the type of matrix entries. If you are writing a function to read a sparse matrix, use CoordDataReader. If you are writing a function to read a sparse graph (a "pattern matrix" in Matrix Market terms), use CoordPatternReader. If you just want to read a sparse matrix into raw compressed sparse row (CSR) arrays, use Raw::Reader. This class is mainly for Teuchos developers.

Template Parameters

Callback The type of a callback (a.k.a. closure) that knows how to add entries to the sparse graph or matrix.

Parameters

Ordinal The type of indices of the sparse graph or matrix.

Instances of Callback must implement an operator() that adds a single entry to the sparse matrix. If the matrix contains values (i.e., is not a "pattern" matrix), the Callback's operator() takes three arguments: the row index, the column index, and the value to add. If the matrix is a "pattern" matrix, then the operator() takes two arguments: the row index, and the column index. In either case, the Callback expects one-based row and column indices, as specified by the Matrix Market standard. The Raw::Adder class provides a model for Callback with the three-argument version of operator().

The Callback object defines for itself what happens if one attempts to insert two entries at the same location. They must be "merged" in some way. Usually the right thing to do is to add the values of the two entries, but you may want to define different behavior. Your Callback implementation may defer merging entries at the same location for performance reasons. (Raw::Adder does this. Its merge() method merges the entries.)

Note that this class does not have the notion of the type of entries of the matrix, only the type of the indices in the matrix (Ordinal). The CoordDataReader subclass defines the type of matrix entries as its Scalar template parameter. The CoordPatternReader subclass does not define the type of matrix entries, because it stores a graph (a "pattern matrix" in Matrix Market terms).

Definition at line 100 of file Teuchos_MatrixMarket_CoordDataReader.hpp.

Constructor & Destructor Documentation

template<class Callback , class Ordinal >

Teuchos::MatrixMarket::CoordDataReaderBase< Callback, Ordinal >::CoordDataReaderBase ( const Teuchos::RCP< Callback > & adder )

inline

Constructor with "adder" argument.

This is the favored way to construct an instance of this type. Only use the no-argument constructor if you have a "chicken-and-egg" problem, where in order to create the Callback instance, you need the graph or matrix dimensions.

Parameters

adder [in/out] Closure (a.k.a. callback) whose operator() adds an entry to the sparse graph or matrix on each invocation.

Definition at line 116 of file Teuchos_MatrixMarket_CoordDataReader.hpp.

template<class Callback , class Ordinal >

Teuchos::MatrixMarket::CoordDataReaderBase< Callback, Ordinal >::CoordDataReaderBase ( )

inline

No-argument constructor.

We offer this option in case the adder's constructor needs the graph or matrix dimensions, so that it's necessary to call readDimensions() first before constructing the adder. You should call setAdder() with a non-null argument before calling read() or readLine().

Definition at line 126 of file Teuchos_MatrixMarket_CoordDataReader.hpp.

template<class Callback , class Ordinal >

virtual Teuchos::MatrixMarket::CoordDataReaderBase< Callback, Ordinal >::~CoordDataReaderBase ( )

inlinevirtual

Virtual destructor for safety and happy compilers.

Definition at line 129 of file Teuchos_MatrixMarket_CoordDataReader.hpp.

Member Function Documentation

template<class Callback , class Ordinal >

void Teuchos::MatrixMarket::CoordDataReaderBase< Callback, Ordinal >::setAdder ( const Teuchos::RCP< Callback > & adder )

inline

Set the Adder object.

Please don't call this after calling read() or readLine(). The right time to call this is right after calling the no-argument constructor, if it's not possible to supply an Adder object before calling readDimensions().

Definition at line 137 of file Teuchos_MatrixMarket_CoordDataReader.hpp.

template<class Callback , class Ordinal >

virtual bool Teuchos::MatrixMarket::CoordDataReaderBase< Callback, Ordinal >::readLine	(	const std::string &	theLine,
		const size_t	lineNumber,
		const bool	tolerant
	)

protectedpure virtual

Read in the data from a single line of the input stream.

Parameters

theLine	[in] The line read in from the input stream.
adder	[in/out] The callback to invoke for adding an entry to the sparse matrix.
lineNumber	[in] Current line number of the file. We use this for generating informative exception messages.
tolerant	[in] Whether to parse tolerantly.

Returns: In tolerant parsing mode (tolerant==true), then this method returns true if parsing the current line succeeded, else false. Otherwise, this method throws an exception (and does not invoke the adder) if parsing the current line did not succeed.

Subclasses must implement this method in order to read one entry of the sparse graph or matrix. Implementations should use the callback (adder_) to add the entry.

Note: To implementers: We defer implementation of this method to subclasses, because the callback for a graph will take different arguments than the callback for a matrix. Abstracting around that using templates isn't worth the trouble. (Remember you're reading from a file and parsing strings. Virtual method call overhead isn't significant by comparison.)

Implemented in Teuchos::MatrixMarket::CoordPatternReader< Callback, Ordinal >, Teuchos::MatrixMarket::CoordDataReader< Callback, Ordinal, Scalar, false >, and Teuchos::MatrixMarket::CoordDataReader< Callback, Ordinal, Scalar, isComplex >.

template<class Callback , class Ordinal >

virtual std::pair<bool, std::vector<size_t> > Teuchos::MatrixMarket::CoordDataReaderBase< Callback, Ordinal >::read	(	std::istream &	in,
		const size_t	startingLineNumber,
		const bool	tolerant,
		const bool	debug = `false`
	)

inlinevirtual

Read in all the data from the given input stream.

Parameters

in	[in/out] The input stream from which to read
startingLineNumber	[in] The line number of the file from which we begin reading. (This is used for informative error output, if an error is detected in the file.)
tolerant	[in] If true, parse tolerantly. The resulting read-in data may be incorrect, but the parser won't throw an exception if it can just let bad data through and continue.
debug	[in] If true, print verbose debugging output.

Returns: If tolerant==false, the returned pair is always true and the empty vector. If tolerant==true, the first entry of the pair is whether all lines of data were read successfully, and the second entry is the list of line numbers containing bad data. The first entry of the pair is false if and only if the vector has nonzero size.

Note: This method is virtual in case derived classes want to override the default behavior. The specific example we have in mind is a "pattern matrix" (i.e., a sparse graph), which we would represent with Scalar=void.

Definition at line 203 of file Teuchos_MatrixMarket_CoordDataReader.hpp.

template<class Callback , class Ordinal >

std::pair<Teuchos::Tuple<Ordinal, 3>, bool> Teuchos::MatrixMarket::CoordDataReaderBase< Callback, Ordinal >::readDimensions	(	std::istream &	in,
		size_t &	lineNumber,
		const bool	tolerant = `false`
	)

inline

Read (numRows, numCols, numNonzeros).

Read one line from the given input stream, and parse it into the number of rows, the number of columns, and the number of nonzeros in the sparse matrix. We assume that those data are in whitespace-delimited format and are read from a Matrix Market - format file.

Parameters

in	[in/out] The input stream from which to attempt to read one line.
lineNumber	The starting line number from which we begin reading from the input stream. Used for diagnostic error output.
tolerant	[in] Whether to read "tolerantly" (setting defaults and returning whether we were successful) or "intolerantly" (throwing an exception on any deviation from the expected format).

Returns: ((numRows, numCols, numNonzeros), success). In tolerant mode, success may be false, meaning that the read-in triple may not be valid.

Definition at line 262 of file Teuchos_MatrixMarket_CoordDataReader.hpp.

Member Data Documentation

template<class Callback , class Ordinal >

Teuchos::RCP<Callback> Teuchos::MatrixMarket::CoordDataReaderBase< Callback, Ordinal >::adder_

protected

Closure that knows how to add entries to the sparse graph or matrix.

Definition at line 103 of file Teuchos_MatrixMarket_CoordDataReader.hpp.

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

Teuchos_MatrixMarket_CoordDataReader.hpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

template<class Callback, class Ordinal> class Teuchos::MatrixMarket::CoordDataReaderBase< Callback, Ordinal >

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

template<class Callback, class Ordinal>
class Teuchos::MatrixMarket::CoordDataReaderBase< Callback, Ordinal >