Thyra_ParameterDrivenMultiVectorInput.hpp

// @HEADER
// ***********************************************************************
// 
//    Thyra: Interfaces and Support for Abstract Numerical Algorithms
//                 Copyright (2004) Sandia Corporation
// 
// Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
// license for use of this work by or on behalf of the U.S. Government.
// 
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// 1. Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the
// documentation and/or other materials provided with the distribution.
//
// 3. Neither the name of the Corporation nor the names of the
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Questions? Contact Roscoe A. Bartlett (bartlettra@ornl.gov) 
// 
// ***********************************************************************
// @HEADER

#ifndef THYRA_PARAMETER_DRIVEN_MULTI_VECTOR_INPUT_HPP
#define THYRA_PARAMETER_DRIVEN_MULTI_VECTOR_INPUT_HPP

#include "Thyra_MultiVectorFileIOBase.hpp"
#include "Thyra_DetachedVectorView.hpp"
#include "Thyra_MultiVectorStdOps.hpp"
#include "Teuchos_ParameterListAcceptor.hpp"
#include "Teuchos_VerboseObject.hpp"
#include "Teuchos_StandardCompositionMacros.hpp"
#include "Teuchos_implicit_cast.hpp"

namespace Thyra {

template<class Scalar>
class ParameterDrivenMultiVectorInput
  : public Teuchos::ParameterListAcceptor
  , public Teuchos::VerboseObject<ParameterDrivenMultiVectorInput<Scalar> >
{
public:


  ParameterDrivenMultiVectorInput();

  STANDARD_CONST_COMPOSITION_MEMBERS( VectorSpaceBase<Scalar>, vecSpc );

  STANDARD_COMPOSITION_MEMBERS( MultiVectorFileIOBase<Scalar>, fileIO );



  void setParameterList(Teuchos::RCP<Teuchos::ParameterList> const& paramList);
  Teuchos::RCP<Teuchos::ParameterList> getNonconstParameterList();
  Teuchos::RCP<Teuchos::ParameterList> unsetParameterList();
  Teuchos::RCP<const Teuchos::ParameterList> getParameterList() const;
  Teuchos::RCP<const Teuchos::ParameterList> getValidParameters() const;



  const std::string& readinFileNameBase() const;

  const Teuchos::Array<Scalar>& readinExplicitArray() const;

  Scalar readinScaleBy() const;


  
  bool readMultiVector(
    const std::string                 &mvName
    ,Thyra::MultiVectorBase<Scalar>   *mv
    ) const;
  
  bool readVector(
    const std::string &vName
    ,Teuchos::RCP<Thyra::VectorBase<Scalar> > *v
    ) const;
  
  Teuchos::RCP<Thyra::VectorBase<Scalar> >
  readVector( const std::string &vName ) const;
  

private:

  mutable Teuchos::RCP<const Teuchos::ParameterList> validParamList_;
  Teuchos::RCP<Teuchos::ParameterList> paramList_;

  std::string fileNameBase_;
  Teuchos::Array<Scalar> explicitArray_;
  Scalar scaleBy_;
  Scalar addScalar_;

  static const std::string FileNameBase_name_;
  static const std::string FileNameBase_default_;

  static const std::string ExplicitArray_name_;
  static const std::string ExplicitArray_default_;

  static const std::string ScaleBy_name_;
  static const double ScaleBy_default_;

  static const std::string AddScalar_name_;
  static const double AddScalar_default_;

};


template<class Scalar>
RCP<const VectorBase<Scalar> >
readVectorOverride(
  const ParameterDrivenMultiVectorInput<Scalar> &pdmvi,
  const std::string &vName,
  const RCP<const VectorBase<Scalar> > &defaultVector
  )
{
  RCP<const VectorBase<Scalar> >
    vector = pdmvi.readVector(vName);
  if (!is_null(vector))
    return vector;
  return defaultVector;
}


// //////////////////////////////////////////
// Inline functions

template<class Scalar>
inline
const std::string&
ParameterDrivenMultiVectorInput<Scalar>::readinFileNameBase() const
{
  return fileNameBase_;
}

template<class Scalar>
inline
const Teuchos::Array<Scalar>&
ParameterDrivenMultiVectorInput<Scalar>::readinExplicitArray() const
{
  return explicitArray_;
}

template<class Scalar>
inline
Scalar
ParameterDrivenMultiVectorInput<Scalar>::readinScaleBy() const
{
  return scaleBy_;
}

// //////////////////////////////////////////
// Implementations

namespace PDMVIUtilityPack {

template<class Scalar>
void copy(
  const Teuchos::Array<Scalar>  &array
  ,VectorBase<Scalar>           *vec
  )
{
  using Teuchos::implicit_cast;
  TEUCHOS_TEST_FOR_EXCEPT(vec==0);
  DetachedVectorView<Scalar> dVec(*vec);
  TEUCHOS_TEST_FOR_EXCEPT(implicit_cast<int>(dVec.subDim())!=implicit_cast<int>(array.size())); // ToDo: Give a very good error message!
  for( Ordinal i = 0; i < dVec.subDim(); ++i ) {
    dVec[i] = array[i];
  }
}

} // namespace PDMVIUtilityPack

// Static data members

template<class Scalar>
const std::string
ParameterDrivenMultiVectorInput<Scalar>::FileNameBase_name_ = "File Name Base";
template<class Scalar>
const std::string
ParameterDrivenMultiVectorInput<Scalar>::FileNameBase_default_ = "";

template<class Scalar>
const std::string
ParameterDrivenMultiVectorInput<Scalar>::ExplicitArray_name_ = "Explicit Array";
template<class Scalar>
const std::string
ParameterDrivenMultiVectorInput<Scalar>::ExplicitArray_default_ = "{}";

template<class Scalar>
const std::string
ParameterDrivenMultiVectorInput<Scalar>::ScaleBy_name_ = "Scale By";
template<class Scalar>
const double
ParameterDrivenMultiVectorInput<Scalar>::ScaleBy_default_ = 1.0;

template<class Scalar>
const std::string
ParameterDrivenMultiVectorInput<Scalar>::AddScalar_name_ = "Add Scalar";
template<class Scalar>
const double
ParameterDrivenMultiVectorInput<Scalar>::AddScalar_default_ = 0.0;

// Constructors/Initializers

template<class Scalar>
ParameterDrivenMultiVectorInput<Scalar>::ParameterDrivenMultiVectorInput()
  :fileNameBase_(FileNameBase_default_),
   scaleBy_(ScaleBy_default_),
   addScalar_(AddScalar_default_)
{}

// Overridden from ParameterListAcceptor

template<class Scalar>
void ParameterDrivenMultiVectorInput<Scalar>::setParameterList(
  Teuchos::RCP<Teuchos::ParameterList> const& paramList
  )
{
  TEUCHOS_TEST_FOR_EXCEPT(0==paramList.get());
  paramList->validateParameters(*getValidParameters());
  paramList_ = paramList;
  fileNameBase_ = paramList_->get(
    FileNameBase_name_,FileNameBase_default_ );
  explicitArray_ = Teuchos::getArrayFromStringParameter<Scalar>(
    *paramList_,ExplicitArray_name_
    ,-1     // An array of any size will do here
    ,false  // The parameter does not need to exist
    );
  scaleBy_ = paramList_->get(ScaleBy_name_,ScaleBy_default_);
  addScalar_ = paramList_->get(AddScalar_name_,AddScalar_default_);
#ifdef TEUCHOS_DEBUG
  paramList_->validateParameters(*getValidParameters(),0);
#endif // TEUCHOS_DEBUG
}

template<class Scalar>
Teuchos::RCP<Teuchos::ParameterList>
ParameterDrivenMultiVectorInput<Scalar>::getNonconstParameterList()
{
  return paramList_;
}

template<class Scalar>
Teuchos::RCP<Teuchos::ParameterList>
ParameterDrivenMultiVectorInput<Scalar>::unsetParameterList()
{
  Teuchos::RCP<Teuchos::ParameterList>
    _paramList = paramList_;
  paramList_ = Teuchos::null;
  return _paramList;
}

template<class Scalar>
Teuchos::RCP<const Teuchos::ParameterList>
ParameterDrivenMultiVectorInput<Scalar>::getParameterList() const
{
  return paramList_;
}

template<class Scalar>
Teuchos::RCP<const Teuchos::ParameterList>
ParameterDrivenMultiVectorInput<Scalar>::getValidParameters() const
{
  if(!validParamList_.get()) {
    Teuchos::RCP<Teuchos::ParameterList>
      pl = Teuchos::rcp(new Teuchos::ParameterList);
    pl->set(
      FileNameBase_name_,FileNameBase_default_
      ,"Base-name of file(s) that will be used to read in the vector.\n"
      "If this parameter is empty \"\", no file(s) will be read.\n"
      "Note that a MultiVectorFileIOBase object and a VectorSpaceBase object\n"
      "must be set internally for this to work."
      );
    pl->set(
      ExplicitArray_name_,ExplicitArray_default_
      ,"The vector specified explicitly as a string interpreted as a Teuchos::Array\n"
      "object.  If this array is set, it will override the vector specified\n"
      "by the above \"" + FileNameBase_name_ + "\" parameter.\n"
      "Note that a VectorSpaceBase object\n"
      "must be set internally for this to work."
      );
    pl->set(
      ScaleBy_name_,ScaleBy_default_,
      "A factor by which the read in vector will be scaled by."
      );
    pl->set(
      AddScalar_name_, AddScalar_default_,
      "A scalar that will added to the read in vector after it\n"
      "optionally scaled."
      );
    validParamList_ = pl;
  }
  return validParamList_;
}

// (Multi)Vector Readers

template<class Scalar>
bool ParameterDrivenMultiVectorInput<Scalar>::readMultiVector(
  const std::string                 &mvName
  ,Thyra::MultiVectorBase<Scalar>   *mv
  ) const
{
  using Teuchos::implicit_cast;
  TEUCHOS_TEST_FOR_EXCEPT(0==mv);
  typedef Teuchos::ScalarTraits<Scalar> ST;
  const Teuchos::EVerbosityLevel verbLevel = this->getVerbLevel();
  Teuchos::RCP<Teuchos::FancyOStream>
    out = this->getOStream();
  const bool trace = ( verbLevel >= implicit_cast<int>(Teuchos::VERB_LOW) );
  Teuchos::OSTab tab(out);
  bool vectorWasRead = false;
  if(fileNameBase_.length()) {
    if( out.get() && trace )
      *out << "\nReading \"" << mvName << "\" from the file(s) with base name \""
           << fileNameBase_ << "\" ...\n";
    fileIO().readMultiVectorFromFile(fileNameBase_,mv);
    vectorWasRead = true;
  }
  if(explicitArray_.size()) {
    if( implicit_cast<Ordinal>(explicitArray_.size()) != vecSpc().dim() ) {
      // Call back to throw an exception with a better erro message!
      Teuchos::getArrayFromStringParameter<Scalar>(
        *paramList_,ExplicitArray_name_,vecSpc().dim(),false);
      TEUCHOS_TEST_FOR_EXCEPT(!"Should never get here!");
    }
    if( out.get() && trace )
      *out << "\nSetting \"" << mvName << "\" directly from the parameter array "
           << explicitArray_ << " ...\n";
    TEUCHOS_TEST_FOR_EXCEPTION(
      mv->domain()->dim()!=implicit_cast<Ordinal>(1), std::logic_error
      ,"Error! We can not handle reading in multi-vectors directly from"
      " the parameter list yet!"
      );
    PDMVIUtilityPack::copy(explicitArray_,&*mv->col(0));
    // ToDo: Find a way to read a matrix from a file (perhaps a nested
    // Array<Array<Scalar> > or something!)
    vectorWasRead = true;
  }
  if( scaleBy_ != ST::one() && vectorWasRead ) {
    if( out.get() && trace )
      *out << "\nScaling \"" << mvName << "\" by " << scaleBy_ << " ...\n";
    Vt_S(Teuchos::ptr(mv), scaleBy_);
  }
  if( addScalar_ != ST::zero() && vectorWasRead ) {
    if( out.get() && trace )
      *out << "\nAdding scalar " << addScalar_ << " to \"" << mvName << "\" ...\n";
    Vp_S(Teuchos::ptr(mv), addScalar_);
  }
  return vectorWasRead;
}

template<class Scalar>
bool ParameterDrivenMultiVectorInput<Scalar>::readVector(
  const std::string                                   &vName
  ,Teuchos::RCP<Thyra::VectorBase<Scalar> >   *v
  ) const
{
  TEUCHOS_TEST_FOR_EXCEPT(0==v);
  bool vectorWasRead = false;
  if( fileNameBase_.length() || explicitArray_.size() ) {
    if(!(*v).get())
      (*v) = createMember(this->vecSpc());
    vectorWasRead = this->readMultiVector(vName, &*(*v));
  }
  return vectorWasRead;
}

template<class Scalar>
Teuchos::RCP<Thyra::VectorBase<Scalar> >
ParameterDrivenMultiVectorInput<Scalar>::readVector(
  const std::string &vName
  ) const
{
  Teuchos::RCP<Thyra::VectorBase<Scalar> > v;
  const bool vectorWasRead = readVector(vName,&v);
  if(!vectorWasRead)
    v = Teuchos::null;
  return v;
}

} // namespace Thyra

#endif // THYRA_PARAMETER_DRIVEN_MULTI_VECTOR_INPUT_HPP