TrilinosWrappers::SparsityPattern Class Reference
[TrilinosWrappersSparsity patterns]

Inheritance diagram for TrilinosWrappers::SparsityPattern:
Inheritance graph
[legend]

List of all members.

Classes

class  ExcAccessToNonLocalElement
class  ExcAccessToNonPresentElement
class  ExcInvalidIndex
class  ExcSourceEqualsDestination
class  ExcTrilinosError

Public Types

typedef
SparsityPatternIterators::const_iterator 
const_iterator

Public Member Functions

Constructors and initalization.



 SparsityPattern ()
 SparsityPattern (const Epetra_Map &InputMap, const unsigned int n_entries_per_row=0)
 SparsityPattern (const Epetra_Map &InputMap, const std::vector< unsigned int > &n_entries_per_row)
 SparsityPattern (const Epetra_Map &InputRowMap, const Epetra_Map &InputColMap, const unsigned int n_entries_per_row=0)
 SparsityPattern (const Epetra_Map &InputRowMap, const Epetra_Map &InputColMap, const std::vector< unsigned int > &n_entries_per_row)
 SparsityPattern (const unsigned int m, const unsigned int n, const unsigned int n_entries_per_row=0)
 SparsityPattern (const unsigned int m, const unsigned int n, const std::vector< unsigned int > &n_entries_per_row)
 SparsityPattern (const SparsityPattern &SP)
virtual ~SparsityPattern ()
void reinit (const Epetra_Map &InputMap, const unsigned int n_entries_per_row=0)
void reinit (const Epetra_Map &InputMap, const std::vector< unsigned int > &n_entries_per_row)
void reinit (const Epetra_Map &InputRowMap, const Epetra_Map &InputColMap, const unsigned int n_entries_per_row=0)
void reinit (const Epetra_Map &InputRowMap, const Epetra_Map &InputColMap, const std::vector< unsigned int > &n_entries_per_row)
void reinit (const unsigned int m, const unsigned int n, const unsigned int n_entries_per_row=0)
void reinit (const unsigned int m, const unsigned int n, const std::vector< unsigned int > &n_entries_per_row)
template<typename SparsityType >
void reinit (const Epetra_Map &InputRowMap, const Epetra_Map &InputColMap, const SparsityType &SP)
template<typename SparsityType >
void reinit (const Epetra_Map &InputMap, const SparsityType &SP)
void copy_from (const SparsityPattern &SP)
template<typename SparsityType >
void copy_from (const SparsityType &SP)
void clear ()
void compress ()
Information on the sparsity pattern



bool is_compressed () const
unsigned int max_entries_per_row () const
unsigned int n_rows () const
unsigned int n_cols () const
unsigned int local_size () const
std::pair< unsigned int,
unsigned int
local_range () const
bool in_local_range (const unsigned int index) const
unsigned int n_nonzero_elements () const
unsigned int row_length (const unsigned int row) const
unsigned int bandwidth () const
bool empty () const
bool exists (const unsigned int i, const unsigned int j) const
unsigned int memory_consumption () const
Adding entries



void add (const unsigned int i, const unsigned int j)
template<typename ForwardIterator >
void add_entries (const unsigned int row, ForwardIterator begin, ForwardIterator end, const bool indices_are_sorted=false)
Access of underlying Trilinos data



const Epetra_CrsGraph & trilinos_sparsity_pattern () const
const Epetra_Map & domain_partitioner () const
const Epetra_Map & range_partitioner () const
const Epetra_Map & row_partitioner () const
const Epetra_Map & col_partitioner () const
Iterators



const_iterator begin () const
const_iterator end () const
const_iterator begin (const unsigned int r) const
const_iterator end (const unsigned int r) const
Input/Output



void write_ascii ()
void print (std::ostream &out) const
void print_gnuplot (std::ostream &out) const

Private Attributes

Epetra_Map row_map
Epetra_Map col_map
bool compressed
std::auto_ptr< Epetra_FECrsGraph > graph

Friends

class SparsityPatternIterators::const_iterator
class SparsityPatternIterators::const_iterator::Accessor

Detailed Description

