]> https://gitweb.dealii.org/ - dealii-svn.git/commitdiff
Augment ParameterHandler documentation.
authorbangerth <bangerth@0785d39b-7218-0410-832d-ea1e28bc413d>
Thu, 9 Sep 2010 02:25:16 +0000 (02:25 +0000)
committerbangerth <bangerth@0785d39b-7218-0410-832d-ea1e28bc413d>
Thu, 9 Sep 2010 02:25:16 +0000 (02:25 +0000)
git-svn-id: https://svn.dealii.org/trunk@21900 0785d39b-7218-0410-832d-ea1e28bc413d

deal.II/base/include/base/parameter_handler.h
deal.II/doc/doxygen/images/parameter_handler.fig [new file with mode: 0644]
deal.II/doc/doxygen/images/parameter_handler.png [new file with mode: 0644]
deal.II/doc/doxygen/images/parameter_handler_background.png [new file with mode: 0644]

index 10a5bafefefbd626f29eb3fa3a5fcf40ee8c55fe..c9c48367d34054a43f2539a904a858ffa63ca4f3 100644 (file)
@@ -824,14 +824,16 @@ namespace Patterns
  *
  *     void LinEq::declare_parameters (ParameterHandler &prm) {
  *       prm.enter_subsection("Linear solver");
- *       prm.declare_entry ("Solver",
- *                          "CG",
- *                         Patterns::Selection("CG|GMRES|GaussElim"),
- *                         "Name of a linear solver for the inner iteration");
- *       prm.declare_entry ("Maximum number of iterations",
- *                          "20",
- *                         ParameterHandler::RegularExpressions::Integer());
- *       ...
+ *       {
+ *         prm.declare_entry ("Solver",
+ *                            "CG",
+ *                           Patterns::Selection("CG|GMRES|GaussElim"),
+ *                           "Name of a linear solver for the inner iteration");
+ *         prm.declare_entry ("Maximum number of iterations",
+ *                            "20",
+ *                           ParameterHandler::RegularExpressions::Integer());
+ *         ...
+ *       }
  *       prm.leave_subsection ();
  *     }
  *   @endcode
@@ -842,10 +844,12 @@ namespace Patterns
  *   @code
  *     void NonLinEq::declare_parameters (ParameterHandler &prm) {
  *       prm.enter_subsection ("Nonlinear solver");
- *       prm.declare_entry ("Nonlinear method",
- *                          "Newton-Raphson",
- *                         ParameterHandler::RegularExpressions::Anything());
- *       eq.declare_parameters (prm);
+ *       {
+ *         prm.declare_entry ("Nonlinear method",
+ *                            "Newton-Raphson",
+ *                           ParameterHandler::RegularExpressions::Anything());
+ *         eq.declare_parameters (prm);
+ *       }
  *       prm.leave_subsection ();
  *     }
  *   @endcode
@@ -862,13 +866,19 @@ namespace Patterns
  *   @code
  *     void NonLinEq::declare_parameters (ParameterHandler &prm) {
  *       prm.enter_subsection ("Nonlinear solver");
- *       prm.enter_subsection ("Linear solver 1");
- *       eq1.declare_parameters (prm);
- *       prm.leave_subsection ();
- *
- *       prm.enter_subsection ("Linear solver 2");
- *       eq2.declare_parameters (prm);
- *       prm.leave_subsection ();
+ *       {
+ *         prm.enter_subsection ("Linear solver 1");
+ *         {
+ *           eq1.declare_parameters (prm);
+ *         }
+ *         prm.leave_subsection ();
+ *
+ *         prm.enter_subsection ("Linear solver 2");
+ *         {
+ *           eq2.declare_parameters (prm);
+ *         }
+ *         prm.leave_subsection ();
+ *       }
  *       prm.leave_subsection ();
  *     }
  *   @endcode
@@ -1208,13 +1218,83 @@ namespace Patterns
  *                Matrix1=Sparse, Matrix2=Full
  *   @endverbatim
  *
- *   <h3>References</h3>
  *
- *   This class is inspired by the <tt>MenuSystem</tt> class of <tt>DiffPack</tt>.
  *
- *   @ingroup input
+ *   <h3>Representation of Parameters</h3>
+ *
+ *   Here is some more internal information about the repesentation of
+ *   parameters:
  *
