Reference documentation for deal.II version Git 3c7a6dea12 2020-04-01 12:43:31 -0400
\(\newcommand{\vcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\vcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
parameter_handler.h
1 // ---------------------------------------------------------------------
2 //
3 // Copyright (C) 1998 - 2019 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.md at
12 // the top level directory of deal.II.
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 
22 #include <deal.II/base/exceptions.h>
23 #include <deal.II/base/patterns.h>
24 #include <deal.II/base/subscriptor.h>
25 
26 #include <boost/archive/basic_archive.hpp>
27 #include <boost/property_tree/ptree_fwd.hpp>
28 #include <boost/property_tree/ptree_serialization.hpp>
29 #include <boost/serialization/split_member.hpp>
30 
31 #include <map>
32 #include <memory>
33 #include <string>
34 #include <vector>
35 
36 DEAL_II_NAMESPACE_OPEN
37 
38 // forward declarations for interfaces and friendship
39 #ifndef DOXYGEN
40 class LogStream;
42 #endif
43 
846 {
847 public:
853  {
858  Text = 1,
859 
863  LaTeX = 2,
868 
875  XML = 4,
876 
881  JSON = 5,
882 
887  ShortText = 193
888  };
889 
890 
891 
896 
902  virtual ~ParameterHandler() override = default;
903 
907  ParameterHandler(const ParameterHandler &) = delete;
908 
913  operator=(const ParameterHandler &) = delete;
914 
949  virtual void
950  parse_input(std::istream & input,
951  const std::string &filename = "input file",
952  const std::string &last_line = "",
953  const bool skip_undefined = false);
954 
998  virtual void
999  parse_input(const std::string &filename,
1000  const std::string &last_line = "",
1001  const bool skip_undefined = false);
1002 
1011  virtual void
1012  parse_input_from_string(const std::string &s,
1013  const std::string &last_line = "",
1014  const bool skip_undefined = false);
1015 
1023  virtual void
1024  parse_input_from_xml(std::istream &input, const bool skip_undefined = false);
1025 
1033  virtual void
1034  parse_input_from_json(std::istream &input, const bool skip_undefined = false);
1035 
1039  void
1040  clear();
1041 
1042 
1062  void
1063  declare_entry(const std::string & entry,
1064  const std::string & default_value,
1065  const Patterns::PatternBase &pattern = Patterns::Anything(),
1066  const std::string & documentation = "");
1067 
1111  void
1112  add_action(const std::string & entry,
1113  const std::function<void(const std::string &value)> &action);
1114 
1124  template <class ParameterType>
1125  void
1126  add_parameter(const std::string & entry,
1127  ParameterType & parameter,
1128  const std::string & documentation = "",
1129  const Patterns::PatternBase &pattern =
1131 
1175  void
1176  declare_alias(const std::string &existing_entry_name,
1177  const std::string &alias_name,
1178  const bool alias_is_deprecated = false);
1179 
1183  void
1184  enter_subsection(const std::string &subsection);
1185 
1189  void
1190  leave_subsection();
1191 
1197  bool
1198  subsection_path_exists(const std::vector<std::string> &sub_path) const;
1199 
1205  std::string
1206  get(const std::string &entry_string) const;
1207 
1218  std::string
1219  get(const std::vector<std::string> &entry_subsection_path,
1220  const std::string & entry_string) const;
1221 
1227  long int
1228  get_integer(const std::string &entry_string) const;
1229 
1238  long int
1239  get_integer(const std::vector<std::string> &entry_subsection_path,
1240  const std::string & entry_string) const;
1241 
1245  double
1246  get_double(const std::string &entry_name) const;
1247 
1254  double
1255  get_double(const std::vector<std::string> &entry_subsection_path,
1256  const std::string & entry_string) const;
1262  bool
1263  get_bool(const std::string &entry_name) const;
1264 
1273  bool
1274  get_bool(const std::vector<std::string> &entry_subsection_path,
1275  const std::string & entry_string) const;
1276 
1286  void
1287  set(const std::string &entry_name, const std::string &new_value);
1288 
1299  void
1300  set(const std::string &entry_name, const char *new_value);
1301 
1311  void
1312  set(const std::string &entry_name, const long int new_value);
1313 
1327  void
1328  set(const std::string &entry_name, const double new_value);
1329 
1339  void
1340  set(const std::string &entry_name, const bool new_value);
1341 
1407  std::ostream &
1408  print_parameters(std::ostream & out,
1409  const OutputStyle style,
1410  const bool sort_alphabetical = true) const;
1411 
1423  void
1424  log_parameters(LogStream &out, const bool sort_alphabetical = true);
1425 
1441  void
1442  log_parameters_section(LogStream &out, const bool sort_alphabetical = true);
1443 
1448  std::size_t
1449  memory_consumption() const;
1450 
1455  template <class Archive>
1456  void
1457  save(Archive &ar, const unsigned int version) const;
1458 
1463  template <class Archive>
1464  void
1465  load(Archive &ar, const unsigned int version);
1466 
1467  BOOST_SERIALIZATION_SPLIT_MEMBER()
1468 
1469 
1472  bool
1473  operator==(const ParameterHandler &prm2) const;
1474 
1484  std::string,
1485  << "The following entry already exists: " << arg1 << ".");
1490  std::string,
1491  std::string,
1492  << "The string <" << arg1
1493  << "> does not match the given pattern <" << arg2 << ">.");
1499  "You can't leave a subsection if you are already at the top level "
1500  "of the subsection hierarchy.");
1505  std::string,
1506  << "You can't ask for entry <" << arg1
1507  << "> you have not yet declared.");
1508 
1516  std::string,
1517  std::string,
1518  << "There are unequal numbers of 'subsection' and 'end' "
1519  "statements in the parameter file <"
1520  << arg1 << ">." << (arg2.size() > 0 ? "\n" + arg2 : ""));
1521 
1527  int,
1528  std::string,
1529  std::string,
1530  << "Line <" << arg1 << "> of file <" << arg2
1531  << ": There is "
1532  "no such subsection to be entered: "
1533  << arg3);
1534 
1541  int,
1542  std::string,
1543  std::string,
1544  << "Line <" << arg1 << "> of file <" << arg2 << ">: " << arg3);
1545 
1552  int,
1553  std::string,
1554  std::string,
1555  std::string,
1556  std::string,
1557  << "Line <" << arg1 << "> of file <" << arg2
1558  << ">:\n"
1559  " The entry value \n"
1560  << " " << arg3 << '\n'
1561  << " for the entry named\n"
1562  << " " << arg4 << '\n'
1563  << " does not match the given pattern:\n"
1564  << " " << arg5);
1565 
1572  "The provided file could not be parsed as a "
1573  "ParameterHandler description.");
1574 
1582  using ExcInvalidEntryForPatternXML DEAL_II_DEPRECATED =
1583  ExcValueDoesNotMatchPattern;
1584 
1593  int,
1594  std::string,
1595  std::string,
1596  << "Line <" << arg1 << "> of file <" << arg2
1597  << ">: This line "
1598  "contains an 'include' or 'INCLUDE' statement, but the given "
1599  "file to include <"
1600  << arg3 << "> cannot be opened.");
1601 
1603 
1604 private:
1609  static const char path_separator = '.';
1610 
1614  std::vector<std::string> subsection_path;
1615 
1624  std::unique_ptr<boost::property_tree::ptree> entries;
1625 
1631  std::vector<std::unique_ptr<const Patterns::PatternBase>> patterns;
1632 
1639  std::vector<std::function<void(const std::string &)>> actions;
1640 
1649  std::string
1650  get_current_path() const;
1651 
1656  std::string
1657  get_current_full_path(const std::string &name) const;
1658 
1663  std::string
1664  get_current_full_path(const std::vector<std::string> &sub_path,
1665  const std::string & name) const;
1666 
1685  void
1686  scan_line(std::string line,
1687  const std::string &input_filename,
1688  const unsigned int current_line_n,
1689  const bool skip_undefined);
1690 
1702  void
1704  const boost::property_tree::ptree & tree,
1705  const std::vector<std::string> & target_subsection_path,
1706  const ParameterHandler::OutputStyle style,
1707  const unsigned int indent_level,
1708  std::ostream & out) const;
1709 
1710  friend class MultipleParameterLoop;
1711 };
1712 
1713 
1714 
1931 class MultipleParameterLoop : public ParameterHandler
1932 {
1933 public:
1939  {
1940  public:
1945  virtual ~UserClass() = default;
1946 
1951  virtual void
1952  create_new(const unsigned int run_no) = 0;
1953 
1957  virtual void
1958  run(ParameterHandler &prm) = 0;
1959  };
1960 
1964  MultipleParameterLoop();
1965 
1970  virtual ~MultipleParameterLoop() override = default;
1971 
1993  virtual void
1994  parse_input(std::istream & input,
1995  const std::string &filename = "input file",
1996  const std::string &last_line = "",
1997  const bool skip_undefined = false) override;
1998 
2007 
2011  void
2012  loop(UserClass &uc);
2013 
2018  std::size_t
2019  memory_consumption() const;
2020 
2021 private:
2025  class Entry
2026  {
2027  public:
2034  {
2042  array
2043  };
2044 
2049  : type(array)
2050  {}
2051 
2057  Entry(const std::vector<std::string> &Path,
2058  const std::string & Name,
2059  const std::string & Value);
2060 
2064  void
2065  split_different_values();
2066 
2070  std::vector<std::string> subsection_path;
2071 
2075  std::string entry_name;
2076 
2080  std::string entry_value;
2081 
2086  std::vector<std::string> different_values;
2087 
2092 
2097  std::size_t
2098  memory_consumption() const;
2099  };
2100 
2104  std::vector<Entry> multiple_choices;
2105 
2110  unsigned int n_branches;
2111 
2115  void
2116  init_branches();
2117 
2124  void
2125  init_branches_current_section();
2126 
2130  void
2131  fill_entry_values(const unsigned int run_no);
2132 };
2133 
2134 
2135 // ---------------------- inline and template functions --------------------
2136 template <class Archive>
2137 inline void
2138 ParameterHandler::save(Archive &ar, const unsigned int) const
2139 {
2140  // Forward to serialization
2141  // function in the base class.
2142  ar &static_cast<const Subscriptor &>(*this);
2143 
2144  ar &*entries.get();
2145 
2146  std::vector<std::string> descriptions;
2147 
2148  for (const auto &pattern : patterns)
2149  descriptions.push_back(pattern->description());
2150 
2151  ar &descriptions;
2152 }
2153 
2154 
2155 template <class Archive>
2156 inline void
2157 ParameterHandler::load(Archive &ar, const unsigned int)
2158 {
2159  // Forward to serialization
2160  // function in the base class.
2161  ar &static_cast<Subscriptor &>(*this);
2162 
2163  ar &*entries.get();
2164 
2165  std::vector<std::string> descriptions;
2166  ar & descriptions;
2167 
2168  patterns.clear();
2169  for (const auto &description : descriptions)
2170  patterns.push_back(Patterns::pattern_factory(description));
2171 }
2172 
2173 
2174 template <class ParameterType>
2175 void
2176 ParameterHandler::add_parameter(const std::string & entry,
2177  ParameterType & parameter,
2178  const std::string & documentation,
2179  const Patterns::PatternBase &pattern)
2180 {
2181  static_assert(std::is_const<ParameterType>::value == false,
2182  "You tried to add a parameter using a type "
2183  "that is const. Use a non-const type.");
2184 
2185  declare_entry(entry,
2187  parameter, pattern.clone()),
2188  pattern,
2189  documentation);
2190 
2191  std::string path = get_current_full_path(entry);
2192  const unsigned int pattern_index =
2193  entries->get<unsigned int>(path + path_separator + "pattern");
2194 
2195  auto action = [&, pattern_index](const std::string &val) {
2197  val, patterns[pattern_index]->clone());
2198  };
2199  add_action(entry, action);
2200 }
2201 
2202 DEAL_II_NAMESPACE_CLOSE
2203 
2204 #endif
std::vector< Entry > multiple_choices
long int get_integer(const std::string &entry_string) const
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:443
static const char path_separator
#define DeclException2(Exception2, type1, type2, outsequence)
Definition: exceptions.h:541
void declare_entry(const std::string &entry, const std::string &default_value, const Patterns::PatternBase &pattern=Patterns::Anything(), const std::string &documentation="")
static ::ExceptionBase & ExcEntryAlreadyExists(std::string arg1)
static ::ExceptionBase & ExcCannotOpenIncludeStatementFile(int arg1, std::string arg2, std::string arg3)
std::string get_current_path() const
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
static ::ExceptionBase & ExcUnbalancedSubsections(std::string arg1, std::string arg2)
virtual void parse_input_from_string(const std::string &s, const std::string &last_line="", const bool skip_undefined=false)
virtual std::unique_ptr< PatternBase > clone() const =0
STL namespace.
std::vector< std::string > subsection_path
void log_parameters(LogStream &out, const bool sort_alphabetical=true)
#define DeclException5( Exception5, type1, type2, type3, type4, type5, outsequence)
Definition: exceptions.h:613
void scan_line(std::string line, const std::string &input_filename, const unsigned int current_line_n, const bool skip_undefined)
static ::ExceptionBase & ExcValueDoesNotMatchPattern(std::string arg1, std::string arg2)
void load(Archive &ar, const unsigned int version)
std::vector< std::string > subsection_path
void add_parameter(const std::string &entry, ParameterType &parameter, const std::string &documentation="", const Patterns::PatternBase &pattern= *Patterns::Tools::Convert< ParameterType >::to_pattern())
bool subsection_path_exists(const std::vector< std::string > &sub_path) const
void enter_subsection(const std::string &subsection)
static ::ExceptionBase & ExcInvalidXMLParameterFile()
static ::ExceptionBase & ExcCannotParseLine(int arg1, std::string arg2, std::string arg3)
double get_double(const std::string &entry_name) const
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:518
virtual void parse_input_from_xml(std::istream &input, const bool skip_undefined=false)
std::string get_current_full_path(const std::string &name) const
std::ostream & print_parameters(std::ostream &out, const OutputStyle style, const bool sort_alphabetical=true) const
#define DeclExceptionMsg(Exception, defaulttext)
Definition: exceptions.h:496
std::unique_ptr< boost::property_tree::ptree > entries
virtual void parse_input(std::istream &input, const std::string &filename="input file", const std::string &last_line="", const bool skip_undefined=false)
std::unique_ptr< PatternBase > pattern_factory(const std::string &description)
Definition: patterns.cc:136
bool get_bool(const std::string &entry_name) const
static ::ExceptionBase & ExcAlreadyAtTopLevel()
std::vector< std::unique_ptr< const Patterns::PatternBase > > patterns
virtual void parse_input_from_json(std::istream &input, const bool skip_undefined=false)
void add_action(const std::string &entry, const std::function< void(const std::string &value)> &action)
void save(Archive &ar, const unsigned int version) const
std::vector< std::string > different_values
void log_parameters_section(LogStream &out, const bool sort_alphabetical=true)
#define DeclException3(Exception3, type1, type2, type3, outsequence)
Definition: exceptions.h:564
std::size_t memory_consumption() const
static ::ExceptionBase & ExcInvalidEntryForPattern(int arg1, std::string arg2, std::string arg3, std::string arg4, std::string arg5)
void recursively_print_parameters(const boost::property_tree::ptree &tree, const std::vector< std::string > &target_subsection_path, const ParameterHandler::OutputStyle style, const unsigned int indent_level, std::ostream &out) const
std::vector< std::function< void(const std::string &)> > actions
virtual ~ParameterHandler() override=default
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)
ExcValueDoesNotMatchPattern ExcInvalidEntryForPatternXML
ParameterHandler & operator=(const ParameterHandler &)=delete