This class implements a wrapper class to use the Trilinos distributed sparsity pattern class Epetra_FECrsGraph. This class is designed to be used for construction of parallel Trilinos matrices. The functionality of this class is modeled after the existing sparsity pattern classes, with the difference that this class can work fully in parallel according to a partitioning of the sparsity pattern rows.

This class has many similarities to the compressed sparsity pattern classes of deal.II (i.e., the classes CompressedSparsityPattern, CompressedSetSparsityPattern, and CompressedSimpleSparsityPattern), since it can dynamically add elements to the pattern without any memory being previously reserved for it. However, it also has a method SparsityPattern::compress(), that finalizes the pattern and enables its use with Trilinos sparse matrices.

Author:
Martin Kronbichler, 2008

Member Typedef Documentation

Declare a typedef for the iterator class.


Constructor & Destructor Documentation

TrilinosWrappers::SparsityPattern::SparsityPattern (  ) 

Default constructor. Generates an empty (zero-size) sparsity pattern.

TrilinosWrappers::SparsityPattern::SparsityPattern ( const Epetra_Map &  InputMap,
const unsigned int  n_entries_per_row = 0 
)

Constructor for a square sparsity pattern using an Epetra_Map and the number of nonzero entries in the rows of the sparsity pattern. Note that this number does not need to be exact, and it is even allowed that the actual sparsity structure has more nonzero entries than specified in the constructor. However it is still advantageous to provide good estimates here since this will considerably increase the performance when creating the sparsity pattern.

TrilinosWrappers::SparsityPattern::SparsityPattern ( const Epetra_Map &  InputMap,
const std::vector< unsigned int > &  n_entries_per_row 
)

Same as before, but now use the exact number of nonzeros in each m row. Since we know the number of elements in the sparsity pattern exactly in this case, we can already allocate the right amount of memory, which makes the creation process by the respective SparsityPattern::reinit call considerably faster. However, this is a rather unusual situation, since knowing the number of entries in each row is usually connected to knowing the indices of nonzero entries, which the sparsity pattern is designed to describe.

TrilinosWrappers::SparsityPattern::SparsityPattern ( const Epetra_Map &  InputRowMap,
const Epetra_Map &  InputColMap,
const unsigned int  n_entries_per_row = 0 
)

This constructor is similar to the one above, but it now takes two different Epetra maps for rows and columns. This interface is meant to be used for generating rectangular sparsity pattern, where one map describes the parallel partitioning of the dofs associated with the sparsity pattern rows and the other one of the sparsity pattern columns. Note that there is no real parallelism along the columns – the processor that owns a certain row always owns all the column elements, no matter how far they might be spread out. The second Epetra_Map is only used to specify the number of columns and for internal arragements when doing matrix-vector products with vectors based on that column map.

The number of columns entries per row is specified as the maximum number of entries argument.

TrilinosWrappers::SparsityPattern::SparsityPattern ( const Epetra_Map &  InputRowMap,
const Epetra_Map &  InputColMap,
const std::vector< unsigned int > &  n_entries_per_row 
)

This constructor is similar to the one above, but it now takes two different Epetra maps for rows and columns. This interface is meant to be used for generating rectangular matrices, where one map specifies the parallel distribution of rows and the second one specifies the distribution of degrees of freedom associated with matrix columns. This second map is however not used for the distribution of the columns themselves – rather, all column elements of a row are stored on the same processor. The vector n_entries_per_row specifies the number of entries in each row of the newly generated matrix.

TrilinosWrappers::SparsityPattern::SparsityPattern ( const unsigned int  m,
const unsigned int  n,
const unsigned int  n_entries_per_row = 0 
)

Generate a sparsity pattern that is completely stored locally, having $m$ rows and $n$ columns. The resulting matrix will be completely stored locally.

The number of columns entries per row is specified as the maximum number of entries argument. As above, this does not need to be an accurate number since the entries are allocated dynamically in a similar manner as for the deal.II CompressedSparsityPattern classes, but a good estimate will reduce the setup time of the sparsity pattern.

TrilinosWrappers::SparsityPattern::SparsityPattern ( const unsigned int  m,
const unsigned int  n,
const std::vector< unsigned int > &  n_entries_per_row 
)

Generate a sparsity pattern that is completely stored locally, having $m$ rows and $n$ columns. The resulting matrix will be completely stored locally.

