From: schrage Date: Wed, 21 Jul 1999 14:33:34 +0000 (+0000) Subject: Rewritten + extended. X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0bfff79c30782a192b9bf346030901e70507c77b;p=dealii-svn.git Rewritten + extended. git-svn-id: https://svn.dealii.org/trunk@1616 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/doc/tutorial/chapter-1.elements/parameters.html b/deal.II/doc/tutorial/chapter-1.elements/parameters.html index c760ef6440..f442255c32 100644 --- a/deal.II/doc/tutorial/chapter-1.elements/parameters.html +++ b/deal.II/doc/tutorial/chapter-1.elements/parameters.html @@ -1,4 +1,3 @@ - @@ -23,15 +22,18 @@

When writing a numerical program you will usually wish to keep it flexible with regard to parameter settings and the like. Rewriting a program -everytime a parameter changes is ever so annoying. +every time a parameter changes is ever so annoying. For this reason deal.II provides a class called ParameterHandler. This class enables you to easily parse a parameter file and extract the values of the parameters. The names and allowed values of the parameters can be defined by you.

+

Introducing parameters into your code

+ +

Introduction - the most simple case

-The way to using runtime parameters in your program is the following: +The most simple way to using runtime parameters in your program is the following:

@@ -58,113 +60,241 @@ The way to using runtime parameters in your program is the following: + + + + + + + + + + + + + + + + + + + +
ParameterHandler prm;
3.Tell the parameter handler about the parameters, their types and their + default values. Here we get one parameter called + "My favourite booze", its default value is + "Stout" and we allow anything as its value. Note that + the parameter name may contain whitespace. + prm.declare_entry("My favourite booze", + "Stout",Patterns::Anything()); + +
4.Generate a parameter file. Following the example above, we + set "My favourite booze" to "Ale". This + file will be called "parameters.in". + set My favourite booze = Ale +
5.Read the parameters from the file. + prm.read_input("parameters.in"); +
6.Find the values of your parameters. + string booze = prm.get("My favourite booze"); +
+

+The few steps outlined above are indeed the most simple case. What, now, if +you have a more complex set of parameters, grouped by purpose ? You could, +for example, wish to solve different equations and set parameters for each +of them. For this purpose you can introduce subsections into +your parameter set. +

+ +

Subsections

+ +

+Parameters declared in different subsections are distinct, although they +may share the same name. Let us stay with the example of two equations +for which you wish to set parameters: Zeldovich-equation and +Sunyaev-equation. You want to be able to use different solvers, +and thus both take a parameter called Solver. +The way to go is to declare two subsections called (preferably) +Zeldovich-equation and Sunyaev-equation. Each of the two +subsections contains a parameter called Solver. +

+

Example: -We enable a program, that is, the class TestCases that really handles -everything to read parameters from a file given on the command line. -Everything that is not strictly relevant to parameter input has been cut out. +We declare subsections for two equations called +Zeldovich-equation and Sunyaev-equation +within a parameter handler. +The allowed values for the parameter Solver are +CG (default) and GMRES. Afterwards +we read the settings from a file called "parameters.in" +and retrieve their values. The values are stored in the strings +zeldovich_solver and sunyaev_solver. +Please note that in order to stick to the essentials this example +violates the + +recommended style for parameter declaration.

-
 
+
 
 
-#include <base/parameter_handler.h>
+// We declare a parameter handler
 
+ParameterHandler prm;
 
-#include <fstream>
-#include <cmath>
-#include <cstdlib>
+// We declare the first subsection and its entry
 
+prm.enter_subsection("Zeldovich-equation")
+prm.declare_entry("Solver","CG",Patterns::Sequence("CG|GMRES"));
+prm.leave_subsection();
 
+// We declare the second subsection and its entry
 
-template <int dim>
-class TestCases : public MultipleParameterLoop::UserClass{
-  public:
-    TestCases ();
-    
-    virtual void declare_parameters (ParameterHandler &prm);
-    virtual void run (ParameterHandler &prm);
+prm.enter_subsection("Sunyaev-equation")
+prm.declare_entry("Solver","CG",Patterns::Sequence("CG|GMRES"));
+prm.leave_subsection();
 
-};
+// The input file is read
 
