A parameter acceptor base class. More...
#include <parameter_acceptor.h>
Public Member Functions | |
ParameterAcceptor (const std::string section_name="") | |
The constructor adds derived classes to the list of acceptors. More... | |
virtual | ~ParameterAcceptor () |
The destructor sets to zero the pointer relative to this index, so that it is safe to destroy the mother class. More... | |
virtual void | parse_parameters (ParameterHandler &prm) |
Parse the parameter file. More... | |
virtual void | parse_parameters_call_back () |
Parse parameter call back. More... | |
virtual void | declare_parameters (ParameterHandler &) |
Generate entries in the given parameter file. More... | |
std::string | get_section_name () const |
Return the section name of this class. More... | |
std::vector< std::string > | get_section_path () const |
Travers all registered classes, and figure out what subsections we need to enter. More... | |
template<class T > | |
void | add_parameter (ParameterHandler &prm, T *parameter, const std::string &entry, const std::string &default_value, const Patterns::PatternBase &pattern=Patterns::Anything(), const std::string &documentation=std::string()) |
Add a parameter the given parameter list. More... | |
template<class T > | |
void | add_parameter (T ¶meter, const std::string &entry, const std::string &documentation=std::string(), ParameterHandler &prm=ParameterAcceptor::prm) |
Add a parameter to the global parameter handler ParameterAcceptor::prm. More... | |
void | enter_my_subsection (ParameterHandler &prm) |
Make sure we enter the right subsection of the global parameter file. More... | |
void | leave_my_subsection (ParameterHandler &prm) |
This function undoes what the enter_my_subsection() function did. More... | |
template<> | |
std_cxx11::shared_ptr< Patterns::PatternBase > | to_pattern (const double &) |
double More... | |
template<> | |
std::string | to_string (const double &entry) |
template<> | |
double | to_type (const std::string ¶meter) |
template<> | |
std_cxx11::shared_ptr< Patterns::PatternBase > | to_pattern (const int &) |
int More... | |
template<> | |
std::string | to_string (const int &entry) |
template<> | |
int | to_type (const std::string ¶meter) |
template<> | |
std_cxx11::shared_ptr< Patterns::PatternBase > | to_pattern (const unsigned int &) |
unsigned int More... | |
template<> | |
std::string | to_string (const unsigned int &entry) |
template<> | |
unsigned int | to_type (const std::string ¶meter) |
template<> | |
std_cxx11::shared_ptr< Patterns::PatternBase > | to_pattern (const bool &) |
bool More... | |
template<> | |
std::string | to_string (const bool &entry) |
template<> | |
bool | to_type (const std::string ¶meter) |
Public Member Functions inherited from Subscriptor | |
Subscriptor () | |
Subscriptor (const Subscriptor &) | |
Subscriptor (Subscriptor &&) | |
virtual | ~Subscriptor () |
Subscriptor & | operator= (const Subscriptor &) |
Subscriptor & | operator= (Subscriptor &&) |
void | subscribe (const char *identifier=0) const |
void | unsubscribe (const char *identifier=0) const |
unsigned int | n_subscriptions () const |
void | list_subscribers () const |
void | serialize (Archive &ar, const unsigned int version) |
Static Public Member Functions | |
static void | initialize (const std::string filename="", const std::string outfilename="") |
Call declare_all_parameters(), read filename (if it is present as input parameter) and parse_all_parameters() on the static member prm. More... | |
static void | clear () |
Clear class list and global parameter file. More... | |
static void | parse_all_parameters (ParameterHandler &prm=ParameterAcceptor::prm) |
Parse the given ParameterHandler. More... | |
static void | log_info () |
Print information about all stored classes. More... | |
static void | declare_all_parameters (ParameterHandler &prm=ParameterAcceptor::prm) |
Initialize the ParameterHandler with all derived classes parameters.This function enters the subsection returned by get_section_name() for each derived class, and declares all parameters that were added using add_parameter(). More... | |
template<class T > | |
static std_cxx11::shared_ptr< Patterns::PatternBase > | to_pattern (const T &) |
Given a class T, construct its default pattern to be used when declaring parameters. More... | |
template<class T > | |
static T | to_type (const std::string &) |
Given a string, fill the value of the given parameter. More... | |
template<class T > | |
static std::string | to_string (const T &) |
Given a parameter, return a string containing the given parameter. More... | |
Static Public Member Functions inherited from Subscriptor | |
static::ExceptionBase & | ExcInUse (int arg1, char *arg2, std::string &arg3) |
static::ExceptionBase & | ExcNoSubscriber (char *arg1, char *arg2) |
Static Public Attributes | |
static ParameterHandler | prm |
Static parameter. More... | |
Protected Attributes | |
const std::string | section_name |
The subsection name for this class. More... | |
Private Attributes | |
const unsigned int | acceptor_id |
The index of this specific class within the class list. More... | |
std::map< std::string, boost::any > | parameters |
A map of parameters that are initialized in this class with the functions add_parameters. More... | |
Static Private Attributes | |
static std::vector< SmartPointer< ParameterAcceptor > > | class_list |
A list containing all constructed classes of type ParameterAcceptor. More... | |
static const char | sep = '/' |
Separator between section and subsection. More... | |
A parameter acceptor base class.
This class is used to define a public interface for classes wich want to use a ParameterHandler to handle parameters. Such basic interface provides two subscription mechanisms: a global subscription mechanism and a local subscription mechanism.
The global subscription mechanism is such that whenever a class that was derived by ParameterAcceptor is constructed, a static registry (ParameterAcceptor::class_list) in the base class is updated with a pointer to the derived class. Such registry is traversed upon invocation of the single function ParameterAcceptor::initialize(file.prm) which in turn calls the method ParameterAcceptor::declare_parameters() for each of the registered classes, reads the file file.prm
(creating it first with default values if it does not exist) and subsequently calls the method ParameterAcceptor::parse_parameters(), again for each of the registered classes. The method log_info() can be used to extract informations about the classes that have been derived from ParameterAcceptor, and that will be parsed when calling ParameterAcceptor::initialize().
ParameterAcceptor conforms to the standard advocated in the deal.II
documentation, and it has a virtual method ParameterAcceptor::declare_parameters and a virtual method ParameterAcceptor::parse_parameters which can be overloaded as the user whishes. However, the base class also has a default implementation of parse_parameters which exploits a local subscription mechanism by storing in a local registry (ParameterAcceptor::parameters) a pointer to all variables that were declared through the ParameterAcceptor::add_parameter method. Such method has two flavours. In the first we use the same syntax of the ParameterHandler::add_entry method, with the addition of two arguments: a ParameterHandler object on which ParameterHandler::add_entry will be called, and a reference to the variable that should hold the entry when a ParameterHandler::get_* methods are called. The second method instead only takes a reference to the variable and to the text entry in the parameter file (with optional documentation).
The variable is stored internally in the ParameterAcceptor::parameters (local to the class instantiation) which is traversed by the default implementation of ParameterAcceptor::parse_parameters. Specialized implementations are provided for the most commonly used variable types.
Derived classes are required to use one of the add_parameter() functions, either inside a declare_paramters() function, or in the constructor of the class.
In either way, ParameterAcceptor::parse_all_parameters() will automatically populate the variables with the parsed parameters. Failure to use the add_parameter() function will result in the user having to call ParameterHandler::get() functions to populate the variables manually. If some post processing is required on the parsed values, the virtual function ParameterAcceptor::parse_parameters_call_back() can be overridden, which is called just after the parse_parameters() function of each class.
The rationale behind this class, is that we want every class to be able to declare parameters only once, and then automatically populate variables with the values from the parameter file, without having to do so manually.
A typical usage of this chain of classes is the following:
An even simpler implementation (not conforming to deal.II
advocated standards) is given by the following example:
Parameter files can be organised into section/subsection/subsubsection. To do so, the std::string passed to ParameterAcceptor within the constructor of the derived class needs to contain the separator "/". In fact, "first/second/third/My Class" will organize the parameters as follows
Let's now discuss some cases with increasing complexities in order to understand the best way to manage them with ParameterAcceptor.
MyClass is derived from ParameterAcceptor and has a member object that is derived itself from ParameterAcceptor.
In this case, the structure of the parameters will be
Note that the sections are alphabetically sorted.
Now suppose that in the main file we need two or more objects of MyClass
What we will read in the parameter file looks like
Note that there is only one section "Forcing term", this is because both objects have defined the same name for the section of their ParsedFunction. There are two strategies to manage this issue. The first one (not recommended) would be to change the name of the section of the ParsedFunction such that it contains also the string passed to the constructor of MyClass:
The other way to proceed (recommended) is to use exploit the /section/subsection approach in the main class.
Now, in the parameter file we can find
Note the "/" at the begin of the string name. This is interpreted by ParameterAcceptor like the root folder in Unix systems. This means that the sections "Class A" and "Class B" will not be nested under any section. On the other hand, if the string does not begin with a "/" as in the previous cases (and for the ParsedFunction also in this last example) the section will be created under the current path, which depends on the previously defined sections/subsections/subsubsections. Indeed, the section "Forcing term" is nested under "Class A" or "Class B". To make things more clear. let's consider the following two examples
The parameter file will have the following structure
If instead one of the paths ends with "/" instead of just a name of the class, subsequen classes will be declared under the full path, as if the class name should be interpreted as a directory:
The parameter file will have the following structure
As a final remark, in order to allow a proper management of all the sections/subsections, the instantiation of objects and the call to ParameterAcceptor::initialize() cannot be done in multithread.
As a convention, in deal2lkit
all modules derived from ParameterAcceptor implement a default constructor which takes one or more optional arguments. The first optional argument is always the name of the section in the parameter file that the derived class should use to fill its local variables. By default, the utility function deal2lkit::type is used to fill the section name with a human readable version of the class name itself. For example, according to the above example, there will be a section named MyClass. Next options are the default values that will be written in the parameter file. There is no need to specify these options, as the user can always change the content of the file to make sure that the right parameters are used at run time, but this possibility allows one to design a program that does something sensible on the first run, without having to change any parameter file.
Definition at line 380 of file parameter_acceptor.h.
ParameterAcceptor::ParameterAcceptor | ( | const std::string | section_name = "" | ) |
The constructor adds derived classes to the list of acceptors.
If a section name is specified, then this is used to scope the parameters in the given section, otherwise a pretty printed version of the derived class is used.
Definition at line 31 of file parameter_acceptor.cc.
|
virtual |
The destructor sets to zero the pointer relative to this index, so that it is safe to destroy the mother class.
Definition at line 40 of file parameter_acceptor.cc.
|
inline |
Add a parameter the given parameter list.
A pointer to the parameter is stored, so that every time the default parse_parameters() function is called, this parameter is updated with the value contained in prm.
Definition at line 495 of file parameter_acceptor.h.
|
inline |
Add a parameter to the global parameter handler ParameterAcceptor::prm.
A pointer to the parameter is stored, so that every time the default parse_parameters() function is called, this parameter is updated with the value contained in prm. The default value of the parameter is taken by the current content of the parameter, and the default Pattern is constructed using the method to_pattern().
Notice that this function has a slightly different behaviour with respect to the other add_parameter() method, since it assumes that the global parameter is always in its root section, and therefore before calling prm.add_entry() it will enter in the sections specified by this class, and leave all entered sections after having declared the variable, leaving the parameter in the same state as before, but having inserted the entry in the nested sections returned by get_section_path().
Definition at line 529 of file parameter_acceptor.h.
|
static |
Clear class list and global parameter file.
Definition at line 99 of file parameter_acceptor.cc.
|
static |
Initialize the ParameterHandler with all derived classes parameters.This function enters the subsection returned by get_section_name() for each derived class, and declares all parameters that were added using add_parameter().
Definition at line 136 of file parameter_acceptor.cc.
|
inlinevirtual |
Generate entries in the given parameter file.
Derived classes may want to overload this function. If you want to make sure the automatic assignement of variables work, you should fill this function only with calls to the add_parameter() method.
Alternatively, you could insert your calls to the add_parameter() function that takes three arguments directly in the constructor.
In this case, the ParameterAcceptor::prm parameter handler is used by default, and you don't need to overload this function. The default implementation in fact does nothing.
In general this approach is here to guarantee backward compatibility with the strategy advocated by the deal.II
library of splitting declaration and parsing of parameters into two functions.
Reimplemented in ParsedGridGenerator< dim, spacedim >, ParsedKDTreeDistance< dim >, IDAInterface< VEC >, ParsedMappedFunctions< spacedim >, ParsedFiniteElement< dim, spacedim >, ParsedDirichletBCs< dim, spacedim >, ParsedZeroAverageConstraints< dim, spacedim >, KINSOLInterface< VEC >, ParsedSolver< VECTOR >, ErrorHandler< ntables >, IMEXStepper< VEC >, ParsedQuadrature< dim >, ParsedFunction< dim >, ParsedGridRefinement, and ParsedDataOut< dim, spacedim >.
Definition at line 449 of file parameter_acceptor.h.
void ParameterAcceptor::enter_my_subsection | ( | ParameterHandler & | prm | ) |
Make sure we enter the right subsection of the global parameter file.
This function should be called when prm is in its root subsection.
Definition at line 185 of file parameter_acceptor.cc.
std::string ParameterAcceptor::get_section_name | ( | ) | const |
Return the section name of this class.
If a name was provided at construction time, then that name is returned, otherwise it returns the name of this class, pretty printed.
Definition at line 45 of file parameter_acceptor.cc.
std::vector< std::string > ParameterAcceptor::get_section_path | ( | ) | const |
Travers all registered classes, and figure out what subsections we need to enter.
Definition at line 149 of file parameter_acceptor.cc.
|
static |
Call declare_all_parameters(), read filename (if it is present as input parameter) and parse_all_parameters() on the static member prm.
If outfilename is present, then write the content that was read in to the outfilename. This is useful to get all used parameters, and not only those that were set in the input file.
Definition at line 52 of file parameter_acceptor.cc.
void ParameterAcceptor::leave_my_subsection | ( | ParameterHandler & | prm | ) |
This function undoes what the enter_my_subsection() function did.
It only makes sense if enter_my_subsection() is called before this one.
Definition at line 194 of file parameter_acceptor.cc.
|
static |
Print information about all stored classes.
Definition at line 110 of file parameter_acceptor.cc.
|
static |
Parse the given ParameterHandler.
This function enters the subsection returned by get_section_name() for each derived class, and parses all parameters that were added using add_parameter().
Definition at line 124 of file parameter_acceptor.cc.
|
virtual |
Parse the parameter file.
This function enters the subsection returned by get_section_name() for each derived class, and parse all parameters that were added using add_parameter().
Reimplemented in ParsedSolver< VECTOR >, ErrorHandler< ntables >, and ParsedFunction< dim >.
Definition at line 398 of file parameter_acceptor.cc.
|
virtual |
Parse parameter call back.
This function is called at the end of parse_parameters, to allow users to process their parameters right after they have been parsed. The default implementation is empty.
You can use this function, for example, to create a quadrature rule after you have read how many quadrature points you wanted to use from the parameter file.
Reimplemented in ParsedFiniteElement< dim, spacedim >, ParsedMappedFunctions< spacedim >, ParsedDirichletBCs< dim, spacedim >, ParsedZeroAverageConstraints< dim, spacedim >, ParsedSolver< VECTOR >, ParsedQuadrature< dim >, and ParsedDataOut< dim, spacedim >.
Definition at line 433 of file parameter_acceptor.cc.
std_cxx11::shared_ptr<Patterns::PatternBase> ParameterAcceptor::to_pattern | ( | const double & | ) |
double
Definition at line 227 of file parameter_acceptor.cc.
std_cxx11::shared_ptr<Patterns::PatternBase> ParameterAcceptor::to_pattern | ( | const int & | ) |
int
Definition at line 247 of file parameter_acceptor.cc.
std_cxx11::shared_ptr<Patterns::PatternBase> ParameterAcceptor::to_pattern | ( | const unsigned int & | ) |
unsigned int
Definition at line 267 of file parameter_acceptor.cc.
std_cxx11::shared_ptr<Patterns::PatternBase> ParameterAcceptor::to_pattern | ( | const bool & | ) |
bool
Definition at line 287 of file parameter_acceptor.cc.
|
static |
Given a class T, construct its default pattern to be used when declaring parameters.
std::string ParameterAcceptor::to_string | ( | const double & | entry | ) |
Definition at line 233 of file parameter_acceptor.cc.
std::string ParameterAcceptor::to_string | ( | const int & | entry | ) |
Definition at line 253 of file parameter_acceptor.cc.
std::string ParameterAcceptor::to_string | ( | const unsigned int & | entry | ) |
Definition at line 273 of file parameter_acceptor.cc.
std::string ParameterAcceptor::to_string | ( | const bool & | entry | ) |
Definition at line 293 of file parameter_acceptor.cc.
|
static |
Given a parameter, return a string containing the given parameter.
double ParameterAcceptor::to_type | ( | const std::string & | parameter | ) |
Definition at line 239 of file parameter_acceptor.cc.
int ParameterAcceptor::to_type | ( | const std::string & | parameter | ) |
Definition at line 259 of file parameter_acceptor.cc.
unsigned int ParameterAcceptor::to_type | ( | const std::string & | parameter | ) |
Definition at line 279 of file parameter_acceptor.cc.
bool ParameterAcceptor::to_type | ( | const std::string & | parameter | ) |
Definition at line 299 of file parameter_acceptor.cc.
|
static |
Given a string, fill the value of the given parameter.
|
private |
The index of this specific class within the class list.
Definition at line 592 of file parameter_acceptor.h.
|
staticprivate |
A list containing all constructed classes of type ParameterAcceptor.
Definition at line 589 of file parameter_acceptor.h.
|
mutableprivate |
A map of parameters that are initialized in this class with the functions add_parameters.
Definition at line 598 of file parameter_acceptor.h.
|
static |
Static parameter.
This is used if the user does not provide one.
Definition at line 582 of file parameter_acceptor.h.
|
protected |
The subsection name for this class.
Definition at line 607 of file parameter_acceptor.h.
|
staticprivate |
Separator between section and subsection.
Definition at line 603 of file parameter_acceptor.h.