The vector n_entries_per_row specifies the number of entries in each row.

TrilinosWrappers::SparsityPattern::SparsityPattern ( const SparsityPattern SP  ) 

Copy constructor. Sets the calling sparsity pattern to be the same as the input sparsity pattern.

virtual TrilinosWrappers::SparsityPattern::~SparsityPattern (  )  [virtual]

Destructor. Made virtual so that one can use pointers to this class.


Member Function Documentation

void TrilinosWrappers::SparsityPattern::reinit ( const Epetra_Map &  InputMap,
const unsigned int  n_entries_per_row = 0 
)

Reinitialization function for generating a square sparsity pattern using an Epetra_Map and the number of nonzero entries in the rows of the sparsity pattern. Note that this number does not need to be exact, and it is even allowed that the actual sparsity structure has more nonzero entries than specified in the constructor. However it is still advantageous to provide good estimates here since this will considerably increase the performance when creating the sparsity pattern.

This function does not create any entries by itself, but provides the correct data structures that can be used by the respective add() function.

void TrilinosWrappers::SparsityPattern::reinit ( const Epetra_Map &  InputMap,
const std::vector< unsigned int > &  n_entries_per_row 
)

Same as before, but now use the exact number of nonzeros in each m row. Since we know the number of elements in the sparsity pattern exactly in this case, we can already allocate the right amount of memory, which makes process of adding entries to the sparsity pattern considerably faster. However, this is a rather unusual situation, since knowing the number of entries in each row is usually connected to knowing the indices of nonzero entries, which the sparsity pattern is designed to describe.

void TrilinosWrappers::SparsityPattern::reinit ( const Epetra_Map &  InputRowMap,
const Epetra_Map &  InputColMap,
const unsigned int  n_entries_per_row = 0 
)

This reinit function is similar to the one above, but it now takes two different Epetra maps for rows and columns. This interface is meant to be used for generating rectangular sparsity pattern, where one map describes the parallel partitioning of the dofs associated with the sparsity pattern rows and the other one of the sparsity pattern columns. Note that there is no real parallelism along the columns – the processor that owns a certain row always owns all the column elements, no matter how far they might be spread out. The second Epetra_Map is only used to specify the number of columns and for internal arragements when doing matrix-vector products with vectors based on that column map.

The number of columns entries per row is specified by the argument n_entries_per_row.

void TrilinosWrappers::SparsityPattern::reinit ( const Epetra_Map &  InputRowMap,
const Epetra_Map &  InputColMap,
const std::vector< unsigned int > &  n_entries_per_row 
)

This reinit function is similar to the one above, but it now takes two different Epetra maps for rows and columns. This interface is meant to be used for generating rectangular matrices, where one map specifies the parallel distribution of rows and the second one specifies the distribution of degrees of freedom associated with matrix columns. This second map is however not used for the distribution of the columns themselves – rather, all column elements of a row are stored on the same processor. The vector n_entries_per_row specifies the number of entries in each row of the newly generated matrix.

void TrilinosWrappers::SparsityPattern::reinit ( const unsigned int  m,
const unsigned int  n,
const unsigned int  n_entries_per_row = 0 
)

Initialize a sparsity pattern that is completely stored locally, having $m$ rows and $n$ columns. The resulting matrix will be completely stored locally.

The number of columns entries per row is specified as the maximum number of entries argument. As above, this does not need to be an accurate number since the entries are allocated dynamically in a similar manner as for the deal.II CompressedSparsityPattern classes, but a good estimate will reduce the setup time of the sparsity pattern.

void TrilinosWrappers::SparsityPattern::reinit ( const unsigned int  m,
const unsigned int  n,
const std::vector< unsigned int > &  n_entries_per_row 
)

Initialize a sparsity pattern that is completely stored locally, having $m$ rows and $n$ columns. The resulting matrix will be completely stored locally.

The vector n_entries_per_row specifies the number of entries in each row.

template<typename SparsityType >
void TrilinosWrappers::SparsityPattern::reinit ( const Epetra_Map &  InputRowMap,
const Epetra_Map &  InputColMap,
const SparsityType &  SP 
) [inline]

