#include <ParameterGroup.hpp>

Inheritance diagram for Opm::parameter::ParameterGroup:

Classes
struct	ConversionFailedException

struct	NotFoundException

struct	RequirementFailedException

struct	WrongTypeException

Public Member Functions
	ParameterGroup ()

	ParameterGroup (const std::string &path, const ParameterGroup *parent, const bool enable_output)

virtual	~ParameterGroup ()

virtual std::string	getTag () const
	This function returns a string describing the ParameterMapItem. More...

template<typename StringArray >
	ParameterGroup (int argc, StringArray argv, const bool verify_syntax=true, const bool enabled_output=true)
	A constructor typically used to initialize a ParameterGroup from command-line arguments. More...

bool	has (const std::string &name) const
	This method checks if there is something with name `name` in the parameter gropup. More...

template<typename T >
T	get (const std::string &name) const
	This method is used to read a parameter from the parameter group. More...

template<typename T , class Requirement >
T	get (const std::string &name, const Requirement &) const

template<typename T >
T	getDefault (const std::string &name, const T &default_value) const
	This method is used to read a parameter from the parameter group. More...

template<typename T , class Requirement >
T	getDefault (const std::string &name, const T &default_value, const Requirement &r) const

ParameterGroup	getGroup (const std::string &name) const
	This method returns the parameter group given by name, i.e. it is an alias of get<ParameterGroup>(). More...

void	disableOutput ()
	Disables the output from get, getDefault and getGroup. By default, such output is enabled. More...

void	enableOutput ()
	Enables the output from get, getDefault and getGroup. By default, such output is enabled. More...

bool	isOutputEnabled () const
	Returs true if and only if output from get, getDefault and getGroup is enabled. More...

void	readXML (const std::string &xml_filename)
	Reads the contents of the xml file specified by xml_filename into this ParameterGroup. More...

void	readParam (const std::string &param_filename)
	Reads the contents of the param file specified by param_filename into this ParameterGroup. More...

void	writeParam (const std::string &param_filename) const
	Writes this ParameterGroup into a param file specified by param_filename. More...

void	writeParamToStream (std::ostream &stream) const
	Writes this ParameterGroup to a stream. More...

template<typename T >
void	get (const char *name, T &value, const T &default_value) const
	vki param interface - deprecated More...

template<typename T >
void	get (const char *name, T &value) const
	vki param interface - deprecated More...

bool	anyUnused () const
	Return true if any parameters are unused. More...

void	displayUsage (bool used_params=false) const
	Shows which parameters which are used or unused. More...

std::string	path () const
	Returns the path of the parameter group. More...

void	insert (const std::string &name, const std::shared_ptr< ParameterMapItem > &data)
	Insert a new item into the group. More...

void	insertParameter (const std::string &name, const std::string &value)
	Insert a new parameter item into the group. More...

const std::vector< std::string > &	unhandledArguments () const
	Unhandled arguments from command line parsing. More...

template<>
std::string	to_string (const bool &b)

template<>
std::string	to_string (const ParameterGroup &)

void	setUsed () const

bool	used () const

Detailed Description

ParameterGroup is a class that is used to provide run-time parameters. The standard use of the class is to call create it with the (int argc, char** argv) constructor (where the arguments are those given by main). This parses the command line, where each token either A) specifies a parameter (by a "param=value" token). B) specifies a xml file to be read (by a "filename.xml" token). C) specifies a param file to be read (by a "filename.param" token). After the tokens are parsed they are stored in a tree structure in the ParameterGroup object; it is worth mentioning that parameters are inherited in this tree structure. Thus, if ``grid_prefix'' is given a value in the root node, this value will be visible in all parts of the tree (unless the parameter is overwritten in a subtree). Applications using this ParameterGroup objects will usually write out a message for each node in the three that is used by the application; this is one way to determine valid parameters.

Parameters specified as "param=value" on the command line

To specify a parameter on the command line, you must know where in the tree the parameter resides. The syntax for specifying parameters on the command line given an application called simulator'' is simulator param1=value grp/param2=valuegrp''. If the same parameters are specified multiple times on the command line, only the last will be used. Thus an application named ``simulator'' run with the following command simulator param=value1 param=value2 will use value2 as the value of ``param''.

XML parameters

In the introduction to this section it was mentioned that the parameters for the simulator are organized in a tree structure. This is mirrored in the XML file by the use of groups; a group is a collection of parameters and subgroups enclosed by a {<ParameterGroup>}-{</ParameterGroup>} pair. The only attribute of relevance in a {ParameterGroup} tag is that of {name}, which is used to navigate in the tree. The actual parameters are specified by the {<Parameter>} tag. Each parameter has three attributes: {name}, {type}, and {value}. Both name and value should be evident. Type is one of {bool} (for things that are either true or false), {int} (for integers), {double} (for floating point numbers with double precision), {string} (for text strings), or {file} (for files and directories relative to the location of the XML file).

param files

A param file consists of multiple lienes, where each line consists of "param=value". This syntax is identical to the one for paramters specified on the command line.

If one combines both XML files and parameters, one should note that that if a parameter is specified on the command line is also found in a XML file, the parameter specified on the command line is the one used. Thus, if parameters.xml'' specifies thatstepsize'' is 2.71828 while, the command used to run the application ``simulator'' is simulator stepsize=3.14159 parameters.xml the simulator will run with ``stepsize'' equal to 3.14159.

Constructor & Destructor Documentation

Opm::parameter::ParameterGroup::ParameterGroup ( )

Opm::parameter::ParameterGroup::ParameterGroup	(	const std::string &	path,
		const ParameterGroup *	parent,
		const bool	enable_output
	)

virtual Opm::parameter::ParameterGroup::~ParameterGroup ( )

virtual

template<typename StringArray >

Opm::parameter::ParameterGroup::ParameterGroup	(	int	argc,
		StringArray	argv,
		const bool	verify_syntax = `true`,
		const bool	enabled_output = `true`
	)

A constructor typically used to initialize a ParameterGroup from command-line arguments.

It is required that argv[0] is the program name, while if 0 < i < argc, then argv[i] is either the name of an xml file, parameter file or parametername=value.

Parameters

argc	is the number of command-line arguments, including the name of the executable.
argv	is an array of char*, each of which is a command line argument.
verify_syntax	If true (default), then it is an error to pass arguments that cannot be handled by the ParameterGroup, or an empty argument list. If false, such arguments are stored and can be retrieved later with unhandledArguments().
enable_output	Whether to enable output or not.

Member Function Documentation

bool Opm::parameter::ParameterGroup::anyUnused ( ) const

Return true if any parameters are unused.

void Opm::parameter::ParameterGroup::disableOutput ( )

Disables the output from get, getDefault and getGroup. By default, such output is enabled.

void Opm::parameter::ParameterGroup::displayUsage ( bool used_params = false ) const

Shows which parameters which are used or unused.

void Opm::parameter::ParameterGroup::enableOutput ( )

Enables the output from get, getDefault and getGroup. By default, such output is enabled.

template<typename T >

T Opm::parameter::ParameterGroup::get ( const std::string & name ) const

inline

This method is used to read a parameter from the parameter group.

NOTE: If the reading of the parameter fails, then this method throws an appropriate exception.

Parameters

name	is the name of the parameter in question.

Returns: The value associated with then name in this parameter group.

Referenced by get(), and Opm::initStateBasic().

template<typename T , class Requirement >

T Opm::parameter::ParameterGroup::get	(	const std::string &	name,
		const Requirement &	r
	)		const

inline

References get(), Opm::parameter::ID_delimiter_path, path(), Opm::parameter::ParameterMapItem::setUsed(), and Opm::parameter::split().

template<typename T >

void Opm::parameter::ParameterGroup::get	(	const char *	name,
		T &	value,
		const T &	default_value
	)		const

inline

vki param interface - deprecated

template<typename T >

void Opm::parameter::ParameterGroup::get	(	const char *	name,
		T &	value
	)		const

inline

vki param interface - deprecated

template<typename T >

T Opm::parameter::ParameterGroup::getDefault	(	const std::string &	name,
		const T &	default_value
	)		const

inline

This method is used to read a parameter from the parameter group.

NOTE: If the reading of the parameter fails, then either a) this method returns default_value if there was no parameter with name name in the parameter group or b) this method throws an appropriate exception.

Parameters

name	is the name of the parameter in question.
default_value	the default value of the parameter in question.

Returns: The value associated with this name in this parameter group.

Referenced by Opm::AdaptiveTimeStepping::AdaptiveTimeStepping(), getDefault(), and Opm::initStateBasic().

template<typename T , class Requirement >

T Opm::parameter::ParameterGroup::getDefault	(	const std::string &	name,
		const T &	default_value,
		const Requirement &	r
	)		const

inline

References getDefault(), Opm::parameter::ID_delimiter_path, path(), Opm::parameter::ParameterMapItem::setUsed(), and Opm::parameter::split().

ParameterGroup Opm::parameter::ParameterGroup::getGroup ( const std::string & name ) const

This method returns the parameter group given by name, i.e. it is an alias of get<ParameterGroup>().

Parameters

name	is the name of the parameter group sought.

Returns: the parameter group sought.

virtual std::string Opm::parameter::ParameterGroup::getTag ( ) const

virtual

This function returns a string describing the ParameterMapItem.

Implements Opm::parameter::ParameterMapItem.

bool Opm::parameter::ParameterGroup::has ( const std::string & name ) const

This method checks if there is something with name name in the parameter gropup.

Parameters

name	is the name of the parameter.

Returns: true if name is the name of something in the parameter group, false otherwise.

Referenced by Opm::initStateBasic().

void Opm::parameter::ParameterGroup::insert	(	const std::string &	name,
		const std::shared_ptr< ParameterMapItem > &	data
	)

Insert a new item into the group.

void Opm::parameter::ParameterGroup::insertParameter	(	const std::string &	name,
		const std::string &	value
	)

Insert a new parameter item into the group.

bool Opm::parameter::ParameterGroup::isOutputEnabled ( ) const

Returs true if and only if output from get, getDefault and getGroup is enabled.

Returns: true if and only if output from get, getDefault and getGroup is enabled.

std::string Opm::parameter::ParameterGroup::path ( ) const

Returns the path of the parameter group.

Referenced by get(), and getDefault().

void Opm::parameter::ParameterGroup::readParam ( const std::string & param_filename )

Reads the contents of the param file specified by param_filename into this ParameterGroup.

NOTE: A param file contains lines on the form 'a/b/c=d'. (e.g. c is a Parameter in the ParameterGroup b, and b is a ParameterGroup in the ParameterGroup a) while '=' separates the name from the value (e.g. the value of the parameter c above will be d). NOTE: A param file does not store any type information about its values.

Parameters

param_filename is the name of a param file.

void Opm::parameter::ParameterGroup::readXML ( const std::string & xml_filename )

Reads the contents of the xml file specified by xml_filename into this ParameterGroup.

Parameters

xml_filename is the name of a xml file.

void Opm::parameter::ParameterMapItem::setUsed ( ) const

inlineinherited

Referenced by get(), and getDefault().

template<>

std::string Opm::parameter::ParameterGroup::to_string ( const bool & b )

inline

References Opm::parameter::ID_false, and Opm::parameter::ID_true.

template<>

std::string Opm::parameter::ParameterGroup::to_string ( const ParameterGroup & )

inline

const std::vector<std::string>& Opm::parameter::ParameterGroup::unhandledArguments ( ) const

Unhandled arguments from command line parsing.

bool Opm::parameter::ParameterMapItem::used ( ) const

inlineinherited

void Opm::parameter::ParameterGroup::writeParam ( const std::string & param_filename ) const

Writes this ParameterGroup into a param file specified by param_filename.

Parameters

param_filename is the name of a param file.

void Opm::parameter::ParameterGroup::writeParamToStream ( std::ostream & stream ) const

Writes this ParameterGroup to a stream.

Parameters

stream is the stream to write to.

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

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation