MultipleParameterLoop Class Reference

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

Inheritance diagram for MultipleParameterLoop:

Classes
class	Entry
class	UserClass

Public Types
enum	OutputStyle {   DefaultStyle = 0x0000 , Short = 0x0001 , KeepDeclarationOrder = 0x0002 , PRM = 0x0010 ,   LaTeX = 0x0020 , Description = 0x0040 , XML = 0x0080 , JSON = 0x0100 ,   ShortPRM = PRM | Short , ShortXML = XML | Short , ShortJSON = JSON | Short , ShortLaTeX = LaTeX | Short ,   KeepOnlyChanged = 0x0200 }

Public Member Functions
	MultipleParameterLoop ()
virtual	~MultipleParameterLoop () override=default
virtual void	parse_input (std::istream &input, const std::string &filename="input file", const std::string &last_line="", const bool skip_undefined=false) override
void	loop (UserClass &uc)
std::size_t	memory_consumption () const
virtual void	parse_input (std::istream &input, const std::string &filename="input file", const std::string &last_line="", const bool skip_undefined=false)
virtual void	parse_input (const std::string &filename, const std::string &last_line="", const bool skip_undefined=false, const bool assert_mandatory_entries_are_found=false)
virtual void	parse_input_from_string (const std::string &s, const std::string &last_line="", const bool skip_undefined=false)
virtual void	parse_input_from_xml (std::istream &input, const bool skip_undefined=false)
virtual void	parse_input_from_json (std::istream &input, const bool skip_undefined=false)
void	clear ()
void	declare_entry (const std::string &entry, const std::string &default_value, const Patterns::PatternBase &pattern=Patterns::Anything(), const std::string &documentation="", const bool has_to_be_set=false)
void	mark_as_deprecated (const std::string &entry, const bool is_deprecated=true)
void	add_action (const std::string &entry, const std::function< void(const std::string &value)> &action, const bool execute_action=true)
template<typename ParameterType >
void	add_parameter (const std::string &entry, ParameterType &parameter, const std::string &documentation="", const Patterns::PatternBase &pattern= *Patterns::Tools::Convert< ParameterType >::to_pattern(), const bool has_to_be_set=false)
void	declare_alias (const std::string &existing_entry_name, const std::string &alias_name, const bool alias_is_deprecated=false)
void	enter_subsection (const std::string &subsection, const bool create_path_if_needed=true)
void	leave_subsection ()
bool	subsection_path_exists (const std::vector< std::string > &sub_path) const
std::string	get_current_path () const
std::string	get_current_full_path (const std::string &name) const
std::string	get_current_full_path (const std::vector< std::string > &sub_path, const std::string &name) const
std::string	get (const std::string &entry_string) const
std::string	get (const std::vector< std::string > &entry_subsection_path, const std::string &entry_string) const
long int	get_integer (const std::string &entry_string) const
long int	get_integer (const std::vector< std::string > &entry_subsection_path, const std::string &entry_string) const
double	get_double (const std::string &entry_name) const
double	get_double (const std::vector< std::string > &entry_subsection_path, const std::string &entry_string) const
bool	get_bool (const std::string &entry_name) const
bool	get_bool (const std::vector< std::string > &entry_subsection_path, const std::string &entry_string) const
void	set (const std::string &entry_name, const std::string &new_value)
void	set (const std::string &entry_name, const char *new_value)
void	set (const std::string &entry_name, const long int new_value)
void	set (const std::string &entry_name, const double new_value)
void	set (const std::string &entry_name, const bool new_value)
std::ostream &	print_parameters (std::ostream &out, const OutputStyle style) const
void	print_parameters (const std::string &filename, const OutputStyle style=DefaultStyle) const
void	log_parameters (LogStream &out, const OutputStyle style=DefaultStyle)
void	log_parameters_section (LogStream &out, const OutputStyle style=DefaultStyle)
template<class Archive >
void	save (Archive &ar, const unsigned int version) const
template<class Archive >
void	load (Archive &ar, const unsigned int version)
template<class Archive >
void	serialize (Archive &archive, const unsigned int version)
bool	operator== (const ParameterHandler &prm2) const
std::set< std::string >	get_entries_wrongly_not_set () const
void	assert_that_entries_have_been_set () const
EnableObserverPointer functionality
Classes derived from EnableObserverPointer provide a facility to subscribe to this object. This is mostly used by the ObserverPointer class.
void	subscribe (std::atomic< bool > *const validity, const std::string &identifier="") const
void	unsubscribe (std::atomic< bool > *const validity, const std::string &identifier="") const
unsigned int	n_subscriptions () const
template<typename StreamType >
void	list_subscribers (StreamType &stream) const
void	list_subscribers () const

Static Public Member Functions
static ::ExceptionBase &	ExcEntryAlreadyExists (std::string arg1)
static ::ExceptionBase &	ExcEntryIsDeprecated (int arg1, std::string arg2, std::string arg3)
static ::ExceptionBase &	ExcEncounteredDeprecatedEntries (std::string arg1)
static ::ExceptionBase &	ExcValueDoesNotMatchPattern (std::string arg1, std::string arg2)
static ::ExceptionBase &	ExcAlreadyAtTopLevel ()
static ::ExceptionBase &	ExcEntryUndeclared (std::string arg1)
static ::ExceptionBase &	ExcUnbalancedSubsections (std::string arg1, std::string arg2)
static ::ExceptionBase &	ExcNoSubsection (int arg1, std::string arg2, std::string arg3)
static ::ExceptionBase &	ExcCannotParseLine (int arg1, std::string arg2, std::string arg3)
static ::ExceptionBase &	ExcInvalidEntryForPattern (int arg1, std::string arg2, std::string arg3, std::string arg4, std::string arg5)
static ::ExceptionBase &	ExcInvalidXMLParameterFile ()
static ::ExceptionBase &	ExcCannotOpenIncludeStatementFile (int arg1, std::string arg2, std::string arg3)
static ::ExceptionBase &	ExcInUse (int arg1, std::string arg2, std::string arg3)
static ::ExceptionBase &	ExcNoSubscriber (std::string arg1, std::string arg2)

