Reference documentation for deal.II version Git 2a81969 2017-11-21 09:22:35 +0100
parameter_handler.h
1 // ---------------------------------------------------------------------
2 //
3 // Copyright (C) 1998 - 2017 by the deal.II authors
4 //
5 // This file is part of the deal.II library.
6 //
7 // The deal.II library is free software; you can use it, redistribute
8 // it, and/or modify it under the terms of the GNU Lesser General
9 // Public License as published by the Free Software Foundation; either
10 // version 2.1 of the License, or (at your option) any later version.
11 // The full text of the license can be found in the file LICENSE at
12 // the top level of the deal.II distribution.
13 //
14 // ---------------------------------------------------------------------
15 
16 #ifndef dealii_parameter_handler_h
17 #define dealii_parameter_handler_h
18 
19 
20 #include <deal.II/base/config.h>
21 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/subscriptor.h>
23 #include <deal.II/base/patterns.h>
24 
25 #include <boost/property_tree/ptree_fwd.hpp>
26 #include <boost/serialization/split_member.hpp>
27 #include <boost/archive/basic_archive.hpp>
28 #include <boost/property_tree/ptree_serialization.hpp>
29 
30 #include <map>
31 #include <vector>
32 #include <string>
33 #include <memory>
34 
35 DEAL_II_NAMESPACE_OPEN
36 
37 // forward declarations for interfaces and friendship
38 class LogStream;
40 
800 {
801 private:
805  ParameterHandler (const ParameterHandler &) = delete;
806 
810  ParameterHandler &operator= (const ParameterHandler &) = delete;
811 
812 public:
817  {
822  Text = 1,
823 
827  LaTeX = 2,
832 
839  XML = 4,
840 
845  JSON = 5,
846 
851  ShortText = 193
852  };
853 
854 
855 
859  ParameterHandler ();
860 
866  virtual ~ParameterHandler () = default;
867 
896  virtual void parse_input (std::istream &input,
897  const std::string &filename = "input file",
898  const std::string &last_line = "");
899 
943  virtual void parse_input (const std::string &filename,
944  const std::string &last_line = "");
945 
954  virtual void parse_input_from_string (const char *s,
955  const std::string &last_line = "");
956 
964  virtual void parse_input_from_xml (std::istream &input);
965 
969  void clear ();
970 
971 
991  void declare_entry (const std::string &entry,
992  const std::string &default_value,
993  const Patterns::PatternBase &pattern = Patterns::Anything(),
994  const std::string &documentation = std::string());
995 
1038  void add_action (const std::string &entry,
1039  const std::function<void (const std::string &value)> &action);
1040 
1050  template <class ParameterType>
1051  void add_parameter(const std::string &entry,
1052  ParameterType &parameter,
1053  const std::string &documentation = std::string(),
1054  const Patterns::PatternBase &pattern =
1056 
1100  void declare_alias (const std::string &existing_entry_name,
1101  const std::string &alias_name,
1102  const bool alias_is_deprecated = false);
1103 
1107  void enter_subsection (const std::string &subsection);
1108 
1112  void leave_subsection ();
1113 
1119  std::string get (const std::string &entry_string) const;
1120 
1126  long int get_integer (const std::string &entry_string) const;
1127 
1131  double get_double (const std::string &entry_name) const;
1132 
1138  bool get_bool (const std::string &entry_name) const;
1139 
1149  void set (const std::string &entry_name,
1150  const std::string &new_value);
1151 
1162  void set (const std::string &entry_name,
1163  const char *new_value);
1164 
1174  void set (const std::string &entry_name,
1175  const long int &new_value);
1176 
1190  void set (const std::string &entry_name,
1191  const double &new_value);
1192 
1202  void set (const std::string &entry_name,
1203  const bool &new_value);
1204 
1205 
1264  std::ostream &
1265  print_parameters (std::ostream &out,
1266  const OutputStyle style) const;
1267 
1285  DEAL_II_DEPRECATED
1286  void print_parameters_section (std::ostream &out,
1287  const OutputStyle style,
1288  const unsigned int indent_level,
1289  const bool include_top_level_elements = false);
1290 
1296  void log_parameters (LogStream &out);
1297 
1307  void log_parameters_section (LogStream &out);
1308 
1313  std::size_t memory_consumption () const;
1314 
1319  template <class Archive>
1320  void save (Archive &ar, const unsigned int version) const;
1321 
1326  template <class Archive>
1327  void load (Archive &ar, const unsigned int version);
1328 
1329  BOOST_SERIALIZATION_SPLIT_MEMBER()
1330 
1331 
1334  bool operator == (const ParameterHandler &prm2) const;
1335 
1345  std::string,
1346  << "The following entry already exists: " << arg1 << ".");
1351  std::string, std::string,
1352  << "The string <" << arg1
1353  << "> does not match the given pattern <" << arg2 << ">.");
1358  "You can't leave a subsection if you are already at the top level "
1359  "of the subsection hierarchy.");
1364  std::string,
1365  << "You can't ask for entry <" << arg1 << "> you have not yet declared.");
1366 
1374  std::string, std::string,
1375  << "There are unequal numbers of 'subsection' and 'end' "
1376  "statements in the parameter file <" << arg1 << ">."
1377  << (arg2.size() > 0 ? "\n" + arg2 : ""));
1378 
1384  int, std::string, std::string,
1385  << "Line <" << arg1 << "> of file <" << arg2 << ": There is "
1386  "no such subsection to be entered: " << arg3);
1387 
1394  int, std::string, std::string, << "Line <" << arg1 <<
1395  "> of file <" << arg2 << ">: " << arg3);
1396 
1403  int, std::string, std::string, std::string, std::string,
1404  << "Line <" << arg1 << "> of file <" << arg2 << ">:\n"
1405  " The entry value \n" << " " << arg3 << '\n' <<
1406  " for the entry named\n" << " " << arg4 << '\n' <<
1407  " does not match the given pattern:\n" << " " <<
1408  arg5);
1409 
1416  "The provided file could not be parsed as a "
1417  "ParameterHandler description.");
1418 
1425  std::string, std::string, std::string,
1426  << " The entry value \n" << " " << arg1 << '\n' <<
1427  " for the entry named\n" << " " << arg2 << '\n' <<
1428  " does not match the given pattern:\n" << " " <<
1429  arg3);
1430 
1438  int, std::string, std::string,
1439  << "Line <" << arg1 << "> of file <" << arg2 << ">: This line "
1440  "contains an 'include' or 'INCLUDE' statement, but the given "
1441  "file to include <" << arg3 << "> cannot be opened.");
1442 
1444 private:
1449  static const char path_separator = '.';
1450 
1454  std::vector<std::string> subsection_path;
1455 
1464  std::unique_ptr<boost::property_tree::ptree> entries;
1465 
1471  std::vector<std::shared_ptr<const Patterns::PatternBase> > patterns;
1472 
1479  std::vector<std::function<void (const std::string &)> > actions;
1480 
1485  static std::string mangle (const std::string &s);
1486 
1490  static std::string demangle (const std::string &s);
1491 
1498  static
1499  std::string
1500  collate_path_string (const std::vector<std::string> &subsection_path);
1501 
1510  std::string get_current_path () const;
1511 
1516  std::string get_current_full_path (const std::string &name) const;
1517 
1530  void scan_line (std::string line,
1531  const std::string &input_filename,
1532  const unsigned int current_line_n);
1533 
1545  void recursively_print_parameters (const std::vector<std::string> &target_subsection_path,
1546  const OutputStyle style,
1547  const unsigned int indent_level,
1548  std::ostream &out) const;
1549 
1550  friend class MultipleParameterLoop;
1551 };
1552 
1553 
1554 
1771 class MultipleParameterLoop : public ParameterHandler
1772 {
1773 public:
1779  {
1780  public:
1785  virtual ~UserClass () = default;
1786 
1791  virtual void create_new (const unsigned int run_no) = 0;
1792 
1796  virtual void run (ParameterHandler &prm) = 0;
1797  };
1798 
1802  MultipleParameterLoop ();
1803 
1808  virtual ~MultipleParameterLoop () = default;
1809 
1825  virtual void parse_input (std::istream &input,
1826  const std::string &filename = "input file",
1827  const std::string &last_line = "") override;
1828 
1837 
1841  void loop (UserClass &uc);
1842 
1847  std::size_t memory_consumption () const;
1848 
1849 private:
1850 
1854  class Entry
1855  {
1856  public:
1863  {
1871  array
1872  };
1873 
1877  Entry () : type (array) {}
1878 
1884  Entry (const std::vector<std::string> &Path,
1885  const std::string &Name,
1886  const std::string &Value);
1887 
1891  void split_different_values ();
1892 
1896  std::vector<std::string> subsection_path;
1897 
1901  std::string entry_name;
1902 
1906  std::string entry_value;
1907 
1912  std::vector<std::string> different_values;
1913 
1918 
1923  std::size_t memory_consumption () const;
1924  };
1925 
1929  std::vector<Entry> multiple_choices;
1930 
1935  unsigned int n_branches;
1936 
1940  void init_branches ();
1941 
1948  void init_branches_current_section ();
1949 
1953  void fill_entry_values (const unsigned int run_no);
1954 };
1955 
1956 
1957 // ---------------------- inline and template functions --------------------
1958 template <class Archive>
1959 inline
1960 void
1961 ParameterHandler::save (Archive &ar, const unsigned int) const
1962 {
1963  // Forward to serialization
1964  // function in the base class.
1965  ar &static_cast<const Subscriptor &>(*this);
1966 
1967  ar & *entries.get();
1968 
1969  std::vector<std::string> descriptions;
1970 
1971  for (unsigned int j=0; j<patterns.size(); ++j)
1972  descriptions.push_back (patterns[j]->description());
1973 
1974  ar &descriptions;
1975 }
1976 
1977 
1978 template <class Archive>
1979 inline
1980 void
1981 ParameterHandler::load (Archive &ar, const unsigned int)
1982 {
1983  // Forward to serialization
1984  // function in the base class.
1985  ar &static_cast<Subscriptor &>(*this);
1986 
1987  ar & *entries.get();
1988 
1989  std::vector<std::string> descriptions;
1990  ar &descriptions;
1991 
1992  patterns.clear ();
1993  for (unsigned int j=0; j<descriptions.size(); ++j)
1994  patterns.push_back (std::shared_ptr<const Patterns::PatternBase>(Patterns::pattern_factory(descriptions[j])));
1995 }
1996 
1997 
1998 template <class ParameterType>
1999 void ParameterHandler::add_parameter(const std::string &entry,
2000  ParameterType &parameter,
2001  const std::string &documentation,
2002  const Patterns::PatternBase &pattern)
2003 {
2004 
2005  static_assert(std::is_const<ParameterType>::value == false,
2006  "You tried to add a parameter using a type "
2007  "that is const. Use a non-const type.");
2008 
2009  declare_entry(entry,
2011  parameter, pattern.clone()),
2012  pattern,
2013  documentation);
2014 
2015  std::string path = get_current_full_path(entry);
2016  const unsigned int pattern_index
2017  = entries->get<unsigned int> (path + path_separator + "pattern");
2018 
2019  auto action = [ &, pattern_index](const std::string &val)
2020  {
2021  parameter =
2022  Patterns::Tools::Convert<ParameterType>::to_value(val, patterns[pattern_index]->clone());
2023  };
2024  add_action(entry, action);
2025 }
2026 
2027 DEAL_II_NAMESPACE_CLOSE
2028 
2029 #endif
void add_parameter(const std::string &entry, ParameterType &parameter, const std::string &documentation=std::string(), const Patterns::PatternBase &pattern=*Patterns::Tools::Convert< ParameterType >::to_pattern())
std::vector< Entry > multiple_choices
void loop(ITERATOR begin, typename identity< ITERATOR >::type end, DOFINFO &dinfo, INFOBOX &info, const std::function< void(DOFINFO &, typename INFOBOX::CellInfo &)> &cell_worker, const std::function< void(DOFINFO &, typename INFOBOX::CellInfo &)> &boundary_worker, const std::function< void(DOFINFO &, DOFINFO &, typename INFOBOX::CellInfo &, typename INFOBOX::CellInfo &)> &face_worker, ASSEMBLER &assembler, const LoopControl &lctrl=LoopControl())
Definition: loop.h:386
static const char path_separator
#define DeclException2(Exception2, type1, type2, outsequence)
Definition: exceptions.h:605
static::ExceptionBase & ExcEntryAlreadyExists(std::string arg1)
static std::string collate_path_string(const std::vector< std::string > &subsection_path)
std::string get_current_full_path(const std::string &name) const
static::ExceptionBase & ExcInvalidEntryForPatternXML(std::string arg1, std::string arg2, std::string arg3)
static::ExceptionBase & ExcCannotOpenIncludeStatementFile(int arg1, std::string arg2, std::string arg3)
static::ExceptionBase & ExcEntryUndeclared(std::string arg1)
static T to_value(const std::string &s, const std::unique_ptr< Patterns::PatternBase > &p=Convert< T >::to_pattern())=delete
virtual ~ParameterHandler()=default
static::ExceptionBase & ExcUnbalancedSubsections(std::string arg1, std::string arg2)
void log_parameters(LogStream &out)
virtual std::unique_ptr< PatternBase > clone() const =0
void set(const std::string &entry_name, const std::string &new_value)
void log_parameters_section(LogStream &out)
STL namespace.
std::vector< std::string > subsection_path
static::ExceptionBase & ExcValueDoesNotMatchPattern(std::string arg1, std::string arg2)
void load(Archive &ar, const unsigned int version)
std::vector< std::string > subsection_path
void enter_subsection(const std::string &subsection)
virtual void parse_input_from_xml(std::istream &input)
static::ExceptionBase & ExcInvalidXMLParameterFile()
std::vector< std::shared_ptr< const Patterns::PatternBase > > patterns
static::ExceptionBase & ExcCannotParseLine(int arg1, std::string arg2, std::string arg3)
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:593
std::ostream & print_parameters(std::ostream &out, const OutputStyle style) const
void save(Archive &ar, const unsigned int version) const
#define DeclExceptionMsg(Exception, defaulttext)
Definition: exceptions.h:582
static std::string mangle(const std::string &s)
std::string get_current_path() const
std::unique_ptr< boost::property_tree::ptree > entries
#define DeclException5(Exception5, type1, type2, type3, type4, type5, outsequence)
Definition: exceptions.h:641
std::unique_ptr< PatternBase > pattern_factory(const std::string &description)
Definition: patterns.cc:139
virtual void parse_input_from_string(const char *s, const std::string &last_line="")
static::ExceptionBase & ExcAlreadyAtTopLevel()
bool get_bool(const std::string &entry_name) const
void add_action(const std::string &entry, const std::function< void(const std::string &value)> &action)
static std::string demangle(const std::string &s)
double get_double(const std::string &entry_name) const
void print_parameters_section(std::ostream &out, const OutputStyle style, const unsigned int indent_level, const bool include_top_level_elements=false)
void declare_entry(const std::string &entry, const std::string &default_value, const Patterns::PatternBase &pattern=Patterns::Anything(), const std::string &documentation=std::string())
std::vector< std::string > different_values
std::vector< std::function< void(const std::string &)> > actions
void scan_line(std::string line, const std::string &input_filename, const unsigned int current_line_n)
#define DeclException3(Exception3, type1, type2, type3, outsequence)
Definition: exceptions.h:617
static::ExceptionBase & ExcInvalidEntryForPattern(int arg1, std::string arg2, std::string arg3, std::string arg4, std::string arg5)
void recursively_print_parameters(const std::vector< std::string > &target_subsection_path, const OutputStyle style, const unsigned int indent_level, std::ostream &out) const
static::ExceptionBase & ExcNoSubsection(int arg1, std::string arg2, std::string arg3)
void declare_alias(const std::string &existing_entry_name, const std::string &alias_name, const bool alias_is_deprecated=false)
std::size_t memory_consumption() const
long int get_integer(const std::string &entry_string) const
ParameterHandler & operator=(const ParameterHandler &)=delete
virtual void parse_input(std::istream &input, const std::string &filename="input file", const std::string &last_line="")