Thyra Package Browser (Single Doxygen Collection) Version of the Day
Thyra_ParameterDrivenMultiVectorInput.hpp
Go to the documentation of this file.
00001 // @HEADER
00002 // ***********************************************************************
00003 // 
00004 //    Thyra: Interfaces and Support for Abstract Numerical Algorithms
00005 //                 Copyright (2004) Sandia Corporation
00006 // 
00007 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
00008 // license for use of this work by or on behalf of the U.S. Government.
00009 // 
00010 // This library is free software; you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as
00012 // published by the Free Software Foundation; either version 2.1 of the
00013 // License, or (at your option) any later version.
00014 //  
00015 // This library is distributed in the hope that it will be useful, but
00016 // WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00018 // Lesser General Public License for more details.
00019 //  
00020 // You should have received a copy of the GNU Lesser General Public
00021 // License along with this library; if not, write to the Free Software
00022 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
00023 // USA
00024 // Questions? Contact Michael A. Heroux (maherou@sandia.gov) 
00025 // 
00026 // ***********************************************************************
00027 // @HEADER
00028 
00029 #ifndef THYRA_PARAMETER_DRIVEN_MULTI_VECTOR_INPUT_HPP
00030 #define THYRA_PARAMETER_DRIVEN_MULTI_VECTOR_INPUT_HPP
00031 
00032 #include "Thyra_MultiVectorFileIOBase.hpp"
00033 #include "Thyra_DetachedVectorView.hpp"
00034 #include "Thyra_MultiVectorStdOps.hpp"
00035 #include "Teuchos_ParameterListAcceptor.hpp"
00036 #include "Teuchos_VerboseObject.hpp"
00037 #include "Teuchos_StandardCompositionMacros.hpp"
00038 #include "Teuchos_implicit_cast.hpp"
00039 
00040 namespace Thyra {
00041 
00075 template<class Scalar>
00076 class ParameterDrivenMultiVectorInput
00077   : public Teuchos::ParameterListAcceptor
00078   , public Teuchos::VerboseObject<ParameterDrivenMultiVectorInput<Scalar> >
00079 {
00080 public:
00081 
00084 
00086   ParameterDrivenMultiVectorInput();
00087 
00091   STANDARD_CONST_COMPOSITION_MEMBERS( VectorSpaceBase<Scalar>, vecSpc );
00092 
00096   STANDARD_COMPOSITION_MEMBERS( MultiVectorFileIOBase<Scalar>, fileIO );
00097 
00099 
00102 
00104   void setParameterList(Teuchos::RCP<Teuchos::ParameterList> const& paramList);
00106   Teuchos::RCP<Teuchos::ParameterList> getNonconstParameterList();
00108   Teuchos::RCP<Teuchos::ParameterList> unsetParameterList();
00110   Teuchos::RCP<const Teuchos::ParameterList> getParameterList() const;
00112   Teuchos::RCP<const Teuchos::ParameterList> getValidParameters() const;
00113 
00115 
00118 
00122   const std::string& readinFileNameBase() const;
00123 
00127   const Teuchos::Array<Scalar>& readinExplicitArray() const;
00128 
00132   Scalar readinScaleBy() const;
00133 
00135 
00138   
00160   bool readMultiVector(
00161     const std::string                 &mvName
00162     ,Thyra::MultiVectorBase<Scalar>   *mv
00163     ) const;
00164   
00205   bool readVector(
00206     const std::string &vName
00207     ,Teuchos::RCP<Thyra::VectorBase<Scalar> > *v
00208     ) const;
00209   
00219   Teuchos::RCP<Thyra::VectorBase<Scalar> >
00220   readVector( const std::string &vName ) const;
00221   
00223 
00224 private:
00225 
00226   mutable Teuchos::RCP<const Teuchos::ParameterList> validParamList_;
00227   Teuchos::RCP<Teuchos::ParameterList> paramList_;
00228 
00229   std::string fileNameBase_;
00230   Teuchos::Array<Scalar> explicitArray_;
00231   Scalar scaleBy_;
00232   Scalar addScalar_;
00233 
00234   static const std::string FileNameBase_name_;
00235   static const std::string FileNameBase_default_;
00236 
00237   static const std::string ExplicitArray_name_;
00238   static const std::string ExplicitArray_default_;
00239 
00240   static const std::string ScaleBy_name_;
00241   static const double ScaleBy_default_;
00242 
00243   static const std::string AddScalar_name_;
00244   static const double AddScalar_default_;
00245 
00246 };
00247 
00248 
00253 template<class Scalar>
00254 RCP<const VectorBase<Scalar> >
00255 readVectorOverride(
00256   const ParameterDrivenMultiVectorInput<Scalar> &pdmvi,
00257   const std::string &vName,
00258   const RCP<const VectorBase<Scalar> > &defaultVector
00259   )
00260 {
00261   RCP<const VectorBase<Scalar> >
00262     vector = pdmvi.readVector(vName);
00263   if (!is_null(vector))
00264     return vector;
00265   return defaultVector;
00266 }
00267 
00268 
00269 // //////////////////////////////////////////
00270 // Inline functions
00271 
00272 template<class Scalar>
00273 inline
00274 const std::string&
00275 ParameterDrivenMultiVectorInput<Scalar>::readinFileNameBase() const
00276 {
00277   return fileNameBase_;
00278 }
00279 
00280 template<class Scalar>
00281 inline
00282 const Teuchos::Array<Scalar>&
00283 ParameterDrivenMultiVectorInput<Scalar>::readinExplicitArray() const
00284 {
00285   return explicitArray_;
00286 }
00287 
00288 template<class Scalar>
00289 inline
00290 Scalar
00291 ParameterDrivenMultiVectorInput<Scalar>::readinScaleBy() const
00292 {
00293   return scaleBy_;
00294 }
00295 
00296 // //////////////////////////////////////////
00297 // Implementations
00298 
00299 namespace PDMVIUtilityPack {
00300 
00301 template<class Scalar>
00302 void copy(
00303   const Teuchos::Array<Scalar>  &array
00304   ,VectorBase<Scalar>           *vec
00305   )
00306 {
00307   using Teuchos::implicit_cast;
00308   TEST_FOR_EXCEPT(vec==0);
00309   DetachedVectorView<Scalar> dVec(*vec);
00310   TEST_FOR_EXCEPT(implicit_cast<int>(dVec.subDim())!=implicit_cast<int>(array.size())); // ToDo: Give a very good error message!
00311   for( Ordinal i = 0; i < dVec.subDim(); ++i ) {
00312     dVec[i] = array[i];
00313   }
00314 }
00315 
00316 } // namespace PDMVIUtilityPack
00317 
00318 // Static data members
00319 
00320 template<class Scalar>
00321 const std::string
00322 ParameterDrivenMultiVectorInput<Scalar>::FileNameBase_name_ = "File Name Base";
00323 template<class Scalar>
00324 const std::string
00325 ParameterDrivenMultiVectorInput<Scalar>::FileNameBase_default_ = "";
00326 
00327 template<class Scalar>
00328 const std::string
00329 ParameterDrivenMultiVectorInput<Scalar>::ExplicitArray_name_ = "Explicit Array";
00330 template<class Scalar>
00331 const std::string
00332 ParameterDrivenMultiVectorInput<Scalar>::ExplicitArray_default_ = "{}";
00333 
00334 template<class Scalar>
00335 const std::string
00336 ParameterDrivenMultiVectorInput<Scalar>::ScaleBy_name_ = "Scale By";
00337 template<class Scalar>
00338 const double
00339 ParameterDrivenMultiVectorInput<Scalar>::ScaleBy_default_ = 1.0;
00340 
00341 template<class Scalar>
00342 const std::string
00343 ParameterDrivenMultiVectorInput<Scalar>::AddScalar_name_ = "Add Scalar";
00344 template<class Scalar>
00345 const double
00346 ParameterDrivenMultiVectorInput<Scalar>::AddScalar_default_ = 0.0;
00347 
00348 // Constructors/Initializers
00349 
00350 template<class Scalar>
00351 ParameterDrivenMultiVectorInput<Scalar>::ParameterDrivenMultiVectorInput()
00352   :fileNameBase_(FileNameBase_default_),
00353    scaleBy_(ScaleBy_default_),
00354    addScalar_(AddScalar_default_)
00355 {}
00356 
00357 // Overridden from ParameterListAcceptor
00358 
00359 template<class Scalar>
00360 void ParameterDrivenMultiVectorInput<Scalar>::setParameterList(
00361   Teuchos::RCP<Teuchos::ParameterList> const& paramList
00362   )
00363 {
00364   TEST_FOR_EXCEPT(0==paramList.get());
00365   paramList->validateParameters(*getValidParameters());
00366   paramList_ = paramList;
00367   fileNameBase_ = paramList_->get(
00368     FileNameBase_name_,FileNameBase_default_ );
00369   explicitArray_ = Teuchos::getArrayFromStringParameter<Scalar>(
00370     *paramList_,ExplicitArray_name_
00371     ,-1     // An array of any size will do here
00372     ,false  // The parameter does not need to exist
00373     );
00374   scaleBy_ = paramList_->get(ScaleBy_name_,ScaleBy_default_);
00375   addScalar_ = paramList_->get(AddScalar_name_,AddScalar_default_);
00376 #ifdef TEUCHOS_DEBUG
00377   paramList_->validateParameters(*getValidParameters(),0);
00378 #endif // TEUCHOS_DEBUG
00379 }
00380 
00381 template<class Scalar>
00382 Teuchos::RCP<Teuchos::ParameterList>
00383 ParameterDrivenMultiVectorInput<Scalar>::getNonconstParameterList()
00384 {
00385   return paramList_;
00386 }
00387 
00388 template<class Scalar>
00389 Teuchos::RCP<Teuchos::ParameterList>
00390 ParameterDrivenMultiVectorInput<Scalar>::unsetParameterList()
00391 {
00392   Teuchos::RCP<Teuchos::ParameterList>
00393     _paramList = paramList_;
00394   paramList_ = Teuchos::null;
00395   return _paramList;
00396 }
00397 
00398 template<class Scalar>
00399 Teuchos::RCP<const Teuchos::ParameterList>
00400 ParameterDrivenMultiVectorInput<Scalar>::getParameterList() const
00401 {
00402   return paramList_;
00403 }
00404 
00405 template<class Scalar>
00406 Teuchos::RCP<const Teuchos::ParameterList>
00407 ParameterDrivenMultiVectorInput<Scalar>::getValidParameters() const
00408 {
00409   if(!validParamList_.get()) {
00410     Teuchos::RCP<Teuchos::ParameterList>
00411       pl = Teuchos::rcp(new Teuchos::ParameterList);
00412     pl->set(
00413       FileNameBase_name_,FileNameBase_default_
00414       ,"Base-name of file(s) that will be used to read in the vector.\n"
00415       "If this parameter is empty \"\", no file(s) will be read.\n"
00416       "Note that a MultiVectorFileIOBase object and a VectorSpaceBase object\n"
00417       "must be set internally for this to work."
00418       );
00419     pl->set(
00420       ExplicitArray_name_,ExplicitArray_default_
00421       ,"The vector specified explicitly as a string interpreted as a Teuchos::Array\n"
00422       "object.  If this array is set, it will override the vector specified\n"
00423       "by the above \"" + FileNameBase_name_ + "\" parameter.\n"
00424       "Note that a VectorSpaceBase object\n"
00425       "must be set internally for this to work."
00426       );
00427     pl->set(
00428       ScaleBy_name_,ScaleBy_default_,
00429       "A factor by which the read in vector will be scaled by."
00430       );
00431     pl->set(
00432       AddScalar_name_, AddScalar_default_,
00433       "A scalar that will added to the read in vector after it\n"
00434       "optionally scaled."
00435       );
00436     validParamList_ = pl;
00437   }
00438   return validParamList_;
00439 }
00440 
00441 // (Multi)Vector Readers
00442 
00443 template<class Scalar>
00444 bool ParameterDrivenMultiVectorInput<Scalar>::readMultiVector(
00445   const std::string                 &mvName
00446   ,Thyra::MultiVectorBase<Scalar>   *mv
00447   ) const
00448 {
00449   using Teuchos::implicit_cast;
00450   TEST_FOR_EXCEPT(0==mv);
00451   typedef Teuchos::ScalarTraits<Scalar> ST;
00452   const Teuchos::EVerbosityLevel verbLevel = this->getVerbLevel();
00453   Teuchos::RCP<Teuchos::FancyOStream>
00454     out = this->getOStream();
00455   const bool trace = ( verbLevel >= implicit_cast<int>(Teuchos::VERB_LOW) );
00456   Teuchos::OSTab tab(out);
00457   bool vectorWasRead = false;
00458   if(fileNameBase_.length()) {
00459     if( out.get() && trace )
00460       *out << "\nReading \"" << mvName << "\" from the file(s) with base name \""
00461            << fileNameBase_ << "\" ...\n";
00462     fileIO().readMultiVectorFromFile(fileNameBase_,mv);
00463     vectorWasRead = true;
00464   }
00465   if(explicitArray_.size()) {
00466     if( implicit_cast<Ordinal>(explicitArray_.size()) != vecSpc().dim() ) {
00467       // Call back to throw an exception with a better erro message!
00468       Teuchos::getArrayFromStringParameter<Scalar>(
00469         *paramList_,ExplicitArray_name_,vecSpc().dim(),false);
00470       TEST_FOR_EXCEPT(!"Should never get here!");
00471     }
00472     if( out.get() && trace )
00473       *out << "\nSetting \"" << mvName << "\" directly from the parameter array "
00474            << explicitArray_ << " ...\n";
00475     TEST_FOR_EXCEPTION(
00476       mv->domain()->dim()!=implicit_cast<Ordinal>(1), std::logic_error
00477       ,"Error! We can not handle reading in multi-vectors directly from"
00478       " the parameter list yet!"
00479       );
00480     PDMVIUtilityPack::copy(explicitArray_,&*mv->col(0));
00481     // ToDo: Find a way to read a matrix from a file (perhaps a nested
00482     // Array<Array<Scalar> > or something!)
00483     vectorWasRead = true;
00484   }
00485   if( scaleBy_ != ST::one() && vectorWasRead ) {
00486     if( out.get() && trace )
00487       *out << "\nScaling \"" << mvName << "\" by " << scaleBy_ << " ...\n";
00488     Vt_S(&*mv,scaleBy_);
00489   }
00490   if( addScalar_ != ST::zero() && vectorWasRead ) {
00491     if( out.get() && trace )
00492       *out << "\nAdding scalar " << addScalar_ << " to \"" << mvName << "\" ...\n";
00493     Vp_S(&*mv,addScalar_);
00494   }
00495   return vectorWasRead;
00496 }
00497 
00498 template<class Scalar>
00499 bool ParameterDrivenMultiVectorInput<Scalar>::readVector(
00500   const std::string                                   &vName
00501   ,Teuchos::RCP<Thyra::VectorBase<Scalar> >   *v
00502   ) const
00503 {
00504   TEST_FOR_EXCEPT(0==v);
00505   bool vectorWasRead = false;
00506   if( fileNameBase_.length() || explicitArray_.size() ) {
00507     if(!(*v).get())
00508       (*v) = createMember(this->vecSpc());
00509     vectorWasRead = this->readMultiVector(vName,&*(*v));
00510   }
00511   return vectorWasRead;
00512 }
00513 
00514 template<class Scalar>
00515 Teuchos::RCP<Thyra::VectorBase<Scalar> >
00516 ParameterDrivenMultiVectorInput<Scalar>::readVector(
00517   const std::string &vName
00518   ) const
00519 {
00520   Teuchos::RCP<Thyra::VectorBase<Scalar> > v;
00521   const bool vectorWasRead = readVector(vName,&v);
00522   if(!vectorWasRead)
00523     v = Teuchos::null;
00524   return v;
00525 }
00526 
00527 } // namespace Thyra
00528 
00529 #endif // THYRA_PARAMETER_DRIVEN_MULTI_VECTOR_INPUT_HPP
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines