Teuchos Package Browser (Single Doxygen Collection) Version of the Day
parameterlist/example/ParameterList/cxx_main.cpp
Go to the documentation of this file.
00001 /*
00002 // @HEADER
00003 // ***********************************************************************
00004 //
00005 //                    Teuchos: Common Tools Package
00006 //                 Copyright (2004) Sandia Corporation
00007 //
00008 // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
00009 // license for use of this work by or on behalf of the U.S. Government.
00010 //
00011 // Redistribution and use in source and binary forms, with or without
00012 // modification, are permitted provided that the following conditions are
00013 // met:
00014 //
00015 // 1. Redistributions of source code must retain the above copyright
00016 // notice, this list of conditions and the following disclaimer.
00017 //
00018 // 2. Redistributions in binary form must reproduce the above copyright
00019 // notice, this list of conditions and the following disclaimer in the
00020 // documentation and/or other materials provided with the distribution.
00021 //
00022 // 3. Neither the name of the Corporation nor the names of the
00023 // contributors may be used to endorse or promote products derived from
00024 // this software without specific prior written permission.
00025 //
00026 // THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
00027 // EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00028 // IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00029 // PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
00030 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00031 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00032 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00033 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00034 // LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00035 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00036 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00037 //
00038 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
00039 //
00040 // ***********************************************************************
00041 // @HEADER
00042 */
00043 
00044 #include "Teuchos_ParameterList.hpp"
00045 #include "Teuchos_StandardParameterEntryValidators.hpp"
00046 #include "Teuchos_Array.hpp"  
00047 #include "Teuchos_Version.hpp"
00048 #include "Teuchos_as.hpp"
00049 
00050 int main(int argc, char* argv[])
00051 {
00052 
00053   using Teuchos::ParameterList;
00054   using Teuchos::RCP;
00055   using Teuchos::Array;
00056   using Teuchos::tuple;
00057   using Teuchos::as;
00058 
00059   std::cout << Teuchos::Teuchos_Version() << std::endl << std::endl;
00060 
00061   // Creating an empty parameter list looks like:
00062   ParameterList myPL;
00063 
00064   // Setting parameters in this list can be easily done:
00065   myPL.set("Max Iters", 1550, "Determines the maximum number of iterations in the solver");
00066   myPL.set("Tolerance", 1e-10, "The tolerance used for the convergence check");
00067   
00068   // For the "Solver" option, create a validator that will automatically
00069   // create documentation for this parameter but will also help in validation.
00070   RCP<Teuchos::StringToIntegralParameterEntryValidator<int> >
00071     solverValidator = Teuchos::rcp(
00072       new Teuchos::StringToIntegralParameterEntryValidator<int>(
00073         Teuchos::tuple<std::string>( "GMRES", "CG", "TFQMR" )
00074         ,"Solver"
00075         )
00076       );
00077   myPL.set(
00078     "Solver"
00079     ,"GMRES" // This will be validated by solverValidator right here!
00080     ,"The type of solver to use"
00081     ,solverValidator
00082     );
00083 
00084   /* The templated ``set'' method should cast the input {\it value} to the
00085      correct data type.  However, in the case where the compiler is not casting the input
00086      value to the expected data type, an explicit cast can be used with the ``set'' method:
00087   */
00088   myPL.set("Tolerance", as<float>(1e-10), "The tolerance used for the convergence check");
00089 
00090   /* Reference-counted pointers can also be passed through a ParameterList.
00091      To illustrate this we will use the Array class to create an array of 10 doubles
00092      representing an initial guess for a linear solver, whose memory is being managed by a 
00093      RCP.
00094    */
00095   
00096   myPL.set<Array<double> >("Initial Guess", tuple<double>( 10, 0.0 ),
00097     "The initial guess as a RCP to an array object.");
00098 
00099   /* A hierarchy of parameter lists can be constructed using {\tt ParameterList}.  This 
00100      means another parameter list is a valid {\it value} in any parameter list.  To create a sublist
00101      in a parameter list and obtain a reference to it:
00102   */
00103   ParameterList& Prec_List = myPL.sublist("Preconditioner", false, 
00104     "Sublist that defines the preconditioner.");
00105 
00106   // Now this parameter list can be filled with values:
00107   Prec_List.set("Type", "ILU", "The tpye of preconditioner to use");
00108   Prec_List.set("Drop Tolerance", 1e-3, 
00109     "The tolerance below which entries from the\n""factorization are left out of the factors.");
00110 
00111   // The parameter list can be queried about the existance of a parameter, sublist, or type:
00112   // Has a solver been chosen?
00113   bool solver_defined = false, prec_defined = false, dtol_double = false;
00114   solver_defined = myPL.isParameter("Solver");
00115   TEUCHOS_ASSERT_EQUALITY(solver_defined, true);  
00116   // Has a preconditioner been chosen?
00117   prec_defined = myPL.isSublist("Preconditioner"); 
00118   TEUCHOS_ASSERT_EQUALITY(prec_defined, true);  
00119   // Has a tolerance been chosen and is it a double-precision number?
00120   bool tol_double = false;
00121   tol_double = myPL.INVALID_TEMPLATE_QUALIFIER isType<double>("Tolerance");
00122   TEUCHOS_ASSERT_EQUALITY(tol_double, false); // It is 'float'!
00123   // Has a drop tolerance been chosen and is it a double-precision number?
00124   dtol_double = Teuchos::isParameterType<double>(Prec_List, "Drop Tolerance"); 
00125   TEUCHOS_ASSERT_EQUALITY(dtol_double, true);
00126 
00127   // Parameters can be retrieved from the parameter list in quite a few ways:
00128   // Get method that creates and sets the parameter if it doesn't exist.
00129   int its = -1;
00130   its = myPL.get("Max Iters", 1200);
00131   TEUCHOS_ASSERT_EQUALITY(its, 1550); // Was already ste
00132   // Get method that retrieves a parameter of a particular type that must exist.
00133   float tol = -1.0;
00134   tol = myPL.get<float>("Tolerance");
00135   TEUCHOS_ASSERT_EQUALITY(tol, as<float>(1e-10));
00136   // Get the "Solver" value and validate!
00137   std::string
00138     solver = solverValidator->validateString(
00139       Teuchos::getParameter<std::string>(myPL,"Solver")
00140       );
00141 
00142   // We can use this same syntax to get arrays out, like the initial guess.
00143   Array<double> init_guess = myPL.get<Array<double> >("Initial Guess");
00144 
00145   std::cout << "\n# Printing this parameter list using opeator<<(...) ...\n\n";
00146   std::cout << myPL << std::endl;
00147 
00148   std::cout << "\n# Printing the parameter list only showing documentation fields ...\n\n";
00149   myPL.print(std::cout,
00150     ParameterList::PrintOptions().showDoc(true).indent(2).showTypes(true)); 
00151 
00152   /* It is important to note that mispelled parameters 
00153      (with additional space characters, capitalizations, etc.) may be ignored.  
00154      Therefore, it is important to be aware that a given parameter has not been used. 
00155      Unused parameters can be printed with method:
00156   */ 
00157   std::cout << "\n# Showing unused parameters ...\n\n";
00158   myPL.unused( std::cout );
00159 
00160   return 0;
00161 
00162 }
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines