ParameterList/cxx_main.cpp

This is an example of how to use the Teuchos::ParameterList class.

00001 #include "Teuchos_ParameterList.hpp"
00002 #include "Teuchos_StandardParameterEntryValidators.hpp"
00003 #include "Teuchos_Array.hpp"  
00004 #include "Teuchos_Version.hpp"
00005 
00006 int main(int argc, char* argv[])
00007 {
00008   std::cout << Teuchos::Teuchos_Version() << std::endl << std::endl;
00009 
00010   // Creating an empty parameter list looks like:
00011   Teuchos::ParameterList My_List;
00012 
00013   // Setting parameters in this list can be easily done:
00014   My_List.set("Max Iters", 1550, "Determines the maximum number of iterations in the solver");
00015   My_List.set("Tolerance", 1e-10, "The tolerance used for the convergence check");
00016   
00017   // For the "Solver" option, create a validator that will automatically
00018   // create documentation for this parameter but will also help in validation.
00019   Teuchos::RCP<Teuchos::StringToIntegralParameterEntryValidator<int> >
00020     solverValidator = Teuchos::rcp(
00021       new Teuchos::StringToIntegralParameterEntryValidator<int>(
00022         Teuchos::tuple<std::string>( "GMRES", "CG", "TFQMR" )
00023         ,"Solver"
00024         )
00025       );
00026   My_List.set(
00027     "Solver"
00028     ,"GMRES" // This will be validated by solverValidator right here!
00029     ,"The type of solver to use."
00030     ,solverValidator
00031     );
00032 
00033   /* The templated ``set'' method should cast the input {\it value} to the
00034      correct data type.  However, in the case where the compiler is not casting the input
00035      value to the expected data type, an explicit cast can be used with the ``set'' method:
00036   */
00037   My_List.set("Tolerance", (float)(1e-10), "The tolerance used for the convergence check");
00038 
00039   /* Reference-counted pointers can also be passed through a Teuchos::ParameterList.
00040      To illustrate this we will use the Teuchos::Array class to create an array of 10 doubles
00041      representing an initial guess for a linear solver, whose memory is being managed by a 
00042      Teuchos::RCP.
00043    */
00044 
00045   Teuchos::RCP<Teuchos::Array<double> > rcp_Array = 
00046     Teuchos::rcp( new Teuchos::Array<double>( 10, 0.0 ) );
00047   
00048   My_List.set("Initial Guess", rcp_Array, "The initial guess as a RCP to an array object.");
00049 
00050   /* A hierarchy of parameter lists can be constructed using {\tt Teuchos::ParameterList}.  This 
00051      means another parameter list is a valid {\it value} in any parameter list.  To create a sublist
00052      in a parameter list and obtain a reference to it:
00053   */
00054   Teuchos::ParameterList&
00055     Prec_List = My_List.sublist("Preconditioner",false,"Sublist that defines the preconditioner.");
00056 
00057   // Now this parameter list can be filled with values:
00058   Prec_List.set("Type", "ILU", "The tpye of preconditioner to use");
00059   Prec_List.set("Drop Tolerance", 1e-3
00060                 ,"The tolerance below which entries from the\n""factorization are left out of the factors.");
00061 
00062   // The parameter list can be queried about the existance of a parameter, sublist, or type:
00063   // Has a solver been chosen?
00064   bool solver_defined = false, prec_defined = false, dtol_double = false;
00065   solver_defined = My_List.isParameter("Solver");
00066   // Has a preconditioner been chosen?
00067   prec_defined = My_List.isSublist("Preconditioner"); 
00068   // Has a tolerance been chosen and is it a double-precision number?
00069   bool tol_double = false;
00070   tol_double = My_List.INVALID_TEMPLATE_QUALIFIER isType<double>("Tolerance");
00071   // Has a drop tolerance been chosen and is it a double-precision number?
00072   dtol_double = Teuchos::isParameterType<double>(Prec_List, "Drop Tolerance"); 
00073 
00074   /* The last two methods for checking the parameter type are equivalent.
00075      There is some question as to whether the syntax of the first type-checking
00076      method is acceptable to older compilers.  Thus, the second type-checking method
00077      is offered as a portable alternative.
00078   */
00079   // Parameters can be retrieved from the parameter list in quite a few ways:
00080   // Get method that creates and sets the parameter if it doesn't exist.
00081   int its = 0;
00082   its = My_List.get("Max Iters", 1200);
00083   float tol;
00084   // Get method that retrieves a parameter of a particular type.
00085   tol = My_List.INVALID_TEMPLATE_QUALIFIER get<float>("Tolerance");
00086   // Get the "Solver" value and validate!
00087   std::string
00088     solver = solverValidator->validateString(
00089       Teuchos::getParameter<std::string>(My_List,"Solver")
00090       );
00091 
00092   /* In the above example, the first ``get'' method is a safe way of
00093      obtaining a parameter when its existence is indefinite but required.
00094      The second ``get'' method should be used when the existense of the parameter
00095      is definite.  This method will throw an std::exception if the parameter doesn't exist. 
00096      The safest way to use the second ``get'' method
00097      is in a try/catch block:
00098   */
00099   try {
00100     tol = My_List.INVALID_TEMPLATE_QUALIFIER get<float>("Tolerance");
00101   }
00102   catch ( const std::exception& e) {
00103     tol = 1e-6;
00104   }
00105 
00106   /* The second ``get'' method uses a syntax that may not be
00107      acceptable to older compilers.  Optionally, there is another portable templated 
00108      ``get'' function that can be used in the place of the second ``get'' method:
00109   */
00110   try {
00111     tol = Teuchos::getParameter<float>(My_List, "Tolerance");
00112   }
00113   catch ( const std::exception& e) {
00114     tol = 1e-6;
00115   }
00116 
00117   /* We can use this same syntax to get reference-counted objects out of the parameter
00118      list, like the initial guess.
00119   */
00120   try {
00121     Teuchos::RCP<Teuchos::Array<double> > init_guess = 
00122       Teuchos::getParameter<Teuchos::RCP<Teuchos::Array<double> > >(My_List, "Initial Guess");
00123   }
00124   catch ( std::exception& e) {
00125     std::cout << e.what() << std::endl;
00126   }
00127 
00128   std::cout << "\n# Printing this parameter list using opeator<<(...) ...\n\n";
00129   std::cout << My_List << std::endl;
00130 
00131   std::cout << "\n# Printing the parameter list only showing documentation fields ...\n\n";
00132   My_List.print(std::cout,Teuchos::ParameterList::PrintOptions().showDoc(true).indent(2).showTypes(true)); 
00133 
00134   /* It is important to note that mispelled parameters 
00135      (with additional space characters, capitalizations, etc.) may be ignored.  
00136      Therefore, it is important to be aware that a given parameter has not been used. 
00137      Unused parameters can be printed with method:
00138   */ 
00139   std::cout << "\n# Showing unused parameters ...\n\n";
00140   My_List.unused( std::cout );
00141 
00142   return 0;
00143 }

Generated on Tue Jul 13 09:22:58 2010 for Teuchos - Trilinos Tools Package by  doxygen 1.4.7