To be used with Checker for "raw" sparse matrix input. More...

#include <Teuchos_MatrixMarket_Raw_Adder.hpp>

Public Member Functions
	Adder ()
	Default constructor. More...

	Adder (const Ordinal expectedNumRows, const Ordinal expectedNumCols, const Ordinal expectedNumEntries, const bool tolerant=false, const bool debug=false)
	Standard constructor. More...

void	operator() (const Ordinal i, const Ordinal j, const Scalar &Aij, const bool countAgainstTotal=true)
	Add an entry to the sparse matrix. More...

void	print (std::ostream &out, const bool doMerge, const bool replace=false)
	Print the sparse matrix data. More...

std::pair< size_type, size_type >	merge (const bool replace=false)
	Merge duplicate elements. More...

void	mergeAndConvertToCSR (size_type &numUniqueElts, size_type &numRemovedElts, Teuchos::ArrayRCP< Ordinal > &rowptr, Teuchos::ArrayRCP< Ordinal > &colind, Teuchos::ArrayRCP< Scalar > &values, const bool replace=false)
	Merge duplicate elements and convert to zero-based CSR. More...

const std::vector< element_type > &	getEntries () const
	A temporary const view of the entries of the matrix. More...

void	clear ()
	Clear all the added matrix entries and reset metadata. More...

const Ordinal	numRows () const
	Computed number of rows. More...

const Ordinal	numCols () const
	Computed number of columns. More...

Detailed Description

template<class Scalar, class Ordinal>
class Teuchos::MatrixMarket::Raw::Adder< Scalar, Ordinal >

To be used with Checker for "raw" sparse matrix input.

Template Parameters

Scalar	The type of entries in the sparse matrix.
Ordinal	The type of indices in the sparse matrix.

This class implements the following interface, which is required by the Callback template parameter of Teuchos::MatrixMarket::CoordDataReader:

class AdderType {
public:
  typedef ... index_type; // Ellipsis represents the actual type
  typedef ... value_type; // Ellipsis represents the actual type
  void operator() (const index_type, const index_type, const value_type&);
};

For Adder, the Scalar template parameter is value_type, and the Ordinal template parameter is index_type. Adder provides a simple implementation of the above interface which is useful for things like printing out a sparse matrix's entries, or converting between storage formats.

It is possible to nest classes that implement the above interface, in order to modify the definition of inserting values into a sparse matrix. (If you are familiar with Emacs Lisp, this is called "advising" (the insertion function, in this case). See the Emacs Lisp Manual for details.) If you are building a chain of classes, each of which implements the above interface by calling the next lower class' operator() beneath it, this class is a good start, since it implements insertion of values directly. SymmetrizingAdder is an example; it "advises" Adder by inserting an entry at (j,i) whenever Adder inserts an entry at (i,j) with i != j.

Definition at line 283 of file Teuchos_MatrixMarket_Raw_Adder.hpp.

Constructor & Destructor Documentation

template<class Scalar , class Ordinal >

Teuchos::MatrixMarket::Raw::Adder< Scalar, Ordinal >::Adder ( )

inline

Default constructor.

If you call the default constructor, we assume that you want tolerant mode (in which the Adder tries to infer the matrix dimensions and number of entries from the actual matrix data, not from any metadata). Tolerant mode is similar to what Matlab does if you give it an ASCII file of (i,j,Aij) triples. It may get the matrix dimensions (m,n) wrong if the lower right entry of the matrix is zero and is not supplied explicitly by calling operator().

Definition at line 300 of file Teuchos_MatrixMarket_Raw_Adder.hpp.

template<class Scalar , class Ordinal >

Teuchos::MatrixMarket::Raw::Adder< Scalar, Ordinal >::Adder	(	const Ordinal	expectedNumRows,
		const Ordinal	expectedNumCols,
		const Ordinal	expectedNumEntries,
		const bool	tolerant = `false`,
		const bool	debug = `false`
	)

inline

Standard constructor.

Parameters

expectedNumRows	[in] Number of rows in the matrix, as specified by the matrix metadata.
expectedNumCols	[in] Number of columns in the matrix, as specified by the matrix metadata.
expectedNumEntries	[in] Number of entries in the matrix, as specified by the matrix metadata.
tolerant	[in] Whether the "expected" metadata is required to match what the read-in matrix entries tell us.
debug	[in] If true, we may print copious status output for debugging purposes.

Definition at line 328 of file Teuchos_MatrixMarket_Raw_Adder.hpp.

Member Function Documentation

template<class Scalar , class Ordinal >

void Teuchos::MatrixMarket::Raw::Adder< Scalar, Ordinal >::operator()	(	const Ordinal	i,
		const Ordinal	j,
		const Scalar &	Aij,
		const bool	countAgainstTotal = `true`
	)

inline

Add an entry to the sparse matrix.

If tolerant==false, this method will perform error checking to ensure that the matrix data matches the metadata. For example, it will check that i and j are in bounds. If countAgainstTotal is true, it will also check to make sure you haven't added more than the expected number of matrix entries. Regardless, this method will update the "actual" metadata.

Parameters

i	[in] (1-based) row index
j	[in] (1-based) column index
Aij	[in] Value of the entry A(i,j)
countAgainstTotal	[in] Whether to count the entry to insert against the total expected number of entries. The default is true. Make this false if you are inserting an entry that wasn't stored in the original Matrix Market file, which you're adding in order to preserve symmetry or some other related structural property of the matrix.

Definition at line 364 of file Teuchos_MatrixMarket_Raw_Adder.hpp.

template<class Scalar , class Ordinal >

void Teuchos::MatrixMarket::Raw::Adder< Scalar, Ordinal >::print	(	std::ostream &	out,
		const bool	doMerge,
		const bool	replace = `false`
	)

inline

Print the sparse matrix data.

We always print the data sorted. You may also merge duplicate entries if you prefer.

Parameters

out	[out] Output stream to which to print
doMerge	[in] Whether to merge entries before printing
replace	[in] If merging, whether to replace duplicate entries; otherwise their values are added together.

Definition at line 409 of file Teuchos_MatrixMarket_Raw_Adder.hpp.

template<class Scalar , class Ordinal >

std::pair<size_type, size_type> Teuchos::MatrixMarket::Raw::Adder< Scalar, Ordinal >::merge ( const bool replace = false )

inline

Merge duplicate elements.

Merge elements of the sparse matrix that have the same row and column indices ("duplicates"). Resize the array of elements to fit just the "unique" (not duplicate) elements.

Parameters

replace [in] If true, replace each duplicate element with the next element sharing the same row and column index. This means that results will depend on the order in which the duplicate elements were added. Otherwise, duplicate elements have their values added together; in that case, the result is independent (in exact arithmetic, not in finite-precision arithmetic) of their order.

Returns: (# unique elements, # removed elements)

Note: This method does not change the "expected" or "seen" numbers of entries, since both of those count entries with the same row and column indices as separate entries.

Definition at line 444 of file Teuchos_MatrixMarket_Raw_Adder.hpp.

template<class Scalar , class Ordinal >

void Teuchos::MatrixMarket::Raw::Adder< Scalar, Ordinal >::mergeAndConvertToCSR	(	size_type &	numUniqueElts,
		size_type &	numRemovedElts,
		Teuchos::ArrayRCP< Ordinal > &	rowptr,
		Teuchos::ArrayRCP< Ordinal > &	colind,
		Teuchos::ArrayRCP< Scalar > &	values,
		const bool	replace = `false`
	)

inline

Merge duplicate elements and convert to zero-based CSR.

Merge elements of the sparse matrix that have the same row and column indices ("duplicates"). Resize the array of elements to fit just the "unique" (not duplicate) elements. Return a CSR (compressed sparse row) version of the data, with zero-based indices.

We combine merge and conversion to CSR because the latter requires the former.

Parameters

numUniqueElts	[out] Same as the first return value of merge().
numRemovedElts	[out] Same as the second return value of merge().
rowptr	[out] Array of numRows+1 offsets, where numRows is the number of rows in the sparse matrix. For row i (zero-based indexing), the entries of that row are in indices rowptr[i] .. rowptr[i+1]-1 of colind and values.
colind	[out] Column indices of the matrix. Same number of entries as values. colind[k] is the column index of values[k].
values	[out] Values stored in the matrix.
replace	[in] If true, replace each duplicate element with the next element sharing the same row and column index. This means that results will depend on the order in which the duplicate elements were added. Otherwise, duplicate elements have their values added together; in that case, the result is independent (in exact arithmetic, not in finite-precision arithmetic) of their order.

Note: This method does not change the "expected" or "seen" numbers of entries, since both of those count entries with the same row and column indices as separate entries.

Definition at line 535 of file Teuchos_MatrixMarket_Raw_Adder.hpp.

template<class Scalar , class Ordinal >

const std::vector<element_type>& Teuchos::MatrixMarket::Raw::Adder< Scalar, Ordinal >::getEntries ( ) const

inline

A temporary const view of the entries of the matrix.

Definition at line 601 of file Teuchos_MatrixMarket_Raw_Adder.hpp.

template<class Scalar , class Ordinal >

void Teuchos::MatrixMarket::Raw::Adder< Scalar, Ordinal >::clear ( )

inline

Clear all the added matrix entries and reset metadata.

Definition at line 606 of file Teuchos_MatrixMarket_Raw_Adder.hpp.

template<class Scalar , class Ordinal >

const Ordinal Teuchos::MatrixMarket::Raw::Adder< Scalar, Ordinal >::numRows ( ) const

inline

Computed number of rows.

"Computed" means "as seen from the matrix data."

Definition at line 616 of file Teuchos_MatrixMarket_Raw_Adder.hpp.

template<class Scalar , class Ordinal >

const Ordinal Teuchos::MatrixMarket::Raw::Adder< Scalar, Ordinal >::numCols ( ) const

inline

Computed number of columns.

"Computed" means "as seen from the matrix data."

Definition at line 621 of file Teuchos_MatrixMarket_Raw_Adder.hpp.

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

Teuchos_MatrixMarket_Raw_Adder.hpp

Public Member Functions

Detailed Description

template<class Scalar, class Ordinal> class Teuchos::MatrixMarket::Raw::Adder< Scalar, Ordinal >

Constructor & Destructor Documentation

Member Function Documentation

template<class Scalar, class Ordinal>
class Teuchos::MatrixMarket::Raw::Adder< Scalar, Ordinal >