+prm.read_input("parameters.in"
 
+// We retrieve the parameters from the first subsection
 
-template <int dim>
-TestCases<dim>::TestCases () :
-		{};
+prm.enter_subsection("Zeldovich-equation")
+string zeldovich_solver = prm.get("Solver");
+prm.leave_subsection();
 
+// We retrieve the parameters from the second subsection
 
+prm.enter_subsection("Sunyaev-equation")
+string sunyaev_solver = prm.get("Solver");
+prm.leave_subsection();
+
+
-template <int dim> -void TestCases<dim>::declare_parameters (ParameterHandler &prm) { - if (dim>=2) - prm.declare_entry ("Test run", "zoom in", - Patterns::Sequence("zoom in|ball|curved line|random")); - else - prm.declare_entry ("Test run", "zoom in", - Patterns::Sequence("zoom in|random")); - prm.declare_entry ("Grid file", "grid.1"); - prm.declare_entry ("Sparsity file", "sparsity.1"); - prm.declare_entry ("Condensed sparsity file", "sparsity.c.1"); -}; +

We continue this example with a sample parameter +file that tells the code to solve the Zeldovich equation using GMRES +and the Sunyaev equation using CG. +

+
+
+subsection Zeldovich-equation
+  set Solver = GMRES
+end
 
+subsection Sunyaev-equation
+  set Solver = CG
+end
+
+
-template <int dim> -void TestCases<dim>::run (ParameterHandler &prm) { - cout << "Test case = " << prm.get ("Test run") << endl - << endl; - - cout << " Making grid..." << endl; +

+There are, as we have seen, two methods within the +ParameterHandler class handling subsections:
+ +void ParameterHandler::enter_subsection(const string &subsection) +
+and
+ +bool ParameterHandler::leave_subsection() +
+Their names are telling. First you enter a subsection, then you declare +(or retrieve) +all the parameters for this subsection and finally you leave it. +Subsections may be nested, i.e. you are at liberty to declare +subsections within subsections within subsections... +

- string test = prm.get ("Test run"); - unsigned int test_case; - if (test=="zoom in") test_case = 1; - else - if (test=="ball") test_case = 2; - else - if (test=="curved line") test_case = 3; - else - if (test=="random") test_case = 4; - else - cerr << "This test seems not to be implemented!" << endl; - - - switch (test_case) - { - case 1: // code for case 1: zoom in - case 2: // code for case 2: ball - case 3: // code for case 3: curved line - case 4: // code for case 4: random - }; +

Parameter types and pattern matching

- cout << " Writing grid..." << endl; - ofstream out(prm.get("Grid file").c_str()); - // code for output +

+The parameter handler allows you to specify that any parameter +be of a distinct type. +Upon reading a file the value of this +parameter is checked against the type and an exception is thrown +if they do not match. An exception is also thrown if the default +parameter if the default parameter does not match the specified type. +Below we show a list of the types available. The first column +gives an explanation, the second lists the corresponding C++ type +and the third column shows how to use this type in deal.II. +Parameter values may not contain linebreaks. +deal.II always gets passed a pointer to a class +handling that type. Those classes are defined in a structure +called Patterns. The include file to be used is the +same as for the ParameterHandler class. +

-}; + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Parameter types
Type + Correspondig C++ type + deal.II type +
Integer number.int + Patterns::Integer() +
Floating point number of double length.double + Patterns::Double() +
One member of a set.enum + Patterns::Sequence("element 1|element 2|...") +
An arbitrary string.string + Patterns::Anything() +
+

Allowed characters

-int main (int argc, char **argv) { - if (argc!=2) - { - cout << "Usage: grid_test parameterfile" << endl << endl; - return 1; - }; +

+Neither the names nor the values of entries may contain the +following characters:
+\ { } |
+

- TestCases<2> tests; - class MultipleParameterLoop input_data; //needs at least gcc2.8 +

+Besides, entries may not contain linebreaks, i.e. entries may not span +multiple lines. +

+ +

+Leading and trailing whitespace is ignored and multiple whitespace is +condensed into one. Entry or subsection +declarations in your code should therefore +not contain multiple whitespace, which will not be recognized. +

+ +

Different input sources

+ +

+

+ +

Parameter output

+ +

+

- tests.declare_parameters(input_data); - input_data.read_input (argv[1]); - input_data.loop (tests); - - return 0; -}; - -