Reference documentation for deal.II version Git d228448 2017-10-17 21:17:08 +0200
Public Member Functions | Static Public Member Functions | Public Attributes | Static Public Attributes | Protected Attributes | Private Member Functions | Private Attributes | Static Private Attributes | List of all members
ParameterAcceptor Class Reference

#include <deal.II/base/parameter_acceptor.h>

Inheritance diagram for ParameterAcceptor:
[legend]

Public Member Functions

 ParameterAcceptor (const std::string &section_name="")
 
virtual ~ParameterAcceptor ()
 
virtual void declare_parameters (ParameterHandler &prm)
 
virtual void parse_parameters (ParameterHandler &prm)
 
std::string get_section_name () const
 
std::vector< std::string > get_section_path () const
 
template<class ParameterType >
void add_parameter (const std::string &entry, ParameterType &parameter, const std::string &documentation=std::string(), ParameterHandler &prm=ParameterAcceptor::prm, const Patterns::PatternBase &pattern=*Patterns::Tools::Convert< ParameterType >::to_pattern())
 
- Public Member Functions inherited from Subscriptor
 Subscriptor ()
 
 Subscriptor (const Subscriptor &)
 
 Subscriptor (Subscriptor &&)
 
virtual ~Subscriptor ()
 
Subscriptoroperator= (const Subscriptor &)
 
Subscriptoroperator= (Subscriptor &&)
 
void subscribe (const char *identifier=nullptr) const
 
void unsubscribe (const char *identifier=nullptr) const
 
unsigned int n_subscriptions () const
 
void list_subscribers () const
 
template<class Archive >
void serialize (Archive &ar, const unsigned int version)
 

Static Public Member Functions

static void initialize (const std::string &filename="", const std::string &output_filename="", const ParameterHandler::OutputStyle output_style_for_prm_format=ParameterHandler::ShortText, ParameterHandler &prm=ParameterAcceptor::prm)
 
static void initialize (std::istream &input_stream, ParameterHandler &prm=ParameterAcceptor::prm)
 
static void clear ()
 
static void parse_all_parameters (ParameterHandler &prm=ParameterAcceptor::prm)
 
static void declare_all_parameters (ParameterHandler &prm=ParameterAcceptor::prm)
 
- Static Public Member Functions inherited from Subscriptor
static::ExceptionBase & ExcInUse (int arg1, char *arg2, std::string &arg3)
 
static::ExceptionBase & ExcNoSubscriber (char *arg1, char *arg2)
 

Public Attributes

boost::signals2::signal< void()> declare_parameters_call_back
 
boost::signals2::signal< void()> parse_parameters_call_back
 

Static Public Attributes

static ParameterHandler prm
 

Protected Attributes

const std::string section_name
 

Private Member Functions

void enter_my_subsection (ParameterHandler &prm)
 
void leave_my_subsection (ParameterHandler &prm)
 

Private Attributes

const unsigned int acceptor_id
 

Static Private Attributes

static std::vector< SmartPointer< ParameterAcceptor > > class_list
 
static const char sep = '/'
 

Detailed Description

A parameter acceptor base class. This class is used to define a public interface for classes wich want to use a single global ParameterHandler to handle parameters. This class declares one static ParameterHandler, and two static functions (declare_all_parameters() and parse_all_parameters()) that manage all of the derived classes.

The basic interface provides two subscription mechanisms: a global subscription mechanism and a local subscription mechanism.

The global subscription mechanism is such that whenever an object of a class derived from ParameterAcceptor is created, then a pointer to that object-of-derived-type is registered, together with a path in the parameter file.

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 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 can be used in two different ways: by overloading the ParameterAcceptor::declare_parameters() and ParameterAcceptor::parse_parameters() methods, or by calling its ParameterAcceptor::add_parameter() method for each parameter we want to have. This in turns makes sure that the given parameter is registered in the global parameter handler (by calling ParameterHandler::add_parameter()), at the correct path. If you define all your parameters using the ParameterAcceptor::add_parameter() method, then you don't need to overload any of the virtual methods of this class.

If some post processing is required on the parsed values, the user can attach a signal to ParameterAcceptor::declare_parameters_call_back and ParameterAcceptor::parse_parameters_call_back, that are called just after the declare_parameters() and parse_parameters() functions of each derived class.

A typical usage of this class 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() :
ParameterAcceptor("Some class name")
{
add_parameter("A param", member_var);
}
private:
std::vector<unsigned int> member_var;
...
};
int main() {
// Make sure you create your object BEFORE calling
// ParameterAcceptor::initialize()
MyClass class;
// With this call, all derived classes will have their
// parameters initialized
}

An implementation that uses user defined declare and parse functions is given by the following example:

