Debian Codegraph @

include/deal.II/base/parameter_acceptor.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2017 - 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_base_parameter_acceptor_h
16 #define dealii_base_parameter_acceptor_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/exceptions.h>
21 #include <deal.II/base/observer_pointer.h>
22 #include <deal.II/base/parameter_handler.h>
23
24 #include <boost/signals2/signal.hpp>
25
26 #include <mutex>
27 #include <set>
28 #include <typeinfo>
29
30 DEAL_II_NAMESPACE_OPEN
31
32 class ParameterAcceptor;
33
34 namespace internal
35 {
36 /**
37 * Compare operator between two parameter acceptors. Same as std::less applied
38 * to the acceptor ids of each instance.
39 */
40 struct ParameterAcceptorCompare;
41 } // namespace internal
42
43 /**
44 * A parameter acceptor base class. This class is used to define a public
45 * interface for classes which want to use a single global ParameterHandler to
46 * handle parameters. This class declares one static ParameterHandler, and two
47 * static functions (declare_all_parameters() and parse_all_parameters()) that
48 * manage all of the derived classes.
49 *
50 * The basic interface provides two subscription mechanisms: a **global
51 * subscription mechanism** and a **local subscription mechanism**.
52 *
53 * The global subscription mechanism is such that whenever an object of a class
54 * derived from ParameterAcceptor is created, then a pointer to that
55 * object-of-derived-type is registered, together with a path in the parameter
56 * file.
57 *
58 * Such registry is traversed upon invocation of the single function
59 * ParameterAcceptor::initialize("file.prm") which in turn calls the method
60 * ParameterAcceptor::declare_parameters() for each of the registered classes,
61 * reads the file `file.prm` and subsequently calls the method
62 * ParameterAcceptor::parse_parameters(), again for each of the registered
63 * classes. The method log_info() can be used to extract information about the
64 * classes that have been derived from ParameterAcceptor, and that will be
65 * parsed when calling ParameterAcceptor::initialize().
66 *
67 * ParameterAcceptor can be used in three different ways: by overloading the
68 * ParameterAcceptor::declare_parameters() and
69 * ParameterAcceptor::parse_parameters() methods, by calling its
70 * ParameterAcceptor::add_parameter() method for each parameter we want to
71 * have, or by constructing a ParameterAcceptorProxy class with your own class,
72 * provided that your class implements the @p declare_parameters and
73 * @p parse_parameters functions (the first can be a static member in this
74 * case).
75 *
76 * By using the add_parameter method, ParameterAcceptor makes sure that the
77 * given parameter is registered in the global parameter handler (by calling
78 * ParameterHandler::add_parameter()), at the correct path. If you define all
79 * your parameters using the ParameterAcceptor::add_parameter() method, then
80 * you don't need to overload any of the virtual methods of this class.
81 *
82 * If some post processing is required on the parsed values, the user can
83 * attach a signal to ParameterAcceptor::declare_parameters_call_back and
84 * ParameterAcceptor::parse_parameters_call_back, that are called just after
85 * the declare_parameters() and parse_parameters() functions of each derived
86 * class. step-69 has an example of doing this.
87 *
88 * A typical usage of this class is the following:
89 *
90 * @code
91 * // This is your own class, derived from ParameterAcceptor
92 * class MyClass : public ParameterAcceptor
93 * {
94 * // The constructor of ParameterAcceptor requires a std::string,
95 * // which defines the section name where the parameters of MyClass
96 * // will be stored.
97 * MyClass()
98 * : ParameterAcceptor("Some class name")
99 * {
100 * add_parameter("A param", member_var);
101 * }
102 *
103 * private:
104 * std::vector<unsigned int> member_var;
105 * ...
106 * };
107 *
108 * int main()
109 * {
110 * // Make sure you create your object BEFORE calling
111 * // ParameterAcceptor::initialize()
112 * MyClass class;
113 *
114 * // With this call, all derived classes will have their
115 * // parameters initialized
116 * ParameterAcceptor::initialize("file.prm");
117 * }
118 * @endcode
119 *
120 * An implementation that uses user defined declare and parse functions is given
121 * by the following example:
122 *
123 * @code
124 * // Again your own class, derived from ParameterAcceptor
125 * //
126 * // If you don't pass anything to the constructor of
127 * // ParameterAcceptor, then the class name is used, "MyClass"
128 * // in this case
129 * class MyClass : public ParameterAcceptor
130 * {
131 * virtual void declare_parameters(ParameterHandler &prm)
132 * {
133 * ...
134 * }
135 *
136 * virtual void parse_parameters(ParameterHandler &prm)
137 * {
138 * ...
139 * }
140 * };
141 *
142 * int main()
143 * {
144 * // Make sure you create your object BEFORE calling
145 * // ParameterAcceptor::initialize()
146 * MyClass class;
147 * ParameterAcceptor::initialize("file.prm");
148 * class.run();
149 * }
150 * @endcode
151 *
152 *
153 * Parameter files can be organised into section/subsection/subsubsection.
154 * To do so, the std::string passed to ParameterAcceptor within the
155 * constructor of the derived class needs to contain the separator "/".
156 * In fact, "first/second/third/My Class" will organize the parameters
157 * as follows
158 *
159 * @code
160 * subsection first
161 * subsection second
162 * subsection third
163 * subsection My Class
164 * ... # all the parameters
165 * end
166 * end
167 * end
168 * end
169 * @endcode
170 *
171 * In the following examples, we propose some use cases with increasing
172 * complexities.
173 *
174 * MyClass is derived from ParameterAcceptor and has a
175 * member object that is derived itself from ParameterAcceptor.
176 * @code
177 * class MyClass : public ParameterAcceptor
178 * {
179 * MyClass (std::string name);
180 * virtual void declare_parameters(ParameterHandler &prm);
181 * private:
182 * SomeParsedClass<dim> my_subclass;
183 * ...
184 * };
185 *
186 * MyClass::MyClass(std::string name)
187 * : ParameterAcceptor(name)
188 * , my_subclass("Forcing term")
189 * {}
190 *
191 * void MyClass::declare_parameters(ParameterHandler &prm)
192 * {
193 * // many add_parameter(...);
194 * }
195 *
196 * ...
197 *
198 * int main()
199 * {
200 * MyClass mc("My Class");
201 * ParameterAcceptor::initialize("file.prm");
202 * }
203 * @endcode
204 *
205 * In this case, the structure of the parameters will be
206 * @code
207 * subsection Forcing term
208 * ... #parameters of SomeParsedClass
209 * end
210 * subsection My class
211 * ... #all the parameters of MyClass defined in declare_parameters
212 * end
213 * @endcode
214 *
215 * Now suppose that in the main file we need two or more objects of MyClass
216 * @code
217 * int main()
218 * {
219 * MyClass ca("Class A");
220 * MyClass cb("Class B");
221 * ParameterAcceptor::initialize("file.prm");
222 * }
223 * @endcode
224 *
225 * What we will read in the parameter file looks like
226 * @code
227 * subsection Class A
228 * ...
229 * end
230 * subsection Class B
231 * ...
232 * end
233 * subsection Forcing term
234 * ...
235 * end
236 * @endcode
237 * Note that there is only one section "Forcing term", this is because
238 * both objects have defined the same name for the section of their
239 * SomeParsedClass. There are two strategies to change this behavior. The
240 * first one (not recommended) would be to change the name of the section
241 * of SomeParsedClass such that it contains also the string passed to
242 * the constructor of MyClass:
243 * @code
244 * MyClass::MyClass(std::string name)
245 * : ParameterAcceptor(name)
246 * , my_subclass(name+" --- forcing term")
247 * {}
248 * @endcode
249 *
250 * The other way to proceed (recommended) is to use exploit the
251 * /section/subsection approach **in the main class**.
252 * @code
253 * int main()
254 * {
255 * MyClass ca("/Class A/Class");
256 * MyClass cb("/Class B/Class");
257 * ParameterAcceptor::initialize("file.prm");
258 * }
259 * @endcode
260 * Now, in the parameter file we can find
261 * @code
262 * subsection Class A
263 * subsection Class
264 * ...
265 * end
266 * subsection Forcing term
267 * ...
268 * end
269 * end
270 * subsection Class B
271 * subsection Class
272 * ...
273 * end
274 * subsection Forcing term
275 * ...
276 * end
277 * end
278 * @endcode
279 *
280 * Note the "/" at the begin of the string name. This is interpreted by
281 * ParameterAcceptor like the root folder in Unix systems. The sections "Class
282 * A" and "Class B" will not be nested under any section. On the other hand, if
283 * the string does not begin with a "/" as in the previous cases the section
284 * will be created **under the current path**, which depends on the previously
285 * defined sections/subsections/subsubsections. Indeed, the section "Forcing
286 * term" is nested under "Class A" or "Class B". To make things more clear.
287 * let's consider the following two examples
288 *
289 * @code
290 * int main()
291 * {
292 * MyClass ca("/Class A/Class");
293 * MyClass cb("Class B/Class");
294 * ParameterAcceptor::initialize("file.prm");
295 * }
296 * @endcode
297 * The parameter file will have the following structure
298 * @code
299 * subsection Class A
300 * subsection Class
301 * ...
302 * end
303 * subsection Forcing term
304 * ...
305 * end
306 * subsection Class B
307 * subsection Class
308 * ...
309 * end
310 * subsection Forcing term
311 * ...
312 * end
313 * end
314 * end
315 * @endcode
316 *
317 * If instead one of the paths ends with "/" instead of just
318 * a name of the class, subsequent classes will interpret this as
319 * a full path, interpreting the class name as a directory name:
320 * @code
321 * int main()
322 * {
323 * MyClass ca("/Class A/Class/");
324 * MyClass cb("Class B/Class");
325 * ParameterAcceptor::initialize("file.prm");
326 * }
327 * @endcode
328 * The parameter file will have the following structure
329 * @code
330 * subsection Class A
331 * subsection Class
332 * ...
333 * subsection Forcing term
334 * ...
335 * end
336 * subsection Class B
337 * subsection Class
338 * ...
339 * end
340 * subsection Forcing term
341 * ...
342 * end
343 * end
344 * end
345 * end
346 * @endcode
347 *
348 * As a final remark, in order to allow a proper management of all the
349 * sections/subsections, the instantiation of objects and the call to
350 * ParameterAcceptor::initialize() cannot be done on multiple, concurrently
351 * running threads.
352 *
353 * If you pass an empty name, the boost::core::demangle() function is used to
354 * fill the section name with a human readable version of the class name
355 * itself.
356 *
357 * See the tutorial program step-60 for an example on how to use this class.
358 */
359 class ParameterAcceptor : public EnableObserverPointer
360 {
361 public:
362 /**
363 * The constructor adds derived classes to the list of acceptors. If
364 * a section name is specified, then this is used to scope the
365 * parameters in the given section, otherwise a pretty printed
366 * version of the derived class is used.
367 */
368 ParameterAcceptor(const std::string &section_name = "");
369
370 /**
371 * Get the acceptor id of this object.
372 */
373 unsigned int
374 get_acceptor_id() const;
375
376 /**
377 * Destructor.
378 */
379 virtual ~ParameterAcceptor() override;
380
381 /**
382 * Call declare_all_parameters(), read the parameters from `filename` (only
383 * if `filename` is a non-empty string), and then call
384 * parse_all_parameters().
385 *
386 * If the parameter `filename` is the empty string, then no attempt to read a
387 * parameter file is done. This may be useful if you are ok with using
388 * default values, and don't want to read external files to use a class
389 * derived from ParameterAcceptor.
390 *
391 * If @p output_filename is not the empty string, then we write the content
392 * that was read into the @p output_filename file, using the style specified
393 * in @p output_style_for_output_filename. The format of both input and output
394 * files are selected using the extensions of the files themselves. This can
395 * be either `prm`, `xml`, or `json` for the @p filename, and any of the
396 * supported formats for the @p output_filename.
397 *
398 * If the input file does not exist, a default one with the same name is
399 * created for you following the style specified in
400 * @p output_style_for_filename, and an exception is thrown.
401 *
402 * By default, the file format used to write the files is deduced from
403 * the extension of the file names. If the corresponding
404 * ParameterHandler::OutputStyle specifies a format specification, this must
405 * be compatible with the file extension, or an exception will be thrown.
406 *
407 * If the extension is not recognized, and you do not specify a format in the
408 * corresponding ParameterHandler::OutputStyle, an assertion is thrown.
409 *
410 * @param filename Input file name
411 * @param output_filename Output file name
412 * @param output_style_for_output_filename How to write the output file
413 * @param prm The ParameterHandler to use
414 * @param output_style_for_filename How to write the default input file if it
415 * does not exist
416 */
417 static void
418 initialize(const std::string &filename = "",
419 const std::string &output_filename = "",
420 const ParameterHandler::OutputStyle
421 output_style_for_output_filename = ParameterHandler::Short,
422 ParameterHandler &prm = ParameterAcceptor::prm,
423 const ParameterHandler::OutputStyle output_style_for_filename =
424 ParameterHandler::DefaultStyle);
425
426 /**
427 * Call declare_all_parameters(), read the parameters from the `input_stream`
428 * in `prm` format, and then call parse_all_parameters().
429 *
430 * An exception is thrown if the `input_stream` is invalid.
431 *
432 * @param input_stream Input stream
433 * @param prm The ParameterHandler to use
434 */
435 static void
436 initialize(std::istream &input_stream,
437 ParameterHandler &prm = ParameterAcceptor::prm);
438
439
440 /**
441 * Clear class list and global parameter file.
442 */
443 static void
444 clear();
445
446 /**
447 * Derived classes can use this method to declare their parameters.
448 * ParameterAcceptor::initialize() calls it for each derived class. The
449 * default implementation is empty.
450 */
451 virtual void
452 declare_parameters(ParameterHandler &prm);
453
454 /**
455 * Declare parameter call back. This signal is triggered right after
456 * declare_parameters() has been called, to allow users to prepare their
457 * variables right after parameters have been declared. The default
458 * implementation is empty.
459 */
460 boost::signals2::signal<void()> declare_parameters_call_back;
461
462 /**
463 * Derived classes can use this method to parse their parameters.
464 * ParameterAcceptor::initialize() calls it for each derived class. The
465 * default implementation is empty.
466 */
467 virtual void
468 parse_parameters(ParameterHandler &prm);
469
470 /**
471 * Parse parameter call back. This function is called at the end of
472 * parse_parameters(), to allow users to process their parameters right after
473 * they have been parsed. The default implementation is empty.
474 *
475 * You can use this function, for example, to create a quadrature rule after
476 * you have read how many quadrature points you wanted to use from the
477 * parameter file.
478 */
479 boost::signals2::signal<void()> parse_parameters_call_back;
480
481 /**
482 * Parse the given ParameterHandler. This function enters the
483 * subsection returned by get_section_name() for each derived class,
484 * and parses all parameters that were added using add_parameter().
485 */
486 static void
487 parse_all_parameters(ParameterHandler &prm = ParameterAcceptor::prm);
488
489 /**
490 * Initialize the global ParameterHandler with all derived classes
491 * parameters.This function enters the subsection returned by
492 * get_section_name() for each derived class, and declares all parameters
493 * that were added using add_parameter().
494 */
495 static void
496 declare_all_parameters(ParameterHandler &prm = ParameterAcceptor::prm);
497
498 /**
499 * Return the section name of this class. If a name was provided
500 * at construction time, then that name is returned, otherwise it
501 * returns the demangled name of this class.
502 */
503 std::string
504 get_section_name() const;
505
506 /**
507 * Traverse all registered classes, and figure out what subsections we need to
508 * enter.
509 */
510 std::vector<std::string>
511 get_section_path() const;
512
513 /**
514 * Add a parameter in the correct path. This method forwards all arguments to
515 * the prm.add_parameter() method, after entering the correct section path.
516 * By default it uses the ParameterAcceptor::prm variable as
517 * ParameterHandler.
518 *
519 * See the documentation of ParameterHandler::add_parameter() for more
520 * information.
521 */
522 template <typename ParameterType>
523 void
524 add_parameter(const std::string &entry,
525 ParameterType &parameter,
526 const std::string &documentation = "",
527 ParameterHandler &prm_ = prm,
528 const Patterns::PatternBase &pattern =
529 *Patterns::Tools::Convert<ParameterType>::to_pattern());
530
531 /**
532 * The global parameter handler.
533 */
534 static ParameterHandler prm;
535
536 /**
537 * Add the given @p subsection to the global path stored in this class.
538 *
539 * This function changes the behavior of enter_my_subsection(), by
540 * appending a new subsection to the path stored in this class.
541 *
542 * This method can be used to split the parameters of this class into
543 * subsections, while still maintaining the general behavior of this
544 * class.
545 *
546 * An example usage is given by the following snippet:
547 * @code
548 * class MyClass : public ParameterAcceptor
549 * {
550 * MyClass()
551 * : ParameterAcceptor("Main section")
552 * {
553 * add_parameter("A param", member_var);
554 * enter_subsection("New section");
555 * add_parameter("Another param", another_member_var);
556 * leave_subsection();
557 * }
558 *
559 * private:
560 * std::vector<unsigned int> member_var = {1,2};
561 * std::map<types::boundary_id, std::string> another_member_var;
562 * ...
563 * };
564 *
565 * int main()
566 * {
567 * // ParameterAcceptor::initialize()
568 * MyClass class;
569 *
570 * // With this call, all derived classes will have their
571 * // parameters initialized
572 * ParameterAcceptor::initialize("file.prm");
573 * }
574 * @endcode
575 *
576 * which will produce a parameter file organized as
577 *
578 * @code
579 * subsection Main section
580 * set A param = 1, 2
581 * subsection New section
582 * set Another param =
583 * end
584 * end
585 * @endcode
586 */
587 void
588 enter_subsection(const std::string &subsection);
589
590 /**
591 * Leave the subsection that was entered by calling the enter_subsection()
592 * function.
593 */
594 void
595 leave_subsection();
596
597 /**
598 * Make sure we enter the right subsection of the given parameter.
599 */
600 void
601 enter_my_subsection(ParameterHandler &prm);
602
603 /**
604 * This function undoes what the enter_my_subsection() function did. It only
605 * makes sense if enter_my_subsection() was called on `prm` before this one.
606 */
607 void
608 leave_my_subsection(ParameterHandler &prm);
609
610 private:
611 /**
612 * Get the next free id for this class.
613 */
614 static unsigned int
615 get_next_free_id();
616
617 /**
618 * A mutex to prevent writing on the class_list set from multiple threads.
619 */
620 static std::mutex class_list_mutex;
621
622 /**
623 * A set containing the address of all constructed classes of type
624 * ParameterAcceptor.
625 */
626 static std::set<ParameterAcceptor *, internal::ParameterAcceptorCompare>
627 class_list;
628
629 /** The id of this specific class instance. */
630 const unsigned int acceptor_id;
631
632 /**
633 * Separator between sections.
634 */
635 static const char sep = '/';
636
637 protected:
638 /** The subsection name for this class. */
639 const std::string section_name;
640
641 /** The subsubsections that are currently active. */
642 std::vector<std::string> subsections;
643 };
644
645
646
647 /**
648 * A proxy ParameterAcceptor wrapper for classes that have a static member
649 * function @p declare_parameters, and a non virtual @p parse_parameters method.
650 *
651 * If you cannot or do not want to derive your "parameter accepting" class from
652 * ParameterAcceptor, for example if by design you are required to have a
653 * static member function @p declare_parameters and a member @p
654 * parse_parameters, or if someone has already implemented such a class for
655 * you, and only provides you with an API that you cannot modify, then you may
656 * be able to use ParameterAcceptor facilities nonetheless, by wrapping your
657 * class into ParameterAcceptorProxy.
658 *
659 * This class implements the public interface of ParameterAcceptor, and at the
660 * same time it derives from the template class @p SourceClass, allowing you to
661 * register your existing @p SourceClass as a ParameterAcceptor class, without
662 * requiring you to explicitly derive your @p SourceClass from
663 * ParameterAcceptor.
664 *
665 * An example usage is given by the following snippet of code, using
666 * Functions::ParsedFunction as an example source class:
667 *
668 * @code
669 * ParameterAcceptorProxy<Functions::ParsedFunction<2> > fun("Some function");
670 * ParameterAcceptor::initialize("test.prm");
671 * @endcode
672 *
673 * The above snippet of code will initialize ParameterAcceptor::prm with a
674 * section "Some function", and will correctly parse and assign to the object
675 * `fun` the expression parsed from the file `test.prm`. If non-existent, the
676 * program will exit, and generate it for you (here you can see the resulting
677 * short text version of the parameter file generated with the above snippet):
678 *
679 * @code
680 * # Parameter file generated with
681 * # DEAL_II_PACKAGE_VERSION = 9.0.0-pre
682 * subsection Some function
683 * set Function constants =
684 * set Function expression = 0
685 * set Variable names = x,y,t
686 * end
687 * @endcode
688 *
689 * The resulting `fun` object, is both a ParsedFunction object and a
690 * ParameterAcceptor one, allowing you to use it as a replacement of the
691 * ParsedFunction class, with automatic declaration and parsing of parameter
692 * files.
693 *
694 * See the tutorial program step-60 for an example on how to use this class.
695 */
696 template <class SourceClass>
697 class ParameterAcceptorProxy : public SourceClass, public ParameterAcceptor
698 {
699 public:
700 /**
701 * Default constructor. The argument `section_name` is forwarded to the
702 * constructor of the ParameterAcceptor class, while all other arguments
703 * are passed to the SourceClass constructor.
704 */
705 template <typename... Args>
706 ParameterAcceptorProxy(const std::string &section_name, Args... args);
707
708 /**
709 * Overloads the ParameterAcceptor::declare_parameters function, by calling
710 * @p SourceClass::declare_parameters with @p prm as an argument.
711 */
712 virtual void
713 declare_parameters(ParameterHandler &prm) override;
714
715 /**
716 * Overloads the ParameterAcceptor::parse_parameters function, by calling
717 * @p SourceClass::parse_parameters with @p prm as an argument.
718 */
719 virtual void
720 parse_parameters(ParameterHandler &prm) override;
721 };
722
723
724
725 // Inline and template functions
726 template <typename ParameterType>
727 void
728 ParameterAcceptor::add_parameter(const std::string &entry,
729 ParameterType &parameter,
730 const std::string &documentation,
731 ParameterHandler &prm,
732 const Patterns::PatternBase &pattern)
733 {
734 enter_my_subsection(prm);
735 prm.add_parameter(entry, parameter, documentation, pattern);
736 leave_my_subsection(prm);
737 }
738
739
740
741 template <class SourceClass>
742 template <typename... Args>
743 ParameterAcceptorProxy<SourceClass>::ParameterAcceptorProxy(
744 const std::string &section_name,
745 Args... args)
746 : SourceClass(args...)
747 , ParameterAcceptor(section_name)
748 {}
749
750
751
752 template <class SourceClass>
753 void
754 ParameterAcceptorProxy<SourceClass>::declare_parameters(ParameterHandler &prm)
755 {
756 SourceClass::declare_parameters(prm);
757 }
758
759
760
761 template <class SourceClass>
762 void
763 ParameterAcceptorProxy<SourceClass>::parse_parameters(ParameterHandler &prm)
764 {
765 SourceClass::parse_parameters(prm);
766 }
767
768 DEAL_II_NAMESPACE_CLOSE
769
770 #endif