deal2lkit: A ToolKit library for Deal.II
ParameterAcceptor Class Reference

A parameter acceptor base class. More...

#include <parameter_acceptor.h>

Inheritance diagram for ParameterAcceptor:
Subscriptor ErrorHandler< ntables > IDAInterface< VEC > IMEXStepper< VEC > KINSOLInterface< VEC > ParsedDataOut< dim, spacedim > ParsedFiniteElement< dim, spacedim > ParsedFunction< dim > ParsedGridGenerator< dim, spacedim > ParsedGridRefinement ParsedKDTreeDistance< dim > ParsedMappedFunctions< spacedim > ParsedQuadrature< dim > ParsedSolver< VECTOR > ParsedZeroAverageConstraints< dim, spacedim >

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 &parameter, 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::PatternBaseto_pattern (const double &)
 double More...
 
template<>
std::string to_string (const double &entry)
 
template<>
double to_type (const std::string &parameter)
 
template<>
std_cxx11::shared_ptr< Patterns::PatternBaseto_pattern (const int &)
 int More...
 
template<>
std::string to_string (const int &entry)
 
template<>
int to_type (const std::string &parameter)
 
template<>
std_cxx11::shared_ptr< Patterns::PatternBaseto_pattern (const unsigned int &)
 unsigned int More...
 
template<>
std::string to_string (const unsigned int &entry)
 
template<>
unsigned int to_type (const std::string &parameter)
 
template<>
std_cxx11::shared_ptr< Patterns::PatternBaseto_pattern (const bool &)
 bool More...
 
template<>
std::string to_string (const bool &entry)
 
template<>
bool to_type (const std::string &parameter)
 
- Public Member Functions inherited from Subscriptor
 Subscriptor ()
 
 Subscriptor (const Subscriptor &)
 
 Subscriptor (Subscriptor &&)
 
virtual ~Subscriptor ()
 
Subscriptoroperator= (const Subscriptor &)
 
Subscriptoroperator= (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::PatternBaseto_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...
 

Detailed Description

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:

// This is your own class, derived from ParameterAcceptor
class MyClass : public ParameterAcceptor {
// The constructor of ParameterAcceptor requires a std::string,
// which defines the section name where the parameters of MyClass
// will be stored.
MyClass(std::string name) :
{}
add_parameters(prm, &member_var, "A param", "Default value");
}
...
};
int main() {
// Make sure you build your class BEFORE calling
// ParameterAcceptor::initialize()
MyClass class;
// With this call, all derived classes will have their
// parameters initialized
}

An even simpler implementation (not conforming to deal.II advocated standards) is given by the following example:

// Again your own class, derived from ParameterAcceptor
class MyClass : public ParameterAcceptor {
// We now fill the parameters inside the constructor
MyClass(std::string name) :
{
add_parameter(&member_var, "A param", "Documentation");
add_parameter(&another_member_var, "Another param");
}
...
};
int main() {
// Make sure you build your class BEFORE calling
// ParameterAcceptor::initialize()
MyClass class;
class.run();
}

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

subsection first
subsection second
subsection third
subsection My Class
... # all the parameters
end
end
end
end

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.

class MyClass : public ParameterAcceptor
{
MyClass (std::string name);
private:
...
};
MyClass::MyClass(std::string name)
:
function("Forcing term")
{}
void MyClass::declare_parmeters(ParameterHandler &prm)
{
// many add_parameter(...);
}
...
int main()
{
MyClass mc("My Class");
}

In this case, the structure of the parameters will be

subsection Forcing term
end
subsection My class
... #all the parameters of MyClass defined in declare_parameters
end

Note that the sections are alphabetically sorted.

Now suppose that in the main file we need two or more objects of MyClass

int main()
{
MyClass ca("Class A");
MyClass cb("Class B");
}

What we will read in the parameter file looks like

subsection Class A
...
end
subsection Class B
...
end
subsection Forcing term
...
end

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:

MyClass::MyClass(std::string name)
:
function(name+" --- forcing term")
{}

The other way to proceed (recommended) is to use exploit the /section/subsection approach in the main class.

int main()
{
MyClass ca("/Class A/Class");
MyClass cb("/Class B/Class");
}

Now, in the parameter file we can find

subsection Class A
subsection Class
...
end
subsection Forcing term
...
end
end
subsection Class B
subsection Class
...
end
subsection Forcing term
...
end
end

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

int main()
{
MyClass ca("/Class A/Class");
MyClass cb("Class B/Class");
}

The parameter file will have the following structure

subsection Class A
subsection Class
...
end
subsection Forcing term
...
end
subsection Class B
subsection Class
...
end
subsection Forcing term
...
end
end
end

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:

int main()
{
MyClass ca("/Class A/Class/");
MyClass cb("Class B/Class");
}

The parameter file will have the following structure

subsection Class A
subsection Class
...
subsection Forcing term
...
end
subsection Class B
subsection Class
...
end
subsection Forcing term
...
end
end
end
end

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.

Constructor & Destructor Documentation

§ ParameterAcceptor()

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.

§ ~ParameterAcceptor()

ParameterAcceptor::~ParameterAcceptor ( )
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.

Member Function Documentation

§ add_parameter() [1/2]

template<class T >
void ParameterAcceptor::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() 
)
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.

§ add_parameter() [2/2]

template<class T >
void ParameterAcceptor::add_parameter ( T &  parameter,
const std::string &  entry,
const std::string &  documentation = std::string(),
ParameterHandler prm = ParameterAcceptor::prm 
)
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.

§ clear()

void ParameterAcceptor::clear ( )
static

Clear class list and global parameter file.

Definition at line 99 of file parameter_acceptor.cc.

§ declare_all_parameters()

void ParameterAcceptor::declare_all_parameters ( ParameterHandler prm = ParameterAcceptor::prm)
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.

§ declare_parameters()

virtual void ParameterAcceptor::declare_parameters ( ParameterHandler )
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.

§ enter_my_subsection()

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.

§ get_section_name()

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.

§ get_section_path()

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.

§ initialize()

void ParameterAcceptor::initialize ( const std::string  filename = "",
const std::string  outfilename = "" 
)
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.

§ leave_my_subsection()

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.

§ log_info()

void ParameterAcceptor::log_info ( )
static

Print information about all stored classes.

Definition at line 110 of file parameter_acceptor.cc.

§ parse_all_parameters()

void ParameterAcceptor::parse_all_parameters ( ParameterHandler prm = ParameterAcceptor::prm)
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.

§ parse_parameters()

void ParameterAcceptor::parse_parameters ( ParameterHandler prm)
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.

§ parse_parameters_call_back()

void ParameterAcceptor::parse_parameters_call_back ( )
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.

§ to_pattern() [1/5]

template<>
std_cxx11::shared_ptr<Patterns::PatternBase> ParameterAcceptor::to_pattern ( const double &  )

double

Definition at line 227 of file parameter_acceptor.cc.

§ to_pattern() [2/5]

template<>
std_cxx11::shared_ptr<Patterns::PatternBase> ParameterAcceptor::to_pattern ( const int &  )

int

Definition at line 247 of file parameter_acceptor.cc.

§ to_pattern() [3/5]

template<>
std_cxx11::shared_ptr<Patterns::PatternBase> ParameterAcceptor::to_pattern ( const unsigned int &  )

unsigned int

Definition at line 267 of file parameter_acceptor.cc.

§ to_pattern() [4/5]

template<>
std_cxx11::shared_ptr<Patterns::PatternBase> ParameterAcceptor::to_pattern ( const bool &  )

bool

Definition at line 287 of file parameter_acceptor.cc.

§ to_pattern() [5/5]

template<class T >
static std_cxx11::shared_ptr<Patterns::PatternBase> ParameterAcceptor::to_pattern ( const T &  )
static

Given a class T, construct its default pattern to be used when declaring parameters.

§ to_string() [1/5]

template<>
std::string ParameterAcceptor::to_string ( const double &  entry)

Definition at line 233 of file parameter_acceptor.cc.

§ to_string() [2/5]

template<>
std::string ParameterAcceptor::to_string ( const int &  entry)

Definition at line 253 of file parameter_acceptor.cc.

§ to_string() [3/5]

template<>
std::string ParameterAcceptor::to_string ( const unsigned int &  entry)

Definition at line 273 of file parameter_acceptor.cc.

§ to_string() [4/5]

template<>
std::string ParameterAcceptor::to_string ( const bool &  entry)

Definition at line 293 of file parameter_acceptor.cc.

§ to_string() [5/5]

template<class T >
static std::string ParameterAcceptor::to_string ( const T &  )
static

Given a parameter, return a string containing the given parameter.

§ to_type() [1/5]

template<>
double ParameterAcceptor::to_type ( const std::string &  parameter)

Definition at line 239 of file parameter_acceptor.cc.

§ to_type() [2/5]

template<>
int ParameterAcceptor::to_type ( const std::string &  parameter)

Definition at line 259 of file parameter_acceptor.cc.

§ to_type() [3/5]

template<>
unsigned int ParameterAcceptor::to_type ( const std::string &  parameter)

Definition at line 279 of file parameter_acceptor.cc.

§ to_type() [4/5]

template<>
bool ParameterAcceptor::to_type ( const std::string &  parameter)

Definition at line 299 of file parameter_acceptor.cc.

§ to_type() [5/5]

template<class T >
static T ParameterAcceptor::to_type ( const std::string &  )
static

Given a string, fill the value of the given parameter.

Member Data Documentation

§ acceptor_id

const unsigned int ParameterAcceptor::acceptor_id
private

The index of this specific class within the class list.

Definition at line 592 of file parameter_acceptor.h.

§ class_list

std::vector< SmartPointer< ParameterAcceptor > > ParameterAcceptor::class_list
staticprivate

A list containing all constructed classes of type ParameterAcceptor.

Definition at line 589 of file parameter_acceptor.h.

§ parameters

std::map<std::string, boost::any> ParameterAcceptor::parameters
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.

§ prm

ParameterHandler ParameterAcceptor::prm
static

Static parameter.

This is used if the user does not provide one.

Definition at line 582 of file parameter_acceptor.h.

§ section_name

const std::string ParameterAcceptor::section_name
protected

The subsection name for this class.

Definition at line 607 of file parameter_acceptor.h.

§ sep

const char ParameterAcceptor::sep = '/'
staticprivate

Separator between section and subsection.

Definition at line 603 of file parameter_acceptor.h.


The documentation for this class was generated from the following files: