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 // 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 
00049 int main(int argc, char* argv[])
00050 {
00051   std::cout << Teuchos::Teuchos_Version() << std::endl << std::endl;
00052 
00053   // Creating an empty parameter list looks like:
00054   Teuchos::ParameterList My_List;
00055 
00056   // Setting parameters in this list can be easily done:
00057   My_List.set("Max Iters", 1550, "Determines the maximum number of iterations in the solver");
00058   My_List.set("Tolerance", 1e-10, "The tolerance used for the convergence check");
00059   
00060   // For the "Solver" option, create a validator that will automatically
00061   // create documentation for this parameter but will also help in validation.
00062   Teuchos::RCP<Teuchos::StringToIntegralParameterEntryValidator<int> >
00063     solverValidator = Teuchos::rcp(
00064       new Teuchos::StringToIntegralParameterEntryValidator<int>(
00065         Teuchos::tuple<std::string>( "GMRES", "CG", "TFQMR" )
00066         ,"Solver"
00067         )
00068       );
00069   My_List.set(
00070     "Solver"
00071     ,"GMRES" // This will be validated by solverValidator right here!
00072     ,"The type of solver to use."
00073     ,solverValidator
00074     );
00075 
00076   /* The templated ``set'' method should cast the input {\it value} to the
00077      correct data type.  However, in the case where the compiler is not casting the input
00078      value to the expected data type, an explicit cast can be used with the ``set'' method:
00079   */
00080   My_List.set("Tolerance", (float)(1e-10), "The tolerance used for the convergence check");
00081 
00082   /* Reference-counted pointers can also be passed through a Teuchos::ParameterList.
00083      To illustrate this we will use the Teuchos::Array class to create an array of 10 doubles
00084      representing an initial guess for a linear solver, whose memory is being managed by a 
00085      Teuchos::RCP.
00086    */
00087 
00088   Teuchos::RCP<Teuchos::Array<double> > rcp_Array = 
00089     Teuchos::rcp( new Teuchos::Array<double>( 10, 0.0 ) );
00090   
00091   My_List.set("Initial Guess", rcp_Array, "The initial guess as a RCP to an array object.");
00092 
00093   /* A hierarchy of parameter lists can be constructed using {\tt Teuchos::ParameterList}.  This 
00094      means another parameter list is a valid {\it value} in any parameter list.  To create a sublist
00095      in a parameter list and obtain a reference to it:
00096   */
00097   Teuchos::ParameterList&
00098     Prec_List = My_List.sublist("Preconditioner",false,"Sublist that defines the preconditioner.");
00099 
00100   // Now this parameter list can be filled with values:
00101   Prec_List.set("Type", "ILU", "The tpye of preconditioner to use");
00102   Prec_List.set("Drop Tolerance", 1e-3
00103                 ,"The tolerance below which entries from the\n""factorization are left out of the factors.");
00104 
00105   // The parameter list can be queried about the existance of a parameter, sublist, or type:
00106   // Has a solver been chosen?
00107   bool solver_defined = false, prec_defined = false, dtol_double = false;
00108   solver_defined = My_List.isParameter("Solver");
00109   // Has a preconditioner been chosen?
00110   prec_defined = My_List.isSublist("Preconditioner"); 
00111   // Has a tolerance been chosen and is it a double-precision number?
00112   bool tol_double = false;
00113   tol_double = My_List.INVALID_TEMPLATE_QUALIFIER isType<double>("Tolerance");
00114   // Has a drop tolerance been chosen and is it a double-precision number?
00115   dtol_double = Teuchos::isParameterType<double>(Prec_List, "Drop Tolerance"); 
00116 
00117   /* The last two methods for checking the parameter type are equivalent.
00118      There is some question as to whether the syntax of the first type-checking
00119      method is acceptable to older compilers.  Thus, the second type-checking method
00120      is offered as a portable alternative.
00121   */
00122   // Parameters can be retrieved from the parameter list in quite a few ways:
00123   // Get method that creates and sets the parameter if it doesn't exist.
00124   int its = 0;
00125   its = My_List.get("Max Iters", 1200);
00126   float tol;
00127   // Get method that retrieves a parameter of a particular type.
00128   tol = My_List.INVALID_TEMPLATE_QUALIFIER get<float>("Tolerance");
00129   // Get the "Solver" value and validate!
00130   std::string
00131     solver = solverValidator->validateString(
00132       Teuchos::getParameter<std::string>(My_List,"Solver")
00133       );
00134 
00135   /* In the above example, the first ``get'' method is a safe way of
00136      obtaining a parameter when its existence is indefinite but required.
00137      The second ``get'' method should be used when the existense of the parameter
00138      is definite.  This method will throw an std::exception if the parameter doesn't exist. 
00139      The safest way to use the second ``get'' method
00140      is in a try/catch block:
00141   */
00142   try {
00143     tol = My_List.INVALID_TEMPLATE_QUALIFIER get<float>("Tolerance");
00144   }
00145   catch ( const std::exception& e) {
00146     tol = 1e-6;
00147   }
00148 
00149   /* The second ``get'' method uses a syntax that may not be
00150      acceptable to older compilers.  Optionally, there is another portable templated 
00151      ``get'' function that can be used in the place of the second ``get'' method:
00152   */
00153   try {
00154     tol = Teuchos::getParameter<float>(My_List, "Tolerance");
00155   }
00156   catch ( const std::exception& e) {
00157     tol = 1e-6;
00158   }
00159 
00160   /* We can use this same syntax to get reference-counted objects out of the parameter
00161      list, like the initial guess.
00162   */
00163   try {
00164     Teuchos::RCP<Teuchos::Array<double> > init_guess = 
00165       Teuchos::getParameter<Teuchos::RCP<Teuchos::Array<double> > >(My_List, "Initial Guess");
00166   }
00167   catch ( std::exception& e) {
00168     std::cout << e.what() << std::endl;
00169   }
00170 
00171   std::cout << "\n# Printing this parameter list using opeator<<(...) ...\n\n";
00172   std::cout << My_List << std::endl;
00173 
00174   std::cout << "\n# Printing the parameter list only showing documentation fields ...\n\n";
00175   My_List.print(std::cout,Teuchos::ParameterList::PrintOptions().showDoc(true).indent(2).showTypes(true)); 
00176 
00177   /* It is important to note that mispelled parameters 
00178      (with additional space characters, capitalizations, etc.) may be ignored.  
00179      Therefore, it is important to be aware that a given parameter has not been used. 
00180      Unused parameters can be printed with method:
00181   */ 
00182   std::cout << "\n# Showing unused parameters ...\n\n";
00183   My_List.unused( std::cout );
00184 
00185   return 0;
00186 }
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines