Debian Codegraph @

include/deal.II/base/parameter_handler.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 1998 - 2025 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_parameter_handler_h
16 #define dealii_parameter_handler_h
17
18
19 #include <deal.II/base/config.h>
20
21 #include <deal.II/base/enable_observer_pointer.h>
22 #include <deal.II/base/exceptions.h>
23 #include <deal.II/base/patterns.h>
24
25 #include <boost/archive/basic_archive.hpp>
26 #include <boost/property_tree/ptree_fwd.hpp>
27 #include <boost/property_tree/ptree_serialization.hpp>
28 #include <boost/serialization/split_member.hpp>
29
30 #include <map>
31 #include <memory>
32 #include <set>
33 #include <string>
34 #include <vector>
35
36 DEAL_II_NAMESPACE_OPEN
37
38 // forward declarations for interfaces and friendship
39 #ifndef DOXYGEN
40 class LogStream;
41 class MultipleParameterLoop;
42 #endif
43
44 /**
45 * The ParameterHandler class provides a standard interface to an input file
46 * which provides at run-time for program parameters such as time step sizes,
47 * geometries, right hand sides etc. The input for the program is given in
48 * files, streams or strings in memory using text like
49 * @code
50 * set Time step size = 0.3
51 * set Geometry = [0,1]x[0,3]
52 * @endcode
53 * Input may be sorted into subsection trees in order to give the input a
54 * logical structure, and input files may include other files.
55 *
56 * The ParameterHandler class is discussed in step-29,
57 * step-33, and step-34.
58 *
59 * <h3>Declaring entries</h3>
60 *
61 * In order to use the facilities of a ParameterHandler object, one first has
62 * to make known the different entries the input file may or may not contain.
63 * This is done in the following way:
64 *
65 * @code
66 * ...
67 * ParameterHandler prm;
68 * prm.declare_entry ("Time step size",
69 * "0.2",
70 * Patterns::Double(),
71 * "Some documentation");
72 * prm.declare_entry ("Geometry",
73 * "[0,1]x[0,1]",
74 * Patterns::Anything());
75 * ...
76 * @endcode
77 * Each entry is declared using the function declare_entry(). The first
78 * parameter is the name of the entry (in short: the entry). The second is the
79 * default answer to be taken in case the entry is not specified in the input
80 * file. The third parameter is a regular expression which the input (and the
81 * default answer) has to match. Several such regular expressions are defined
82 * in Patterns. This parameter can be omitted, in which case it will default
83 * to Patterns::Anything, i.e. a pattern that matches every input string. The
84 * fourth parameter can be used to document the intent or expected format of
85 * an entry; its value is printed as a comment when writing all entries of a
86 * ParameterHandler object using the print_parameters() function to allow for
87 * easier understanding of a parameter file. It can be omitted as well, in
88 * which case no such documentation will be printed.
89 *
90 * Entries may be located in subsections which form a kind of input tree. For
91 * example input parameters for linear solver routines should be classified in
92 * a subsection named <tt>Linear solver</tt> or any other suitable name. This
93 * is accomplished in the following way:
94 * @code
95 * ...
96 * LinEq eq;
97 * eq.declare_parameters (prm);
98 * ...
99 *
100 * void LinEq::declare_parameters (ParameterHandler &prm)
101 * {
102 * prm.enter_subsection("Linear solver");
103 * {
104 * prm.declare_entry ("Solver",
105 * "CG",
106 * Patterns::Selection("CG|GMRES|GaussElim"),
107 * "Name of a linear solver for the inner iteration");
108 * prm.declare_entry ("Maximum number of iterations", "20",
109 * ParameterHandler::RegularExpressions::Integer());
110 * ...
111 * }
112 * prm.leave_subsection ();
113 * }
114 * @endcode
115 *
116 * Subsections may be nested. For example a nonlinear solver may have a linear
117 * solver as member object. Then the function call tree would be something
118 * like (if the class <tt>NonLinEq</tt> has a member variables <tt>eq</tt> of
119 * type <tt>LinEq</tt>):
120 * @code
121 * void NonLinEq::declare_parameters (ParameterHandler &prm)
122 * {
123 * prm.enter_subsection ("Nonlinear solver");
124 * {
125 * prm.declare_entry ("Nonlinear method",
126 * "Newton-Raphson",
127 * ParameterHandler::RegularExpressions::Anything());
128 * eq.declare_parameters (prm);
129 * }
130 * prm.leave_subsection ();
131 * }
132 * @endcode
133 *
134 * For class member functions which declare the different entries we propose
135 * to use the common name <tt>declare_parameters</tt>. In normal cases this
136 * method can be <tt>static</tt> since the entries will not depend on any
137 * previous knowledge. Classes for which entries should logically be grouped
138 * into subsections should declare these subsections themselves. If a class
139 * has two or more member variables of the same type both of which should have
140 * their own parameters, this parent class' method <tt>declare_parameters</tt>
141 * is responsible to group them into different subsections:
142 * @code
143 * void NonLinEq::declare_parameters (ParameterHandler &prm)
144 * {
145 * prm.enter_subsection ("Nonlinear solver");
146 * {
147 * prm.enter_subsection ("Linear solver 1");
148 * {
149 * eq1.declare_parameters (prm);
150 * }
151 * prm.leave_subsection ();
152 *
153 * prm.enter_subsection ("Linear solver 2");
154 * {
155 * eq2.declare_parameters (prm);
156 * }
157 * prm.leave_subsection ();
158 * }
159 * prm.leave_subsection ();
160 * }
161 * @endcode
162 *
163 *
164 * <h3>Input files and special characters</h3>
165 *
166 * For the first example above the input file would look like the following:
167 * @code
168 * ...
169 * subsection Nonlinear solver
170 * set Nonlinear method = Gradient
171 * # this is a comment
172 * subsection Linear solver
173 * set Solver = CG
174 * set Maximum number of iterations = 30
175 * end
176 * end
177 * ... # other stuff
178 * @endcode
179 * The words <tt>subsection</tt>, <tt>set</tt> and <tt>end</tt> may be either
180 * written in lowercase or uppercase letters. Leading and trailing whitespace
181 * is removed, multiple whitespace is condensed into only one. Since the
182 * latter applies also to the name of an entry, an entry name will not be
183 * recognized if in the declaration multiple whitespace is used.
184 *
185 * In entry names and values the following characters are not allowed:
186 * <tt>\#</tt>, <tt>{</tt>, <tt>}</tt>, <tt>|</tt>. Their use is reserved for
187 * the MultipleParameterLoop class.
188 *
189 * Comments starting with \# are skipped.
190 *
191 * Continuation lines are allowed by means of the character <tt>\\</tt>, which
192 * must be the last character (aside from whitespace, which is ignored) of the
193 * line. When a line is a continuation (i.e., the previous line ended in a
194 * <tt>\\</tt>), then, unlike the default behavior of the <tt>C</tt>
195 * preprocessor, all whitespace at the beginning of the line is ignored.
196 *
197 * We propose to use the following scheme to name entries: start the first
198 * word with a capital letter and use lowercase letters further on. The same
199 * applies to the possible entry values to the right of the <tt>=</tt> sign.
200 *
201 * The class can also handle json-files and XML-files. The json input file might
202 * look like the following for the previous example:
203 * @code
204 * {
205 * "Nonlinear solver" : {
206 * "Nonlinear method" : "Gradient",
207 * "Linear solver" : {
208 * "Solver" : "CG",
209 * "Maximum number of iterations" : 30
210 * }
211 * }
212 * }
213 * @endcode
214 * The advantage of using json-files is that this format is natively supported
215 * by Python, simplifying the running of parameter studies tremendously.
216 *
217 * <h3>Including other input files</h3>
218 *
219 * An input file can include other include files using the syntax
220 * @code
221 * ...
222 * include some_other_file.prm
223 * ...
224 * @endcode
225 * The file so referenced is searched for relative to the current directory
226 * (not relative to the directory in which the including parameter file is
227 * located, since this is not known to all three versions of the parse_input()
228 * function).
229 *
230 *
231 * <h3>Reading data from input sources</h3>
232 *
233 * In order to read input there are three possibilities: reading from an
234 * <tt>std::istream</tt> object, reading from a file of which the name is
235 * given and reading from a string in memory in which the lines are separated
236 * by <tt>@\n</tt> characters. These possibilities are used as follows:
237 * @code
238 * ParameterHandler prm;
239 * ...
240 * // declaration of entries
241 * ...
242 * prm.parse_input (std::cin); // read input from standard in,
243 * // or
244 * prm.parse_input ("simulation.prm");
245 * // or
246 * char *in = "set Time step size = 0.3 \n ...";
247 * prm.parse_input_from_string (in);
248 * ...
249 * @endcode
250 * You can use several sources of input successively. Entries which are
251 * changed more than once will be overwritten every time they are used.
252 *
253 * You should not try to declare entries using declare_entry() and
254 * enter_subsection() with as yet unknown subsection names after using
255 * parse_input(). The results in this case are unspecified.
256 *
257 * If an error occurs upon reading the input, error messages are written to
258 * <tt>std::cerr</tt> and the reader function returns with a return value of
259 * <code>false</code>. This is opposed to almost all other functions in
260 * deal.II, which would normally throw an exception if an error occurs; this
261 * difference in behavior is a relic of the fact that this class predates
262 * deal.II and had previously been written for a different project.
263 *
264 *
265 * <h3>Using the %ParameterHandler Graphical User Interface</h3>
266 *
267 * An alternative to using the hand-written input files shown above is to use
268 * the graphical user interface (GUI) that accompanies this class.
269 *
270 * See <a href="https://github.com/dealii/parameter_gui">the parameter_gui
271 * github repository</a> for further details.
272 *
273 * <h3>Getting entry values out of a %ParameterHandler object</h3>
274 *
275 * Each class gets its data out of a ParameterHandler object by calling the
276 * get() member functions like this:
277 * @code
278 * void NonLinEq::get_parameters (ParameterHandler &prm)
279 * {
280 * prm.enter_subsection ("Nonlinear solver");
281 * std::string method = prm.get ("Nonlinear method");
282 * eq.get_parameters (prm);
283 * prm.leave_subsection ();
284 * }
285 * @endcode
286 * get() returns the value of the given entry. If the entry was not specified
287 * in the input source(s), the default value is returned. You have to enter
288 * and leave subsections exactly as you did when declaring subsections. You may
289 * choose the order in which to traverse the subsection tree.
290 *
291 * It is possible to avoid calls to enter_subsection() and leave_subsection()
292 * by supplying get() with a vector of strings representing the path from
293 * which to get a value. For example, the following two versions of
294 * get_parameters() will produce the same result:
295 * @code
296 * void NonLinEq::get_parameters (ParameterHandler &prm)
297 * {
298 * prm.enter_subsection ("Equation 1 Settings");
299 * prm.enter_subsection ("Linear solver");
300 * solver_ = prm.get ("Solver");
301 * prm.leave_subsection ();
302 * prm.leave_subsection ();
303 * }
304 * @endcode
305 *
306 * @code
307 * void NonLinEq::get_parameters (const ParameterHandler &prm)
308 * {
309 * std::vector<std::string> path =
310 * {"Equation 1 Settings", "Linear solver"};
311 * solver_ = prm.get (path, "Solver");
312 * }
313 * @endcode
314 *
315 * The latter method allows the ParameterHandler reference to be @p const.
316 *
317 * It is guaranteed that only entries matching the given regular expression
318 * are returned, i.e. an input entry value which does not match the regular
319 * expression is not stored.
320 *
321 * You can use get() to retrieve the parameter in text form, get_integer() to
322 * get an integer or get_double() to get a double. You can also use
323 * get_bool(). It will cause an internal error if the string could not be
324 * converted to an integer, double or a bool. This should, though, not happen
325 * if you correctly specified the regular expression for this entry; you
326 * should not try to get out an integer or a double from an entry for which no
327 * according regular expression was set. The internal error is raised through
328 * the Assert() macro family which only works in debug mode.
329 *
330 * If you want to print out all user selectable features, use the
331 * print_parameters() function. It is generally a good idea to print all
332 * parameters at the beginning of a log file, since this way input and output
333 * are together in one file which makes matching at a later time easier.
334 * Additionally, the function also print those entries which have not been
335 * modified in the input file and are thus set to default values; since
336 * default values may change in the process of program development, you cannot
337 * know the values of parameters not specified in the input file.
338 *
339 *
340 *
341 * <h3>Adding Actions to Parameters</h3>
342 *
343 * It is often convenient to have something happen as soon as a parameter
344 * value is read. This could be a check that it is valid -- say, that a
345 * file that is listed in the parameter file exists -- or to initiate
346 * something else in response, such as setting a variable outside the
347 * ParameterHandler (as in the example shown below). In almost all cases,
348 * this "action" could also be initiated once all parameters are read
349 * via parse_input(), but it is sometimes <i>convenient</i> to do it
350 * right away.
351 *
352 * This is facilitated by the add_action() function that can be called
353 * after declaring a parameter via declare_entry(). "Actions" are in essence
354 * pointers to functions that will be called for parameters that have
355 * associated actions. These functions take the value of a parameter as
356 * argument, and can then do whatever they want with it -- e.g., save it
357 * somewhere outside the ParameterHandler object. (Exactly when the
358 * action is called is described in the documentation of the
359 * add_action() function.) Of course, in C++ one doesn't usually pass
360 * around the address of a function, but an action can be a function-like
361 * object (taking a string as argument) that results from calling
362 * such as a
363 * <a href="http://en.cppreference.com/w/cpp/language/lambda">lambda
364 * function</a> that has the form
365 * @code
366 * [] (const std::string &value) { ... do something with the value ... }
367 * @endcode
368 * and that is attached to a specific parameter.
369 *
370 * A typical example of such an action would be as follows: let's assume
371 * that you have a program that declares a parameter for the number
372 * of iterations it is going to run, say
373 * @code
374 * class MyAlgorithm
375 * {
376 * public:
377 * void run ();
378 * private:
379 * unsigned int n_iterations;
380 * };
381 * @endcode
382 * then one could obtain this parameter from a parameter file using a
383 * code snippet in @p run() as follows:
384 * @code
385 * void MyAlgorithm::run ()
386 * {
387 * ParameterHandler prm;
388 * prm.declare_entry ("Number of iterations", // name of parameter
389 * "10", // default value
390 * Patterns::Integer(1,100),// allowed values: 1...100
391 * "The number of ..."); // some documentation
392 *
393 * // next read the parameter from an input file...
394 * prm.parse_input ("my_algorithm.prm");
395 *
396 * // ...and finally get the value for use in the program:
397 * n_iterations = prm.get_integer ("Number of iterations");
398 *
399 * ... actual code doing something useful follows here...
400 * @endcode
401 *
402 * This two-step process -- first declaring the parameter, and later reading
403 * it -- is a bit cumbersome because one has to first declare <i>all</i>
404 * parameters and at a later time retrieve them from the ParameterHandler
405 * object. In large programs, these two things also often happen in
406 * different functions.
407 *
408 * To avoid this, it would be nice if we could put both the declaration
409 * and the retrieval into the same place. This can be done via actions,
410 * and the function would then look like this:
411 * @code
412 * void MyAlgorithm::run ()
413 * {
414 * ParameterHandler prm;
415 * prm.declare_entry ("Number of iterations", // name of parameter
416 * "10", // default value
417 * Patterns::Integer(1,100),// allowed values: 1...100
418 * "The number of ..."); // some documentation
419 * prm.add_action ("Number of iterations",
420 * [&](const std::string &value)
421 * {
422 * this->n_iterations = Utilities::string_to_int(value);
423 * });
424 *
425 * // next read the parameter from an input file...
426 * prm.parse_input ("my_algorithm.prm");
427 *
428 * ... actual code doing something useful follows here...
429 * @endcode
430 * Here, the action consists of a lambda function that takes the value
431 * for this parameter as a string, and then converts it to an integer
432 * to store in the variable where it belongs. This action is
433 * executed inside the call to <code>prm.parse_input()</code>, and so
434 * there is now no longer a need to extract the parameter's value
435 * at a later time. Furthermore, the code that sets the member variable
436 * is located right next to the place where the parameter is actually
437 * declared, so we no longer need to have two separate parts of the code
438 * base that deal with input parameters.
439 *
440 * Of course, it is possible to execute far more involved actions than
441 * just setting a member variable as shown above, even though that is
442 * a typical case.
443 *
444 *
445 * <h3>Style guide for data retrieval</h3>
446 *
447 * We propose that every class which gets data out of a ParameterHandler
448 * object provides a function named <tt>get_parameters</tt>. This should be
449 * declared <tt>virtual</tt>. <tt>get_parameters</tt> functions in derived
450 * classes should call the <tt>BaseClass::get_parameters</tt> function.
451 *
452 *
453 * <h3>Experience with large parameter lists</h3>
454 *
455 * Experience has shown that in programs defining larger numbers of parameters
456 * (more than, say, fifty) it is advantageous to define an additional class
457 * holding these parameters. This class is more like a C-style structure,
458 * having a large number of variables, usually public. It then has at least
459 * two functions, which declare and parse the parameters. In the main program,
460 * the main class has an object of this parameter class and delegates
461 * declaration and parsing of parameters to this object.
462 *
463 * The advantage of this approach is that you can keep out the technical
464 * details (declaration and parsing) out of the main class and additionally
465 * don't clutter up your main class with dozens or more variables denoting the
466 * parameters.
467 *
468 *
469 *
470 * <h3>Worked Example</h3>
471 *
472 * This is the code:
473 * @code
474 * #include <deal.II/base/parameter_handler.h>
475 *
476 * #include <iostream>
477 * #include <string>
478 *
479 * using namespace dealii;
480 * class LinearEquation
481 * {
482 * public:
483 * static void declare_parameters (ParameterHandler &prm);
484 * void get_parameters (ParameterHandler &prm);
485 * private:
486 * std::string method;
487 * int max_iterations;
488 * };
489 *
490 *
491 *
492 * class Problem
493 * {
494 * private:
495 * LinearEquation eq1, eq2;
496 * std::string matrix1, matrix2;
497 * std::string outfile;
498 * public:
499 * static void declare_parameters (ParameterHandler &prm);
500 * void get_parameters (ParameterHandler &prm);
501 *
502 * void do_something ();
503 * };
504 *
505 *
506 *
507 * void LinearEquation::declare_parameters (ParameterHandler &prm)
508 * {
509 * // declare parameters for the linear solver in a subsection
510 * prm.enter_subsection ("Linear solver");
511 * {
512 * prm.declare_entry ("Solver",
513 * "CG",
514 * Patterns::Selection("CG|BiCGStab|GMRES"),
515 * "Name of a linear solver for the inner iteration");
516 * prm.declare_entry ("Maximum number of iterations",
517 * "20",
518 * Patterns::Integer());
519 * }
520 * prm.leave_subsection ();
521 * }
522 *
523 *
524 *
525 * void LinearEquation::get_parameters (ParameterHandler &prm)
526 * {
527 * prm.enter_subsection ("Linear solver");
528 * {
529 * method = prm.get ("Solver");
530 * max_iterations = prm.get_integer ("Maximum number of iterations");
531 * }
532 * prm.leave_subsection ();
533 * std::cout << " LinearEquation: method=" << method
534 * << ", max_iterations=" << max_iterations
535 * << std::endl;
536 * }
537 *
538 *
539 *
540 * void Problem::declare_parameters (ParameterHandler &prm)
541 * {
542 * // first some global parameter entries
543 * prm.declare_entry (
544 * "Output file",
545 * "out",
546 * Patterns::Anything(),
547 * "Name of the output file, either relative or absolute");
548 * prm.declare_entry ("Equation 1", "Laplace",
549 * Patterns::Anything(),
550 * "String identifying the equation we want to solve");
551 * prm.declare_entry ("Equation 2",
552 * "Elasticity",
553 * Patterns::Anything());
554 *
555 * // declare parameters for the first equation
556 * prm.enter_subsection ("Equation 1 Settings");
557 * {
558 * prm.declare_entry ("Matrix type",
559 * "Sparse",
560 * Patterns::Selection("Full|Sparse|Diagonal"),
561 * "Type of the matrix to be used, either full, "
562 * "sparse, or diagonal");
563 * LinearEquation::declare_parameters (prm); // for eq1
564 * }
565 * prm.leave_subsection ();
566 *
567 * // declare parameters for the second equation
568 * prm.enter_subsection ("Equation 2 Settings");
569 * {
570 * prm.declare_entry ("Matrix type",
571 * "Sparse",
572 * Patterns::Selection("Full|Sparse|Diagonal"));
573 * LinearEquation::declare_parameters (prm); // for eq2
574 * }
575 * prm.leave_subsection ();
576 * }
577 *
578 *
579 *
580 * void Problem::get_parameters (ParameterHandler &prm)
581 * {
582 * // entries of the problem class
583 * outfile = prm.get ("Output file");
584 * std::string equation1 = prm.get ("Equation 1"),
585 * equation2 = prm.get ("Equation 2");
586 *
587 * // get parameters for the first equation
588 * prm.enter_subsection ("Equation 1 Settings");
589 * {
590 * matrix1 = prm.get ("Matrix type");
591 * eq1.get_parameters (prm); // for eq1
592 * }
593 * prm.leave_subsection ();
594 *
595 * // get parameters for the second equation
596 * prm.enter_subsection ("Equation 2 Settings");
597 * {
598 * matrix2 = prm.get ("Matrix type");
599 * eq2.get_parameters (prm); // for eq2
600 * }
601 * prm.leave_subsection ();
602 * std::cout
603 * << " Problem: outfile=" << outfile << '\n'
604 * << " eq1=" << equation1 << ", eq2=" << equation2 << '\n'
605 * << " matrix1=" << matrix1 << ", matrix2=" << matrix2
606 * << std::endl;
607 * }
608 *
609 *
610 *
611 * void Problem::do_something ()
612 * {
613 * // While this example does nothing here, at this point in the program
614 * // all of the parameters are known so we can start doing computations.
615 * }
616 *
617 *
618 *
619 * int main ()
620 * {
621 * ParameterHandler prm;
622 * Problem p;
623 * p.declare_parameters (prm);
624 * // read input from "prmtest.prm"; giving argv[1] would also be a
625 * // good idea
626 * prm.parse_input ("prmtest.prm");
627 * // print parameters to std::cout as ASCII text
628 * std::cout << "\n\n";
629 * prm.print_parameters (std::cout, ParameterHandler::Text);
630 * // get parameters into the program
631 * std::cout << "\n\n" << "Getting parameters:" << std::endl;
632 * p.get_parameters (prm);
633 * // now run the program with these input parameters
634 * p.do_something ();
635 * }
636 * @endcode
637 *
638 *
639 * This is the input file (named "prmtest.prm"):
640 * @code
641 * # first declare the types of equations
642 * set Equation 1 = Poisson
643 * set Equation 2 = Stokes
644 *
645 * subsection Equation 1 Settings
646 * set Matrix type = Sparse
647 * subsection Linear solver # parameters for linear solver 1
648 * set Solver = Gauss-Seidel
649 * set Maximum number of iterations = 40
650 * end
651 * end
652 *
653 * subsection Equation 2 Settings
654 * set Matrix type = Full
655 * subsection Linear solver
656 * set Solver = CG
657 * set Maximum number of iterations = 100
658 * end
659 * end
660 * @endcode
661 *
662 * And here is the output of the program:
663 * @code
664 * Line <8> of file <prmtest.prm>:
665 * The entry value
666 * Gauss-Seidel
667 * for the entry named
668 * Solver
669 * does not match the given pattern
670 * [Selection CG|BiCGStab|GMRES ]
671 *
672 *
673 * # Listing of Parameters
674 * # ---------------------
675 * # String identifying the equation we want to solve
676 * set Equation 1 = Poisson # default: Laplace
677 * set Equation 2 = Stokes # default: Elasticity
678 *
679 * # Name of the output file, either relative to the present path or absolute
680 * set Output file = out
681 *
682 *
683 * subsection Equation 1 Settings
684 * # Type of the matrix to be used, either full, sparse, or diagonal
685 * set Matrix type = Sparse
686 *
687 *
688 * subsection Linear solver
689 * set Maximum number of iterations = 40 # default: 20
690 * # Name of a linear solver for the inner iteration
691 * set Solver = CG
692 * end
693 *
694 * end
695 *
696 *
697 * subsection Equation 2 Settings
698 * set Matrix type = Full # default: Sparse
699 *
700 *
701 * subsection Linear solver
702 * set Maximum number of iterations = 100 # default: 20
703 * # Name of a linear solver for the inner iteration
704 * set Solver = CG
705 * end
706 *
707 * end
708 *
709 *
710 *
711 *
712 * Getting parameters:
713 * LinearEquation: method=CG, max_iterations=40
714 * LinearEquation: method=CG, max_iterations=100
715 * Problem: outfile=out
716 * eq1=Poisson, eq2=Stokes
717 * matrix1=Sparse, matrix2=Full
718 * @endcode
719 *
720 *
721 *
722 * <h3>Representation of Parameters</h3>
723 *
724 * Here is some more internal information about the representation of
725 * parameters:
726 *
727 * Logically, parameters and the nested sections they are arranged in can be
728 * thought of as a hierarchical directory structure, or a tree. Take, for
729 * example, the following code declaring a set of parameters and sections they
730 * live in:
731 * @code
732 * ParameterHandler prm;
733 *
734 * prm.declare_entry ("Maximal number of iterations",
735 * "10",
736 * Patterns::Integer (1, 1000),
737 * "A parameter that describes the maximal number of "
738 * "iterations the CG method is to take before giving "
739 * "up on a matrix.");
740 * prm.enter_subsection ("Preconditioner");
741 * {
742 * prm.declare_entry(
743 * "Kind",
744 * "SSOR",
745 * Patterns::Selection ("SSOR|Jacobi"),
746 * "A string that describes the kind of preconditioner to use.");
747 * prm.declare_entry(
748 * "Relaxation factor",
749 * "1.0",
750 * Patterns::Double (0, 1),
751 * "The numerical value (between zero and one) for the "
752 * "relaxation factor to use in the preconditioner.");
753 * }
754 * prm.leave_subsection ();
755 * @endcode
756 *
757 * We can think of the parameters so arranged as a file system in which every
758 * parameter is a directory. The name of this directory is the name of the
759 * parameter, and in this directory lie files that describe the parameter.
760 * These files are at the time of writing this documentation (other fields,
761 * such as those indicating "actions" may also exist in each directory):
762 *
763 * - <code>value</code>: The content of this file is the current value of this
764 * parameter; initially, the content of the file equals the default value of
765 * the parameter.
766 * - <code>default_value</code>: The content of this file is the default value
767 * of the parameter.
768 * - <code>pattern</code>: A textual representation of the pattern that
769 * describes the parameter's possible values.
770 * - <code>pattern_index</code>: A number that indexes the Patterns::PatternBase
771 * object that is used to describe the parameter.
772 * - <code>documentation</code>: The content of this file is the documentation
773 * given for a parameter as the last argument of the
774 * ParameterHandler::declare_entry call. With the exception of the
775 * <code>value</code> file, the contents of files are never changed after
776 * declaration of a parameter.
777 *
778 * Alternatively, a directory in this file system may not have a file called
779 * <code>value</code> in it. In that case, the directory represents a
780 * subsection as declared above, and the directory's name will correspond to
781 * the name of the subsection. It will then have no files in it at all, but it
782 * may have further directories in it: some of these directories will be
783 * parameters (indicates by the presence of files) or further nested
784 * subsections.
785 *
786 * Given this explanation, the code above will lead to a hierarchical
787 * representation of data that looks like this (the content of files is
788 * indicated at the right in a different font):
789 *
790 * @image html parameter_handler.png
791 *
792 * Once parameters have been read in, the contents of the <code>value</code>
793 * "files" may be different while the other files remain untouched.
794 *
795 * Using the ParameterHandler::print_parameters() function with
796 * ParameterHandler::XML as second argument, we can get a complete
797 * representation of this data structure in XML. It will look like this:
798 * @code
799 * <?xml version="1.0" encoding="utf-8"?>
800 * <ParameterHandler>
801 * <Maximal_20number_20of_20iterations>
802 * <value>10</value>
803 * <default_value>10</default_value>
804 * <documentation>
805 * A parameter that describes the maximal number of iterations the CG
806 * method is to take before giving up on a matrix.
807 * </documentation>
808 * <pattern>0</pattern>
809 * <pattern_description>
810 * [Integer range 1...1000 (inclusive)]
811 * </pattern_description>
812 * </Maximal_20number_20of_20iterations>
813 * <Preconditioner>
814 * <Kind><value>SSOR</value>
815 * <default_value>SSOR</default_value>
816 * <documentation>
817 * A string that describes the kind of preconditioner to use.
818 * </documentation>
819 * <pattern>1</pattern>
820 * <pattern_description>SSOR|Jacobi</pattern_description>
821 * </Kind>
822 * <Relaxation_20factor>
823 * <value>1.0</value>
824 * <default_value>1.0</default_value>
825 * <documentation>
826 * The numerical value (between zero and one) for the relaxation
827 * factor to use in the preconditioner.
828 * </documentation>
829 * <pattern>2</pattern>
830 * <pattern_description>
831 * [Floating point range 0...1 (inclusive)]
832 * </pattern_description>
833 * </Relaxation_20factor>
834 * </Preconditioner>
835 * <ParameterHandler>
836 * @endcode
837 * This representation closely resembles the directory/file structure
838 * discussed above. The only difference is that directory and file names are
839 * mangled: since they should only contain letters and numbers, every
840 * character in their names that is not a letter or number is replaced by an
841 * underscore followed by its two-digit hexadecimal representation. In
842 * addition, the special name "value" is mangled when used as the name of a
843 * parameter, given that this name is also used to name special files in the
844 * hierarchy structure. Finally, the entire tree is wrapped into a tag
845 * <code>%ParameterHandler</code> to satisfy the XML requirement that there be
846 * only a single top-level construct in each file.
847 *
848 * The tree structure (and its XML representation) is what the graphical user
849 * interface (see above) uses to represent parameters like a directory/file
850 * collection.
851 *
852 *
853 * @ingroup input
854 */
855 class ParameterHandler : public EnableObserverPointer
856 {
857 public:
858 /**
859 * List of possible output formats used for functions like
860 * ParameterHandler::print_parameters(). The options can be categorized into
861 * two groups:
862 * - format options: PRM, LaTeX, Description, XML, JSON
863 * - stylistic options: Short, KeepDeclarationOrder
864 *
865 * Only one format option may be specified at the time. Any function that
866 * accepts an OutputStyle as an option will throw if you specify more than
867 * one.
868 *
869 * A number of shortcuts of commonly used option combinations are provided.
870 * E.g., ShortPRM prints the parameters in the PRM format, while skipping the
871 * documentation.
872 */
873 enum OutputStyle
874 {
875 /**
876 * Default stylistic style: print documentation and sort all parameters
877 * alphabetically.
878 */
879 DefaultStyle = 0x0000,
880
881 /**
882 * Write input for ParameterHandler without comments or changed default
883 * values.
884 */
885 Short = 0x0001,
886
887 /**
888 * Keep the order of the parameters as they have been declared.
889 */
890 KeepDeclarationOrder = 0x0002,
891
892 /**
893 * Write human readable output suitable to be read by
894 * ParameterHandler::parse_input() again.
895 */
896 PRM = 0x0010,
897
898 /**
899 * Write parameters as a LaTeX table.
900 */
901 LaTeX = 0x0020,
902
903 /**
904 * Write out declared parameters with description and possible values.
905 *
906 * @note This format is not suitable to be read back again.
907 */
908 Description = 0x0040,
909
910 /**
911 * Write out everything as an <a
912 * href="http://en.wikipedia.org/wiki/XML">XML</a> file suitable to be read
913 * by ParameterHandler::parse_input_from_xml() again.
914 *
915 * See the general documentation of this class for an example of output.
916 */
917 XML = 0x0080,
918
919 /**
920 * Write out everything as a <a
921 * href="http://en.wikipedia.org/wiki/JSON">JSON</a> file suitable to be
922 * read by ParameterHandler::parse_input_from_json() again.
923 */
924 JSON = 0x0100,
925
926 /**
927 * Write the content of ParameterHandler without comments or changed default
928 * values.
929 */
930 ShortPRM = PRM | Short,
931
932 /**
933 * Write the content of ParameterHandler without comments or changed default
934 * values as a XML file.
935 */
936 ShortXML = XML | Short,
937
938 /**
939 * Write the content of ParameterHandler without comments or changed default
940 * values as a JSON file.
941 */
942 ShortJSON = JSON | Short,
943
944 /**
945 * Write the content of ParameterHandler without comments or changed default
946 * values as a LaTeX file.
947 */
948 ShortLaTeX = LaTeX | Short,
949
950 /**
951 * Write out only parameters with changed values.
952 */
953 KeepOnlyChanged = 0x0200,
954 };
955
956
957
958 /**
959 * Constructor.
960 */
961 ParameterHandler();
962
963 /**
964 * Destructor. Declare this only to have a virtual destructor, which is
965 * safer as we have virtual functions. It actually does nothing
966 * spectacular.
967 */
968 virtual ~ParameterHandler() override = default;
969
970 /**
971 * Inhibit automatic CopyConstructor.
972 */
973 ParameterHandler(const ParameterHandler &) = delete;
974
975 /**
976 * Inhibit automatic assignment operator.
977 */
978 ParameterHandler &
979 operator=(const ParameterHandler &) = delete;
980
981 /**
982 * Parse each line from a stream until the stream returns the <tt>eof</tt>
983 * condition or error to provide values for known parameter fields. The second
984 * argument can be used to denote the name of the file (if that's what the
985 * input stream represents) we are reading from; this is only used when
986 * creating output for exceptions.
987 *
988 * If non-empty @p last_line is provided, the ParameterHandler object
989 * will stop parsing lines after encountering @p last_line .
990 * This is handy when adding extra data that shall be parsed manually.
991 *
992 * If @p skip_undefined is <code>true</code>, the parameter handler
993 * will skip undefined sections and entries. This is useful for partially
994 * parsing a parameter file, for example to obtain only the spatial dimension
995 * of the problem. By default all entries and subsections are expected to be
996 * declared.
997 *
998 * The function sets the value of all parameters it encounters in the
999 * input file to the provided value. Parameters not explicitly listed
1000 * in the input file are left at the value they previously held, which
1001 * will be the default value provided to declare_entry() unless one
1002 * has previously read a different input file.
1003 *
1004 * Each parameter value is matched against the pattern for this
1005 * parameter that was provided to declare_entry(), and for each parameter
1006 * all associated actions that may previously have been set by
1007 * add_action() are executed. If a parameter does not satisfy its
1008 * pattern, or if an associated action throws an exception, then the
1009 * value provided for the parameter is not set and the current
1010 * object reverts to the subsection it was in before the current
1011 * function was called. No further processing of the input stream
1012 * occurs, that is everything that comes after the parameter whose
1013 * value does not satisfy its pattern is ignored.
1014 */
1015 virtual void
1016 parse_input(std::istream &input,
1017 const std::string &filename = "input file",
1018 const std::string &last_line = "",
1019 const bool skip_undefined = false);
1020
1021 /**
1022 * Parse input from a specified parameter file @p filename independently
1023 * of the type of input file (prm, xml, json) being used. The code path
1024 * selected by this function is extracted from the ending of the filename,
1025 * so the user has to make sure that the content of the input file is
1026 * consistent with its name.
1027 *
1028 * The parameter @p last_line will only be used for parameter files of .prm type.
1029 * See the other parse_input function for documentation.
1030 *
1031 * The user can specify whether parameters in the input file not added to the
1032 * parameter handler will be skipped by @p skip_undefined (enables partial
1033 * parsing), and whether the code will assert that all parameters of the
1034 * parameter handler declared with flag `has_to_be_set=true` are indeed found
1035 * in the input file.
1036 *
1037 * If the function is called with `skip_undefined=true`, it is recommended to
1038 * also set `assert_mandatory_entries_are_found=true`. For example, this
1039 * ensures that parameters with typos in the input file will not be skipped,
1040 * while such mistakes would otherwise remain unrecognized.
1041 */
1042 virtual void
1043 parse_input(const std::string &filename,
1044 const std::string &last_line = "",
1045 const bool skip_undefined = false,
1046 const bool assert_mandatory_entries_are_found = false);
1047
1048 /**
1049 * Parse input from a string to populate known parameter fields. The lines
1050 * in the string must be separated by <tt>@\n</tt> characters.
1051 *
1052 * The function in essence reads the entire file into a stream and
1053 * then calls the other parse_input() function with that stream. See
1054 * there for more information.
1055 */
1056 virtual void
1057 parse_input_from_string(const std::string &s,
1058 const std::string &last_line = "",
1059 const bool skip_undefined = false);
1060
1061 /**
1062 * Parse input from an XML stream to populate known parameter fields. This
1063 * could be from a file originally written by the print_parameters() function
1064 * using the XML output style and then modified by hand as necessary, or from
1065 * a file written using this method and then modified by the graphical
1066 * parameter GUI (see the general documentation of this class).
1067 */
1068 virtual void
1069 parse_input_from_xml(std::istream &input, const bool skip_undefined = false);
1070
1071 /**
1072 * Parse input from a JSON stream to populate known parameter fields. This
1073 * could be from a file originally written by the print_parameters() function
1074 * using the JSON output style and then modified by hand as necessary, or from
1075 * a separate program that knows how to write JSON format for ParameterHandler
1076 * input.
1077 */
1078 virtual void
1079 parse_input_from_json(std::istream &input, const bool skip_undefined = false);
1080
1081 /**
1082 * Clear all contents.
1083 */
1084 void
1085 clear();
1086
1087
1088 /**
1089 * Declare a new entry with name <tt>entry</tt>, default and for which any
1090 * input has to match the <tt>pattern</tt> (default: any pattern).
1091 *
1092 * The function generates an exception of type ExcValueDoesNotMatchPattern
1093 * if the default value doesn't match the given pattern, using the C++ throw
1094 * mechanism. However, this exception is only generated <i>after</i> the
1095 * entry has been created; if you have code where no sensible default value
1096 * for a parameter is possible, you can then catch and ignore this
1097 * exception.
1098 *
1099 * The parameter @p documentation defaulting to an empty string is used
1100 * to add a documenting text to each entry which will be printed as a comment
1101 * when this class is asked to write out all declarations to a stream using
1102 * the print_parameters() function.
1103 *
1104 * The parameter @p has_to_be_set can be used in order to declare this
1105 * parameter as a parameter whose default value has to be overwritten by
1106 * one of the methods provided by this class. Whether a parameter has been set
1107 * successfully can be queried by the functions get_entries_wrongly_not_set()
1108 * and assert_that_entries_have_been_set().
1109 *
1110 * @note An entry can be declared more than once without generating an
1111 * error, for example to override an earlier default value.
1112 */
1113 void
1114 declare_entry(const std::string &entry,
1115 const std::string &default_value,
1116 const Patterns::PatternBase &pattern = Patterns::Anything(),
1117 const std::string &documentation = "",
1118 const bool has_to_be_set = false);
1119
1120 /**
1121 * Mark a previously declared parameter as deprecated. This will cause an
1122 * exception of type ExcEncounteredDeprecatedEntries to be thrown if
1123 * the parameter is used in an input file that is parsed by the
1124 * parse_input() function.
1125 *
1126 * The exception message will list the name of the parameter(s) that
1127 * were encountered in the input file.
1128 *
1129 * @param entry The name of the parameter to be marked as deprecated.
1130 * @param is_deprecated An optional parameter that can be used to
1131 * set the deprecation status of the parameter. If set to true, the
1132 * parameter will be marked as deprecated. This is the default behavior.
1133 * If set to false, the parameter will be marked as not deprecated.
1134 * This is useful if a parameter is marked as deprecated by
1135 * one function, but another function wants to keep using it.
1136 */
1137 void
1138 mark_as_deprecated(const std::string &entry, const bool is_deprecated = true);
1139
1140 /**
1141 * Attach an action to the parameter with name @p entry in the current
1142 * section. The action needs to be a function-like object that takes the
1143 * value of the parameter as a (string) argument. See the general
1144 * documentation of this class for a longer description of actions, as well as
1145 * examples.
1146 *
1147 * The action is executed in three different circumstances:
1148 * - With the default value of the parameter with name @p name, at
1149 * the end of the current function if @p execute_action is set to
1150 * true. This is useful because it allows for the action to execute
1151 * whatever it needs to do at least once for each parameter, even
1152 * those that are not actually specified in the input file (and
1153 * thus remain at their default values). Note that if the action
1154 * is executed, it converts the default value to a string and back
1155 * afterwards. This can lead to round-off errors so that the default
1156 * values might change in the case of floating-point numbers.
1157 * - Within the ParameterHandler::set() functions that explicitly
1158 * set a value for a parameter.
1159 * - Within the parse_input() function and similar functions such
1160 * as parse_input_from_string(). Here, the action is executed
1161 * whenever the parameter with which it is associated is read
1162 * from the input, after it has been established that the value
1163 * so read matches the pattern that corresponds to this parameter,
1164 * and before the value is actually saved.
1165 *
1166 * It is valid to add multiple actions to the same parameter. They will
1167 * in that case be executed in the same order in which they were added.
1168 *
1169 * @note Actions may modify all sorts of variables in their scope. The
1170 * only thing an action should not modify is the ParameterHandler object
1171 * it is attached to. In other words, it is not allowed to enter or
1172 * leave sections of the current ParameterHandler object. It is, in
1173 * principle, acceptable to call ParameterHandler::get() and related
1174 * functions on other parameters in the current section, but since
1175 * there is no guarantee about the order in which they will be read
1176 * from an input file, you will not want to rely on the values these
1177 * functions would return.
1178 *
1179 * @note Throwing an exception in an action is generally not a good
1180 * idea, but yields fundamentally the same result as if one tries to
1181 * read a parameter from a file for which the value does not satisfy
1182 * the pattern associated with the parameter. In other words, the
1183 * value just read is discarded, and ParameterHandler::parse_input()
1184 * stops to read any further content from the file. See
1185 * ParameterHandler::parse_input() for more information.
1186 */
1187 void
1188 add_action(const std::string &entry,
1189 const std::function<void(const std::string &value)> &action,
1190 const bool execute_action = true);
1191
1192 /**
1193 * Declare a new entry name @p entry, set its default value to the content of
1194 * the variable @p parameter, and create an action that will fill @p
1195 * parameter with updated values when a file is parsed, or the entry is set
1196 * to a new value.
1197 *
1198 * By default, the pattern to use is obtained by calling the function
1199 * Patterns::Tools::Convert<T>::to_pattern(), but a custom one can be used.
1200 *
1201 * The parameter @p has_to_be_set can be used in order to declare this
1202 * parameter as a parameter whose default value has to be overwritten by
1203 * one of the methods provided by this class. Whether a parameter has been set
1204 * successfully can be queried by the functions get_entries_wrongly_not_set()
1205 * and assert_that_entries_have_been_set().
1206 */
1207 template <typename ParameterType>
1208 void
1209 add_parameter(const std::string &entry,
1210 ParameterType &parameter,
1211 const std::string &documentation = "",
1212 const Patterns::PatternBase &pattern =
1213 *Patterns::Tools::Convert<ParameterType>::to_pattern(),
1214 const bool has_to_be_set = false);
1215
1216 /**
1217 * Create an alias for an existing entry. This provides a way to refer to a
1218 * parameter in the input file using an alternate name. The alias will be in
1219 * the current section, and the referenced entry needs to be an existing
1220 * entry in the current section.
1221 *
1222 * The primary purpose of this function is to allow for a backward
1223 * compatible way of changing names in input files of applications for which
1224 * backward compatibility is important. This can be achieved by changing the
1225 * name of the parameter in the call to declare_entry(), and then creating
1226 * an alias that maps the old name to the new name. This way, old input
1227 * files can continue to refer to parameters under the old name, and they
1228 * will automatically be mapped to the new parameter name.
1229 *
1230 * It is valid to set the same parameter multiple times in an input file.
1231 * The value that will ultimately be chosen in such cases is simply the last
1232 * value set. This rule also applies to aliases, where the final value of a
1233 * parameter is the last value set either through the current name of the
1234 * parameter or through any of its possible multiple aliases. For example,
1235 * if you have an input file that looks like
1236 * @code
1237 * set parm1 = 1
1238 * set parm1_alias = 2
1239 * @endcode
1240 * where <code>parm1_alias</code> is an alias declared via
1241 * @code
1242 * prm.declare_alias ("parm1", "parm1_alias");
1243 * @endcode
1244 * then the final value for the parameter called <code>parm1</code> will be
1245 * 2, not 1.
1246 *
1247 * @param existing_entry_name The name of an existing parameter in the
1248 * current section that the alias should refer to.
1249 * @param alias_name An alternate name for the parameter referenced by the
1250 * first argument.
1251 * @param alias_is_deprecated If true, mark the alias as deprecated. This
1252 * will then be listed in the description of the alias if you call
1253 * print_parameters(), and you will get a warning on the screen when reading
1254 * an input file that contains this deprecated alias. The purpose of this
1255 * argument is to be able to allow the use of an old name for a parameter
1256 * (see above) but make it clear that this old name will eventually be
1257 * removed.
1258 */
1259 void
1260 declare_alias(const std::string &existing_entry_name,
1261 const std::string &alias_name,
1262 const bool alias_is_deprecated = false);
1263
1264 /**
1265 * Enter a subsection. If it does not yet exist, create it if requested.
1266 */
1267 void
1268 enter_subsection(const std::string &subsection,
1269 const bool create_path_if_needed = true);
1270
1271 /**
1272 * Leave present subsection.
1273 */
1274 void
1275 leave_subsection();
1276
1277 /**
1278 * Check whether a subsection or a subsection path exists in current tree.
1279 * The input parameter @p sub_path is assumed to be relative to the
1280 * currently selected path.
1281 */
1282 bool
1283 subsection_path_exists(const std::vector<std::string> &sub_path) const;
1284
1285 /**
1286 * Return the string that identifies the current path into the property
1287 * tree. The path elements are separated by the path_separator, which is a
1288 * '.'. This is only a path, i.e., it is not terminated by the path_separator
1289 * character.
1290 *
1291 * This function simply calls collate_path_string() with
1292 * @p subsection_path as argument.
1293 */
1294 std::string
1295 get_current_path() const;
1296
1297 /**
1298 * Given the name of an entry as argument, the function computes a full path
1299 * into the parameter tree using the current subsection. The path elements are
1300 * separated by the path_separator, which is a '.'.
1301 */
1302 std::string
1303 get_current_full_path(const std::string &name) const;
1304
1305 /**
1306 * This function computes a full path into the parameter tree given a path
1307 * from the current subsection and the name of an entry. The path elements are
1308 * separated by the path_separator, which is a '.'.
1309 */
1310 std::string
1311 get_current_full_path(const std::vector<std::string> &sub_path,
1312 const std::string &name) const;
1313
1314 /**
1315 * Return value of entry @p entry_string. If the entry was changed,
1316 * then the changed value is returned, otherwise the default value. If the
1317 * value of an undeclared entry is required, an @p Assert will fail.
1318 */
1319 std::string
1320 get(const std::string &entry_string) const;
1321
1322 /**
1323 * Return value of entry @p entry_string. If the entry was changed,
1324 * then the changed value is returned, otherwise the default value. If the
1325 * value of an undeclared entry is required, an @p Assert will fail.
1326 * If @p entry_subsection_path is non-empty, the value will be gotten
1327 * from the subsection represented by that path instead of the current
1328 * subsection. The first string in @p entry_subsection_path must be the name
1329 * of a subsection of the current section, and each next string must be the
1330 * name of a subsection of the one before it.
1331 */
1332 std::string
1333 get(const std::vector<std::string> &entry_subsection_path,
1334 const std::string &entry_string) const;
1335
1336 /**
1337 * Return value of entry @p entry_string as <code>long int</code>. (A long
1338 * int is chosen so that even very large unsigned values can be returned by
1339 * this function).
1340 */
1341 long int
1342 get_integer(const std::string &entry_string) const;
1343
1344 /**
1345 * Return value of entry @p entry_string as <code>long int</code>. (A long
1346 * int is chosen so that even very large unsigned values can be returned by
1347 * this function).
1348 * If @p entry_subsection_path is non-empty, the value will be gotten
1349 * from the subsection represented by that path instead of the current
1350 * subsection.
1351 */
1352 long int
1353 get_integer(const std::vector<std::string> &entry_subsection_path,
1354 const std::string &entry_string) const;
1355
1356 /**
1357 * Return value of entry @p entry_name as @p double.
1358 */
1359 double
1360 get_double(const std::string &entry_name) const;
1361
1362 /**
1363 * Return value of entry @p entry_name as @p double.
1364 * If @p entry_subsection_path is non-empty, the value will be gotten
1365 * from the subsection represented by that path instead of the current
1366 * subsection.
1367 */
1368 double
1369 get_double(const std::vector<std::string> &entry_subsection_path,
1370 const std::string &entry_string) const;
1371 /**
1372 * Return value of entry @p entry_name as @p bool. The entry may
1373 * be "true" or "yes" for @p true, "false" or "no" for @p false
1374 * respectively.
1375 */
1376 bool
1377 get_bool(const std::string &entry_name) const;
1378
1379 /**
1380 * Return value of entry @p entry_name as @p bool. The entry may
1381 * be "true" or "yes" for @p true, "false" or "no" for @p false
1382 * respectively.
1383 * If @p entry_subsection_path is non-empty, the value will be gotten
1384 * from the subsection represented by that path instead of the current
1385 * subsection.
1386 */
1387 bool
1388 get_bool(const std::vector<std::string> &entry_subsection_path,
1389 const std::string &entry_string) const;
1390
1391 /**
1392 * Change the value presently stored for <tt>entry_name</tt> to the one
1393 * given in the second argument.
1394 *
1395 * The parameter must already exist in the present subsection.
1396 *
1397 * The function throws an exception of type ExcValueDoesNotMatchPattern if
1398 * the new value does not conform to the pattern for this entry.
1399 */
1400 void
1401 set(const std::string &entry_name, const std::string &new_value);
1402
1403 /**
1404 * Same as above, but an overload where the second argument is a character
1405 * pointer. This is necessary, since otherwise the call to
1406 * <code>set("abc","def")</code> will be mapped to the function taking one
1407 * string and a bool as arguments, which is certainly not what is most often
1408 * intended.
1409 *
1410 * The function throws an exception of type ExcValueDoesNotMatchPattern if
1411 * the new value does not conform to the pattern for this entry.
1412 */
1413 void
1414 set(const std::string &entry_name, const char *new_value);
1415
1416 /**
1417 * Change the value presently stored for <tt>entry_name</tt> to the one
1418 * given in the second argument.
1419 *
1420 * The parameter must already exist in the present subsection.
1421 *
1422 * The function throws an exception of type ExcValueDoesNotMatchPattern if
1423 * the new value does not conform to the pattern for this entry.
1424 */
1425 void
1426 set(const std::string &entry_name, const long int new_value);
1427
1428 /**
1429 * Change the value presently stored for <tt>entry_name</tt> to the one
1430 * given in the second argument.
1431 *
1432 * The parameter must already exist in the present subsection.
1433 *
1434 * For internal purposes, the new value needs to be converted to a string.
1435 * This is done using 16 digits of accuracy, so the set value and the one
1436 * you can get back out using get_double() may differ in the 16th digit.
1437 *
1438 * The function throws an exception of type ExcValueDoesNotMatchPattern if
1439 * the new value does not conform to the pattern for this entry.
1440 */
1441 void
1442 set(const std::string &entry_name, const double new_value);
1443
1444 /**
1445 * Change the value presently stored for <tt>entry_name</tt> to the one
1446 * given in the second argument.
1447 *
1448 * The parameter must already exist in the present subsection.
1449 *
1450 * The function throws an exception of type ExcValueDoesNotMatchPattern if
1451 * the new value does not conform to the pattern for this entry.
1452 */
1453 void
1454 set(const std::string &entry_name, const bool new_value);
1455
1456 /**
1457 * Print all parameters with the given @p style to @p out.
1458 *
1459 * Before printing, all current parameters and subsections are sorted
1460 * alphabetically by default.
1461 * This behavior can be disabled setting the optional parameter @p style
1462 * to <tt>KeepDeclarationOrder</tt>: in this case entries are printed in the
1463 * same order as they have been declared.
1464 *
1465 * In <tt>PRM</tt>, <tt>XML</tt>, and <tt>JSON</tt> format, the output is
1466 * formatted in such a way that it is
1467 * possible to use it for later input again. This is most useful to record
1468 * the parameters for a specific run, since if you output the parameters
1469 * using this function into a log file, you can always recover the results
1470 * by simply copying the output to your input file.
1471 *
1472 * Besides the name and value of each entry, the output also contains the
1473 * default value of entries if it is different from the actual value, as
1474 * well as the documenting string given to the declare_entry() function if
1475 * available.
1476 *
1477 * By using the flag <tt>Short</tt> in combination with <tt>PRM</tt>,
1478 * <tt>XML</tt>, <tt>JSON</tt>, or <tt>LaTeX</tt> (or by using the shortcuts
1479 * <tt>ShortPRM</tt>, <tt>ShortXML</tt>, <tt>ShortJSON</tt>, or
1480 * <tt>ShortLaTeX</tt>), a reduced output can be generated, only containing
1481 * the values and skipping the documentation.
1482 *
1483 * In <tt>XML</tt> format, the output starts with one root element
1484 * <tt>ParameterHandler</tt> in order to get a valid XML document and all
1485 * subsections under it.
1486 *
1487 * In <tt>LaTeX</tt> format, the output contains the same information but in
1488 * a format so that the resulting file can be input into a latex document
1489 * such as a manual for the code for which this object handles run-time
1490 * parameters. The various sections of parameters are then represented by
1491 * latex section and subsection commands as well as by nested enumerations.
1492 *
1493 * You can reference specific parameter sections and individual parameters
1494 * by the labels that are generated automatically for each entry. The
1495 * labels have the format <code>parameters:section1/subsection1</code>
1496 * and <code>parameters:section1/subsection1/someentry</code>. Because
1497 * special characters can appear in the section and entry names, these
1498 * will be "mangled". Here, all characters except <code>[a-zA-Z0-9]</code>
1499 * are replaced by <code>_XX</code>, where <code>XX</code> is the two-digit
1500 * ascii code of the character in hexadecimal encoding (so a space becomes
1501 * <code>_20</code> for example).
1502 *
1503 * While this function escapes special LaTeX-specific characters (backslash,
1504 * underscore, etc.) in most of the output (names, default values, etc.),
1505 * the documentation string is passed as-is. This means you can use math
1506 * environments and other formatting in the description, but you need
1507 * to escape quotes, backslashes, underscores, etc. yourself.
1508 *
1509 * In addition, all parameter names are listed with <code>@\index</code>
1510 * statements in two indices called <code>prmindex</code> (where the name of
1511 * each parameter is listed in the index) and <code>prmindexfull</code>
1512 * where parameter names are listed sorted by the section in which they
1513 * exist. By default, the LaTeX program ignores these <code>@\index</code>
1514 * commands, but they can be used to generate an index by using the
1515 * following commands in the preamble of the latex file:
1516 * @code
1517 * \usepackage{imakeidx}
1518 * \makeindex[name=prmindex, title=Index of run-time parameter entries]
1519 * \makeindex[name=prmindexfull,
1520 * title=Index of run-time parameters with section names]
1521 * @endcode
1522 * and at the end of the file this:
1523 * @code
1524 * \printindex[prmindex]
1525 * \printindex[prmindexfull]
1526 * @endcode
1527 */
1528 std::ostream &
1529 print_parameters(std::ostream &out, const OutputStyle style) const;
1530
1531
1532
1533 /**
1534 * Print all parameters to the file given by @p filename with the given output
1535 * style @p style.
1536 *
1537 * This function deduces the output format from the extension of the specified
1538 * filename. Supported extensions are `prm`, `xml`, `tex`, and `json`. Hence,
1539 * it is not necessary to specify an output format via the @p style argument
1540 * as long as one of these extensions is added to the filename. If an output
1541 * format is specified in the @p style parameter nevertheless, the output
1542 * format has to be consistent with the filename extension.
1543 *
1544 * If no extension is specified or the extension is not supported, the
1545 * output format is deduced from the @p style argument.
1546 *
1547 * If neither the extension is supported, nor does the @p style parameter
1548 * contain a format specification, an assertion is thrown.
1549 *
1550 * @param filename The output file name.
1551 * @param style The style with which output is produced.
1552 */
1553 void
1554 print_parameters(const std::string &filename,
1555 const OutputStyle style = DefaultStyle) const;
1556
1557 /**
1558 * Print parameters to a logstream. This function allows to print all
1559 * parameters into a log-file. Sections will be indented in the usual
1560 * log-file style.
1561 *
1562 * All current parameters and subsections are sorted
1563 * alphabetically by default.
1564 * This behavior can be disabled setting the optional parameter @p style
1565 * to <tt>KeepDeclarationOrder</tt>: in this case entries are printed in the
1566 * same order as they have been declared.
1567 *
1568 * @note All style settings in @p style not related to the ordering are
1569 * ignored.
1570 */
1571 void
1572 log_parameters(LogStream &out, const OutputStyle style = DefaultStyle);
1573
1574 /**
1575 * Log parameters in the present subsection. The subsection is determined by
1576 * the <tt>subsection_path</tt> member variable. This variable is controlled
1577 * by entering and leaving subsections through the enter_subsection() and
1578 * leave_subsection() functions.
1579 *
1580 * All current parameters and subsections are sorted
1581 * alphabetically by default.
1582 * This behavior can be disabled setting the optional parameter @p style
1583 * to <tt>KeepDeclarationOrder</tt>: in this case entries are printed in the
1584 * same order as they have been declared.
1585 *
1586 * @note All style settings in @p style not related to the ordering are
1587 * ignored.
1588 *
1589 * In most cases, you will not want to use this function directly, but have
1590 * it called recursively by the previous function.
1591 */
1592 void
1593 log_parameters_section(LogStream &out,
1594 const OutputStyle style = DefaultStyle);
1595
1596 /**
1597 * Determine an estimate for the memory consumption (in bytes) of this
1598 * object.
1599 */
1600 std::size_t
1601 memory_consumption() const;
1602
1603 /**
1604 * Write the data of this object to a stream for the purpose of
1605 * serialization using the [BOOST serialization
1606 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
1607 */
1608 template <class Archive>
1609 void
1610 save(Archive &ar, const unsigned int version) const;
1611
1612 /**
1613 * Read the data of this object from a stream for the purpose of
1614 * serialization using the [BOOST serialization
1615 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
1616 */
1617 template <class Archive>
1618 void
1619 load(Archive &ar, const unsigned int version);
1620
1621 #ifdef DOXYGEN
1622 /**
1623 * Write and read the data of this object from a stream for the purpose
1624 * of serialization using the [BOOST serialization
1625 * library](https://www.boost.org/doc/libs/1_74_0/libs/serialization/doc/index.html).
1626 */
1627 template <class Archive>
1628 void
1629 serialize(Archive &archive, const unsigned int version);
1630 #else
1631 // This macro defines the serialize() method that is compatible with
1632 // the templated save() and load() method that have been implemented.
1633 BOOST_SERIALIZATION_SPLIT_MEMBER()
1634 #endif
1635
1636 /**
1637 * Test for equality.
1638 */
1639 bool
1640 operator==(const ParameterHandler &prm2) const;
1641
1642 /**
1643 * Return a set of parameter names (including subsection names) corresponding
1644 * to those entries of the parameter handler that have not been set by one of
1645 * the functions parsing parameters from an input file or by an explicit call
1646 * to one of the set() functions, but that have been declared as mandatory
1647 * parameters that must be set (through the last argument of the
1648 * declare_entry() function or add_parameter() function).
1649 */
1650 std::set<std::string>
1651 get_entries_wrongly_not_set() const;
1652
1653 /**
1654 * Asserts that those entries of the parameter handler with flag
1655 * `has_to_be_set = true` have been set. An exception is invoked
1656 * if at least one of these parameters has not been set.
1657 */
1658 void
1659 assert_that_entries_have_been_set() const;
1660
1661 /**
1662 * @addtogroup Exceptions
1663 * @{
1664 */
1665
1666 /**
1667 * Exception
1668 */
1669 DeclException1(ExcEntryAlreadyExists,
1670 std::string,
1671 << "The following entry already exists: " << arg1 << '.');
1672
1673 /**
1674 * Exception
1675 */
1676 DeclException3(ExcEntryIsDeprecated,
1677 int,
1678 std::string,
1679 std::string,
1680 << "Line <" << arg1 << "> of file <" << arg2 << ">: "
1681 << "Entry <" << arg3 << "> is deprecated.");
1682
1683 /**
1684 * Exception
1685 */
1686 DeclException1(ExcEncounteredDeprecatedEntries,
1687 std::string,
1688 << "The following deprecated entries were encountered:\n\n"
1689 << arg1);
1690
1691 /**
1692 * Exception
1693 */
1694 DeclException2(ExcValueDoesNotMatchPattern,
1695 std::string,
1696 std::string,
1697 << "The string <" << arg1
1698 << "> does not match the given pattern <" << arg2 << ">.");
1699 /**
1700 * Exception
1701 */
1702 DeclExceptionMsg(
1703 ExcAlreadyAtTopLevel,
1704 "You can't leave a subsection if you are already at the top level "
1705 "of the subsection hierarchy.");
1706
1707 /**
1708 * Exception
1709 */
1710 DeclException1(ExcEntryUndeclared,
1711 std::string,
1712 << "You can't ask for entry <" << arg1
1713 << "> you have not yet declared.");
1714
1715 /**
1716 * Exception for when there are an unequal number of 'subsection' and 'end'
1717 * statements. The first argument is the name of the file and the second
1718 * argument is a formatted list of the subsection path before and after
1719 * entering the parser.
1720 */
1721 DeclException2(ExcUnbalancedSubsections,
1722 std::string,
1723 std::string,
1724 << "There are unequal numbers of 'subsection' and 'end' "
1725 "statements in the parameter file <"
1726 << arg1 << ">." << (arg2.size() > 0 ? "\n" + arg2 : ""));
1727
1728 /**
1729 * Exception for when, during parsing of a parameter file, the parser
1730 * encounters a subsection in the file that was not previously declared.
1731 */
1732 DeclException3(ExcNoSubsection,
1733 int,
1734 std::string,
1735 std::string,
1736 << "Line <" << arg1 << "> of file <" << arg2
1737 << ">: You are trying to enter a subsection '" << arg3
1738 << "', but the ParameterHandler object does "
1739 << "not know of any such subsection.");
1740
1741 /**
1742 * General exception for a line that could not be parsed, taking, as
1743 * arguments, the line number, file name, and a brief description of why the
1744 * line cannot be parsed.
1745 */
1746 DeclException3(ExcCannotParseLine,
1747 int,
1748 std::string,
1749 std::string,
1750 << "Line <" << arg1 << "> of file <" << arg2 << ">: " << arg3);
1751
1752 /**
1753 * Exception for an entry in a parameter file that does not match the
1754 * provided pattern. The arguments are, in order, the line number, file
1755 * name, entry value, entry name, and a description of the pattern.
1756 */
1757 DeclException5(ExcInvalidEntryForPattern,
1758 int,
1759 std::string,
1760 std::string,
1761 std::string,
1762 std::string,
1763 << "Line <" << arg1 << "> of file <" << arg2
1764 << ">:\n"
1765 " The entry value \n"
1766 << " " << arg3 << '\n'
1767 << " for the entry named\n"
1768 << " " << arg4 << '\n'
1769 << " does not match the given pattern:\n"
1770 << " " << arg5);
1771
1772 /**
1773 * Exception for when an XML file cannot be read at all. This happens when
1774 * there is no top-level XML element called "ParameterHandler" or when there
1775 * are multiple top level elements.
1776 */
1777 DeclExceptionMsg(ExcInvalidXMLParameterFile,
1778 "The provided file could not be parsed as a "
1779 "ParameterHandler description.");
1780
1781 /**
1782 * Exception for when the file given in an include statement cannot be
1783 * open. The arguments are, in order, the line number of the include
1784 * statement, current parameter file name, and the name of the file intended
1785 * for inclusion.
1786 */
1787 DeclException3(
1788 ExcCannotOpenIncludeStatementFile,
1789 int,
1790 std::string,
1791 std::string,
1792 << "Line <" << arg1 << "> of file <" << arg2
1793 << ">: This line "
1794 "contains an 'include' or 'INCLUDE' statement, but the given "
1795 "file to include <"
1796 << arg3 << "> cannot be opened.");
1797
1798 /** @} */
1799
1800 private:
1801 /**
1802 * The separator used when accessing elements of a path into the parameter
1803 * tree.
1804 */
1805 static const char path_separator = '.';
1806
1807 /**
1808 * Path of presently selected subsections; empty list means top level
1809 */
1810 std::vector<std::string> subsection_path;
1811
1812 /**
1813 * The complete tree of sections and entries. See the general documentation
1814 * of this class for a description how data is stored in this variable.
1815 *
1816 * The variable is a pointer so that we can use an incomplete type, rather
1817 * than having to include all of the property_tree stuff from boost. This
1818 * works around a problem with gcc 4.5.
1819 */
1820 std::unique_ptr<boost::property_tree::ptree> entries;
1821
1822 /**
1823 * A map that stores a pair of boolean variables for each entry
1824 * added to the parameter handler. The first bool describes whether the
1825 * parameter has to be set according to the last argument of the functions
1826 * declare_entry() or add_parameter(), and the second bool contains the
1827 * information whether the parameter has been set by any of the functions
1828 * parsing input parameters or by a set function of this class.
1829 */
1830 std::map<std::string, std::pair<bool, bool>> entries_set_status;
1831
1832 /**
1833 * A list of patterns that are used to describe the parameters of this
1834 * object. Every nodes in the property tree corresponding to a parameter
1835 * stores an index into this array.
1836 */
1837 std::vector<std::unique_ptr<const Patterns::PatternBase>> patterns;
1838
1839 /**
1840 * A list of actions that are associated with parameters. These
1841 * are added by the add_action() function. Nodes in the property
1842 * tree corresponding to individual parameters
1843 * store indices into this array in order to reference specific actions.
1844 */
1845 std::vector<std::function<void(const std::string &)>> actions;
1846
1847 /**
1848 * Scan one line of input. <tt>input_filename</tt> and
1849 * <tt>current_line_n</tt> are the name of the input file and the number of
1850 * the line presently scanned (these are used in exception messages to show
1851 * where parse errors occurred). This function will raise an exception if
1852 * the line contains an undeclared subsection or entry, if the line's entry
1853 * does not match its given pattern, or if the line could not be understood
1854 * as a valid parameter file expression.
1855 *
1856 * The function modifies its argument, but also takes it by value, so the
1857 * caller's variable is not changed.
1858 *
1859 * If @p skip_undefined is <code>true</code>, the parser
1860 * will skip undefined sections and entries. This is useful for partially
1861 * parsing a parameter file, for example to obtain only the spatial dimension
1862 * of the problem. By default all entries and subsections are expected to be
1863 * declared.
1864 */
1865 void
1866 scan_line(std::string line,
1867 const std::string &input_filename,
1868 const unsigned int current_line_n,
1869 const bool skip_undefined);
1870
1871 /**
1872 * Print out the parameters of the subsection given by the
1873 * @p target_subsection_path argument, as well as all subsections
1874 * within it recursively. This function is called from the
1875 * print_parameters() function, and is implemented for all @p style
1876 * arguments other than XML and JSON (where we can output the
1877 * entire set of parameters via BOOST functions). The @p indent_level
1878 * argument indicates how many spaces the output should be indented,
1879 * so that subsections properly nest inside the output of higher
1880 * sections.
1881 */
1882 void
1883 recursively_print_parameters(
1884 const boost::property_tree::ptree &tree,
1885 const std::vector<std::string> &target_subsection_path,
1886 const ParameterHandler::OutputStyle style,
1887 const unsigned int indent_level,
1888 std::ostream &out) const;
1889
1890 friend class MultipleParameterLoop;
1891 };
1892
1893 /**
1894 * Global operator which returns an object in which all bits are set which are
1895 * either set in the first or the second argument. This operator exists since
1896 * if it did not then the result of the bit-or <tt>operator |</tt> would be an
1897 * integer which would in turn trigger a compiler warning when we tried to
1898 * assign it to an object of type ParameterHandler::OutputStyle.
1899 */
1900 inline ParameterHandler::OutputStyle
1901 operator|(const ParameterHandler::OutputStyle f1,
1902 const ParameterHandler::OutputStyle f2)
1903 {
1904 return static_cast<ParameterHandler::OutputStyle>(
1905 static_cast<unsigned int>(f1) | static_cast<unsigned int>(f2));
1906 }
1907
1908 /**
1909 * The class MultipleParameterLoop offers an easy possibility to test several
1910 * parameter sets during one run of the program. For this it uses the
1911 * ParameterHandler class to read in data in a standardized form, searches for
1912 * variant entry values and performs a loop over all combinations of
1913 * parameters.
1914 *
1915 * Variant entry values are given like this:
1916 * @verbatim
1917 * set Time step size = { 0.1 | 0.2 | 0.3 }
1918 * @endverbatim
1919 * The loop will then perform three runs of the program, one for each value of
1920 * <tt>Time step size</tt>, while all other parameters are as specified or
1921 * with their default value. If there are several variant entry values in the
1922 * input, a loop is performed for each combination of variant values:
1923 * @verbatim
1924 * set Time step size = { 0.1 | 0.2 }
1925 * set Solver = { CG | GMRES }
1926 * @endverbatim
1927 * will result in four runs of the programs, with time step 0.1 and 0.2 for
1928 * each of the two solvers.
1929 *
1930 * In addition to variant entries, this class also supports <i>array
1931 * entries</i> that look like this:
1932 * @verbatim
1933 * set Output file = ofile.{{ 1 | 2 | 3 | 4 }}
1934 * @endverbatim
1935 * This indicates that if there are variant entries producing a total of four
1936 * different runs, then we will write their results to the files
1937 * <tt>ofile.1</tt>, <tt>ofile.2</tt>, <tt>ofile.3</tt> and <tt>ofile.4</tt>,
1938 * respectively. Array entries do not generate multiple runs of the main loop
1939 * themselves, but if there are variant entries, then in the <i>n</i>th run of
1940 * the main loop, also the <i>n</i>th value of an array is returned.
1941 *
1942 * Since the different variants are constructed in the order of declaration,
1943 * not in the order in which the variant entries appear in the input file, it
1944 * may be difficult to guess the mapping between the different variants and
1945 * the appropriate entry in an array. You will have to check the order of
1946 * declaration, or use only one variant entry.
1947 *
1948 * It is guaranteed that only selections which match the regular expression
1949 * (pattern) given upon declaration of an entry are given back to the program.
1950 * If a variant value does not match the regular expression, the default value
1951 * is stored and an error is issued. Before the first run of the loop, all
1952 * possible values are checked for their conformance, so that the error is
1953 * issued at the very beginning of the program.
1954 *
1955 *
1956 * <h3>Usage</h3>
1957 *
1958 * The usage of this class is similar to the ParameterHandler class. First the
1959 * entries and subsections have to be declared, then a loop is performed in
1960 * which the different parameter sets are set, a new instance of a user class
1961 * is created which is then called. Taking the classes of the example for the
1962 * ParameterHandler class, the extended program would look like this:
1963 * @code
1964 * class HelperClass : public MultipleParameterLoop::UserClass
1965 * {
1966 * public:
1967 * HelperClass ();
1968 *
1969 * virtual void create_new (const unsigned int run_no);
1970 * virtual void run (ParameterHandler &prm);
1971 *
1972 * static void declare_parameters (ParameterHandler &prm);
1973 * private:
1974 * std::unique_ptr<Problem> p;
1975 * };
1976 *
1977 *
1978 * HelperClass::HelperClass () : p(0) {}
1979 *
1980 *
1981 * void HelperClass::create_new (const unsigned int run_no)
1982 * {
1983 * p = std::make_unique<Problem>());
1984 * }
1985 *
1986 *
1987 * void HelperClass::declare_parameters (ParameterHandler &prm)
1988 * {
1989 * Problem::declare_parameters (prm);
1990 * }
1991 *
1992 *
1993 * void HelperClass::run (ParameterHandler &prm)
1994 * {
1995 * p->get_parameters (prm);
1996 * p->do_useful_work ();
1997 * }
1998 *
1999 *
2000 *
2001 * int main ()
2002 * {
2003 * class MultipleParameterLoop prm;
2004 * HelperClass h;
2005 * HelperClass::declare_parameters (prm);
2006 * prm.parse_input ("prmtest.prm");
2007 * prm.loop (h);
2008 * return 0;
2009 * }
2010 * @endcode
2011 *
2012 * As can be seen, first a new helper class has to be set up. This must
2013 * contain a virtual constructor for a problem class. You can also derive your
2014 * problem class from MultipleParameterLoop::UserClass and let
2015 * <tt>create_new</tt> clear all member variables. If you have access to all
2016 * inherited member variables in some way this is the recommended procedure. A
2017 * third possibility is to use multiple inheritance and derive a helper class
2018 * from both the MultipleParameterLoop::UserClass and the problem class. In
2019 * any case, <tt>create_new</tt> has to provide a clean problem object which
2020 * is the problem in the second and third possibility.
2021 *
2022 * The derived class also has to provide for member functions which declare
2023 * the entries and which run the program. Running the program includes getting
2024 * the parameters out of the ParameterHandler object.
2025 *
2026 * After defining an object of this helper class and an object of the
2027 * MultipleParameterLoop class, the entries have to be declared in the same
2028 * way as for the ParameterHandler class. Then the input has to be read.
2029 * Finally the loop is called. This executes the following steps:
2030 * @code
2031 * for (each combination)
2032 * {
2033 * UserObject.create_new (run_no);
2034 *
2035 * // set parameters for this run
2036 *
2037 * UserObject.run (*this);
2038 * }
2039 * @endcode
2040 * <tt>UserObject</tt> is the parameter to the <tt>loop</tt> function.
2041 * <tt>create_new</tt> is given the number of the run (starting from one) to
2042 * enable naming output files differently for each run.
2043 *
2044 *
2045 * <h3>Syntax for variant and array entry values</h3>
2046 *
2047 * Variant values are specified like <tt>prefix{ v1 | v2 | v3 | ...
2048 * }postfix</tt>. Whitespace to the right of the opening brace <tt>{</tt> is
2049 * ignored as well as to the left of the closing brace <tt>}</tt> while
2050 * whitespace on the respectively other side is not ignored. Whitespace around
2051 * the mid symbols <tt>|</tt> is also ignored. The empty selection <tt>prefix{
2052 * v1 | }postfix</tt> is also allowed and produces the strings
2053 * <tt>prefixv1postfix</tt> and <tt>prefixpostfix</tt>.
2054 *
2055 * The syntax for array values is equal, apart from the double braces:
2056 * <tt>prefix{{ v1 | v2 | v3 }}postfix</tt>.
2057 *
2058 *
2059 * <h3>Worked example</h3>
2060 *
2061 * Given the above extensions to the example program for the ParameterHandler
2062 * and the following input file
2063 * @verbatim
2064 * set Equation 1 = Poisson
2065 * set Equation 2 = Navier-Stokes
2066 * set Output file= results.{{ 1 | 2 | 3 | 4 | 5 | 6 }}
2067 *
2068 * subsection Equation 1
2069 * set Matrix type = Sparse
2070 * subsection Linear solver
2071 * set Solver = CG
2072 * set Maximum number of iterations = { 10 | 20 | 30 }
2073 * end
2074 * end
2075 *
2076 * subsection Equation 2
2077 * set Matrix type = Full
2078 * subsection Linear solver
2079 * set Solver = { BiCGStab | GMRES }
2080 * set Maximum number of iterations = 100
2081 * end
2082 * end
2083 * @endverbatim
2084 * this is the output:
2085 * @verbatim
2086 * LinEq: Method=CG, MaxIterations=10
2087 * LinEq: Method=BiCGStab, MaxIterations=100
2088 * Problem: outfile=results.1
2089 * eq1=Poisson, eq2=Navier-Stokes
2090 * Matrix1=Sparse, Matrix2=Full
2091 * LinEq: Method=CG, MaxIterations=20
2092 * LinEq: Method=BiCGStab, MaxIterations=100
2093 * Problem: outfile=results.2
2094 * eq1=Poisson, eq2=Navier-Stokes
2095 * Matrix1=Sparse, Matrix2=Full
2096 * LinEq: Method=CG, MaxIterations=30
2097 * LinEq: Method=BiCGStab, MaxIterations=100
2098 * Problem: outfile=results.3
2099 * eq1=Poisson, eq2=Navier-Stokes
2100 * Matrix1=Sparse, Matrix2=Full
2101 * LinEq: Method=CG, MaxIterations=10
2102 * LinEq: Method=GMRES, MaxIterations=100
2103 * Problem: outfile=results.4
2104 * eq1=Poisson, eq2=Navier-Stokes
2105 * Matrix1=Sparse, Matrix2=Full
2106 * LinEq: Method=CG, MaxIterations=20
2107 * LinEq: Method=GMRES, MaxIterations=100
2108 * Problem: outfile=results.5
2109 * eq1=Poisson, eq2=Navier-Stokes
2110 * Matrix1=Sparse, Matrix2=Full
2111 * LinEq: Method=CG, MaxIterations=30
2112 * LinEq: Method=GMRES, MaxIterations=100
2113 * Problem: outfile=results.6
2114 * eq1=Poisson, eq2=Navier-Stokes
2115 * Matrix1=Sparse, Matrix2=Full
2116 * @endverbatim
2117 * Since <tt>create_new</tt> gets the number of the run it would also be
2118 * possible to output the number of the run.
2119 *
2120 *
2121 * @ingroup input
2122 */
2123 class MultipleParameterLoop : public ParameterHandler
2124 {
2125 public:
2126 /**
2127 * This is the class the helper class or the problem class has to be derived
2128 * of.
2129 */
2130 class UserClass
2131 {
2132 public:
2133 /**
2134 * Destructor. It doesn't actually do anything, but is declared to force
2135 * derived classes to have a virtual destructor.
2136 */
2137 virtual ~UserClass() = default;
2138
2139 /**
2140 * <tt>create_new</tt> must provide a clean object, either by creating a
2141 * new one or by cleaning an old one.
2142 */
2143 virtual void
2144 create_new(const unsigned int run_no) = 0;
2145
2146 /**
2147 * Get the parameters and run any necessary action.
2148 */
2149 virtual void
2150 run(ParameterHandler &prm) = 0;
2151 };
2152
2153 /**
2154 * Constructor
2155 */
2156 MultipleParameterLoop();
2157
2158 /**
2159 * Destructor. Declare this only to have a virtual destructor, which is
2160 * safer as we have virtual functions. It actually does nothing spectacular.
2161 */
2162 virtual ~MultipleParameterLoop() override = default;
2163
2164 /**
2165 * Read input from a stream until the stream returns the <tt>eof</tt>
2166 * condition or error. The second argument can be used to denote the name of
2167 * the file (if that's what the input stream represents) we are reading
2168 * from; this is only used when creating output for error messages.
2169 *
2170 * If non-empty @p last_line is provided, the ParameterHandler object
2171 * will stop parsing lines after encountering @p last_line .
2172 * This is handy when adding extra data that shall be parsed manually.
2173 *
2174 * If @p skip_undefined is <code>true</code>, the parameter handler
2175 * will skip undefined sections and entries. This is useful for partially
2176 * parsing a parameter file, for example to obtain only the spatial dimension
2177 * of the problem. By default all entries and subsections are expected to be
2178 * declared.
2179 *
2180 * @note This is the only overload of the three <tt>parse_input</tt>
2181 * functions implemented by ParameterHandler overridden with new behavior by
2182 * this class. This is because the other two <tt>parse_input</tt> functions
2183 * just reformat their inputs and then call this version.
2184 */
2185 virtual void
2186 parse_input(std::istream &input,
2187 const std::string &filename = "input file",
2188 const std::string &last_line = "",
2189 const bool skip_undefined = false) override;
2190
2191 /**
2192 * Overriding virtual functions which are overloaded (like
2193 * ParameterHandler::parse_input, which has two different sets of input
2194 * argument types) causes the non-overridden functions to be hidden. Get
2195 * around this by explicitly using both variants of
2196 * ParameterHandler::parse_input and then overriding the one we care about.
2197 */
2198 using ParameterHandler::parse_input;
2199
2200 /**
2201 * run the central loop.
2202 */
2203 void
2204 loop(UserClass &uc);
2205
2206 /**
2207 * Determine an estimate for the memory consumption (in bytes) of this
2208 * object.
2209 */
2210 std::size_t
2211 memory_consumption() const;
2212
2213 private:
2214 /**
2215 * An object in the list of entries with multiple values.
2216 */
2217 class Entry
2218 {
2219 public:
2220 /**
2221 * Declare what a multiple entry is: a variant entry (in curly braces
2222 * <tt>{</tt>, <tt>}</tt>) or an array (in double curly braces
2223 * <tt>{{</tt>, <tt>}}</tt>).
2224 */
2225 enum MultipleEntryType
2226 {
2227 /**
2228 * A variant entry.
2229 */
2230 variant,
2231 /**
2232 * An array entry.
2233 */
2234 array
2235 };
2236
2237 /**
2238 * Constructor
2239 */
2240 Entry()
2241 : type(array)
2242 {}
2243
2244 /**
2245 * Construct an object with given subsection path, name and value. The
2246 * splitting up into the different variants is done later by
2247 * <tt>split_different_values</tt>.
2248 */
2249 Entry(const std::vector<std::string> &Path,
2250 const std::string &Name,
2251 const std::string &Value);
2252
2253 /**
2254 * Split the entry value into the different branches.
2255 */
2256 void
2257 split_different_values();
2258
2259 /**
2260 * Path to variant entry.
2261 */
2262 std::vector<std::string> subsection_path;
2263
2264 /**
2265 * Name of entry.
2266 */
2267 std::string entry_name;
2268
2269 /**
2270 * Original variant value.
2271 */
2272 std::string entry_value;
2273
2274 /**
2275 * List of entry values constructed out of what was given in the input
2276 * file.
2277 */
2278 std::vector<std::string> different_values;
2279
2280 /**
2281 * Store whether this entry is a variant entry or an array.
2282 */
2283 MultipleEntryType type;
2284
2285 /**
2286 * Determine an estimate for the memory consumption (in bytes) of this
2287 * object.
2288 */
2289 std::size_t
2290 memory_consumption() const;
2291 };
2292
2293 /**
2294 * List of variant entry values.
2295 */
2296 std::vector<Entry> multiple_choices;
2297
2298 /**
2299 * Number of branches constructed from the different combinations of the
2300 * variants. This obviously equals the number of runs to be performed.
2301 */
2302 unsigned int n_branches;
2303
2304 /**
2305 * Initialize the different branches, i.e. construct the combinations.
2306 */
2307 void
2308 init_branches();
2309
2310 /**
2311 * Traverse the section currently set by
2312 * enter_subsection()/leave_subsection() and see which of the entries are
2313 * variant or array entries. Then fill the multiple_choices variable using
2314 * this information.
2315 */
2316 void
2317 init_branches_current_section();
2318
2319 /**
2320 * Transfer the entry values for one run to the entry tree.
2321 */
2322 void
2323 fill_entry_values(const unsigned int run_no);
2324 };
2325
2326
2327 // ---------------------- inline and template functions --------------------
2328 template <class Archive>
2329 inline void
2330 ParameterHandler::save(Archive &ar, const unsigned int) const
2331 {
2332 // Forward to serialization
2333 // function in the base class.
2334 ar &static_cast<const EnableObserverPointer &>(*this);
2335
2336 ar &*entries.get();
2337
2338 std::vector<std::string> descriptions;
2339
2340 descriptions.reserve(patterns.size());
2341 for (const auto &pattern : patterns)
2342 descriptions.push_back(pattern->description());
2343
2344 ar &descriptions;
2345 }
2346
2347
2348 template <class Archive>
2349 inline void
2350 ParameterHandler::load(Archive &ar, const unsigned int)
2351 {
2352 // Forward to serialization
2353 // function in the base class.
2354 ar &static_cast<EnableObserverPointer &>(*this);
2355
2356 ar &*entries.get();
2357
2358 std::vector<std::string> descriptions;
2359 ar &descriptions;
2360
2361 patterns.clear();
2362 for (const auto &description : descriptions)
2363 patterns.push_back(Patterns::pattern_factory(description));
2364 }
2365
2366
2367 template <typename ParameterType>
2368 void
2369 ParameterHandler::add_parameter(const std::string &entry,
2370 ParameterType &parameter,
2371 const std::string &documentation,
2372 const Patterns::PatternBase &pattern,
2373 const bool has_to_be_set)
2374 {
2375 static_assert(std::is_const_v<ParameterType> == false,
2376 "You tried to add a parameter using a type "
2377 "that is const. Use a non-const type.");
2378
2379 declare_entry(entry,
2380 Patterns::Tools::Convert<ParameterType>::to_string(parameter,
2381 pattern),
2382 pattern,
2383 documentation,
2384 has_to_be_set);
2385
2386 std::string path = get_current_full_path(entry);
2387 const unsigned int pattern_index =
2388 entries->get<unsigned int>(path + path_separator + "pattern");
2389
2390 auto action = [&, pattern_index](const std::string &val) {
2391 parameter = Patterns::Tools::Convert<ParameterType>::to_value(
2392 val, *patterns[pattern_index]);
2393 };
2394 add_action(entry, action, false);
2395 }
2396
2397 DEAL_II_NAMESPACE_CLOSE
2398
2399 #endif