From: Wolfgang Bangerth Date: Thu, 9 Sep 2010 02:25:16 +0000 (+0000) Subject: Augment ParameterHandler documentation. X-Git-Tag: v8.0.0~5558 X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1f5fa2c1602f3ded21a86612dd6fb039e563ffe2;p=dealii.git Augment ParameterHandler documentation. git-svn-id: https://svn.dealii.org/trunk@21900 0785d39b-7218-0410-832d-ea1e28bc413d --- diff --git a/deal.II/base/include/base/parameter_handler.h b/deal.II/base/include/base/parameter_handler.h index 10a5bafefe..c9c48367d3 100644 --- a/deal.II/base/include/base/parameter_handler.h +++ b/deal.II/base/include/base/parameter_handler.h @@ -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 * - *

References

* - * This class is inspired by the MenuSystem class of DiffPack. * - * @ingroup input + *

Representation of Parameters

+ * + * 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: + * - value: 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. + * - default_value: The content of this file is the default value + * value of the parameter. + * - pattern: A textual representation of the pattern that describes + * the parameter's possible values. + * - pattern_index: A number that indexes the Patterns::PatternBase + * object that is used to to describe the parameter. + * - documentation: 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 value 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 + * value 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 value + * "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. * * - *

References

- * - * This class is inspired by the Multipleloop class of DiffPack. - * * @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 index 0000000000..56d16d64e4 --- /dev/null +++ b/deal.II/doc/doxygen/images/parameter_handler.fig @@ -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 index 0000000000..ca1ab96e45 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 index 0000000000..46a08b4f45 Binary files /dev/null and b/deal.II/doc/doxygen/images/parameter_handler_background.png differ