Runner Namespace Reference

Gather some functions and classes typically used in the main() of the FSI-suite applications. More...

Functions
std::tuple< int, int, std::string, std::string >	get_dimensions_and_parameter_files (char **argv)
	Parse from the command line the parameter file names (both input and output) and the running dimensions (both dim and spacedim). More...
int	setup_parameters_from_cli (char **argv, const std::string &input_parameter_file, const std::string &output_parameter_file)
	Setup the ParameterAcceptor::prm according to the parameters specified in the parameter file, and the parameters specified from the command line. More...
template<typename Class >
void	run (char **argv, const std::string &input_parameter_file, const std::string &output_parameter_file)
	Setup parameters from the command line, and call the Class::run() method. More...
std::pair< unsigned int, unsigned int >	get_dimension_and_spacedimension (const std::string &prm_file, const unsigned int default_dim=2, const unsigned int default_spacedim=2)
	Retrieves the dimension and space dimension from a parameter file. More...

Detailed Description

Gather some functions and classes typically used in the main() of the FSI-suite applications.

Function Documentation

get_dimensions_and_parameter_files()

std::tuple< int, int, std::string, std::string > Runner::get_dimensions_and_parameter_files

(

char **

argv

)

Parse from the command line the parameter file names (both input and output) and the running dimensions (both dim and spacedim).

Retrieves the dimensions and parameter files from the command line arguments.

This function uses the command line interface parsers from the argh library (https://github.com/adishavit/argh), and recognizes the following parameters from the command line:

./your_code_here --help
Usage: ./your_code_here [OPTIONS] [PRM FILE]
Options:
-h, --help                        Print this help message
-p, --prm_file <filename>         Input parameter file. Defaults to the
                                  empty string (meaning: use the default
                                  values, or the values specified on the
                                  command line). Notice that you can
                                  specify the input paramter file also as
                                  the first positional arguement to the
                                  program.
-o, --output_prm_file <filename>  Where to write the file containing the
                                  actual parameters used in this run of
                                  the program. It defaults to the string
                                  `used_./mesh_handler' followed by a
                                  string of the type '1d_2d' containing
                                  the dimension and the spacedimension at
                                  which the program was run if the input
                                  parameter file is not specified,
                                  otherwise it defaults to the string
                                  `used_' followed by the name of the
                                  input parameter file.
-d, --dim <value>                 Dimension at which this program should
                                  be run. Defaults to 2.
-s, --spacedim <value>            Space dimension at which this program
                                  should run. Defaults to 2.
-"Section/option name"=<value>    Any of the options that you can specify
                                  in the parameter file. The format here
                                  is the following: -"Section/Subsection/
                                  option"="value,another value", where the
                                  quotes are required only if an otpion
                                  contains spaces, or if a value contains
                                  separators, like commas, columns, etc.

Warning

This function is usually called before any class initialization takes place. You should use this function in conjunction with its companion function setup_parameters_from_cli(). The order of execution must follow the following guidelines:

1. call get_dimensions_and_parameter_files()
2. initialize the classes of the correct dimension and spacedimension
3. call ParameterAcceptor::initialize()
4. call setup_parameters_from_cli()

Example usage (assuming you have a class called MyClass derived from ParameterAcceptor):

int main(int argc, char **argv) {
 auto [dim, spacedim, infile, outfile] =
      get_dimensions_and_parameter_files(argv);
 // do something with dim and spacedim...
 MyClass<dimpar, spacedimpar> my_class;
 ParameterAcceptor::initialize();
 // Check we were not asked to print help message
 if(setup_parameters_from_cli(argv, infile, outfile) == -1)
   return 0;
 my_class.run();
}

Parameters

argv	Arguments of the command line.

Returns

(dim, spacedim, input_parameters, output_parameters) Desired dimension and spacedimesion of the problem to run, and input and output parameter filenames.

This function parses the command line arguments and extracts the dimensions and parameter file names. It supports both options and positional arguments for specifying the input parameter file. It also checks if the dimensions specified in the parameter file and the command line arguments match.

Parameters

argv	The command line arguments.

Returns

A tuple containing the dimensions and parameter file names. The tuple elements are in the following order:

• int: The dimension.
• int: The space dimension.
• std::string: The input parameter file name.
• std::string: The output parameter file name.

Definition at line 89 of file runner.cc.

References AssertThrow, deallog, StandardExceptions::ExcMessage(), and get_dimension_and_spacedimension().

setup_parameters_from_cli()

int Runner::setup_parameters_from_cli	(	char **	argv,
		const std::string &	input_parameter_file,
		const std::string &	output_parameter_file
	)

Setup the ParameterAcceptor::prm according to the parameters specified in the parameter file, and the parameters specified from the command line.

Sets up the program parameters from the command-line arguments.

This function uses the command line interface parsers from the argh library (https://github.com/adishavit/argh), and allows you to specify input parameter files, output parameter files, and to change any option recognized by the parameter file itself from the command line.

This function is usually used in conjunction with the function get_dimensions_and_parameter_files(), in order to ask from the command line what simulation to run (1d, 2d, 3d, etc.), and what input parameter files to read from. These are then passed to this function, after you have called at least once ParameterAcceptor::initialize() on your classes (which you will have instantiated with the correct dimension thanks to the function above).

Example usage (assuming you have a class called MyClass derived from ParameterAcceptor):

int main(int argc, char **argv) {
 auto [dim, spacedim, infile, outfile] =
      get_dimensions_and_parameter_files(argv);
 // do something with dim and spacedim...
 if(dim == 2 && spacedim == 2) {
   MyClass<2, 2> my_class;
   ParameterAcceptor::initialize();
   // Check we were not asked to print help message
   if(setup_parameters_from_cli(argv, infile, outfile) == -1)
     return 0;
   my_class.run();
 }
}

If the option -h or --help is found on the command line, this function outputs the following help message:

./your_code_here --help
Usage: ./your_code_here [OPTIONS] [PRM FILE]
Options:
-h, --help                        Print this help message
-i, --input_prm_file <filename>   Input parameter file. Defaults to the
                                  empty string (meaning: use the default
                                  values, or the values specified on the
                                  command line). Notice that you can
                                  specify the input paramter file also as
                                  the first positional arguement to the
                                  program.
-o, --output_prm_file <filename>  Where to write the file containing the
                                  actual parameters used in this run of
                                  the program. It defaults to the string
                                  `used_./mesh_handler' followed by a
                                  string of the type '1d_2d' containing
                                  the dimension and the spacedimension at
                                  which the program was run if the input
                                  parameter file is not specified,
                                  otherwise it defaults to the string
                                  `used_' followed by the name of the
                                  input parameter file.
-d, --dim <value>                 Dimension at which this program should
                                  be run. Defaults to 2.
-s, --spacedim <value>            Space dimension at which this program
                                  should run. Defaults to 2.
-"Section/option name"=<value>    Any of the options that you can specify
                                  in the parameter file. The format here
                                  is the following: -"Section/Subsection/
                                  option"="value,another value", where the
                                  quotes are required only if an otpion
                                  contains spaces, or if a value contains
                                  separators, like commas, columns, etc.

followed by a list of the options that are recognized by the parameter file, i.e., for the mesh_handler.cc application, we get:

...
Listing of Parameters:
 
set Arguments                 = Any string
set Initial grid refinement   = An integer
set Input name                = Any string
set Output name               = Any string
set Transform to simplex grid = A boolean value (true or false)
set Verbosity                 = An integer n such that -1<= n <=2147483647

Warning

This function is usually called after classes are constructed and initialized (i.e., after calling ParameterAcceptor::initialize()). In order to extract dimension and spacedimension from the command line, you can use this function in conjunction with its companion function get_dimensions_and_parameter_files(). The order of execution must follow the following guidelines:

1. call get_dimensions_and_parameter_files()
2. initialize the classes of the correct dimension and spacedimension
3. call ParameterAcceptor::initialize()
4. call setup_parameters_from_cli()

Returns

0: everything is fine, 1: unused parameters, -1: help printed

This function parses the command-line arguments using the argh library and sets up the program parameters accordingly. It initializes the ParameterAcceptor with the input and output parameter file paths. If the -h or --help option is provided, it prints the help message and the list of available options. The function also handles setting the values for options specified in the command-line arguments. It ignores any positional arguments other than the program name and the input parameter file. After setting up the parameters, it initializes the ParameterAcceptor again with the output parameter file path. If the --pause option is provided and the current MPI process is the root process, it waits for a keypress before continuing.

Parameters

argv	The command-line arguments.
input_parameter_file	The path to the input parameter file.
output_parameter_file	The path to the output parameter file.

Returns

Returns 0 if everything went fine, or 1 if there were any warnings or errors.

Definition at line 183 of file runner.cc.

References b(), deallog, ParameterHandler::Description, ParameterHandler::enter_subsection(), ParameterAcceptor::initialize(), ParameterHandler::KeepDeclarationOrder, ParameterHandler::leave_subsection(), ParameterHandler::print_parameters(), ParameterAcceptor::prm, sec(), ParameterHandler::set(), ParameterHandler::Short, Utilities::split_string_list(), and Utilities::MPI::this_mpi_process().

Referenced by run().

run()

template<typename Class >

void Runner::run	(	char **	argv,
		const std::string &	input_parameter_file,
		const std::string &	output_parameter_file
	)

Setup parameters from the command line, and call the Class::run() method.

Template Parameters

Class

Type of the class to instantiate and run.

Parameters

argv	Arguments of the command line.
input_parameter_file	Input parameter file.
output_parameter_file	Output parameter file.

Definition at line 219 of file runner.h.

References setup_parameters_from_cli().

get_dimension_and_spacedimension()

std::pair<unsigned int, unsigned int> Runner::get_dimension_and_spacedimension	(	const std::string &	prm_file,
		const unsigned int	default_dim = 2,
		const unsigned int	default_spacedim = 2
	)

Retrieves the dimension and space dimension from a parameter file.

This function reads a parameter file and retrieves the values of the "dimension" and "space dimension" parameters. If the reading of the input file fails, it returns the default values provided.

prm_file The path to the parameter file. default_dim The default value for the dimension. default_spacedim The default value for the space dimension.

Returns

A pair containing the dimension and space dimension.

Exceptions

std::exception

If an error occurs while parsing the input file.

Definition at line 46 of file runner.cc.

References ParameterHandler::declare_entry(), ParameterHandler::get_integer(), ParameterHandler::parse_input(), and ParameterAcceptor::prm.

Referenced by get_dimensions_and_parameter_files().