Thyra  Version of the Day
Thyra_ParameterDrivenMultiVectorInput.hpp
1 // @HEADER
2 // ***********************************************************************
3 //
4 // Thyra: Interfaces and Support for Abstract Numerical Algorithms
5 // Copyright (2004) Sandia Corporation
6 //
7 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
8 // license for use of this work by or on behalf of the U.S. Government.
9 //
10 // Redistribution and use in source and binary forms, with or without
11 // modification, are permitted provided that the following conditions are
12 // met:
13 //
14 // 1. Redistributions of source code must retain the above copyright
15 // notice, this list of conditions and the following disclaimer.
16 //
17 // 2. Redistributions in binary form must reproduce the above copyright
18 // notice, this list of conditions and the following disclaimer in the
19 // documentation and/or other materials provided with the distribution.
20 //
21 // 3. Neither the name of the Corporation nor the names of the
22 // contributors may be used to endorse or promote products derived from
23 // this software without specific prior written permission.
24 //
25 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
26 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
29 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
30 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
31 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
32 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
33 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
34 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
35 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
36 //
37 // Questions? Contact Roscoe A. Bartlett (bartlettra@ornl.gov)
38 //
39 // ***********************************************************************
40 // @HEADER
41 
42 #ifndef THYRA_PARAMETER_DRIVEN_MULTI_VECTOR_INPUT_HPP
43 #define THYRA_PARAMETER_DRIVEN_MULTI_VECTOR_INPUT_HPP
44 
45 #include "Thyra_MultiVectorFileIOBase.hpp"
46 #include "Thyra_DetachedVectorView.hpp"
47 #include "Thyra_MultiVectorStdOps.hpp"
48 #include "Teuchos_ParameterListAcceptor.hpp"
49 #include "Teuchos_VerboseObject.hpp"
50 #include "Teuchos_StandardCompositionMacros.hpp"
51 #include "Teuchos_implicit_cast.hpp"
52 
53 namespace Thyra {
54 
88 template<class Scalar>
90  : public Teuchos::ParameterListAcceptor
91  , public Teuchos::VerboseObject<ParameterDrivenMultiVectorInput<Scalar> >
92 {
93 public:
94 
97 
100 
105 
110 
112 
115 
117  void setParameterList(Teuchos::RCP<Teuchos::ParameterList> const& paramList);
119  Teuchos::RCP<Teuchos::ParameterList> getNonconstParameterList();
121  Teuchos::RCP<Teuchos::ParameterList> unsetParameterList();
123  Teuchos::RCP<const Teuchos::ParameterList> getParameterList() const;
125  Teuchos::RCP<const Teuchos::ParameterList> getValidParameters() const;
126 
128 
131 
135  const std::string& readinFileNameBase() const;
136 
140  const Teuchos::Array<Scalar>& readinExplicitArray() const;
141 
145  Scalar readinScaleBy() const;
146 
148 
151 
173  bool readMultiVector(
174  const std::string &mvName
176  ) const;
177 
218  bool readVector(
219  const std::string &vName
220  ,Teuchos::RCP<Thyra::VectorBase<Scalar> > *v
221  ) const;
222 
232  Teuchos::RCP<Thyra::VectorBase<Scalar> >
233  readVector( const std::string &vName ) const;
234 
236 
237 private:
238 
239  mutable Teuchos::RCP<const Teuchos::ParameterList> validParamList_;
240  Teuchos::RCP<Teuchos::ParameterList> paramList_;
241 
242  std::string fileNameBase_;
243  Teuchos::Array<Scalar> explicitArray_;
244  Scalar scaleBy_;
245  Scalar addScalar_;
246 
247  static const std::string FileNameBase_name_;
248  static const std::string FileNameBase_default_;
249 
250  static const std::string ExplicitArray_name_;
251  static const std::string ExplicitArray_default_;
252 
253  static const std::string ScaleBy_name_;
254  static const double ScaleBy_default_;
255 
256  static const std::string AddScalar_name_;
257  static const double AddScalar_default_;
258 
259 };
260 
261 
266 template<class Scalar>
267 RCP<const VectorBase<Scalar> >
270  const std::string &vName,
271  const RCP<const VectorBase<Scalar> > &defaultVector
272  )
273 {
274  RCP<const VectorBase<Scalar> >
275  vector = pdmvi.readVector(vName);
276  if (!is_null(vector))
277  return vector;
278  return defaultVector;
279 }
280 
281 
282 // //////////////////////////////////////////
283 // Inline functions
284 
285 template<class Scalar>
286 inline
287 const std::string&
289 {
290  return fileNameBase_;
291 }
292 
293 template<class Scalar>
294 inline
295 const Teuchos::Array<Scalar>&
297 {
298  return explicitArray_;
299 }
300 
301 template<class Scalar>
302 inline
303 Scalar
305 {
306  return scaleBy_;
307 }
308 
309 // //////////////////////////////////////////
310 // Implementations
311 
312 namespace PDMVIUtilityPack {
313 
314 template<class Scalar>
315 void copy(
316  const Teuchos::Array<Scalar> &array
317  ,VectorBase<Scalar> *vec
318  )
319 {
320  using Teuchos::implicit_cast;
321  TEUCHOS_TEST_FOR_EXCEPT(vec==0);
322  DetachedVectorView<Scalar> dVec(*vec);
323  TEUCHOS_TEST_FOR_EXCEPT(implicit_cast<int>(dVec.subDim())!=implicit_cast<int>(array.size())); // ToDo: Give a very good error message!
324  for( Ordinal i = 0; i < dVec.subDim(); ++i ) {
325  dVec[i] = array[i];
326  }
327 }
328 
329 } // namespace PDMVIUtilityPack
330 
331 // Static data members
332 
333 template<class Scalar>
334 const std::string
335 ParameterDrivenMultiVectorInput<Scalar>::FileNameBase_name_ = "File Name Base";
336 template<class Scalar>
337 const std::string
338 ParameterDrivenMultiVectorInput<Scalar>::FileNameBase_default_ = "";
339 
340 template<class Scalar>
341 const std::string
342 ParameterDrivenMultiVectorInput<Scalar>::ExplicitArray_name_ = "Explicit Array";
343 template<class Scalar>
344 const std::string
345 ParameterDrivenMultiVectorInput<Scalar>::ExplicitArray_default_ = "{}";
346 
347 template<class Scalar>
348 const std::string
349 ParameterDrivenMultiVectorInput<Scalar>::ScaleBy_name_ = "Scale By";
350 template<class Scalar>
351 const double
352 ParameterDrivenMultiVectorInput<Scalar>::ScaleBy_default_ = 1.0;
353 
354 template<class Scalar>
355 const std::string
356 ParameterDrivenMultiVectorInput<Scalar>::AddScalar_name_ = "Add Scalar";
357 template<class Scalar>
358 const double
359 ParameterDrivenMultiVectorInput<Scalar>::AddScalar_default_ = 0.0;
360 
361 // Constructors/Initializers
362 
363 template<class Scalar>
365  :fileNameBase_(FileNameBase_default_),
366  scaleBy_(ScaleBy_default_),
367  addScalar_(AddScalar_default_)
368 {}
369 
370 // Overridden from ParameterListAcceptor
371 
372 template<class Scalar>
374  Teuchos::RCP<Teuchos::ParameterList> const& paramList
375  )
376 {
377  TEUCHOS_TEST_FOR_EXCEPT(0==paramList.get());
378  paramList->validateParameters(*getValidParameters());
379  paramList_ = paramList;
380  fileNameBase_ = paramList_->get(
381  FileNameBase_name_,FileNameBase_default_ );
382  explicitArray_ = Teuchos::getArrayFromStringParameter<Scalar>(
383  *paramList_,ExplicitArray_name_
384  ,-1 // An array of any size will do here
385  ,false // The parameter does not need to exist
386  );
387  scaleBy_ = paramList_->get(ScaleBy_name_,ScaleBy_default_);
388  addScalar_ = paramList_->get(AddScalar_name_,AddScalar_default_);
389 #ifdef TEUCHOS_DEBUG
390  paramList_->validateParameters(*getValidParameters(),0);
391 #endif // TEUCHOS_DEBUG
392 }
393 
394 template<class Scalar>
395 Teuchos::RCP<Teuchos::ParameterList>
397 {
398  return paramList_;
399 }
400 
401 template<class Scalar>
402 Teuchos::RCP<Teuchos::ParameterList>
404 {
405  Teuchos::RCP<Teuchos::ParameterList>
406  _paramList = paramList_;
407  paramList_ = Teuchos::null;
408  return _paramList;
409 }
410 
411 template<class Scalar>
412 Teuchos::RCP<const Teuchos::ParameterList>
414 {
415  return paramList_;
416 }
417 
418 template<class Scalar>
419 Teuchos::RCP<const Teuchos::ParameterList>
421 {
422  if(!validParamList_.get()) {
423  Teuchos::RCP<Teuchos::ParameterList>
424  pl = Teuchos::rcp(new Teuchos::ParameterList);
425  pl->set(
426  FileNameBase_name_,FileNameBase_default_
427  ,"Base-name of file(s) that will be used to read in the vector.\n"
428  "If this parameter is empty \"\", no file(s) will be read.\n"
429  "Note that a MultiVectorFileIOBase object and a VectorSpaceBase object\n"
430  "must be set internally for this to work."
431  );
432  pl->set(
433  ExplicitArray_name_,ExplicitArray_default_
434  ,"The vector specified explicitly as a string interpreted as a Teuchos::Array\n"
435  "object. If this array is set, it will override the vector specified\n"
436  "by the above \"" + FileNameBase_name_ + "\" parameter.\n"
437  "Note that a VectorSpaceBase object\n"
438  "must be set internally for this to work."
439  );
440  pl->set(
441  ScaleBy_name_,ScaleBy_default_,
442  "A factor by which the read in vector will be scaled by."
443  );
444  pl->set(
445  AddScalar_name_, AddScalar_default_,
446  "A scalar that will added to the read in vector after it\n"
447  "optionally scaled."
448  );
449  validParamList_ = pl;
450  }
451  return validParamList_;
452 }
453 
454 // (Multi)Vector Readers
455 
456 template<class Scalar>
458  const std::string &mvName
460  ) const
461 {
462  using Teuchos::implicit_cast;
463  TEUCHOS_TEST_FOR_EXCEPT(0==mv);
464  typedef Teuchos::ScalarTraits<Scalar> ST;
465  const Teuchos::EVerbosityLevel verbLevel = this->getVerbLevel();
466  Teuchos::RCP<Teuchos::FancyOStream>
467  out = this->getOStream();
468  const bool trace = ( verbLevel >= implicit_cast<int>(Teuchos::VERB_LOW) );
469  Teuchos::OSTab tab(out);
470  bool vectorWasRead = false;
471  if(fileNameBase_.length()) {
472  if( out.get() && trace )
473  *out << "\nReading \"" << mvName << "\" from the file(s) with base name \""
474  << fileNameBase_ << "\" ...\n";
475  fileIO().readMultiVectorFromFile(fileNameBase_,mv);
476  vectorWasRead = true;
477  }
478  if(explicitArray_.size()) {
479  if( implicit_cast<Ordinal>(explicitArray_.size()) != vecSpc().dim() ) {
480  // Call back to throw an exception with a better erro message!
481  Teuchos::getArrayFromStringParameter<Scalar>(
482  *paramList_,ExplicitArray_name_,vecSpc().dim(),false);
483  TEUCHOS_TEST_FOR_EXCEPT(!"Should never get here!");
484  }
485  if( out.get() && trace )
486  *out << "\nSetting \"" << mvName << "\" directly from the parameter array "
487  << explicitArray_ << " ...\n";
488  TEUCHOS_TEST_FOR_EXCEPTION(
489  mv->domain()->dim()!=implicit_cast<Ordinal>(1), std::logic_error
490  ,"Error! We can not handle reading in multi-vectors directly from"
491  " the parameter list yet!"
492  );
493  PDMVIUtilityPack::copy(explicitArray_,&*mv->col(0));
494  // ToDo: Find a way to read a matrix from a file (perhaps a nested
495  // Array<Array<Scalar> > or something!)
496  vectorWasRead = true;
497  }
498  if( scaleBy_ != ST::one() && vectorWasRead ) {
499  if( out.get() && trace )
500  *out << "\nScaling \"" << mvName << "\" by " << scaleBy_ << " ...\n";
501  Vt_S(Teuchos::ptr(mv), scaleBy_);
502  }
503  if( addScalar_ != ST::zero() && vectorWasRead ) {
504  if( out.get() && trace )
505  *out << "\nAdding scalar " << addScalar_ << " to \"" << mvName << "\" ...\n";
506  Vp_S(Teuchos::ptr(mv), addScalar_);
507  }
508  return vectorWasRead;
509 }
510 
511 template<class Scalar>
513  const std::string &vName
514  ,Teuchos::RCP<Thyra::VectorBase<Scalar> > *v
515  ) const
516 {
517  TEUCHOS_TEST_FOR_EXCEPT(0==v);
518  bool vectorWasRead = false;
519  if( fileNameBase_.length() || explicitArray_.size() ) {
520  if(!(*v).get())
521  (*v) = createMember(this->vecSpc());
522  vectorWasRead = this->readMultiVector(vName, &*(*v));
523  }
524  return vectorWasRead;
525 }
526 
527 template<class Scalar>
528 Teuchos::RCP<Thyra::VectorBase<Scalar> >
530  const std::string &vName
531  ) const
532 {
533  Teuchos::RCP<Thyra::VectorBase<Scalar> > v;
534  const bool vectorWasRead = readVector(vName,&v);
535  if(!vectorWasRead)
536  v = Teuchos::null;
537  return v;
538 }
539 
540 } // namespace Thyra
541 
542 #endif // THYRA_PARAMETER_DRIVEN_MULTI_VECTOR_INPUT_HPP
bool readVector(const std::string &vName, Teuchos::RCP< Thyra::VectorBase< Scalar > > *v) const
Read a Vector as directed by the set parameter sublist, allocating the Vector object if it has not al...
Scalar readinScaleBy() const
Return the value of the parameter "Explicit Array" that was read in from the setParameterList() funct...
RCP< const VectorBase< Scalar > > readVectorOverride(const ParameterDrivenMultiVectorInput< Scalar > &pdmvi, const std::string &vName, const RCP< const VectorBase< Scalar > > &defaultVector)
Read a vector and override if one is read.
const std::string & readinFileNameBase() const
Return the value of the parameter "File Name Base" that was read in from the setParameterList() funct...
const Teuchos::Array< Scalar > & readinExplicitArray() const
Return the value of the parameter "Explicit Array" that was read in from the setParameterList() funct...
Abstract interface for objects that represent a space for vectors.
Concrete utility class that an ANA can use for reading in a (multi)vector as directed by a parameter ...
void setParameterList(Teuchos::RCP< Teuchos::ParameterList > const &paramList)
Teuchos::RCP< Teuchos::ParameterList > getNonconstParameterList()
Teuchos::Ordinal Ordinal
Type for the dimension of a vector space. `*.
Interface for a collection of column vectors called a multi-vector.
Create an explicit mutable (non-const) view of a VectorBase object.
RCP< const VectorBase< Scalar > > col(Ordinal j) const
Calls colImpl().
STANDARD_CONST_COMPOSITION_MEMBERS(VectorSpaceBase< Scalar >, vecSpc)
Set the vector space used to create the (multi)vectors that are read in.
Abstract strategy interface for reading and writing (multi)vector objects to and from files...
Abstract interface for finite-dimensional dense vectors.
Teuchos::RCP< Teuchos::ParameterList > unsetParameterList()
virtual RCP< const VectorSpaceBase< Scalar > > domain() const =0
Return a smart pointer for the domain space for this operator.
Teuchos::RCP< const Teuchos::ParameterList > getValidParameters() const
bool readMultiVector(const std::string &mvName, Thyra::MultiVectorBase< Scalar > *mv) const
Read a MultiVector that has already been allocated, as directed by the set parameter sublist...
Teuchos::RCP< const Teuchos::ParameterList > getParameterList() const
STANDARD_COMPOSITION_MEMBERS(MultiVectorFileIOBase< Scalar >, fileIO)
Set the MultiVectorFileIOBase object that will be used to read the vector from file(s).