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

Inheritance diagram for MultipleParameterLoop:

Classes
class	Entry

class	UserClass

Public Member Functions
	MultipleParameterLoop ()

virtual	~MultipleParameterLoop ()

virtual bool	read_input (std::istream &input, const std::string &filename="input file", const std::string &last_line="") 1

virtual void	parse_input (std::istream &input, const std::string &filename="input file", const std::string &last_line="")

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="")

virtual void	parse_input (const std::string &filename, const std::string &last_line="")

virtual bool	read_input (std::istream &input, const std::string &filename="input file", const std::string &last_line="") 1

virtual bool	read_input (const std::string &filename, const bool optional=false, const bool write_stripped_file=false, const std::string &last_line="") 1

Public Member Functions inherited from ParameterHandler
	ParameterHandler ()

virtual	~ParameterHandler ()

virtual bool	read_input (const std::string &filename, const bool optional=false, const bool write_stripped_file=false, const std::string &last_line="") 1

virtual void	parse_input (const std::string &filename, const std::string &last_line="")

virtual bool	read_input_from_string (const char *s, const std::string &last_line="")

virtual void	parse_input_from_string (const char *s, const std::string &last_line="")

virtual bool	read_input_from_xml (std::istream &input) 1

virtual void	parse_input_from_xml (std::istream &input)

void	clear ()

void	declare_entry (const std::string &entry, const std::string &default_value, const Patterns::PatternBase &pattern=Patterns::Anything(), const std::string &documentation=std::string())

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)

void	leave_subsection ()

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

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

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

bool	get_bool (const std::string &entry_name) 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)

void	print_parameters_section (std::ostream &out, const OutputStyle style, const unsigned int indent_level, const bool include_top_level_elements=false)

void	log_parameters (LogStream &out)

void	log_parameters_section (LogStream &out)

std::size_t	memory_consumption () const

template<class Archive >
void	save (Archive &ar, const unsigned int version) const

template<class Archive >
void	load (Archive &ar, const unsigned int version)

bool	operator== (const ParameterHandler &prm2) const

Public Member Functions inherited from Subscriptor
	Subscriptor ()

	Subscriptor (const Subscriptor &)

	Subscriptor (Subscriptor &&)

virtual	~Subscriptor ()

Subscriptor &	operator= (const Subscriptor &)

Subscriptor &	operator= (Subscriptor &&)

void	subscribe (const char *identifier=0) const

void	unsubscribe (const char *identifier=0) const

unsigned int	n_subscriptions () const

void	list_subscribers () const

template<class Archive >
void	serialize (Archive &ar, const unsigned int version)

Private Member Functions
void	init_branches ()

void	init_branches_current_section ()

void	fill_entry_values (const unsigned int run_no)

Private Attributes
std::vector< Entry >	multiple_choices

unsigned int	n_branches

Additional Inherited Members
Public Types inherited from ParameterHandler
enum	OutputStyle { Text = 1, LaTeX = 2, Description = 3, XML = 4, JSON = 5, ShortText = 193 }

Static Public Member Functions inherited from ParameterHandler
static ::ExceptionBase &	ExcEntryAlreadyExists (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 &	ExcInvalidEntryForPatternXML (std::string arg1, std::string arg2, std::string arg3)

static ::ExceptionBase &	ExcCannotOpenIncludeStatementFile (int arg1, std::string arg2, std::string arg3)

Static Public Member Functions inherited from Subscriptor
static ::ExceptionBase &	ExcInUse (int arg1, char *arg2, std::string &arg3)

static ::ExceptionBase &	ExcNoSubscriber (char arg1, char arg2)

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_cxx11::shared_ptr<Problem> p;
};
HelperClass::HelperClass () : p(0) {}
void HelperClass::create_new (const unsigned int run_no)
{
  p.reset(new 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.

Author: Wolfgang Bangerth, October 1997, 2010

Definition at line 2435 of file parameter_handler.h.

Constructor & Destructor Documentation

◆ MultipleParameterLoop()

MultipleParameterLoop::MultipleParameterLoop ( )

Constructor

Definition at line 3115 of file parameter_handler.cc.

◆ ~MultipleParameterLoop()

MultipleParameterLoop::~MultipleParameterLoop ( )

virtual

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

Definition at line 3122 of file parameter_handler.cc.

Member Function Documentation

◆ read_input() [1/3]

bool MultipleParameterLoop::read_input	(	std::istream &	input,
		const std::string &	filename = `"input file"`,
		const std::string &	last_line = `""`
	)

virtual

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.

Return whether the read was successful.

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.

Note: Of the three read_input functions implemented by ParameterHandler, this method and its replacement (MultipleParameterLoop::parse_input) are the only ones overridden with new behavior by this class. This is because the other two read_input functions just reformat their inputs and then call this version.

Deprecated:: This function has been deprecated in favor of the replacement MultipleParameterLoop::parse_input, which raises exceptions to indicate errors instead of returning an error code.

Reimplemented from ParameterHandler.

Definition at line 3128 of file parameter_handler.cc.

◆ parse_input() [1/3]

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

virtual

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.

Note: Of the three parse_input functions implemented by ParameterHandler, this method and the deprecated method MultipleParameterLoop::read_input are the only ones 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 3155 of file parameter_handler.cc.

◆ loop()

void MultipleParameterLoop::loop ( MultipleParameterLoop::UserClass & uc )

run the central loop.

Definition at line 3170 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 3312 of file parameter_handler.cc.

◆ init_branches()

void MultipleParameterLoop::init_branches ( )

private

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

Definition at line 3183 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 3222 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 3262 of file parameter_handler.cc.

◆ parse_input() [2/3]

void ParameterHandler::parse_input

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.

Definition at line 1641 of file parameter_handler.cc.

◆ parse_input() [3/3]

void ParameterHandler::parse_input

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.

Definition at line 1777 of file parameter_handler.cc.

◆ read_input() [2/3]

bool ParameterHandler::read_input

For backwards compatibility also include the deprecated read functions.

Definition at line 1616 of file parameter_handler.cc.

◆ read_input() [3/3]

bool ParameterHandler::read_input

For backwards compatibility also include the deprecated read functions.

Definition at line 1744 of file parameter_handler.cc.

Member Data Documentation

◆ multiple_choices

std::vector<Entry> MultipleParameterLoop::multiple_choices

private

List of variant entry values.

Definition at line 2626 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 2632 of file parameter_handler.h.

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

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

Classes

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Usage

Syntax for variant and array entry values

Worked example

Constructor & Destructor Documentation

◆ MultipleParameterLoop()

◆ ~MultipleParameterLoop()

Member Function Documentation

◆ read_input() [1/3]

◆ parse_input() [1/3]

◆ loop()

◆ memory_consumption()

◆ init_branches()

◆ init_branches_current_section()

◆ fill_entry_values()

◆ parse_input() [2/3]

◆ parse_input() [3/3]

◆ read_input() [2/3]

◆ read_input() [3/3]

Member Data Documentation

◆ multiple_choices

◆ n_branches