Teuchos Package Browser (Single Doxygen Collection)  Version of the Day
AlgorithmA.cpp
Go to the documentation of this file.
1 /*
2 // @HEADER
3 // ***********************************************************************
4 //
5 // Teuchos: Common Tools Package
6 // Copyright (2004) Sandia Corporation
7 //
8 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
9 // license for use of this work by or on behalf of the U.S. Government.
10 //
11 // Redistribution and use in source and binary forms, with or without
12 // modification, are permitted provided that the following conditions are
13 // met:
14 //
15 // 1. Redistributions of source code must retain the above copyright
16 // notice, this list of conditions and the following disclaimer.
17 //
18 // 2. Redistributions in binary form must reproduce the above copyright
19 // notice, this list of conditions and the following disclaimer in the
20 // documentation and/or other materials provided with the distribution.
21 //
22 // 3. Neither the name of the Corporation nor the names of the
23 // contributors may be used to endorse or promote products derived from
24 // this software without specific prior written permission.
25 //
26 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
27 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
29 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
30 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
31 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
32 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
33 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
34 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
35 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
36 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
37 //
38 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
39 //
40 // ***********************************************************************
41 // @HEADER
42 */
43 
44 #include "AlgorithmA.hpp"
47 
48 
49 // This is a typical function that would be present in Trilinos right now what
50 // does not know about FancyOStream and does not derive from VerboseObject.
51 // However, because of the magic of FancyOStream, this output will be indented
52 // correctly!
53 void someDumbFunction( std::ostream &out, const std::string &indentSpacer )
54 {
55  out << "\nEntering someDumbFunction(...)\n";
56  {
57  out << std::endl << indentSpacer << "I am \"dumb\" code that knows nothing of FancyOStream and does indenting manually! ...\n";
58  }
59  out << "\nLeaving someDumbFunction(...)\n";
60  // Note that this output will be indented correctly even through it knows nothing of FancyOStream
61 }
62 
63 // This is a function who's interface was written before there was a
64 // FancyOStream and therefore is written in terms of std::ostream. However,
65 // in this case the implementation has been modifed to use FancyOStream as
66 // shown.
67 void someLessDumbFunction( std::ostream &out_arg )
68 {
69  using Teuchos::OSTab;
70  // Get a FancyOStream from out_arg or create a new one ...
72  out = Teuchos::getFancyOStream(Teuchos::rcp(&out_arg,false));
73  // Do our tab indent and our name.
74  OSTab tab(out,1,"LDUMBALGO");
75  *out << "\nEntering someLessDumbFunction(...)\n";
76  {
77  Teuchos::OSTab(out_arg).o()
78  << std::endl << "I am less \"dumb\" code that knows about FancyOStream but my interface does not support it directly! ...\n";
79  *Teuchos::tab(out)
80  << std::endl << "Another print from this less \"dumb\" code ...\n";
81  }
82  *out << "\nLeaving someLessDumbFunction(...)\n";
83 }
84 
85 
86 namespace {
87 
88 const std::string AlgoType_name = "Algo Type";
89 const std::string AlgoType_default = "Bob";
90 
91 const std::string AlgoTol_name = "Algo Tol";
92 const double AlgoTol_default = 1e-5;
93 
94 } // namespace
95 
96 
97 const std::string AlgorithmA::toString( AlgorithmA::EAlgoType algoType )
98 {
99  switch(algoType) {
100  case ALGO_BOB: return "Bob";
101  case ALGO_JOHN: return "John";
102  case ALGO_HARRY: return "Harry";
103  default: TEUCHOS_TEST_FOR_EXCEPT("Should never get here!");
104  }
105  return ""; // never be called!
106 }
107 
108 
110  : algoType_(ALGO_BOB), algoTol_(AlgoTol_default)
111 {
112  this->setLinePrefix("ALGO_A"); // I tell me who I am for line prefix outputting
113 }
114 
115 
117  Teuchos::RCP<Teuchos::ParameterList> const& paramList
118  )
119 {
120  TEUCHOS_TEST_FOR_EXCEPT(is_null(paramList));
121  // Validate and set the parameter defaults. Here, the parameters are
122  // validated and the state of *this is not changed unless the parameter
123  // validation succeeds. Also, any validators that are defined for various
124  // parameters are passed along so that they can be used in extracting
125  // values!
127  paramList_ = paramList;
128  // Get the enum value for the algorithm type. Here, the actual type stored
129  // for the algorithm type in the parameter list is an std::string but this
130  // helper function does all the work of extracting the validator set in
131  // getValidParameters() and set on *paramList_ through the
132  // validateParametersAndSetDefaults(...) function above!
133  algoType_ = Teuchos::getIntegralValue<EAlgoType>(*paramList_,AlgoType_name);
134  // Get the tolerance for the algorithm. Here, the actual type of the
135  // parameter stored on input could be many different types. Here, I can
136  // just assume that it is a double since it would have been converted to a
137  // double above in validateParametersAndSetDefaults(...).
138  algoTol_ = Teuchos::getParameter<double>(*paramList_,AlgoTol_name);
139  // Read the sublist for verbosity settings.
140  Teuchos::readVerboseObjectSublist(&*paramList_,this);
141 #ifdef TEUCHOS_DEBUG
143 #endif
144 }
145 
146 
149 {
150  return paramList_;
151 }
152 
153 
156 {
159  return paramList;
160 }
161 
162 
165 {
166  return paramList_;
167 }
168 
169 
172 {
174  using Teuchos::setStringToIntegralParameter;
175  using Teuchos::tuple;
176  static RCP<const ParameterList> validParams;
177  if (is_null(validParams)) {
178  RCP<ParameterList>
179  pl = Teuchos::rcp(new ParameterList("AlgorithmA"));
180  setStringToIntegralParameter<EAlgoType>(
181  AlgoType_name, AlgoType_default,
182  "The algorithm type to use",
183  tuple<std::string>("Bob", "John", "Harry"),
184  tuple<EAlgoType>(ALGO_BOB, ALGO_JOHN, ALGO_HARRY),
185  &*pl
186  );
187  Teuchos::setDoubleParameter(
188  AlgoTol_name, AlgoTol_default,
189  "The tolerance for the algorithm.",
190  &*pl
191  );
192  Teuchos::setupVerboseObjectSublist(&*pl);
193  validParams = pl;
194  }
195  return validParams;
196 }
197 
198 
200 {
201  using Teuchos::OSTab;
202  // Get the verbosity that we are going to use
203  Teuchos::EVerbosityLevel verbLevel = this->getVerbLevel();
204  // Here I grab the stream that I will use for outputting. It is a good
205  // idea to grab the RCP to this object just to be safe.
207  // Here I set my line prefix and a single indent. The convention will
208  // be that a called function will set its own indent. This convention makes
209  // the most sense.
210  OSTab tab = this->getOSTab(); // This sets the line prefix and adds one tab
211  if(out.get() && includesVerbLevel(verbLevel,Teuchos::VERB_LOW,true))
212  *out << "\nEntering AlgorithmA::doAlgorithm() with verbLevel="<<Teuchos::toString(verbLevel)<<"\n";
213  {
214  // Here I use a simple macro for the typical case of one tab indent to
215  // save typing. The idea is that this should be as easy to write as
216  // OSTab tab; but is more general.
218  if(out.get() && includesVerbLevel(verbLevel,Teuchos::VERB_LOW,true))
219  *out
220  << "\nI am \"smart\" code that knows about FancyOStream and OSTab ...\n"
221  << "\nDoing algorithm of type \""<<toString(algoType_)<<"\""
222  << "\nUsing tolerance of " << algoTol_ << "\n";
223  {
224  // Here I temporaraly turn off tabbing so that I can print an imporant warning message.
225  OSTab tab2 = this->getOSTab(OSTab::DISABLE_TABBING);
226  if(out.get() && includesVerbLevel(verbLevel,Teuchos::VERB_LOW,true))
227  *out << "\n***\n*** Warning, I am doing something very dangerous so watch out!!!\n***\n";
228  }
229  if(out.get() && includesVerbLevel(verbLevel,Teuchos::VERB_LOW,true))
230  *out << "\nHere I am doing some more stuff and printing with indenting turned back on!\n";
231  {
232  // Here I am going to be calling a dumb piece of code that does not
233  // know about the FancyOStream system and will not use tabs or
234  // anything like that. There is a lot of code in Trilinos that
235  // falls in this category. The first thing I do is manually indent
236  // the stream one tab and set a line prefix for the dumb code since
237  // it may not do this itself.
238  OSTab tab2 = this->getOSTab(1,"DUMBALGO");
239  // Now a Pass in the updated FancyOStream object, which is properly
240  // indented now, through the std::ostream interface. I also pass in
241  // the std::string that is being used for creating tabs. The output from
242  // this function will be indented correctly without the dumb code
243  // knowing it!
244  someDumbFunction(*out,out->getTabIndentStr());
245  }
246  // Here I am calling a less dumb piece of code who's interface does
247  // not support FancyOStream but the implementation does. Note that
248  // this function also follows the convention of doing an initial
249  // indent.
250  someLessDumbFunction(*out);
251  }
252  if(out.get() && includesVerbLevel(verbLevel,Teuchos::VERB_LOW,true))
253  *out << "\nLeaving AlgorithmA::doAlgorithm()\n";
254 }
EVerbosityLevel
Verbosity level.
bool is_null(const boost::shared_ptr< T > &p)
Returns true if p.get()==NULL.
Generate only a minimal amount of output.
void setParameterList(Teuchos::RCP< Teuchos::ParameterList > const &paramList)
Set parameters from a parameter list and return with default values.
Definition: AlgorithmA.cpp:116
virtual OSTab getOSTab(const int tabs=1, const std::string &linePrefix="") const
Create a tab object which sets the number of tabs and optionally the line prefix. ...
EAlgoType algoType_
Definition: AlgorithmA.hpp:97
Teuchos::RCP< Teuchos::ParameterList > unsetParameterList()
Unset the parameter list that was set using setParameterList().
Definition: AlgorithmA.cpp:155
virtual EVerbosityLevel getVerbLevel() const
Get the verbosity level.
#define TEUCHOS_OSTAB
virtual RCP< FancyOStream > getOStream() const
Return the output stream to be used for out for *this object.
const std::basic_string< char_type, traits_type > & getTabIndentStr() const
Get the tab indent string.
basic_OSTab< char > OSTab
T * get() const
Get the raw C++ pointer to the underlying object.
virtual VerboseObjectBase & setLinePrefix(const std::string &linePrefix)
Set line prefix name for this object.
void validateParameters(ParameterList const &validParamList, int const depth=1000, EValidateUsed const validateUsed=VALIDATE_USED_ENABLED, EValidateDefaults const validateDefaults=VALIDATE_DEFAULTS_ENABLED) const
Validate the parameters in this list given valid selections in the input list.
void someDumbFunction(std::ostream &out, const std::string &indentSpacer)
Definition: AlgorithmA.cpp:53
TEUCHOS_DEPRECATED RCP< T > rcp(T *p, Dealloc_T dealloc, bool owns_mem)
Deprecated.
std::string toString(const HashSet< Key > &h)
void validateParametersAndSetDefaults(ParameterList const &validParamList, int const depth=1000)
Validate the parameters in this list given valid selections in the input list and set defaults for th...
A list of parameters of arbitrary type.
TEUCHOSCORE_LIB_DLL_EXPORT bool includesVerbLevel(const EVerbosityLevel verbLevel, const EVerbosityLevel requestedVerbLevel, const bool isDefaultLevel=false)
Return true if the verbosity level includes the given level.
static const std::string toString(AlgorithmA::EAlgoType algoType)
Definition: AlgorithmA.cpp:97
double algoTol_
Definition: AlgorithmA.hpp:98
void someLessDumbFunction(std::ostream &out_arg)
Definition: AlgorithmA.cpp:67
Smart reference counting pointer class for automatic garbage collection.
Teuchos::RCP< const Teuchos::ParameterList > getParameterList() const
Get const version of the parameter list that was set using setParameterList().
Definition: AlgorithmA.cpp:164
RCP< basic_FancyOStream< CharT, Traits > > tab(const RCP< basic_FancyOStream< CharT, Traits > > &out, const int tabs=1, const std::basic_string< CharT, Traits > linePrefix="")
Create a tab for an RCP-wrapped basic_FancyOStream object to cause the indentation of all output auto...
Teuchos::RCP< Teuchos::ParameterList > paramList_
Definition: AlgorithmA.hpp:96
void doAlgorithm()
Definition: AlgorithmA.cpp:199
Teuchos::RCP< Teuchos::ParameterList > getNonconstParameterList()
Get a nonconst version of the parameter list that was set using setParameterList().
Definition: AlgorithmA.cpp:148
#define TEUCHOS_TEST_FOR_EXCEPT(throw_exception_test)
This macro is designed to be a short version of TEUCHOS_TEST_FOR_EXCEPTION() that is easier to call...
Teuchos::RCP< const Teuchos::ParameterList > getValidParameters() const
Return a ParameterList containing all of the valid parameters that this->setParameterList(...) will accept, along with any validators.
Definition: AlgorithmA.cpp:171