Teuchos Package Browser (Single Doxygen Collection) Version of the Day
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 // This library is free software; you can redistribute it and/or modify
00012 // it under the terms of the GNU Lesser General Public License as
00013 // published by the Free Software Foundation; either version 2.1 of the
00014 // License, or (at your option) any later version.
00015 //
00016 // This library is distributed in the hope that it will be useful, but
00017 // WITHOUT ANY WARRANTY; without even the implied warranty of
00018 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00019 // Lesser General Public License for more details.
00020 //
00021 // You should have received a copy of the GNU Lesser General Public
00022 // License along with this library; if not, write to the Free Software
00023 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
00024 // USA
00025 // Questions? Contact Michael A. Heroux (maherou@sandia.gov)
00026 //
00027 // ***********************************************************************
00028 // @HEADER
00029 */
00030 
00031 #include "Teuchos_ParameterList.hpp"
00032 #include "Teuchos_StandardParameterEntryValidators.hpp"
00033 #include "Teuchos_Array.hpp"  
00034 #include "Teuchos_Version.hpp"
00035 
00036 int main(int argc, char* argv[])
00037 {
00038   std::cout << Teuchos::Teuchos_Version() << std::endl << std::endl;
00039 
00040   // Creating an empty parameter list looks like:
00041   Teuchos::ParameterList My_List;
00042 
00043   // Setting parameters in this list can be easily done:
00044   My_List.set("Max Iters", 1550, "Determines the maximum number of iterations in the solver");
00045   My_List.set("Tolerance", 1e-10, "The tolerance used for the convergence check");
00046   
00047   // For the "Solver" option, create a validator that will automatically
00048   // create documentation for this parameter but will also help in validation.
00049   Teuchos::RCP<Teuchos::StringToIntegralParameterEntryValidator<int> >
00050     solverValidator = Teuchos::rcp(
00051       new Teuchos::StringToIntegralParameterEntryValidator<int>(
00052         Teuchos::tuple<std::string>( "GMRES", "CG", "TFQMR" )
00053         ,"Solver"
00054         )
00055       );
00056   My_List.set(
00057     "Solver"
00058     ,"GMRES" // This will be validated by solverValidator right here!
00059     ,"The type of solver to use."
00060     ,solverValidator
00061     );
00062 
00063   /* The templated ``set'' method should cast the input {\it value} to the
00064      correct data type.  However, in the case where the compiler is not casting the input
00065      value to the expected data type, an explicit cast can be used with the ``set'' method:
00066   */
00067   My_List.set("Tolerance", (float)(1e-10), "The tolerance used for the convergence check");
00068 
00069   /* Reference-counted pointers can also be passed through a Teuchos::ParameterList.
00070      To illustrate this we will use the Teuchos::Array class to create an array of 10 doubles
00071      representing an initial guess for a linear solver, whose memory is being managed by a 
00072      Teuchos::RCP.
00073    */
00074 
00075   Teuchos::RCP<Teuchos::Array<double> > rcp_Array = 
00076     Teuchos::rcp( new Teuchos::Array<double>( 10, 0.0 ) );
00077   
00078   My_List.set("Initial Guess", rcp_Array, "The initial guess as a RCP to an array object.");
00079 
00080   /* A hierarchy of parameter lists can be constructed using {\tt Teuchos::ParameterList}.  This 
00081      means another parameter list is a valid {\it value} in any parameter list.  To create a sublist
00082      in a parameter list and obtain a reference to it:
00083   */
00084   Teuchos::ParameterList&
00085     Prec_List = My_List.sublist("Preconditioner",false,"Sublist that defines the preconditioner.");
00086 
00087   // Now this parameter list can be filled with values:
00088   Prec_List.set("Type", "ILU", "The tpye of preconditioner to use");
00089   Prec_List.set("Drop Tolerance", 1e-3
00090                 ,"The tolerance below which entries from the\n""factorization are left out of the factors.");
00091 
00092   // The parameter list can be queried about the existance of a parameter, sublist, or type:
00093   // Has a solver been chosen?
00094   bool solver_defined = false, prec_defined = false, dtol_double = false;
00095   solver_defined = My_List.isParameter("Solver");
00096   // Has a preconditioner been chosen?
00097   prec_defined = My_List.isSublist("Preconditioner"); 
00098   // Has a tolerance been chosen and is it a double-precision number?
00099   bool tol_double = false;
00100   tol_double = My_List.INVALID_TEMPLATE_QUALIFIER isType<double>("Tolerance");
00101   // Has a drop tolerance been chosen and is it a double-precision number?
00102   dtol_double = Teuchos::isParameterType<double>(Prec_List, "Drop Tolerance"); 
00103 
00104   /* The last two methods for checking the parameter type are equivalent.
00105      There is some question as to whether the syntax of the first type-checking
00106      method is acceptable to older compilers.  Thus, the second type-checking method
00107      is offered as a portable alternative.
00108   */
00109   // Parameters can be retrieved from the parameter list in quite a few ways:
00110   // Get method that creates and sets the parameter if it doesn't exist.
00111   int its = 0;
00112   its = My_List.get("Max Iters", 1200);
00113   float tol;
00114   // Get method that retrieves a parameter of a particular type.
00115   tol = My_List.INVALID_TEMPLATE_QUALIFIER get<float>("Tolerance");
00116   // Get the "Solver" value and validate!
00117   std::string
00118     solver = solverValidator->validateString(
00119       Teuchos::getParameter<std::string>(My_List,"Solver")
00120       );
00121 
00122   /* In the above example, the first ``get'' method is a safe way of
00123      obtaining a parameter when its existence is indefinite but required.
00124      The second ``get'' method should be used when the existense of the parameter
00125      is definite.  This method will throw an std::exception if the parameter doesn't exist. 
00126      The safest way to use the second ``get'' method
00127      is in a try/catch block:
00128   */
00129   try {
00130     tol = My_List.INVALID_TEMPLATE_QUALIFIER get<float>("Tolerance");
00131   }
00132   catch ( const std::exception& e) {
00133     tol = 1e-6;
00134   }
00135 
00136   /* The second ``get'' method uses a syntax that may not be
00137      acceptable to older compilers.  Optionally, there is another portable templated 
00138      ``get'' function that can be used in the place of the second ``get'' method:
00139   */
00140   try {
00141     tol = Teuchos::getParameter<float>(My_List, "Tolerance");
00142   }
00143   catch ( const std::exception& e) {
00144     tol = 1e-6;
00145   }
00146 
00147   /* We can use this same syntax to get reference-counted objects out of the parameter
00148      list, like the initial guess.
00149   */
00150   try {
00151     Teuchos::RCP<Teuchos::Array<double> > init_guess = 
00152       Teuchos::getParameter<Teuchos::RCP<Teuchos::Array<double> > >(My_List, "Initial Guess");
00153   }
00154   catch ( std::exception& e) {
00155     std::cout << e.what() << std::endl;
00156   }
00157 
00158   std::cout << "\n# Printing this parameter list using opeator<<(...) ...\n\n";
00159   std::cout << My_List << std::endl;
00160 
00161   std::cout << "\n# Printing the parameter list only showing documentation fields ...\n\n";
00162   My_List.print(std::cout,Teuchos::ParameterList::PrintOptions().showDoc(true).indent(2).showTypes(true)); 
00163 
00164   /* It is important to note that mispelled parameters 
00165      (with additional space characters, capitalizations, etc.) may be ignored.  
00166      Therefore, it is important to be aware that a given parameter has not been used. 
00167      Unused parameters can be printed with method:
00168   */ 
00169   std::cout << "\n# Showing unused parameters ...\n\n";
00170   My_List.unused( std::cout );
00171 
00172   return 0;
00173 }
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines