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

Inheritance diagram for ParameterAcceptorProxy< SourceClass >:

Public Member Functions
template<typename... Args>
	ParameterAcceptorProxy (const std::string &section_name, Args... args)

virtual void	declare_parameters (ParameterHandler &prm) override

virtual void	parse_parameters (ParameterHandler &prm) override

std::string	get_section_name () const

std::vector< std::string >	get_section_path () const

template<class ParameterType >
void	add_parameter (const std::string &entry, ParameterType &parameter, const std::string &documentation="", ParameterHandler &prm_=prm, const Patterns::PatternBase &pattern= *Patterns::Tools::Convert< ParameterType >::to_pattern())

void	enter_subsection (const std::string &subsection)

void	leave_subsection ()

void	enter_my_subsection (ParameterHandler &prm)

void	leave_my_subsection (ParameterHandler &prm)

Static Public Member Functions
static void	initialize (const std::string &filename="", const std::string &output_filename="", const ParameterHandler::OutputStyle output_style_for_output_filename=ParameterHandler::Short, ParameterHandler &prm=ParameterAcceptor::prm, const ParameterHandler::OutputStyle output_style_for_filename=ParameterHandler::DefaultStyle)

static void	initialize (std::istream &input_stream, ParameterHandler &prm=ParameterAcceptor::prm)

static void	clear ()

static void	parse_all_parameters (ParameterHandler &prm=ParameterAcceptor::prm)

static void	declare_all_parameters (ParameterHandler &prm=ParameterAcceptor::prm)

Public Attributes
boost::signals2::signal< void()>	declare_parameters_call_back

boost::signals2::signal< void()>	parse_parameters_call_back

Static Public Attributes
static ParameterHandler	prm

Protected Attributes
const std::string	section_name

std::vector< std::string >	subsections

Private Attributes
const unsigned int	acceptor_id

Static Private Attributes
static std::vector< SmartPointer< ParameterAcceptor > >	class_list

static const char	sep = '/'

Subscriptor functionality
Classes derived from Subscriptor provide a facility to subscribe to this object. This is mostly used by the SmartPointer 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

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

static std::mutex	mutex

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 ::ExceptionBase &	ExcInUse (int arg1, std::string arg2, std::string arg3)

static ::ExceptionBase &	ExcNoSubscriber (std::string arg1, std::string arg2)

using	map_value_type = decltype(counter_map)::value_type

using	map_iterator = decltype(counter_map)::iterator

void	check_no_subscribers () const noexcept

Detailed Description

template<class SourceClass>
class ParameterAcceptorProxy< SourceClass >

A proxy ParameterAcceptor wrapper for classes that have a static member function declare_parameters, and a non virtual parse_parameters method.

If you cannot or do not want to derive your "parameter accepting" class from ParameterAcceptor, for example if by design you are required to have a static member function declare_parameters and a member parse_parameters, or if someone has already implemented such a class for you, and only provides you with an API that you cannot modify, then you may be able to use ParameterAcceptor facilities nonetheless, by wrapping your class into ParameterAcceptorProxy.

This class implements the public interface of ParameterAcceptor, and at the same time it derives from the template class SourceClass, allowing you to register your existing SourceClass as a ParameterAcceptor class, without requiring you to explicitly derive your SourceClass from ParameterAcceptor.

An example usage is given by the following snippet of code, using Functions::ParsedFunction as an example source class:

ParameterAcceptorProxy<Functions::ParsedFunction<2> > fun("Some function");

ParameterAcceptor::initialize("test.prm");

ParameterAcceptorProxy

Definition: parameter_acceptor.h:669

ParameterAcceptor::initialize

static void initialize(const std::string &filename="", const std::string &output_filename="", const ParameterHandler::OutputStyle output_style_for_output_filename=ParameterHandler::Short, ParameterHandler &prm=ParameterAcceptor::prm, const ParameterHandler::OutputStyle output_style_for_filename=ParameterHandler::DefaultStyle)

Definition: parameter_acceptor.cc:60

The above snippet of code will initialize ParameterAcceptor::prm with a section "Some function", and will correctly parse and assign to the object fun the expression parsed from the file test.prm. If non-existent, the program will exit, and generate it for you (here you can see the resulting short text version of the parameter file generated with the above snippet):

# Parameter file generated with
# DEAL_II_PACKAGE_VERSION = 9.0.0-pre
subsection Some function
  set Function constants  =
  set Function expression = 0
  set Variable names      = x,y,t
end

The resulting fun object, is both a ParsedFunction object and a ParameterAcceptor one, allowing you to use it as a replacement of the ParsedFunction class, with automatic declaration and parsing of parameter files.

See the tutorial program step-60 for an example on how to use this class.

Definition at line 668 of file parameter_acceptor.h.

Constructor & Destructor Documentation

◆ ParameterAcceptorProxy()

template<class SourceClass >

template<typename... Args>

ParameterAcceptorProxy< SourceClass >::ParameterAcceptorProxy	(	const std::string &	section_name,
		Args...	args
	)

Default constructor. The argument section_name is forwarded to the constructor of the ParameterAcceptor class, while all other arguments are passed to the SourceClass constructor.

Definition at line 714 of file parameter_acceptor.h.

Member Function Documentation

◆ declare_parameters()

template<class SourceClass >

void ParameterAcceptorProxy< SourceClass >::declare_parameters ( ParameterHandler & prm )

overridevirtual

Overloads the ParameterAcceptor::declare_parameters function, by calling SourceClass::declare_parameters with prm as an argument.

Reimplemented from ParameterAcceptor.

Definition at line 725 of file parameter_acceptor.h.

◆ parse_parameters()

template<class SourceClass >

void ParameterAcceptorProxy< SourceClass >::parse_parameters ( ParameterHandler & prm )

overridevirtual

Overloads the ParameterAcceptor::parse_parameters function, by calling SourceClass::parse_parameters with prm as an argument.

Reimplemented from ParameterAcceptor.

Definition at line 734 of file parameter_acceptor.h.

◆ initialize() [1/2]

void ParameterAcceptor::initialize	(	const std::string &	filename = `""`,
		const std::string &	output_filename = `""`,
		const ParameterHandler::OutputStyle	output_style_for_output_filename = `ParameterHandler::Short`,
		ParameterHandler &	prm = `ParameterAcceptor::prm`,
		const ParameterHandler::OutputStyle	output_style_for_filename = `ParameterHandler::DefaultStyle`
	)

staticinherited

Call declare_all_parameters(), read the parameters from filename (only if filename is a non-empty string), and then call parse_all_parameters().

If the parameter filename is the empty string, then no attempt to read a parameter file is done. This may be useful if you are ok with using default values, and don't want to read external files to use a class derived from ParameterAcceptor.

If output_filename is not the empty string, then we write the content that was read into the output_filename file, using the style specified in output_style_for_output_filename. The format of both input and output files are selected using the extensions of the files themselves. This can be either prm, xml, or json for the filename, and any of the supported formats for the output_filename.

If the input file does not exist, a default one with the same name is created for you following the style specified in output_style_for_filename, and an exception is thrown.

By default, the file format used to write the files is deduced from the extension of the file names. If the corresponding ParameterHandler::OutputStyle specifies a format specification, this must be compatible with the file extension, or an exception will be thrown.

If the extension is not recognized, and you do not specify a format in the corresponding ParameterHandler::OutputStyle, an assertion is thrown.

Parameters

filename	Input file name
output_filename	Output file name
output_style_for_output_filename	How to write the output file
prm	The ParameterHandler to use
output_style_for_filename	How to write the default input file if it does not exist

Definition at line 60 of file parameter_acceptor.cc.

◆ initialize() [2/2]

void ParameterAcceptor::initialize	(	std::istream &	input_stream,
		ParameterHandler &	prm = `ParameterAcceptor::prm`
	)

staticinherited

Call declare_all_parameters(), read the parameters from the input_stream in prm format, and then call parse_all_parameters().

An exception is thrown if the input_stream is invalid.

Parameters

input_stream	Input stream
prm	The ParameterHandler to use

Definition at line 94 of file parameter_acceptor.cc.

◆ clear()

void ParameterAcceptor::clear ( )

staticinherited

Clear class list and global parameter file.

Definition at line 106 of file parameter_acceptor.cc.

◆ parse_all_parameters()

void ParameterAcceptor::parse_all_parameters ( ParameterHandler & prm = ParameterAcceptor::prm )

staticinherited

Parse the given ParameterHandler. This function enters the subsection returned by get_section_name() for each derived class, and parses all parameters that were added using add_parameter().

Definition at line 127 of file parameter_acceptor.cc.

◆ declare_all_parameters()

void ParameterAcceptor::declare_all_parameters ( ParameterHandler & prm = ParameterAcceptor::prm )

staticinherited

Initialize the global ParameterHandler with all derived classes parameters.This function enters the subsection returned by get_section_name() for each derived class, and declares all parameters that were added using add_parameter().

Definition at line 142 of file parameter_acceptor.cc.

◆ get_section_name()

std::string ParameterAcceptor::get_section_name ( ) const

inherited

Return the section name of this class. If a name was provided at construction time, then that name is returned, otherwise it returns the demangled name of this class.

Definition at line 51 of file parameter_acceptor.cc.

◆ get_section_path()

std::vector< std::string > ParameterAcceptor::get_section_path ( ) const

inherited

Traverse all registered classes, and figure out what subsections we need to enter.

Definition at line 157 of file parameter_acceptor.cc.

◆ add_parameter()

template<class ParameterType >

void ParameterAcceptor::add_parameter	(	const std::string &	entry,
		ParameterType &	parameter,
		const std::string &	documentation = `""`,
		ParameterHandler &	prm_ = `prm`,
		const Patterns::PatternBase &	pattern = `*Patterns::Tools::Convert<ParameterType>::to_pattern()`
	)

inherited

Add a parameter in the correct path. This method forwards all arguments to the prm.add_parameter() method, after entering the correct section path. By default it uses the ParameterAcceptor::prm variable as ParameterHandler.

See the documentation of ParameterHandler::add_parameter() for more information.

Definition at line 699 of file parameter_acceptor.h.

◆ enter_subsection()

void ParameterAcceptor::enter_subsection ( const std::string & subsection )

inherited

Add the given subsection to the global path stored in this class.

This function changes the behavior of enter_my_subsection(), by appending a new subsection to the path stored in this class.

This method can be used to split the parameters of this class into subsections, while still maintaining the general behavior of this class.

An example usage is given by the following snippet:

class MyClass : public ParameterAcceptor
{
  MyClass()
    : ParameterAcceptor("Main section")
  {
    add_parameter("A param", member_var);
    enter_subsection("New section");
    add_parameter("Another param", another_member_var);
    leave_subsection();
  }
 
private:
  std::vector<unsigned int> member_var = {1,2};
  std::map<types::boundary_id, std::string> another_member_var;
  ...
};
 
int main()
{
  // ParameterAcceptor::initialize()
  MyClass class;
 
  // With this call, all derived classes will have their
  // parameters initialized
  ParameterAcceptor::initialize("file.prm");
}

which will produce a parameter file organized as

subsection Main section
  set A param = 1, 2
  subsection New section
    set Another param =
  end
end

Definition at line 202 of file parameter_acceptor.cc.

◆ leave_subsection()

void ParameterAcceptor::leave_subsection ( )

inherited

Leave the subsection that was entered by calling the enter_subsection() function.

Definition at line 217 of file parameter_acceptor.cc.

◆ enter_my_subsection()

void ParameterAcceptor::enter_my_subsection ( ParameterHandler & prm = ParameterAcceptor::prm )

inherited

Make sure we enter the right subsection of the given parameter.

Definition at line 227 of file parameter_acceptor.cc.

◆ leave_my_subsection()

void ParameterAcceptor::leave_my_subsection ( ParameterHandler & prm = ParameterAcceptor::prm )

inherited

This function undoes what the enter_my_subsection() function did. It only makes sense if enter_my_subsection() was called on prm before this one.

Definition at line 240 of file parameter_acceptor.cc.

Member Data Documentation

◆ declare_parameters_call_back

boost::signals2::signal<void()> ParameterAcceptor::declare_parameters_call_back

inherited

Declare parameter call back. This signal is triggered right after declare_parameters() has been called, to allow users to prepare their variables right after parameters have been declared. The default implementation is empty.

Definition at line 443 of file parameter_acceptor.h.

◆ parse_parameters_call_back

boost::signals2::signal<void()> ParameterAcceptor::parse_parameters_call_back

inherited

Parse parameter call back. This function is called at the end of parse_parameters(), to allow users to process their parameters right after they have been parsed. The default implementation is empty.

You can use this function, for example, to create a quadrature rule after you have read how many quadrature points you wanted to use from the parameter file.

Definition at line 462 of file parameter_acceptor.h.

◆ prm

ParameterHandler ParameterAcceptor::prm

staticinherited

The global parameter handler.

Definition at line 517 of file parameter_acceptor.h.

◆ class_list

std::vector< SmartPointer< ParameterAcceptor > > ParameterAcceptor::class_list

staticprivateinherited

A list containing all constructed classes of type ParameterAcceptor.

Definition at line 598 of file parameter_acceptor.h.

◆ acceptor_id

const unsigned int ParameterAcceptor::acceptor_id

privateinherited

The index of this specific class within the class list.

Definition at line 601 of file parameter_acceptor.h.

◆ sep

const char ParameterAcceptor::sep = '/'

staticprivateinherited

Separator between sections.

Definition at line 606 of file parameter_acceptor.h.

◆ section_name

const std::string ParameterAcceptor::section_name

protectedinherited

The subsection name for this class.

Definition at line 610 of file parameter_acceptor.h.

◆ subsections

std::vector<std::string> ParameterAcceptor::subsections

protectedinherited

The subsubsections that are currently active.

Definition at line 613 of file parameter_acceptor.h.

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

include/deal.II/base/parameter_acceptor.h

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Attributes

Private Attributes

Static Private Attributes

Subscriptor functionality

Detailed Description

Constructor & Destructor Documentation

◆ ParameterAcceptorProxy()

Member Function Documentation

◆ declare_parameters()

◆ parse_parameters()

◆ initialize() [1/2]

◆ initialize() [2/2]

◆ clear()

◆ parse_all_parameters()

◆ declare_all_parameters()

◆ get_section_name()

◆ get_section_path()

◆ add_parameter()

◆ enter_subsection()

◆ leave_subsection()

◆ enter_my_subsection()

◆ leave_my_subsection()

Member Data Documentation

◆ declare_parameters_call_back

◆ parse_parameters_call_back

◆ prm

◆ class_list

◆ acceptor_id

◆ sep

◆ section_name

◆ subsections