Private Types
using	map_value_type = decltype(counter_map)::value_type
using	map_iterator = decltype(counter_map)::iterator

Private Member Functions
void	init_branches ()
void	init_branches_current_section ()
void	fill_entry_values (const unsigned int run_no)
void	scan_line (std::string line, const std::string &input_filename, const unsigned int current_line_n, const bool skip_undefined)
void	recursively_print_parameters (const boost::property_tree::ptree &tree, const std::vector< std::string > &target_subsection_path, const ParameterHandler::OutputStyle style, const unsigned int indent_level, std::ostream &out) const
void	check_no_subscribers () const noexcept

Private Attributes
std::vector< Entry >	multiple_choices
unsigned int	n_branches
std::vector< std::string >	subsection_path
std::unique_ptr< boost::property_tree::ptree >	entries
std::map< std::string, std::pair< bool, bool > >	entries_set_status
std::vector< std::unique_ptr< const Patterns::PatternBase > >	patterns
std::vector< std::function< void(const std::string &)> >	actions
std::atomic< unsigned int >	counter
std::map< std::string, unsigned int >	counter_map
std::vector< std::atomic< bool > * >	validity_pointers
const std::type_info *	object_info

Static Private Attributes
static const char	path_separator = '.'
static std::mutex	mutex

Detailed Description

The class MultipleParameterLoop offers an easy possibility to test several parameter sets during one run of the program. For this it uses the ParameterHandler class to read in data in a standardized form, searches for variant entry values and performs a loop over all combinations of parameters.

Variant entry values are given like this:

*     set Time step size = { 0.1 | 0.2 | 0.3 }
*   

The loop will then perform three runs of the program, one for each value of Time step size, while all other parameters are as specified or with their default value. If there are several variant entry values in the input, a loop is performed for each combination of variant values:

*     set Time step size = { 0.1 | 0.2 }
*     set Solver         = { CG  | GMRES }
*   

will result in four runs of the programs, with time step 0.1 and 0.2 for each of the two solvers.

In addition to variant entries, this class also supports array entries that look like this:

*     set Output file = ofile.{{ 1 | 2 | 3 | 4 }}
*   

This indicates that if there are variant entries producing a total of four different runs, then we will write their results to the files ofile.1, ofile.2, ofile.3 and ofile.4, respectively. Array entries do not generate multiple runs of the main loop themselves, but if there are variant entries, then in the nth run of the main loop, also the nth value of an array is returned.

Since the different variants are constructed in the order of declaration, not in the order in which the variant entries appear in the input file, it may be difficult to guess the mapping between the different variants and the appropriate entry in an array. You will have to check the order of declaration, or use only one variant entry.

It is guaranteed that only selections which match the regular expression (pattern) given upon declaration of an entry are given back to the program. If a variant value does not match the regular expression, the default value is stored and an error is issued. Before the first run of the loop, all possible values are checked for their conformance, so that the error is issued at the very beginning of the program.

Usage

The usage of this class is similar to the ParameterHandler class. First the entries and subsections have to be declared, then a loop is performed in which the different parameter sets are set, a new instance of a user class is created which is then called. Taking the classes of the example for the ParameterHandler class, the extended program would look like this:

class HelperClass : public MultipleParameterLoop::UserClass
{
public:
  HelperClass ();
 
  virtual void create_new (const unsigned int run_no);
  virtual void run (ParameterHandler &prm);
 
  static void declare_parameters (ParameterHandler &prm);
private:
  std::unique_ptr<Problem> p;
};
 
 
HelperClass::HelperClass () : p(0) {}
 
 
void HelperClass::create_new (const unsigned int run_no)
{
  p = std::make_unique<Problem>());
}
 
 
void HelperClass::declare_parameters (ParameterHandler &prm)
{
  Problem::declare_parameters (prm);
}
 
 
void HelperClass::run (ParameterHandler &prm)
{
  p->get_parameters (prm);
  p->do_useful_work ();
}
 
 
 
int main ()
{
  class MultipleParameterLoop prm;
  HelperClass h;
  HelperClass::declare_parameters (prm);
  prm.parse_input ("prmtest.prm");
  prm.loop (h);
  return 0;
}

As can be seen, first a new helper class has to be set up. This must contain a virtual constructor for a problem class. You can also derive your problem class from MultipleParameterLoop::UserClass and let create_new clear all member variables. If you have access to all inherited member variables in some way this is the recommended procedure. A third possibility is to use multiple inheritance and derive a helper class from both the MultipleParameterLoop::UserClass and the problem class. In any case, create_new has to provide a clean problem object which is the problem in the second and third possibility.

The derived class also has to provide for member functions which declare the entries and which run the program. Running the program includes getting the parameters out of the ParameterHandler object.

After defining an object of this helper class and an object of the MultipleParameterLoop class, the entries have to be declared in the same way as for the ParameterHandler class. Then the input has to be read. Finally the loop is called. This executes the following steps:

for (each combination)
  {
    UserObject.create_new (run_no);
 
    // set parameters for this run
 
    UserObject.run (*this);
  }

UserObject is the parameter to the loop function. create_new is given the number of the run (starting from one) to enable naming output files differently for each run.

Syntax for variant and array entry values

Variant values are specified like prefix{ v1 | v2 | v3 | ... }postfix. Whitespace to the right of the opening brace { is ignored as well as to the left of the closing brace } while whitespace on the respectively other side is not ignored. Whitespace around the mid symbols | is also ignored. The empty selection prefix{ v1 | }postfix is also allowed and produces the strings prefixv1postfix and prefixpostfix.

The syntax for array values is equal, apart from the double braces: prefix{{ v1 | v2 | v3 }}postfix.

Worked example

Given the above extensions to the example program for the ParameterHandler and the following input file

*     set Equation 1 = Poisson
*     set Equation 2 = Navier-Stokes
*     set Output file= results.{{ 1 | 2 | 3 | 4 | 5 | 6 }}
*
*     subsection Equation 1
*       set Matrix type = Sparse
*       subsection Linear solver
*         set Solver                       = CG
*         set Maximum number of iterations = { 10 | 20 | 30 }
*       end
*     end
*
*     subsection Equation 2
*       set Matrix type = Full
*       subsection Linear solver
*         set Solver                       = { BiCGStab | GMRES }
*         set Maximum number of iterations = 100
*       end
*     end
*   

this is the output:

*     LinEq: Method=CG, MaxIterations=10
*     LinEq: Method=BiCGStab, MaxIterations=100
*     Problem: outfile=results.1
*              eq1=Poisson, eq2=Navier-Stokes
*              Matrix1=Sparse, Matrix2=Full
*     LinEq: Method=CG, MaxIterations=20
*     LinEq: Method=BiCGStab, MaxIterations=100
*     Problem: outfile=results.2
*              eq1=Poisson, eq2=Navier-Stokes
*              Matrix1=Sparse, Matrix2=Full
*     LinEq: Method=CG, MaxIterations=30
*     LinEq: Method=BiCGStab, MaxIterations=100
*     Problem: outfile=results.3
*              eq1=Poisson, eq2=Navier-Stokes
*              Matrix1=Sparse, Matrix2=Full
*     LinEq: Method=CG, MaxIterations=10
*     LinEq: Method=GMRES, MaxIterations=100
*     Problem: outfile=results.4
*              eq1=Poisson, eq2=Navier-Stokes
*              Matrix1=Sparse, Matrix2=Full
*     LinEq: Method=CG, MaxIterations=20
*     LinEq: Method=GMRES, MaxIterations=100
*     Problem: outfile=results.5
*              eq1=Poisson, eq2=Navier-Stokes
*              Matrix1=Sparse, Matrix2=Full
*     LinEq: Method=CG, MaxIterations=30
*     LinEq: Method=GMRES, MaxIterations=100
*     Problem: outfile=results.6
*              eq1=Poisson, eq2=Navier-Stokes
*              Matrix1=Sparse, Matrix2=Full
*   

Since create_new gets the number of the run it would also be possible to output the number of the run.

Definition at line 2122 of file parameter_handler.h.

Member Typedef Documentation

map_value_type

using EnableObserverPointer::map_value_type = decltype(counter_map)::value_type

privateinherited

The data type used in counter_map.

Definition at line 238 of file enable_observer_pointer.h.

map_iterator

using EnableObserverPointer::map_iterator = decltype(counter_map)::iterator

privateinherited

The iterator type used in counter_map.

Definition at line 243 of file enable_observer_pointer.h.

Member Enumeration Documentation

OutputStyle

enum ParameterHandler::OutputStyle

inherited

List of possible output formats used for functions like ParameterHandler::print_parameters(). The options can be categorized into two groups:

• format options: PRM, LaTeX, Description, XML, JSON
• stylistic options: Short, KeepDeclarationOrder

Only one format option may be specified at the time. Any function that accepts an OutputStyle as an option will throw if you specify more than one.

A number of shortcuts of commonly used option combinations are provided. E.g., ShortPRM prints the parameters in the PRM format, while skipping the documentation.

Enumerator
DefaultStyle	Default stylistic style: print documentation and sort all parameters alphabetically.
Short	Write input for ParameterHandler without comments or changed default values.
KeepDeclarationOrder	Keep the order of the parameters as they have been declared.
PRM	Write human readable output suitable to be read by ParameterHandler::parse_input() again.
LaTeX	Write parameters as a LaTeX table.
Description	Write out declared parameters with description and possible values. Note This format is not suitable to be read back again.
XML	Write out everything as an XML file suitable to be read by ParameterHandler::parse_input_from_xml() again. See the general documentation of this class for an example of output.
JSON	Write out everything as a JSON file suitable to be read by ParameterHandler::parse_input_from_json() again.
ShortPRM	Write the content of ParameterHandler without comments or changed default values.
ShortXML	Write the content of ParameterHandler without comments or changed default values as a XML file.
ShortJSON	Write the content of ParameterHandler without comments or changed default values as a JSON file.
ShortLaTeX	Write the content of ParameterHandler without comments or changed default values as a LaTeX file.
KeepOnlyChanged	Write out only parameters with changed values.

Definition at line 872 of file parameter_handler.h.

Constructor & Destructor Documentation

MultipleParameterLoop()

MultipleParameterLoop::MultipleParameterLoop

(

)

Constructor

Definition at line 2268 of file parameter_handler.cc.

~MultipleParameterLoop()

virtual MultipleParameterLoop::~MultipleParameterLoop ( )

overridevirtualdefault

Destructor. Declare this only to have a virtual destructor, which is safer as we have virtual functions. It actually does nothing spectacular.

Member Function Documentation

parse_input() [1/3]

void MultipleParameterLoop::parse_input ( std::istream &  input, const std::string &  filename = "input file", const std::string &  last_line = "", const bool  skip_undefined = false  )

overridevirtual

