Permutation stores and describes a permutation matrix P. More...

#include <EpetraExt_Permutation.h>

Inheritance diagram for EpetraExt::TPermutation< T, int_type >:

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 Types inherited from EpetraExt::SameTypeTransform< T >
typedef T	TransformType

typedef T *	TransformTypePtr

typedef T &	TransformTypeRef

Public Types inherited from EpetraExt::Transform< T, T >
typedef T	OriginalType

typedef T *	OriginalTypePtr

typedef Teuchos::RCP< T >	OriginalTypeRCP

typedef T &	OriginalTypeRef

typedef T	NewType

typedef T *	NewTypePtr

typedef Teuchos::RCP< T >	NewTypeRCP

typedef T &	NewTypeRef

Public Member Functions
	TPermutation (Epetra_DataAccess CV, const Epetra_BlockMap &map, int_type *permutation)
	Constructor. More...

	TPermutation (const Epetra_BlockMap &map)
	Constructor. More...

	TPermutation (const TPermutation< T, int_type > &src)
	Copy Constructor. More...

virtual	~TPermutation ()
	Destructor. More...

OutputRef	operator() (InputRef orig)
	This method creates a new object which is a permuted copy of the input argument. More...

OutputRef	operator() (InputRef orig, bool column_permutation)
	This method creates a new object which is a permuted copy of the input argument. More...

Public Member Functions inherited from EpetraExt::StructuralSameTypeTransform< T >
bool	fwd ()
	Forward transfer of data from `orig` object input in the `operator()` method call to the new object created in this same call. More...

bool	rvs ()
	Reverse transfer of data from new object created in the `operator()` method call to the `orig` object input to this same method. More...

virtual	~StructuralSameTypeTransform ()

Public Member Functions inherited from EpetraExt::SameTypeTransform< T >
virtual	~SameTypeTransform ()

Public Member Functions inherited from EpetraExt::Transform< T, T >
virtual	~Transform ()

virtual bool	analyze (OriginalTypeRef orig)
	Initial analysis phase of transform. More...

virtual NewTypeRef	construct ()
	Construction of new object as a result of the transform. More...

virtual bool	isConstructed ()
	Check for whether transformed object has been constructed. More...

Additional Inherited Members
Protected Member Functions inherited from EpetraExt::Transform< T, T >
	Transform ()
	Default constructor, protected to allow only derived classes to use. More...

Protected Attributes inherited from EpetraExt::Transform< T, T >
OriginalTypePtr	origObj_

NewTypePtr	newObj_

Detailed Description

template<typename T, typename int_type>
class EpetraExt::TPermutation< T, int_type >

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
       a template and instead we could either overload or template-ize the
       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);

Questions and comments about this class may be directed to Alan Williams.

Definition at line 117 of file EpetraExt_Permutation.h.

Member Typedef Documentation

template<typename T, typename int_type>

typedef EpetraExt::SameTypeTransform<T>::TransformTypeRef EpetraExt::TPermutation< T, int_type >::OutputRef

Definition at line 148 of file EpetraExt_Permutation.h.

template<typename T, typename int_type>

typedef EpetraExt::SameTypeTransform<T>::TransformTypeRef EpetraExt::TPermutation< T, int_type >::InputRef

Definition at line 149 of file EpetraExt_Permutation.h.

template<typename T, typename int_type>

typedef EpetraExt::SameTypeTransform<T>::TransformTypePtr EpetraExt::TPermutation< T, int_type >::OutputPtr

Definition at line 150 of file EpetraExt_Permutation.h.

template<typename T, typename int_type>

typedef EpetraExt::SameTypeTransform<T>::TransformTypePtr EpetraExt::TPermutation< T, int_type >::InputPtr

Definition at line 151 of file EpetraExt_Permutation.h.

Constructor & Destructor Documentation

template<typename T , typename int_type>

EpetraExt::TPermutation< T, int_type >::TPermutation	(	Epetra_DataAccess	CV,
		const Epetra_BlockMap &	map,
		int_type *	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.

Definition at line 431 of file EpetraExt_Permutation_impl.h.

template<typename T , typename int_type>

EpetraExt::TPermutation< T, int_type >::TPermutation ( 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.

Definition at line 445 of file EpetraExt_Permutation_impl.h.

template<typename T, typename int_type>

EpetraExt::TPermutation< T, int_type >::TPermutation ( const TPermutation< T, int_type > & src )

Copy Constructor.

Definition at line 457 of file EpetraExt_Permutation_impl.h.

template<typename T , typename int_type >

EpetraExt::TPermutation< T, int_type >::~TPermutation ( )

virtual

Destructor.

Definition at line 469 of file EpetraExt_Permutation_impl.h.

Member Function Documentation

template<typename T, typename int_type>

OutputRef EpetraExt::TPermutation< T, int_type >::operator() ( InputRef orig )

virtual

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.

Implements EpetraExt::Transform< T, T >.

template<typename T, typename int_type>

OutputRef EpetraExt::TPermutation< T, int_type >::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 = Porig), a value of true means that a column-permutation will be performed (result = origP).

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

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

template<typename T, typename int_type> class EpetraExt::TPermutation< T, int_type >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

template<typename T, typename int_type>
class EpetraExt::TPermutation< T, int_type >