EpetraExt::Permutation< T > Class Template Reference

`#include <EpetraExt_Permutation.h>`

Inheritance diagram for EpetraExt::Permutation< T >:

[legend]
Collaboration diagram for EpetraExt::Permutation< T >:
[legend]
List of all members.

Public Types

typedef EpetraExt::SameTypeTransform<
T >::TransformTypeRef
OutputRef
typedef EpetraExt::SameTypeTransform<
T >::TransformTypeRef
InputRef
typedef EpetraExt::SameTypeTransform<
T >::TransformTypePtr
OutputPtr
typedef EpetraExt::SameTypeTransform<
T >::TransformTypePtr
InputPtr

Public Member Functions

Permutation (Epetra_DataAccess CV, const Epetra_BlockMap &map, int *permutation)
Permutation (const Epetra_BlockMap &map)
Permutation (const Permutation< T > &src)
virtual ~Permutation ()
OutputRef operator() (InputRef orig)
OutputRef operator() (InputRef orig, bool column_permutation)

Detailed Description

template<typename T> class EpetraExt::Permutation< T >

Permutation stores and describes a permutation matrix P. As described in "Matrix Computations" (Golub and Van Loan), a permutation matrix is the identity matrix with its rows re-ordered. The permutation is internally stored as an integer vector p, where p[i] is the column-index of the "1" in P's i-th row. Consider the example of permuting a matrix A by applying the permutation matrix P to form the result B. i.e., B = PA. If p[i] = j, then row j of A becomes row i of B.

This Permutation class is templated on the type of the object to be permuted. However, not all objects are eligible to be template parameters. Currently the following objects may be used: Epetra_CrsMatrix, Epetra_CrsGraph and Epetra_MultiVector.

A test program which exercises this Permutation class is located in the directory packages/epetraext/test/Permutation.

```    Implementation Notes:
Permutation currently inherits StructuralSameTypeTransform, which in turn
inherits Transform through SameTypeTransform. Permutation, and its base classes,
are templates. A couple of noteworthy consequences result from this:```

```       1. A separate instantiation of Permutation must be created for each type
of object to be permuted. Example:
Epetra_CrsGraph& graph = ...
Epetra_CrsMatrix& A = ...
Permutation<Epetra_CrsGraph> graph_perm(...);
Permutation<Epetra_CrsMatrix> matrix_perm(...);```

```         Epetra_CrsMatrix& PA = matrix_perm(A);
Epetra_CrsGraph& Pgraph = graph_perm(graph);```

```       2. Following the semantics of Transform, when the Permutation class is used
to create a new permuted copy of an object, ownership of the new copy is
retained by Permutation. Permutation will destroy the new object. This means
that only one object should be permuted by a Permutation instance.```

```    It is not clear that these are desirable behaviors for permutations. It is
possible that Permutation will be altered to remove these limitations, as
follows:```

```       1. If Permutation doesn't inherit Transform, then Permutation need not be
operator() method member. This would allow a single instantiation of
Permutation to be used for permuting all of the eligible target types.```

```       2. Allowing the caller (user) to take ownership of the newly-produced
permuted objects would allow a single Permutation instance to be used
repeatedly since it would no longer need to hold a pointer to the new object
for later deletion.```

```       Then, example usage could look like this:
Epetra_CrsMatrix& A = ...
Epetra_MultiVector& v = ...
Permutation P(...);```

```	 Epetra_CrsMatrix PA = P(A);
Epetra_MultiVector Pv = P(v);
```

Constructor & Destructor Documentation

 template EpetraExt::Permutation< T >::Permutation ( Epetra_DataAccess CV, const Epetra_BlockMap & map, int * permutation )

Constructor

Parameters:
 CV Set to either Copy or View. map Defines the index space to be permuted. permutation Array defining the permutation. The length of this array must be 'map.NumMyElements()'. This array is the local portion of the 'p' vector described in the 'Detailed Description' section.

 template EpetraExt::Permutation< T >::Permutation ( const Epetra_BlockMap & map )

Constructor. This constructor creates an empty permutation object. The contents must then be set using regular Epetra_IntVector methods.

Parameters:
 map Defines the index space to be permuted.

 template EpetraExt::Permutation< T >::Permutation ( const Permutation< T > & src )
 Copy Constructor

 template EpetraExt::Permutation< T >::~Permutation ( ) ` [virtual]`
 Destructor

Member Function Documentation

 template Permutation< T >::OutputRef EpetraExt::Permutation< T >::operator() ( InputRef orig, bool column_permutation )

This method creates a new object which is a permuted copy of the input argument.

The same notes apply to this method (regarding collective communications etc.) as to the row-permutation operator method above.

Parameters:
 orig Input Object to be permuted. column_permutation Optional Input, defaults to false if not provided. A value of false means that a row-permutation will be performed (result = P*orig), a value of true means that a column-permutation will be performed (result = orig*P).

 template Permutation< T >::OutputRef EpetraExt::Permutation< T >::operator() ( InputRef orig )

This method creates a new object which is a permuted copy of the input argument.

Notes:

• This is a collective function, so in a parallel setting it must be called by all processors before any will complete it. (This is because map objects are being created, and import/export operations are being performed.)
• The new object that is created, if it is a graph or matrix, has already had FillComplete() called before it is returned to the user.
• The new object will be destroyed by this permutation object, so the caller should not delete it.

Parameters:
 orig Input Object to be permuted.

The documentation for this class was generated from the following files:
• EpetraExt_Permutation.h
• EpetraExt_Permutation.cpp

Generated on Thu Sep 18 12:43:01 2008 for EpetraExt by  1.3.9.1