Read input from a stream until the stream returns the eof condition or error. The second argument can be used to denote the name of the file (if that's what the input stream represents) we are reading from; this is only used when creating output for error messages.

If non-empty last_line is provided, the ParameterHandler object will stop parsing lines after encountering last_line . This is handy when adding extra data that shall be parsed manually.

If skip_undefined is true, the parameter handler will skip undefined sections and entries. This is useful for partially parsing a parameter file, for example to obtain only the spatial dimension of the problem. By default all entries and subsections are expected to be declared.

Note

This is the only overload of the three parse_input functions implemented by ParameterHandler overridden with new behavior by this class. This is because the other two parse_input functions just reformat their inputs and then call this version.

Reimplemented from ParameterHandler.

Definition at line 2275 of file parameter_handler.cc.

loop()

void MultipleParameterLoop::loop

(

MultipleParameterLoop::UserClass &

uc

)

run the central loop.

Definition at line 2292 of file parameter_handler.cc.

memory_consumption()

std::size_t MultipleParameterLoop::memory_consumption

(

)

const

Determine an estimate for the memory consumption (in bytes) of this object.

Definition at line 2426 of file parameter_handler.cc.

init_branches()

void MultipleParameterLoop::init_branches ( )

private

Initialize the different branches, i.e. construct the combinations.

Definition at line 2306 of file parameter_handler.cc.

init_branches_current_section()

void MultipleParameterLoop::init_branches_current_section ( )

private

Traverse the section currently set by enter_subsection()/leave_subsection() and see which of the entries are variant or array entries. Then fill the multiple_choices variable using this information.

Definition at line 2347 of file parameter_handler.cc.

fill_entry_values()

void MultipleParameterLoop::fill_entry_values ( const unsigned int  run_no )

private

Transfer the entry values for one run to the entry tree.

Definition at line 2378 of file parameter_handler.cc.

parse_input() [2/3]

void ParameterHandler::parse_input ( std::istream &  input, const std::string &  filename = "input file", const std::string &  last_line = "", const bool  skip_undefined = false  )

virtual

Overriding virtual functions which are overloaded (like ParameterHandler::parse_input, which has two different sets of input argument types) causes the non-overridden functions to be hidden. Get around this by explicitly using both variants of ParameterHandler::parse_input and then overriding the one we care about.

Reimplemented from ParameterHandler.

Definition at line 1015 of file parameter_handler.cc.

parse_input() [3/3]

void ParameterHandler::parse_input ( const std::string &  filename, const std::string &  last_line = "", const bool  skip_undefined = false, const bool  assert_mandatory_entries_are_found = false  )

virtual

Overriding virtual functions which are overloaded (like ParameterHandler::parse_input, which has two different sets of input argument types) causes the non-overridden functions to be hidden. Get around this by explicitly using both variants of ParameterHandler::parse_input and then overriding the one we care about.

Reimplemented from ParameterHandler.

Definition at line 1042 of file parameter_handler.cc.

parse_input_from_string()

void ParameterHandler::parse_input_from_string ( const std::string &  s, const std::string &  last_line = "", const bool  skip_undefined = false  )

virtualinherited

Parse input from a string to populate known parameter fields. The lines in the string must be separated by \n characters.

The function in essence reads the entire file into a stream and then calls the other parse_input() function with that stream. See there for more information.

Definition at line 611 of file parameter_handler.cc.

parse_input_from_xml()

void ParameterHandler::parse_input_from_xml ( std::istream &  input, const bool  skip_undefined = false  )

virtualinherited

Parse input from an XML stream to populate known parameter fields. This could be from a file originally written by the print_parameters() function using the XML output style and then modified by hand as necessary, or from a file written using this method and then modified by the graphical parameter GUI (see the general documentation of this class).

Definition at line 792 of file parameter_handler.cc.

parse_input_from_json()

void ParameterHandler::parse_input_from_json ( std::istream &  input, const bool  skip_undefined = false  )

virtualinherited

Parse input from a JSON stream to populate known parameter fields. This could be from a file originally written by the print_parameters() function using the JSON output style and then modified by hand as necessary, or from a separate program that knows how to write JSON format for ParameterHandler input.

Definition at line 848 of file parameter_handler.cc.

clear()

void ParameterHandler::clear ( )

inherited

Clear all contents.

Definition at line 884 of file parameter_handler.cc.

declare_entry()

void ParameterHandler::declare_entry ( const std::string &  entry, const std::string &  default_value, const Patterns::PatternBase &  pattern = Patterns::Anything(), const std::string &  documentation = "", const bool  has_to_be_set = false  )

inherited

Declare a new entry with name entry, default and for which any input has to match the pattern (default: any pattern).

The function generates an exception of type ExcValueDoesNotMatchPattern if the default value doesn't match the given pattern, using the C++ throw mechanism. However, this exception is only generated after the entry has been created; if you have code where no sensible default value for a parameter is possible, you can then catch and ignore this exception.

The parameter documentation defaulting to an empty string is used to add a documenting text to each entry which will be printed as a comment when this class is asked to write out all declarations to a stream using the print_parameters() function.

The parameter has_to_be_set can be used in order to declare this parameter as a parameter whose default value has to be overwritten by one of the methods provided by this class. Whether a parameter has been set successfully can be queried by the functions get_entries_wrongly_not_set() and assert_that_entries_have_been_set().

Note

An entry can be declared more than once without generating an error, for example to override an earlier default value.

Definition at line 893 of file parameter_handler.cc.

mark_as_deprecated()

void ParameterHandler::mark_as_deprecated ( const std::string &  entry, const bool  is_deprecated = true  )

inherited

Mark a previously declared parameter as deprecated. This will cause an exception of type ExcEncounteredDeprecatedEntries to be thrown if the parameter is used in an input file that is parsed by the parse_input() function.

The exception message will list the name of the parameter(s) that were encountered in the input file.

Parameters

entry	The name of the parameter to be marked as deprecated.
is_deprecated	An optional parameter that can be used to set the deprecation status of the parameter. If set to true, the parameter will be marked as deprecated. This is the default behavior. If set to false, the parameter will be marked as not deprecated. This is useful if a parameter is marked as deprecated by one function, but another function wants to keep using it.

Definition at line 1040 of file parameter_handler.cc.

add_action()

void ParameterHandler::add_action ( const std::string &  entry, const std::function< void(const std::string &value)> &  action, const bool  execute_action = true  )

inherited

Attach an action to the parameter with name entry in the current section. The action needs to be a function-like object that takes the value of the parameter as a (string) argument. See the general documentation of this class for a longer description of actions, as well as examples.

The action is executed in three different circumstances:

• With the default value of the parameter with name name, at the end of the current function if execute_action is set to true. This is useful because it allows for the action to execute whatever it needs to do at least once for each parameter, even those that are not actually specified in the input file (and thus remain at their default values). Note that if the action is executed, it converts the default value to a string and back afterwards. This can lead to round-off errors so that the default values might change in the case of floating-point numbers.
• Within the ParameterHandler::set() functions that explicitly set a value for a parameter.
• Within the parse_input() function and similar functions such as parse_input_from_string(). Here, the action is executed whenever the parameter with which it is associated is read from the input, after it has been established that the value so read matches the pattern that corresponds to this parameter, and before the value is actually saved.

It is valid to add multiple actions to the same parameter. They will in that case be executed in the same order in which they were added.

Note

Actions may modify all sorts of variables in their scope. The only thing an action should not modify is the ParameterHandler object it is attached to. In other words, it is not allowed to enter or leave sections of the current ParameterHandler object. It is, in principle, acceptable to call ParameterHandler::get() and related functions on other parameters in the current section, but since there is no guarantee about the order in which they will be read from an input file, you will not want to rely on the values these functions would return.

Throwing an exception in an action is generally not a good idea, but yields fundamentally the same result as if one tries to read a parameter from a file for which the value does not satisfy the pattern associated with the parameter. In other words, the value just read is discarded, and ParameterHandler::parse_input() stops to read any further content from the file. See ParameterHandler::parse_input() for more information.

Definition at line 939 of file parameter_handler.cc.

add_parameter()

template<typename ParameterType >

void ParameterHandler::add_parameter ( const std::string &  entry, ParameterType &  parameter, const std::string &  documentation = "", const Patterns::PatternBase &  pattern = *Patterns::Tools::Convert<ParameterType>::to_pattern(), const bool  has_to_be_set = false  )

inherited

Declare a new entry name entry, set its default value to the content of the variable parameter, and create an action that will fill parameter with updated values when a file is parsed, or the entry is set to a new value.

By default, the pattern to use is obtained by calling the function Patterns::Tools::Convert<T>::to_pattern(), but a custom one can be used.

The parameter has_to_be_set can be used in order to declare this parameter as a parameter whose default value has to be overwritten by one of the methods provided by this class. Whether a parameter has been set successfully can be queried by the functions get_entries_wrongly_not_set() and assert_that_entries_have_been_set().

Definition at line 2368 of file parameter_handler.h.

declare_alias()

void ParameterHandler::declare_alias ( const std::string &  existing_entry_name, const std::string &  alias_name, const bool  alias_is_deprecated = false  )

inherited

Create an alias for an existing entry. This provides a way to refer to a parameter in the input file using an alternate name. The alias will be in the current section, and the referenced entry needs to be an existing entry in the current section.

The primary purpose of this function is to allow for a backward compatible way of changing names in input files of applications for which backward compatibility is important. This can be achieved by changing the name of the parameter in the call to declare_entry(), and then creating an alias that maps the old name to the new name. This way, old input files can continue to refer to parameters under the old name, and they will automatically be mapped to the new parameter name.

It is valid to set the same parameter multiple times in an input file. The value that will ultimately be chosen in such cases is simply the last value set. This rule also applies to aliases, where the final value of a parameter is the last value set either through the current name of the parameter or through any of its possible multiple aliases. For example, if you have an input file that looks like

set parm1       = 1
set parm1_alias = 2

where parm1_alias is an alias declared via

prm.declare_alias ("parm1", "parm1_alias");

then the final value for the parameter called parm1 will be 2, not 1.

Parameters

existing_entry_name	The name of an existing parameter in the current section that the alias should refer to.
alias_name	An alternate name for the parameter referenced by the first argument.
alias_is_deprecated	If true, mark the alias as deprecated. This will then be listed in the description of the alias if you call print_parameters(), and you will get a warning on the screen when reading an input file that contains this deprecated alias. The purpose of this argument is to be able to allow the use of an old name for a parameter (see above) but make it clear that this old name will eventually be removed.

Definition at line 977 of file parameter_handler.cc.

enter_subsection()

void ParameterHandler::enter_subsection ( const std::string &  subsection, const bool  create_path_if_needed = true  )

inherited

Enter a subsection. If it does not yet exist, create it if requested.

Definition at line 1068 of file parameter_handler.cc.

leave_subsection()

void ParameterHandler::leave_subsection ( )

inherited

Leave present subsection.

Definition at line 1092 of file parameter_handler.cc.

subsection_path_exists()

bool ParameterHandler::subsection_path_exists ( const std::vector< std::string > &  sub_path ) const

inherited

Check whether a subsection or a subsection path exists in current tree. The input parameter sub_path is assumed to be relative to the currently selected path.

Definition at line 1105 of file parameter_handler.cc.

get_current_path()

std::string ParameterHandler::get_current_path ( ) const

inherited

Return the string that identifies the current path into the property tree. The path elements are separated by the path_separator, which is a '.'. This is only a path, i.e., it is not terminated by the path_separator character.

This function simply calls collate_path_string() with subsection_path as argument.

Definition at line 392 of file parameter_handler.cc.

get_current_full_path() [1/2]

std::string ParameterHandler::get_current_full_path ( const std::string &  name ) const

inherited

Given the name of an entry as argument, the function computes a full path into the parameter tree using the current subsection. The path elements are separated by the path_separator, which is a '.'.

Definition at line 400 of file parameter_handler.cc.

get_current_full_path() [2/2]

std::string ParameterHandler::get_current_full_path ( const std::vector< std::string > &  sub_path, const std::string &  name  ) const

inherited

This function computes a full path into the parameter tree given a path from the current subsection and the name of an entry. The path elements are separated by the path_separator, which is a '.'.

Definition at line 414 of file parameter_handler.cc.

get() [1/2]

std::string ParameterHandler::get ( const std::string &  entry_string ) const

inherited

Return value of entry entry_string. If the entry was changed, then the changed value is returned, otherwise the default value. If the value of an undeclared entry is required, an Assert will fail.

Definition at line 1126 of file parameter_handler.cc.

get() [2/2]

std::string ParameterHandler::get ( const std::vector< std::string > &  entry_subsection_path, const std::string &  entry_string  ) const

inherited

Return value of entry entry_string. If the entry was changed, then the changed value is returned, otherwise the default value. If the value of an undeclared entry is required, an Assert will fail. If entry_subsection_path is non-empty, the value will be gotten from the subsection represented by that path instead of the current subsection. The first string in entry_subsection_path must be the name of a subsection of the current section, and each next string must be the name of a subsection of the one before it.

Definition at line 1143 of file parameter_handler.cc.

get_integer() [1/2]

long int ParameterHandler::get_integer ( const std::string &  entry_string ) const

inherited

Return value of entry entry_string as long int. (A long int is chosen so that even very large unsigned values can be returned by this function).

Definition at line 1164 of file parameter_handler.cc.

get_integer() [2/2]

long int ParameterHandler::get_integer ( const std::vector< std::string > &  entry_subsection_path, const std::string &  entry_string  ) const

inherited

Return value of entry entry_string as long int. (A long int is chosen so that even very large unsigned values can be returned by this function). If entry_subsection_path is non-empty, the value will be gotten from the subsection represented by that path instead of the current subsection.

Definition at line 1183 of file parameter_handler.cc.

get_double() [1/2]

double ParameterHandler::get_double ( const std::string &  entry_name ) const

inherited

Return value of entry entry_name as double.

Definition at line 1207 of file parameter_handler.cc.

get_double() [2/2]

double ParameterHandler::get_double ( const std::vector< std::string > &  entry_subsection_path, const std::string &  entry_string  ) const

inherited

Return value of entry entry_name as double. If entry_subsection_path is non-empty, the value will be gotten from the subsection represented by that path instead of the current subsection.

Definition at line 1227 of file parameter_handler.cc.

get_bool() [1/2]

bool ParameterHandler::get_bool ( const std::string &  entry_name ) const

inherited

Return value of entry entry_name as bool. The entry may be "true" or "yes" for true, "false" or "no" for false respectively.

Definition at line 1252 of file parameter_handler.cc.

get_bool() [2/2]

bool ParameterHandler::get_bool ( const std::vector< std::string > &  entry_subsection_path, const std::string &  entry_string  ) const

inherited

Return value of entry entry_name as bool. The entry may be "true" or "yes" for true, "false" or "no" for false respectively. If entry_subsection_path is non-empty, the value will be gotten from the subsection represented by that path instead of the current subsection.

Definition at line 1269 of file parameter_handler.cc.

set() [1/5]

void ParameterHandler::set ( const std::string &  entry_name, const std::string &  new_value  )

inherited

Change the value presently stored for entry_name to the one given in the second argument.

The parameter must already exist in the present subsection.

The function throws an exception of type ExcValueDoesNotMatchPattern if the new value does not conform to the pattern for this entry.

Definition at line 1291 of file parameter_handler.cc.

set() [2/5]

void ParameterHandler::set ( const std::string &  entry_name, const char *  new_value  )

inherited

Same as above, but an overload where the second argument is a character pointer. This is necessary, since otherwise the call to set("abc","def") will be mapped to the function taking one string and a bool as arguments, which is certainly not what is most often intended.

The function throws an exception of type ExcValueDoesNotMatchPattern if the new value does not conform to the pattern for this entry.

Definition at line 1344 of file parameter_handler.cc.

set() [3/5]

void ParameterHandler::set ( const std::string &  entry_name, const long int  new_value  )

inherited

Change the value presently stored for entry_name to the one given in the second argument.

The parameter must already exist in the present subsection.

The function throws an exception of type ExcValueDoesNotMatchPattern if the new value does not conform to the pattern for this entry.

Definition at line 1366 of file parameter_handler.cc.

set() [4/5]

void ParameterHandler::set ( const std::string &  entry_name, const double  new_value  )

inherited

Change the value presently stored for entry_name to the one given in the second argument.

The parameter must already exist in the present subsection.

For internal purposes, the new value needs to be converted to a string. This is done using 16 digits of accuracy, so the set value and the one you can get back out using get_double() may differ in the 16th digit.

The function throws an exception of type ExcValueDoesNotMatchPattern if the new value does not conform to the pattern for this entry.

Definition at line 1352 of file parameter_handler.cc.

set() [5/5]

void ParameterHandler::set ( const std::string &  entry_name, const bool  new_value  )

inherited

Change the value presently stored for entry_name to the one given in the second argument.

The parameter must already exist in the present subsection.

The function throws an exception of type ExcValueDoesNotMatchPattern if the new value does not conform to the pattern for this entry.

Definition at line 1379 of file parameter_handler.cc.

print_parameters() [1/2]

std::ostream & ParameterHandler::print_parameters ( std::ostream &  out, const OutputStyle  style  ) const

inherited

Print all parameters with the given style to out.

Before printing, all current parameters and subsections are sorted alphabetically by default. This behavior can be disabled setting the optional parameter style to KeepDeclarationOrder: in this case entries are printed in the same order as they have been declared.

In PRM, XML, and JSON format, the output is formatted in such a way that it is possible to use it for later input again. This is most useful to record the parameters for a specific run, since if you output the parameters using this function into a log file, you can always recover the results by simply copying the output to your input file.

Besides the name and value of each entry, the output also contains the default value of entries if it is different from the actual value, as well as the documenting string given to the declare_entry() function if available.

By using the flag Short in combination with PRM, XML, JSON, or LaTeX (or by using the shortcuts ShortPRM, ShortXML, ShortJSON, or ShortLaTeX), a reduced output can be generated, only containing the values and skipping the documentation.

In XML format, the output starts with one root element ParameterHandler in order to get a valid XML document and all subsections under it.

In LaTeX format, the output contains the same information but in a format so that the resulting file can be input into a latex document such as a manual for the code for which this object handles run-time parameters. The various sections of parameters are then represented by latex section and subsection commands as well as by nested enumerations.

You can reference specific parameter sections and individual parameters by the labels that are generated automatically for each entry. The labels have the format parameters:section1/subsection1 and parameters:section1/subsection1/someentry. Because special characters can appear in the section and entry names, these will be "mangled". Here, all characters except [a-zA-Z0-9] are replaced by _XX, where XX is the two-digit ascii code of the character in hexadecimal encoding (so a space becomes _20 for example).

While this function escapes special LaTeX-specific characters (backslash, underscore, etc.) in most of the output (names, default values, etc.), the documentation string is passed as-is. This means you can use math environments and other formatting in the description, but you need to escape quotes, backslashes, underscores, etc. yourself.

In addition, all parameter names are listed with \index statements in two indices called prmindex (where the name of each parameter is listed in the index) and prmindexfull where parameter names are listed sorted by the section in which they exist. By default, the LaTeX program ignores these \index commands, but they can be used to generate an index by using the following commands in the preamble of the latex file :

\usepackage{imakeidx}
\makeindex[name=prmindex, title=Index of run-time parameter entries]
\makeindex[name=prmindexfull,
           title=Index of run-time parameters with section names]

and at the end of the file this:

\printindex[prmindex]
\printindex[prmindexfull]

Definition at line 1389 of file parameter_handler.cc.

print_parameters() [2/2]

void ParameterHandler::print_parameters ( const std::string &  filename, const OutputStyle  style = DefaultStyle  ) const

inherited

Print all parameters to the file given by filename with the given output style style.

This function deduces the output format from the extension of the specified filename. Supported extensions are prm, xml, tex, and json. Hence, it is not necessary to specify an output format via the style argument as long as one of these extensions is added to the filename. If an output format is specified in the style parameter nevertheless, the output format has to be consistent with the filename extension.

If no extension is specified or the extension is not supported, the output format is deduced from the style argument.

If neither the extension is supported, nor does the style parameter contain a format specification, an assertion is thrown.

Parameters

filename	The output file name.
style	The style with which output is produced.

Definition at line 1505 of file parameter_handler.cc.

log_parameters()

void ParameterHandler::log_parameters ( LogStream &  out, const OutputStyle  style = DefaultStyle  )

inherited

Print parameters to a logstream. This function allows to print all parameters into a log-file. Sections will be indented in the usual log-file style.

All current parameters and subsections are sorted alphabetically by default. This behavior can be disabled setting the optional parameter style to KeepDeclarationOrder: in this case entries are printed in the same order as they have been declared.

Note

All style settings in style not related to the ordering are ignored.

Definition at line 1919 of file parameter_handler.cc.

log_parameters_section()

void ParameterHandler::log_parameters_section ( LogStream &  out, const OutputStyle  style = DefaultStyle  )

inherited

Log parameters in the present subsection. The subsection is determined by the subsection_path member variable. This variable is controlled by entering and leaving subsections through the enter_subsection() and leave_subsection() functions.

All current parameters and subsections are sorted alphabetically by default. This behavior can be disabled setting the optional parameter style to KeepDeclarationOrder: in this case entries are printed in the same order as they have been declared.

Note

All style settings in style not related to the ordering are ignored.

In most cases, you will not want to use this function directly, but have it called recursively by the previous function.

Definition at line 1930 of file parameter_handler.cc.

save()

template<class Archive >

void ParameterHandler::save ( Archive &  ar, const unsigned int  version  ) const

inlineinherited

Write the data of this object to a stream for the purpose of serialization using the BOOST serialization library.

Definition at line 2329 of file parameter_handler.h.

load()

template<class Archive >

void ParameterHandler::load ( Archive &  ar, const unsigned int  version  )

inlineinherited

Read the data of this object from a stream for the purpose of serialization using the BOOST serialization library.

Definition at line 2349 of file parameter_handler.h.

serialize()

template<class Archive >

void ParameterHandler::serialize ( Archive &  archive, const unsigned int  version  )

inherited

Write and read the data of this object from a stream for the purpose of serialization using the BOOST serialization library.

operator==()

bool ParameterHandler::operator== ( const ParameterHandler &  prm2 ) const

inherited

Test for equality.

Definition at line 2203 of file parameter_handler.cc.

get_entries_wrongly_not_set()

std::set< std::string > ParameterHandler::get_entries_wrongly_not_set ( ) const

inherited

Return a set of parameter names (including subsection names) corresponding to those entries of the parameter handler that have not been set by one of the functions parsing parameters from an input file or by an explicit call to one of the set() functions, but that have been declared as mandatory parameters that must be set (through the last argument of the declare_entry() function or add_parameter() function).

Definition at line 2228 of file parameter_handler.cc.

assert_that_entries_have_been_set()

void ParameterHandler::assert_that_entries_have_been_set ( ) const

inherited

Asserts that those entries of the parameter handler with flag has_to_be_set = true have been set. An exception is invoked if at least one of these parameters has not been set.

Definition at line 2242 of file parameter_handler.cc.

scan_line()

void ParameterHandler::scan_line ( std::string  line, const std::string &  input_filename, const unsigned int  current_line_n, const bool  skip_undefined  )

privateinherited

Scan one line of input. input_filename and current_line_n are the name of the input file and the number of the line presently scanned (these are used in exception messages to show where parse errors occurred). This function will raise an exception if the line contains an undeclared subsection or entry, if the line's entry does not match its given pattern, or if the line could not be understood as a valid parameter file expression.

The function modifies its argument, but also takes it by value, so the caller's variable is not changed.

If skip_undefined is true, the parser will skip undefined sections and entries. This is useful for partially parsing a parameter file, for example to obtain only the spatial dimension of the problem. By default all entries and subsections are expected to be declared.

Definition at line 1976 of file parameter_handler.cc.

recursively_print_parameters()

void ParameterHandler::recursively_print_parameters ( const boost::property_tree::ptree &  tree, const std::vector< std::string > &  target_subsection_path, const ParameterHandler::OutputStyle  style, const unsigned int  indent_level, std::ostream &  out  ) const

privateinherited

Print out the parameters of the subsection given by the target_subsection_path argument, as well as all subsections within it recursively. This function is called from the print_parameters() function, and is implemented for all style arguments other than XML and JSON (where we can output the entire set of parameters via BOOST functions). The indent_level argument indicates how many spaces the output should be indented, so that subsections properly nest inside the output of higher sections.

Definition at line 1530 of file parameter_handler.cc.

subscribe()

void EnableObserverPointer::subscribe ( std::atomic< bool > *const  validity, const std::string &  identifier = ""  ) const

inherited

Subscribes a user of the object by storing the pointer validity. The subscriber may be identified by text supplied as identifier.

Definition at line 131 of file enable_observer_pointer.cc.

unsubscribe()

void EnableObserverPointer::unsubscribe ( std::atomic< bool > *const  validity, const std::string &  identifier = ""  ) const

inherited

Unsubscribes a user from the object.

Note

The identifier and the validity pointer must be the same as the one supplied to subscribe().

Definition at line 151 of file enable_observer_pointer.cc.

n_subscriptions()

unsigned int EnableObserverPointer::n_subscriptions ( ) const

inlineinherited

Return the present number of subscriptions to this object. This allows to use this class for reference counted lifetime determination where the last one to unsubscribe also deletes the object.

Definition at line 322 of file enable_observer_pointer.h.

list_subscribers() [1/2]

template<typename StreamType >

void EnableObserverPointer::list_subscribers ( StreamType &  stream ) const

inlineinherited

List the subscribers to the input stream.

Definition at line 339 of file enable_observer_pointer.h.

list_subscribers() [2/2]

void EnableObserverPointer::list_subscribers ( ) const

inherited

List the subscribers to deallog.

Definition at line 199 of file enable_observer_pointer.cc.

check_no_subscribers()

void EnableObserverPointer::check_no_subscribers ( ) const

privatenoexceptinherited

Check that there are no objects subscribing to this object. If this check passes then it is safe to destroy the current object. It this check fails then this function will either abort or print an error message to deallog (by using the AssertNothrow mechanism), but will not throw an exception.

Note

Since this function is just a consistency check it does nothing in release mode.

If this function is called when there is an uncaught exception then, rather than aborting, this function prints an error message to the standard error stream and returns.

Definition at line 53 of file enable_observer_pointer.cc.

Member Data Documentation

multiple_choices

std::vector<Entry> MultipleParameterLoop::multiple_choices

private

List of variant entry values.

Definition at line 2295 of file parameter_handler.h.

n_branches

unsigned int MultipleParameterLoop::n_branches

private

Number of branches constructed from the different combinations of the variants. This obviously equals the number of runs to be performed.

Definition at line 2301 of file parameter_handler.h.

path_separator

const char ParameterHandler::path_separator = '.'

staticprivateinherited

The separator used when accessing elements of a path into the parameter tree.

Definition at line 1804 of file parameter_handler.h.

subsection_path

std::vector<std::string> ParameterHandler::subsection_path

privateinherited

Path of presently selected subsections; empty list means top level

Definition at line 1809 of file parameter_handler.h.

entries

std::unique_ptr<boost::property_tree::ptree> ParameterHandler::entries

privateinherited

The complete tree of sections and entries. See the general documentation of this class for a description how data is stored in this variable.

The variable is a pointer so that we can use an incomplete type, rather than having to include all of the property_tree stuff from boost. This works around a problem with gcc 4.5.

Definition at line 1819 of file parameter_handler.h.

entries_set_status

std::map<std::string, std::pair<bool, bool> > ParameterHandler::entries_set_status

privateinherited

A map that stores a pair of boolean variables for each entry added to the parameter handler. The first bool describes whether the parameter has to be set according to the last argument of the functions declare_entry() or add_parameter(), and the second bool contains the information whether the parameter has been set by any of the functions parsing input parameters or by a set function of this class.

Definition at line 1829 of file parameter_handler.h.

patterns

std::vector<std::unique_ptr<const Patterns::PatternBase> > ParameterHandler::patterns

privateinherited

A list of patterns that are used to describe the parameters of this object. Every nodes in the property tree corresponding to a parameter stores an index into this array.

Definition at line 1836 of file parameter_handler.h.

actions

std::vector<std::function<void(const std::string &)> > ParameterHandler::actions

privateinherited

A list of actions that are associated with parameters. These are added by the add_action() function. Nodes in the property tree corresponding to individual parameters store indices into this array in order to reference specific actions.

Definition at line 1844 of file parameter_handler.h.

counter

std::atomic<unsigned int> EnableObserverPointer::counter

mutableprivateinherited

Store the number of objects which subscribed to this object. Initially, this number is zero, and upon destruction it shall be zero again (i.e. all objects which subscribed should have unsubscribed again).

The creator (and owner) of an object is counted in the map below if HE manages to supply identification.

We use the mutable keyword in order to allow subscription to constant objects also.

This counter may be read from and written to concurrently in multithreaded code: hence we use the std::atomic class template.

Definition at line 227 of file enable_observer_pointer.h.

counter_map

std::map<std::string, unsigned int> EnableObserverPointer::counter_map

mutableprivateinherited

In this map, we count subscriptions for each different identification string supplied to subscribe().

Definition at line 233 of file enable_observer_pointer.h.

validity_pointers

std::vector<std::atomic<bool> *> EnableObserverPointer::validity_pointers

mutableprivateinherited

In this vector, we store pointers to the validity bool in the ObserverPointer objects that subscribe to this class.

Definition at line 249 of file enable_observer_pointer.h.

object_info

const std::type_info* EnableObserverPointer::object_info

mutableprivateinherited

Pointer to the typeinfo object of this object, from which we can later deduce the class name. Since this information on the derived class is neither available in the destructor, nor in the constructor, we obtain it in between and store it here.

Definition at line 257 of file enable_observer_pointer.h.

mutex

std::mutex EnableObserverPointer::mutex

staticprivateinherited

A mutex used to ensure data consistency when accessing the mutable members of this class. This lock is used in the subscribe() and unsubscribe() functions, as well as in list_subscribers().

Definition at line 280 of file enable_observer_pointer.h.

---

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

• include/deal.II/base/parameter_handler.h
• source/base/parameter_handler.cc