| 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 §ion_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 ¶meter, |
| 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 §ion_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 ¶meter, |
| 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 §ion_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 |