Teuchos Package Browser (Single Doxygen Collection) Version of the Day
example/ParameterList/cxx_main.cpp
Go to the documentation of this file.
00001 /*
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 // ***********************************************************************
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
00052   using Teuchos::ParameterList;
00053   using Teuchos::RCP;
00054   using Teuchos::Array;
00055   using Teuchos::tuple;
00056
00057   std::cout << Teuchos::Teuchos_Version() << std::endl << std::endl;
00058
00059   // Creating an empty parameter list looks like:
00060   ParameterList myPL;
00061
00062   // Setting parameters in this list can be easily done:
00063   myPL.set("Max Iters", 1550, "Determines the maximum number of iterations in the solver");
00064   myPL.set("Tolerance", 1e-10, "The tolerance used for the convergence check");
00065
00066   // For the "Solver" option, create a validator that will automatically
00067   // create documentation for this parameter but will also help in validation.
00068   RCP<Teuchos::StringToIntegralParameterEntryValidator<int> >
00069     solverValidator = Teuchos::rcp(
00070       new Teuchos::StringToIntegralParameterEntryValidator<int>(
00071         Teuchos::tuple<std::string>( "GMRES", "CG", "TFQMR" )
00072         ,"Solver"
00073         )
00074       );
00075   myPL.set(
00076     "Solver"
00077     ,"GMRES" // This will be validated by solverValidator right here!
00078     ,"The type of solver to use"
00079     ,solverValidator
00080     );
00081
00082   /* The templated set'' method should cast the input {\it value} to the
00083      correct data type.  However, in the case where the compiler is not casting the input
00084      value to the expected data type, an explicit cast can be used with the set'' method:
00085   */
00086   myPL.set("Tolerance", (float)(1e-10), "The tolerance used for the convergence check");
00087
00088   /* Reference-counted pointers can also be passed through a ParameterList.
00089      To illustrate this we will use the Array class to create an array of 10 doubles
00090      representing an initial guess for a linear solver, whose memory is being managed by a
00091      RCP.
00092    */
00093
00094   myPL.set<Array<double> >("Initial Guess", tuple<double>( 10, 0.0 ),
00095     "The initial guess as a RCP to an array object.");
00096
00097   /* A hierarchy of parameter lists can be constructed using {\tt ParameterList}.  This
00098      means another parameter list is a valid {\it value} in any parameter list.  To create a sublist
00099      in a parameter list and obtain a reference to it:
00100   */
00101   ParameterList& Prec_List = myPL.sublist("Preconditioner", false,
00102     "Sublist that defines the preconditioner.");
00103
00104   // Now this parameter list can be filled with values:
00105   Prec_List.set("Type", "ILU", "The tpye of preconditioner to use");
00106   Prec_List.set("Drop Tolerance", 1e-3,
00107     "The tolerance below which entries from the\n""factorization are left out of the factors.");
00108
00109   // The parameter list can be queried about the existance of a parameter, sublist, or type:
00110   // Has a solver been chosen?
00111   bool solver_defined = false, prec_defined = false, dtol_double = false;
00112   solver_defined = myPL.isParameter("Solver");
00113   // Has a preconditioner been chosen?
00114   prec_defined = myPL.isSublist("Preconditioner");
00115   // Has a tolerance been chosen and is it a double-precision number?
00116   bool tol_double = false;
00117   tol_double = myPL.INVALID_TEMPLATE_QUALIFIER isType<double>("Tolerance");
00118   // Has a drop tolerance been chosen and is it a double-precision number?
00119   dtol_double = Teuchos::isParameterType<double>(Prec_List, "Drop Tolerance");
00120
00121   // Parameters can be retrieved from the parameter list in quite a few ways:
00122   // Get method that creates and sets the parameter if it doesn't exist.
00123   int its = -1;
00124   its = myPL.get("Max Iters", 1200);
00125   // Get method that retrieves a parameter of a particular type that must exist.
00126   float tol = -1.0;
00127   tol = myPL.get<float>("Tolerance");
00128   // Get the "Solver" value and validate!
00129   std::string
00130     solver = solverValidator->validateString(
00131       Teuchos::getParameter<std::string>(myPL,"Solver")
00132       );
00133
00134   // We can use this same syntax to get arrays out, like the initial guess.
00135   Array<double> init_guess = myPL.get<Array<double> >("Initial Guess");
00136
00137   std::cout << "\n# Printing this parameter list using opeator<<(...) ...\n\n";
00138   std::cout << myPL << std::endl;
00139
00140   std::cout << "\n# Printing the parameter list only showing documentation fields ...\n\n";
00141   myPL.print(std::cout,
00142     ParameterList::PrintOptions().showDoc(true).indent(2).showTypes(true));
00143
00144   /* It is important to note that mispelled parameters
00145      (with additional space characters, capitalizations, etc.) may be ignored.
00146      Therefore, it is important to be aware that a given parameter has not been used.
00147      Unused parameters can be printed with method:
00148   */
00149   std::cout << "\n# Showing unused parameters ...\n\n";
00150   myPL.unused( std::cout );
00151
00152   return 0;
00153
00154 }