// Again your own class, derived from ParameterAcceptor
//
// If you don't pass anything to the constructor of
// ParameterAcceptor, then the class name is used, "MyClass"
// in this case
class MyClass : public ParameterAcceptor {
virtual void declare_parameters(ParameterHandler &prm) {
...
}
virtual void parse_parameters(ParameterHandler &prm) {
...
}
};
int main() {
// Make sure you create your object 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

In the following examples, we propose some use cases with increasing complexities.

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:
SomeParsedClass<dim> my_subclass;
...
};
MyClass::MyClass(std::string name)
:
my_subclass("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
... #parameters of SomeParsedClass
end
subsection My class
... #all the parameters of MyClass defined in declare_parameters
end

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
...
subsection Class B
...
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 SomeParsedClass. There are two strategies to change this behaviour. The first one (not recommended) would be to change the name of the section of SomeParsedClass such that it contains also the string passed to the constructor of MyClass:

MyClass::MyClass(std::string name)
:
my_subclass(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. 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 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, subsequent classes will interpret this as a full path, interpreting the class name as a directory name:

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 on multiple, concurrently running threads.

If you pass an empty name, the boost::core::demangle() function is used to fill the section name with a human readable version of the class name itself.

Author
Luca Heltai, 2017.

Definition at line 339 of file parameter_acceptor.h.

Constructor & Destructor Documentation

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 ( )
virtual

Destructor.

Definition at line 40 of file parameter_acceptor.cc.

Member Function Documentation

void ParameterAcceptor::initialize ( const std::string &  filename = "",
const std::string &  output_filename = "",
const ParameterHandler::OutputStyle  output_style_for_prm_format = ParameterHandler::ShortText,
ParameterHandler prm = ParameterAcceptor::prm 
)
static

Call declare_all_parameters(), read the parameters from filename (only if filename is a non-empty string), and then call parse_all_parameters().

If the parameter filename is the empty string, then no attempt to read a parameter file is done. This may be useful if you are ok with using default values, and don't want to read external files to use a class derived from ParameterAcceptor.

If outfilename is not the emtpy string, then write the content that was read in to the outfilename. The format of both input and output files are selected using the extensions of the files themselves. This can be either prm or xml for input, and prm, xml, or tex/latex for output. If the output format is prm, then output_style_for_prm_format is used to decide wether we write the full documentation as well, or only the parameters.

If the input file does not exist, a default one with the same name is created for you, and an exception is thrown.

Parameters
filenameInput file name
output_filenameOutput file name
output_style_for_prm_formatHow to write the output file if format is prm

Definition at line 52 of file parameter_acceptor.cc.

void ParameterAcceptor::initialize ( std::istream &  input_stream,
ParameterHandler prm = ParameterAcceptor::prm 
)
static

Call declare_all_parameters(), read the parameters from the input_stream in prm format, and then call parse_all_parameters().

An exception is thrown if the input_stream is invalid.

Parameters
input_streamInput stream
prmThe ParameterHandler to use

Definition at line 127 of file parameter_acceptor.cc.

void ParameterAcceptor::clear ( )
static

Clear class list and global parameter file.

Definition at line 138 of file parameter_acceptor.cc.

void ParameterAcceptor::declare_parameters ( ParameterHandler prm)
virtual

Derived classes can use this method to declare their parameters. ParameterAcceptor::initialize() calls it for each derived class. The default implementation is empty.

Definition at line 146 of file parameter_acceptor.cc.

void ParameterAcceptor::parse_parameters ( ParameterHandler prm)
virtual

Derived classes can use this method to parse their parameters. ParameterAcceptor::initialize() calls it for each derived class. The default implementation is empty.

Definition at line 151 of file parameter_acceptor.cc.

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 156 of file parameter_acceptor.cc.

void ParameterAcceptor::declare_all_parameters ( ParameterHandler prm = ParameterAcceptor::prm)
static

Initialize the global 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 168 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 demangled name of this class.

Definition at line 45 of file parameter_acceptor.cc.

std::vector< std::string > ParameterAcceptor::get_section_path ( ) const

Traverse all registered classes, and figure out what subsections we need to enter.

Definition at line 182 of file parameter_acceptor.cc.

template<class ParameterType >
void ParameterAcceptor::add_parameter ( const std::string &  entry,
ParameterType &  parameter,
const std::string &  documentation = std::string(),
ParameterHandler prm = ParameterAcceptor::prm,
const Patterns::PatternBase pattern = *Patterns::Tools::Convert<ParameterType>::to_pattern() 
)

Add a parameter in the correct path. This method forwards all arguments to the prm.add_parameter() method, after entering the correct section path. By default it uses the ParameterAcceptor::prm variable as ParameterHandler.

See the documentation of ParameterHandler::add_parameter() for more information.

Definition at line 521 of file parameter_acceptor.h.

void ParameterAcceptor::enter_my_subsection ( ParameterHandler prm = ParameterAcceptor::prm)
private

Make sure we enter the right subsection of the given parameter.

Definition at line 220 of file parameter_acceptor.cc.

void ParameterAcceptor::leave_my_subsection ( ParameterHandler prm = ParameterAcceptor::prm)
private

This function undoes what the enter_my_subsection() function did. It only makes sense if enter_my_subsection() was called on prm before this one.

Definition at line 229 of file parameter_acceptor.cc.

Member Data Documentation

boost::signals2::signal<void()> ParameterAcceptor::declare_parameters_call_back

Declare parameter call back. This signal is triggered right after declare_parameters() has been called, to allow users to prepare their variables right after parameters have been decalred. The default implementation is empty.

Definition at line 416 of file parameter_acceptor.h.

boost::signals2::signal<void()> ParameterAcceptor::parse_parameters_call_back

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.

Definition at line 434 of file parameter_acceptor.h.

ParameterHandler ParameterAcceptor::prm
static

The global parameter handler.

Definition at line 484 of file parameter_acceptor.h.

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

A list containing all constructed classes of type ParameterAcceptor.

Definition at line 502 of file parameter_acceptor.h.

const unsigned int ParameterAcceptor::acceptor_id
private

The index of this specific class within the class list.

Definition at line 505 of file parameter_acceptor.h.

const char ParameterAcceptor::sep = '/'
staticprivate

Separator between sections.

Definition at line 510 of file parameter_acceptor.h.

const std::string ParameterAcceptor::section_name
protected

The subsection name for this class.

Definition at line 514 of file parameter_acceptor.h.


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