![]() |
Reference documentation for deal.II version 8.1.0
|
#include <parameter_handler.h>
Classes | |
class | Entry |
class | UserClass |
Public Member Functions | |
MultipleParameterLoop () | |
virtual | ~MultipleParameterLoop () |
virtual bool | read_input (std::istream &input, const std::string &filename="input file") |
virtual bool | read_input (const std::string &FileName, const bool optional=false, const bool write_stripped_file=false) |
virtual bool | read_input_from_string (const char *s) |
void | loop (UserClass &uc) |
std::size_t | memory_consumption () const |
![]() | |
ParameterHandler () | |
virtual | ~ParameterHandler () |
virtual bool | read_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 | enter_subsection (const std::string &subsection) |
bool | 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) |
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 |
DeclException1 (ExcEntryAlreadyExists, std::string,<< "The following entry already exists: "<< arg1) | |
DeclException2 (ExcValueDoesNotMatchPattern, std::string, std::string,<< "The string <"<< arg1<< "> does not match the given pattern <"<< arg2<< ">") | |
DeclException0 (ExcAlreadyAtTopLevel) | |
DeclException1 (ExcEntryUndeclared, std::string,<< "You can't ask for entry <"<< arg1<< "> you have not yet declared") | |
DeclException1 (ExcConversionError, std::string,<< "Error when trying to convert the following string: "<< arg1) | |
![]() | |
Subscriptor () | |
Subscriptor (const Subscriptor &) | |
virtual | ~Subscriptor () |
Subscriptor & | operator= (const Subscriptor &) |
void | subscribe (const char *identifier=0) const |
void | unsubscribe (const char *identifier=0) const |
unsigned int | n_subscriptions () const |
void | list_subscribers () const |
DeclException3 (ExcInUse, int, char *, std::string &,<< "Object of class "<< arg2<< " is still used by "<< arg1<< " other objects.\n"<< "(Additional information: "<< arg3<< ")\n"<< "Note the entry in the Frequently Asked Questions of "<< "deal.II (linked to from http://www.dealii.org/) for "<< "more information on what this error means.") | |
DeclException2 (ExcNoSubscriber, char *, char *,<< "No subscriber with identifier \""<< arg2<< "\" did subscribe to this object of class "<< arg1) | |
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 | |
![]() | |
enum | OutputStyle { Text = 1, LaTeX = 2, Description = 3, XML = 4, JSON = 5, ShortText = 193 } |
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.
<h3>Usage</h3> 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:
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:
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.
<h3>Syntax for variant and array entry values</h3> Variant values are specified like <tt>prefix{ v1 | v2 | v3 | ... }postfix</tt>. Whitespace to the right of the opening brace <tt>{</tt> is ignored as well as to the left of the closing brace <tt>}</tt> while whitespace on the respectively other side is not ignored. Whitespace around the mid symbols <tt>|</tt> is also ignored. The empty selection <tt>prefix{ v1 | }postfix</tt> is also allowed and produces the strings <tt>prefixv1postfix</tt> and <tt>prefixpostfix</tt>. The syntax for array values is equal, apart from the double braces: <tt>prefix{{ v1 | v2 | v3 }}postfix</tt>. <h3>Worked example</h3> 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 2202 of file parameter_handler.h.
MultipleParameterLoop::MultipleParameterLoop | ( | ) |
Constructor
|
virtual |
Destructor. Declare this only to have a virtual destructor, which is safer as we have virtual functions. It actually does nothing spectacular.
|
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.
Reimplemented from ParameterHandler.
|
virtual |
Read input from a file the name of which is given. The PathSearch class "PARAMETERS" is used to find the file.
Return whether the read was successful.
Unless optional
is true
, this function will automatically generate the requested file with default values if the file did not exist. This file will not contain additional comments if write_stripped_file
is true
.
Reimplemented from ParameterHandler.
|
virtual |
Read input from a string in memory. The lines in memory have to be separated by \n
characters.
Reimplemented from ParameterHandler.
void MultipleParameterLoop::loop | ( | UserClass & | uc | ) |
run the central loop.
std::size_t MultipleParameterLoop::memory_consumption | ( | ) | const |
Determine an estimate for the memory consumption (in bytes) of this object.
|
private |
Initialize the different branches, i.e. construct the combinations.
|
private |
Traverse the section currently set by enter_subsection()/leave_subsection() and see which of the entries are variante/array entries. Then fill the multiple_choices variable using this information.
|
private |
Transfer the entry values for one run to the entry tree.
|
private |
List of variant entry values.
Definition at line 2364 of file parameter_handler.h.
|
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 2370 of file parameter_handler.h.