Vector Base Support Subclasses for SPMD Thyra Implementations]

Base subclass for simplistic SPMD linear operators. More...

#include <Thyra_SpmdLinearOpBaseDecl.hpp>

Inheritance diagram for Thyra::SpmdLinearOpBase< Scalar >:


Overridden from EuclideanLinearOpBase
Teuchos::RefCountPtr< const ScalarProdVectorSpaceBase< Scalar > >	rangeScalarProdVecSpc () const

Teuchos::RefCountPtr< const ScalarProdVectorSpaceBase< Scalar > >	domainScalarProdVecSpc () const

void	euclideanApply (const ETransp M_trans, const MultiVectorBase< Scalar > &X, MultiVectorBase< Scalar > *Y, const Scalar alpha, const Scalar beta) const
	Calls protected `euclideanApply()` function.
Protected constructors/initializers/accessors
	SpmdLinearOpBase ()
virtual void	setSpaces (const Teuchos::RefCountPtr< const SpmdVectorSpaceBase< Scalar > > &range, const Teuchos::RefCountPtr< const SpmdVectorSpaceBase< Scalar > > &domain)
	Initialize vector spaces using pre-formed `SpmdVectorSpaceBase` objects.
virtual void	setLocalDimensions (const Teuchos::RefCountPtr< const Teuchos::Comm< Index > > &comm, const Index localDimRange, const Index localDimDomain)
	Initialize vector spaces given local dimensions (uses `DefaultSpmdVectorSpace`).
void	forceUnitStride (const bool &forceUnitStride)
	Set if unit stride is forced for vector data views or not.
Protected virtual functions to be overridden by subclasses
virtual void	euclideanApply (const ETransp M_trans, const RTOpPack::ConstSubVectorView< Scalar > &local_x, const RTOpPack::SubVectorView< Scalar > *local_y, const Scalar alpha, const Scalar beta) const =0
	Apply the operator to explicit vector data.
virtual void	euclideanApply (const ETransp M_trans, const RTOpPack::ConstSubMultiVectorView< Scalar > &local_X, const RTOpPack::SubMultiVectorView< Scalar > *local_Y, const Scalar alpha, const Scalar beta) const
	Apply the operator to explicit multi-vector data.

Detailed Description

template<class Scalar>
class Thyra::SpmdLinearOpBase< Scalar >

Base subclass for simplistic SPMD linear operators.

This subclass defines machinery for developing concrete LinearOpBase subclasses for SPMD environments where it is assumed that all of the local elements in associated vectors and multi-vectors are immediately and cheaply available in each process.

This base subclass derives from EuclideanLinearOpBase and therefore any application-specific scalar products can easily be incorporated.

Notes to subclass developers:

The only function that a subclass must override in order to provide a concrete implementation is the explicit single-vector version euclideanApply().

This function is called on the subclass implementation passing in views of explicit data. The raw pointers to the local input and input/output arrays are passed in simple templated classes RTOpPack::ConstSubVectorView and RTOpPack::SubVectorView. Getting raw pointers out of these objects is easy.

It is easy to create concrete subclasses of SpmdLinearOpBase (see SpmdTridiagLinearOp for a concrete example). All one has to do is to create a derived base class (MySpmdLinearOp for example) of the form:

template<class Scalar>
class MySpmdLinearOp : public SpmdLinearOpBase<Scalar> {
private:
  // Declare your classes private data
  ...
public:
  // Declare you classes constructors, destructor and other initialization functions
  ...
protected:
  // Override the version of euclideanApply() that takes explicit data
  void euclideanApply(
    const ETransp                                M_trans
    ,const RTOpPack::ConstSubVectorView<Scalar>  &local_x_in
    ,const RTOpPack::SubVectorView<Scalar>       *local_y_out
    ,const Scalar                                alpha
    ,const Scalar                                beta
    ) const
    {
      // Get raw pointers to local vector data to make me feel better!
      const Scalar *local_x     = local_x_in.values();
      const Index  local_x_dim  = local_x_in.subDim();
      Scalar       *local_y     = local_y_out->values();
      const Index  local_y_dim  = local_y_out->subDim();
      // Perform operation the operation
      if( real_trans(M_trans) == ::Thyra::NOTRANS ) {
        // Perform the non-transposed operator: y = alpha*M*x + beta*y
        ...
      }
      else {
        // Perform the transposed operation: y = alpha*M'*x + beta*y
        ...
      }
  };

Of course the above function will have to perform some type of process-to-process communication in order to apply any non-trivial distributed-memory linear operator but that is always the case.

If you do not need to handle arbitrary scalar data types then you do not have to support them. For example, to define a subclass that only supports double you would declare a non-templated version of the form:

class MySpmdLinearOp : public SpmdLinearOpBase<double> {
private:
  // Declare your classes private data
  ...
public:
  // Declare you classes constructors, destructor and other initialization functions
  ...
protected:
  // Override the version of euclideanApply() that takes explicit data
  void euclideanApply(
    const ETransp                                M_trans
    ,const RTOpPack::ConstSubVectorView<double>  &local_x_in
    ,const RTOpPack::SubVectorView<double>       *local_y_out
    ,const double                                alpha
    ,const double                                beta
    ) const
    {
      // Get raw pointers to vector data to make me feel better!
      const double *local_x     = local_x_in.values();
      const Index  local_x_dim  = local_x_in.subDim();
      double       *local_y     = local_y_out->values();
      const Index  local_y_dim  = local_y_out->subDim();
      // Perform operation the operation
      if( real_trans(M_trans) == ::Thyra::NOTRANS ) {
        // Perform the non-transposed operator: y = alpha*M*x + beta*y
        ...
      }
      else {
        // Perform the transposed operation: y = alpha*M'*x + beta*y
        ...
      }
  };

By default, pointers to explicit data returned from local_x.values() and local_y->values() above are forced to have unit stride to simplify things. However, if your subclass can efficiently handle non-unit stride vector data (as the BLAS can for example) then you can allow this by calling the function this->forceUnitStride() and passing in false. The function this->forceUnitStride() can only be called by your subclasses as it is declared protected so do not worry about silly users messing with this, it is none of their business.

The explicit multi-vector version of euclideanApply() has a default implementation that calls the explicit single-vector version (that a subclass must supply) one column at a time. A subclass should only override this default multi-vector version if it can do something more efficient for multi-vectors.

Examples:: ExampleTridiagSerialLinearOp.hpp, and ExampleTridiagSpmdLinearOp.hpp.

Definition at line 173 of file Thyra_SpmdLinearOpBaseDecl.hpp.

Constructor & Destructor Documentation

template<class Scalar>

Thyra::SpmdLinearOpBase< Scalar >::SpmdLinearOpBase ( )

Construct to uninitialized
Postconditions:

this->domain().get() == NULL

this->range().get() == NULL

Definition at line 90 of file Thyra_SpmdLinearOpBase.hpp.

Member Function Documentation

template<class Scalar>

Teuchos::RefCountPtr< const ScalarProdVectorSpaceBase< Scalar > > Thyra::SpmdLinearOpBase< Scalar >::rangeScalarProdVecSpc ( ) const [virtual]

Implements Thyra::EuclideanLinearOpBase< Scalar >.
Definition at line 44 of file Thyra_SpmdLinearOpBase.hpp.

template<class Scalar>

Teuchos::RefCountPtr< const ScalarProdVectorSpaceBase< Scalar > > Thyra::SpmdLinearOpBase< Scalar >::domainScalarProdVecSpc ( ) const [virtual]

Implements Thyra::EuclideanLinearOpBase< Scalar >.
Definition at line 51 of file Thyra_SpmdLinearOpBase.hpp.

template<class Scalar>

void Thyra::SpmdLinearOpBase< Scalar >::euclideanApply ( const ETransp M_trans,

const MultiVectorBase< Scalar > & X,

MultiVectorBase< Scalar > * Y,

const Scalar alpha,

const Scalar beta

) const [virtual]

Calls protected euclideanApply() function.

Implements Thyra::SingleScalarEuclideanLinearOpBase< Scalar >.
Definition at line 57 of file Thyra_SpmdLinearOpBase.hpp.

template<class Scalar>

void Thyra::SpmdLinearOpBase< Scalar >::forceUnitStride ( const bool & forceUnitStride ) [inline, protected]

Set if unit stride is forced for vector data views or not.

Parameters:

forceUnitStride [in]

Postconditions:

this->forceUnitStride() == forceUnitStride

Definition at line 211 of file Thyra_SpmdLinearOpBaseDecl.hpp.

template<class Scalar>

void Thyra::SpmdLinearOpBase< Scalar >::setSpaces ( const Teuchos::RefCountPtr< const SpmdVectorSpaceBase< Scalar > > & range,

const Teuchos::RefCountPtr< const SpmdVectorSpaceBase< Scalar > > & domain

) [virtual]

Initialize vector spaces using pre-formed SpmdVectorSpaceBase objects.

Parameters:

domain [in] Smart pointer to domain space

range [in] Smart pointer to range space

Preconditions:

domain.get() != NULL

range.get() != NULL

Postconditions:

this->domain().get() == domain.get()

this->range().get() == range.get()

Definition at line 95 of file Thyra_SpmdLinearOpBase.hpp.

template<class Scalar>

void Thyra::SpmdLinearOpBase< Scalar >::setLocalDimensions ( const Teuchos::RefCountPtr< const Teuchos::Comm< Index > > & comm,

const Index localDimRange,

const Index localDimDomain

) [virtual]

Initialize vector spaces given local dimensions (uses DefaultSpmdVectorSpace).

Parameters:

comm [in] Spmd Communicator

localDimRange [in] The local number of vector elements in the domain space.

localDimDomain [in] The local number of vector elements in the domain space.

Preconditions:

localDimRange > 0

localDimDomain > 0

Postconditions:

dynamic_cast<SpmdVectorSpace<Scalar>&>(*this->range()).localSubDim() == localDimRange

dynamic_cast<SpmdVectorSpace<Scalar>&>(*this->domain()).localSubDim() == localDimDomain

dynamic_cast<const DefaultSpmdVectorSpace<Scalar>*>(this->range().get()) != NULL

dynamic_cast<const DefaultSpmdVectorSpace<Scalar>*>(this->domain().get()) != NULL

Definition at line 116 of file Thyra_SpmdLinearOpBase.hpp.

template<class Scalar>

virtual void Thyra::SpmdLinearOpBase< Scalar >::euclideanApply ( const ETransp M_trans,

const RTOpPack::ConstSubVectorView< Scalar > & local_x,

const RTOpPack::SubVectorView< Scalar > * local_y,

const Scalar alpha,

const Scalar beta

) const [pure virtual]

Apply the operator to explicit vector data.

See LinearOpBase::euclideanApply() for a discussion of the arguments to this function. What differentiates this function is that local_x and local_y are passed as objects with explicit pointers to local vector data.
Since this function is protected and does not get directly called by a client. Instead, this function is called by the vector version of euclideanApply().

template<class Scalar>

void Thyra::SpmdLinearOpBase< Scalar >::euclideanApply ( const ETransp M_trans,

const RTOpPack::ConstSubMultiVectorView< Scalar > & local_X,

const RTOpPack::SubMultiVectorView< Scalar > * local_Y,

const Scalar alpha,

const Scalar beta

) const [virtual]

Apply the operator to explicit multi-vector data.

See LinearOpBase::euclideanApply() for a discussion of the arguments to this function. What differentiates this function is that local_X and local_Y are passed as objects with explicit pointers to local multi-vector data.
Since this function is protected and does not get directly called by a client. Instead, this function is called by the multi-vector version of euclideanApply().
The default implementation just calls the above vector version one column at a time. A subclass should only override this function if it can provide a cache-smart version. At any rate, one can get up and going very quickly by just providing an override for the simpler single-vector version. Then latter, if profiling data justifies it, one can provide a specialized override for this function in an attempt to improve performance.
Definition at line 138 of file Thyra_SpmdLinearOpBase.hpp.

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

Generated on Thu Sep 18 12:32:34 2008 for Thyra Operator/Vector Support by

1.3.9.1

Thyra::SpmdLinearOpBase< Scalar > Class Template Reference [Thyra Operator/Vector Base Support Subclasses for SPMD Thyra Implementations]

Overridden from EuclideanLinearOpBase

Protected constructors/initializers/accessors

Protected virtual functions to be overridden by subclasses

Detailed Description

template<class Scalar> class Thyra::SpmdLinearOpBase< Scalar >

Constructor & Destructor Documentation

Member Function Documentation

Thyra::SpmdLinearOpBase< Scalar > Class Template Reference
[Thyra Operator/Vector Base Support Subclasses for SPMD Thyra Implementations]

template<class Scalar>
class Thyra::SpmdLinearOpBase< Scalar >