Reinit function. Takes one of the deal.II sparsity patterns and a parallel partitioning of the rows and columns for initializing the current Trilinos sparsity pattern.

template<typename SparsityType >
void TrilinosWrappers::SparsityPattern::reinit ( const Epetra_Map &  InputMap,
const SparsityType &  SP 
) [inline]

Reinit function. Takes one of the deal.II sparsity patterns and a parallel partitioning of the rows and columns for initializing the current Trilinos sparsity pattern.

void TrilinosWrappers::SparsityPattern::copy_from ( const SparsityPattern SP  ) 

Copy function. Sets the calling sparsity pattern to be the same as the input sparsity pattern.

template<typename SparsityType >
void TrilinosWrappers::SparsityPattern::copy_from ( const SparsityType &  SP  )  [inline]

Copy function from one of the deal.II sparsity patterns. If used in parallel, this function uses an ad-hoc partitioning of the rows and columns.

void TrilinosWrappers::SparsityPattern::clear (  ) 

Release all memory and return to a state just like after having called the default constructor.

This is a collective operation that needs to be called on all processors in order to avoid a dead lock.

void TrilinosWrappers::SparsityPattern::compress (  ) 

In analogy to our own SparsityPattern class, this function compresses the sparsity pattern and allows the resulting pattern to be used for actually generating a matrix. This function also exchanges non-local data that might have accumulated during the addition of new elements. This function must therefore be called once the structure is fixed. This is a collective operation, i.e., it needs to be run on all processors when used in parallel.

bool TrilinosWrappers::SparsityPattern::is_compressed (  )  const

Returns the state of the sparsity pattern, i.e., whether compress() needs to be called after an operation requiring data exchange.

unsigned int TrilinosWrappers::SparsityPattern::max_entries_per_row (  )  const

Gives the maximum number of entries per row on the current processor.

unsigned int TrilinosWrappers::SparsityPattern::n_rows (  )  const

Return the number of rows in this sparsity pattern.

unsigned int TrilinosWrappers::SparsityPattern::n_cols (  )  const

Return the number of columns in this sparsity pattern.

unsigned int TrilinosWrappers::SparsityPattern::local_size (  )  const

Return the local dimension of the sparsity pattern, i.e. the number of rows stored on the present MPI process. In the sequential case, this number is the same as n_rows(), but for parallel matrices it may be smaller.

To figure out which elements exactly are stored locally, use local_range().

std::pair<unsigned int, unsigned int> TrilinosWrappers::SparsityPattern::local_range (  )  const

Return a pair of indices indicating which rows of this sparsity pattern are stored locally. The first number is the index of the first row stored, the second the index of the one past the last one that is stored locally. If this is a sequential matrix, then the result will be the pair (0,n_rows()), otherwise it will be a pair (i,i+n), where n=local_size().

bool TrilinosWrappers::SparsityPattern::in_local_range ( const unsigned int  index  )  const

Return whether index is in the local range or not, see also local_range().

unsigned int TrilinosWrappers::SparsityPattern::n_nonzero_elements (  )  const

Return the number of nonzero elements of this sparsity pattern.

unsigned int TrilinosWrappers::SparsityPattern::row_length ( const unsigned int  row  )  const

Number of entries in a specific row.

unsigned int TrilinosWrappers::SparsityPattern::bandwidth (  )  const

Compute the bandwidth of the matrix represented by this structure. The bandwidth is the maximum of $|i-j|$ for which the index pair $(i,j)$ represents a nonzero entry of the matrix. Consequently, the maximum bandwidth a $n\times m$ matrix can have is $\max\{n-1,m-1\}$.

bool TrilinosWrappers::SparsityPattern::empty (  )  const

Return whether the object is empty. It is empty if no memory is allocated, which is the same as when both dimensions are zero.

bool TrilinosWrappers::SparsityPattern::exists ( const unsigned int  i,
const unsigned int  j 
) const

Return whether the index (i,j) exists in the sparsity pattern (i.e., it may be non-zero) or not.

unsigned int TrilinosWrappers::SparsityPattern::memory_consumption (  )  const

Determine an estimate for the memory consumption (in bytes) of this object. Currently not implemented for this class.

void TrilinosWrappers::SparsityPattern::add ( const unsigned int  i,
const unsigned int  j 
)

