Teuchos - Trilinos Tools Package Version of the Day
Public Member Functions
Teuchos::MatrixMarket::Raw::Adder< Scalar, Ordinal > Class Template Reference

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

#include <Teuchos_MatrixMarket_Raw_Adder.hpp>

List of all members.

Public Member Functions

 Adder ()
 Default constructor.
 Adder (const Ordinal expectedNumRows, const Ordinal expectedNumCols, const Ordinal expectedNumEntries, const bool tolerant=false, const bool debug=false)
 Standard constructor.
void operator() (const Ordinal i, const Ordinal j, const Scalar &Aij, const bool countAgainstTotal=true)
 Add an entry to the sparse matrix.
void print (std::ostream &out, const bool doMerge, const bool replace=false)
 Print the sparse matrix data.
std::pair< size_type, size_type > merge (const bool replace=false)
 Merge duplicate elements.
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.
const std::vector< element_type > & getEntries () const
 A temporary const view of the entries of the matrix.
void clear ()
 Clear all the added matrix entries and reset metadata.
const Ordinal numRows () const
 Computed number of rows.
const Ordinal numCols () const
 Computed number of columns.

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:
ScalarThe type of entries in the sparse matrix.
OrdinalThe 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 282 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 299 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 327 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 363 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 408 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 443 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 534 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 600 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 605 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 615 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 620 of file Teuchos_MatrixMarket_Raw_Adder.hpp.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines