Teuchos Package Browser (Single Doxygen Collection)  Version of the Day
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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
142  paramList_->validateParameters(*this->getValidParameters());
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
EAlgoType algoType_
Definition: AlgorithmA.hpp:97
Teuchos::RCP< Teuchos::ParameterList > unsetParameterList()
Unset the parameter list that was set using setParameterList().
Definition: AlgorithmA.cpp:155
#define TEUCHOS_OSTAB
T * get() const
Get the raw C++ pointer to the underlying object.
basic_OSTab< char > OSTab
const std::basic_string< char_type, traits_type > & getTabIndentStr() const
Get the tab indent string.
virtual VerboseObjectBase & setLinePrefix(const std::string &linePrefix)
Set line prefix name for this object.
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.
Teuchos::RCP< const Teuchos::ParameterList > getValidParameters() const
Return a ParameterList containing all of the valid parameters that this-&gt;setParameterList(...) will accept, along with any validators.
Definition: AlgorithmA.cpp:171
std::string toString(const HashSet< Key > &h)
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. ...
Teuchos::RCP< const Teuchos::ParameterList > getParameterList() const
Get const version of the parameter list that was set using setParameterList().
Definition: AlgorithmA.cpp:164
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.
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
virtual EVerbosityLevel getVerbLevel() const
Get the verbosity level.
void doAlgorithm()
Definition: AlgorithmA.cpp:199
virtual RCP< FancyOStream > getOStream() const
Return the output stream to be used for out for *this object.
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...