Add the element (i,j) to the sparsity pattern.

template<typename ForwardIterator >
void TrilinosWrappers::SparsityPattern::add_entries ( const unsigned int  row,
ForwardIterator  begin,
ForwardIterator  end,
const bool  indices_are_sorted = false 
) [inline]

Add several elements in one row to the sparsity pattern.

const Epetra_CrsGraph& TrilinosWrappers::SparsityPattern::trilinos_sparsity_pattern (  )  const

Return a const reference to the underlying Trilinos Epetra_CrsGraph data that stores the sparsity pattern.

const Epetra_Map& TrilinosWrappers::SparsityPattern::domain_partitioner (  )  const

Return a const reference to the underlying Trilinos Epetra_Map that sets the parallel partitioning of the domain space of this sparsity pattern, i.e., the partitioning of the vectors matrices based on this sparsity pattern are multiplied with.

const Epetra_Map& TrilinosWrappers::SparsityPattern::range_partitioner (  )  const

Return a const reference to the underlying Trilinos Epetra_Map that sets the partitioning of the range space of this sparsity pattern, i.e., the partitioning of the vectors that are result from matrix-vector products.

const Epetra_Map& TrilinosWrappers::SparsityPattern::row_partitioner (  )  const

Return a const reference to the underlying Trilinos Epetra_Map that sets the partitioning of the sparsity pattern rows. Equal to the partitioning of the range.

const Epetra_Map& TrilinosWrappers::SparsityPattern::col_partitioner (  )  const

Return a const reference to the underlying Trilinos Epetra_Map that sets the partitioning of the sparsity pattern columns. This is in general not equal to the partitioner Epetra_Map for the domain because of overlap in the matrix.

const_iterator TrilinosWrappers::SparsityPattern::begin (  )  const

STL-like iterator with the first entry.

const_iterator TrilinosWrappers::SparsityPattern::end (  )  const

Final iterator.

const_iterator TrilinosWrappers::SparsityPattern::begin ( const unsigned int  r  )  const

STL-like iterator with the first entry of row r.

Note that if the given row is empty, i.e. does not contain any nonzero entries, then the iterator returned by this function equals end(r). Note also that the iterator may not be dereferencable in that case.

const_iterator TrilinosWrappers::SparsityPattern::end ( const unsigned int  r  )  const

Final iterator of row r. It points to the first element past the end of line r, or past the end of the entire sparsity pattern.

Note that the end iterator is not necessarily dereferencable. This is in particular the case if it is the end iterator for the last row of a matrix.

void TrilinosWrappers::SparsityPattern::write_ascii (  ) 

Abstract Trilinos object that helps view in ASCII other Trilinos objects. Currently this function is not implemented. TODO: Not implemented.

void TrilinosWrappers::SparsityPattern::print ( std::ostream &  out  )  const

Print the sparsity pattern to the given stream, using the format (line,col).

void TrilinosWrappers::SparsityPattern::print_gnuplot ( std::ostream &  out  )  const

Print the sparsity of the matrix in a format that gnuplot understands and which can be used to plot the sparsity pattern in a graphical way. The format consists of pairs i j of nonzero elements, each representing one entry of this matrix, one per line of the output file. Indices are counted from zero on, as usual. Since sparsity patterns are printed in the same way as matrices are displayed, we print the negative of the column index, which means that the (0,0) element is in the top left rather than in the bottom left corner.

Print the sparsity pattern in gnuplot by setting the data style to dots or points and use the plot command.


Friends And Related Function Documentation


Member Data Documentation

Epetra Trilinos mapping of the matrix rows that assigns parts of the matrix to the individual processes. This map is provided either via the constructor or in a reinit function.

Pointer to the user-supplied Epetra Trilinos mapping of the matrix columns that assigns parts of the matrix to the individual processes.

A boolean variable to hold information on whether the vector is compressed or not.

std::auto_ptr<Epetra_FECrsGraph> TrilinosWrappers::SparsityPattern::graph [private]

A sparsity pattern object in Trilinos to be used for finite element based problems which allows for adding non-local elements to the pattern.


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

deal.II documentation generated on Mon Nov 23 22:58:40 2009 by doxygen 1.6.1