- *   @author Wolfgang Bangerth, October 1997, revised February 1998
+ *   Logically, parameters and the nested sections they are arranged in can be
+ *   thought of as a hierarchical directory structure, or a tree. Take, for
+ *   example, the following code declaring a set of parameters and sections
+ *   they live in:
+ *   @code
+ *     ParameterHandler prm;
+ *
+ *     prm.declare_entry ("Maximal number of iterations",
+ *                        "10",
+ *                        Patterns::Integer (1, 1000),
+ *                        "A parameter that describes the maximal number of "
+ *                        "iterations the CG method is to take before giving "
+ *                        "up on a matrix.");
+ *     prm.enter_subsection ("Preconditioner");
+ *     {
+ *       prm.declare_parameter ("Kind",
+ *                              "SSOR",
+ *                              Patterns::Selection ("SSOR|Jacobi"),
+ *                              "A string that describes the kind of preconditioner "
+ *                              "to use.");
+ *       prm.declare_parameter ("Relaxation factor",
+ *                              "1.0",
+ *                              Patterns::Double (0, 1),
+ *                              "The numerical value (between zero and one) for the "
+ *                              "relaxation factor to use in the preconditioner.");
+ *     }
+ *     prm.leave_subsection ();
+ *   @endcode
+ *
+ *   We can think of the parameters so arrange as a file system in which every
+ *   parameter is a directory. The name of this directory is the name of the
+ *   parameter, and in this directory lie files that describe the
+ *   parameter. These files are:
+ *   - <code>value</code>: The content of this file is the current value of this
+ *     parameter; initially, the content of the file equals the default value of
+ *     the parameter.
+ *   - <code>default_value</code>: The content of this file is the default value
+ *     value of the parameter.
+ *   - <code>pattern</code>: A textual representation of the pattern that describes
+ *     the parameter's possible values.
+ *   - <code>pattern_index</code>: A number that indexes the Patterns::PatternBase
+ *     object that is used to to describe the parameter.
+ *   - <code>documentation</code>: The content of this file is the documentation
+ *     given for a parameter as the last argument of the
+ *     ParameterHandler::declare_entry call.
+ *   With the exception of the <code>value</code> file, the contents of files
+ *   are never changed after declaration of a parameter.
+ *
+ *   Alternatively, a directory in this file system may not have a file called
+ *   <code>value</code> in it. In that case, the directory represents a
+ *   subsection as declared above, and the directory's name will correspond to
+ *   the name of the subsection. It will then have no files in it at all, but
+ *   it may have further directories in it: some of these directories will be
+ *   parameters (indicates by the presence of files) or further nested
+ *   subsections.
+ *
+ *   Given this explanation, the code above will lead to a hierarchical
+ *   representation of data that looks like this (the content of files is
+ *   indicated at the right in a different font):
+ *     @image html parameter_handler.png
+ *   Once parameters have been read in, the contents of the <code>value</code>
+ *   "files" may be different while the other files remain untouched.
+ *
+ *   Using the ParameterHandler::print_parameters() function with
+ *   ParameterHandler::XML as second argument, we can get a complete
+ *   representation of this data structure in XML. It will look like
+ *   this:
+ *
+ *   @ingroup input
+ *   @author Wolfgang Bangerth, October 1997, revised February 1998, 2010
  */
 class ParameterHandler : public Subscriptor
 {
@@ -1978,13 +2058,8 @@ class ParameterHandler : public Subscriptor
  *   the number of the run.
  *
  *
- *   <h3>References</h3>
- *
- *   This class is inspired by the <tt>Multipleloop</tt> class of <tt>DiffPack</tt>.
- *
  *   @ingroup input
- *
- *   @author Wolfgang Bangerth, October 1997
+ *   @author Wolfgang Bangerth, October 1997, 2010
  */
 class MultipleParameterLoop : public ParameterHandler
 {
diff --git a/deal.II/doc/doxygen/images/parameter_handler.fig b/deal.II/doc/doxygen/images/parameter_handler.fig
new file mode 100644 (file)
index 0000000..56d16d6
--- /dev/null
@@ -0,0 +1,27 @@
+#FIG 3.2  Produced by xfig version 3.2.5b
+Landscape
+Center
+Metric
+A4      
+100.00
+Single
+-2
+1200 2
+2 5 0 1 0 -1 57 -1 -1 0.000 0 0 -1 0 0 5
+       0 parameter_handler_background.png
+        450 315 10935 315 10935 5837 450 5837 450 315
+4 0 0 50 -1 19 12 0.0000 4 135 105 4500 1665 0\001
+4 0 0 50 -1 19 12 0.0000 4 195 3480 4500 5040 [Floating point range 0...1 (inclusive)]\001
+4 0 0 50 -1 19 12 0.0000 4 135 210 4500 1935 10\001
+4 0 0 50 -1 19 12 0.0000 4 195 3135 4500 1350 [Integer range 1...1000 (inclusive)]\001
+4 0 0 50 -1 19 12 0.0000 4 195 4650 4500 1080 A parameter that describes the maximal number...\001
+4 0 0 50 -1 19 12 0.0000 4 135 210 4500 810 10\001
+4 0 0 50 -1 19 12 0.0000 4 135 105 4500 5355 2\001
+4 0 0 50 -1 19 12 0.0000 4 135 105 4500 3645 1\001
+4 0 0 50 -1 19 12 0.0000 4 150 555 4500 3960 SSOR\001
+4 0 0 50 -1 19 12 0.0000 4 180 1230 4500 3375 SSOR|Jacobi\001
+4 0 0 50 -1 19 12 0.0000 4 195 2280 4500 3105 A string that describes...\001
+4 0 0 50 -1 19 12 0.0000 4 150 555 4500 2790 SSOR\001
+4 0 0 50 -1 19 12 0.0000 4 135 270 4500 4500 1.0\001
+4 0 0 50 -1 19 12 0.0000 4 135 270 4500 5625 1.0\001
+4 0 0 50 -1 19 12 0.0000 4 180 3825 4500 4770 The numerical value (between zero and...\001
diff --git a/deal.II/doc/doxygen/images/parameter_handler.png b/deal.II/doc/doxygen/images/parameter_handler.png
new file mode 100644 (file)
index 0000000..ca1ab96
Binary files /dev/null and b/deal.II/doc/doxygen/images/parameter_handler.png differ
diff --git a/deal.II/doc/doxygen/images/parameter_handler_background.png b/deal.II/doc/doxygen/images/parameter_handler_background.png
new file mode 100644 (file)
index 0000000..46a08b4
Binary files /dev/null and b/deal.II/doc/doxygen/images/parameter_handler_background.png differ

In the beginning the Universe was created. This has made a lot of people very angry and has been widely regarded as a bad move.

Douglas Adams


Typeset in Trocchi and Trocchi Bold Sans Serif.