Reference documentation for deal.II version Git 42dd89c428 2021-07-27 06:40:55 +0200
\(\newcommand{\dealvcentcolon}{\mathrel{\mathop{:}}}\) \(\newcommand{\dealcoloneq}{\dealvcentcolon\mathrel{\mkern-1.2mu}=}\) \(\newcommand{\jump}[1]{\left[\!\left[ #1 \right]\!\right]}\) \(\newcommand{\average}[1]{\left\{\!\left\{ #1 \right\}\!\right\}}\)
parameter_handler.h
Go to the documentation of this file.
1 // ---------------------------------------------------------------------
2 //
3 // Copyright (C) 1998 - 2021 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 
23 #include <deal.II/base/patterns.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 
37 
38 // forward declarations for interfaces and friendship
39 #ifndef DOXYGEN
40 class LogStream;
42 #endif
43 
841 {
842 public:
859  {
864  DefaultStyle = 0x0000,
865 
870  Short = 0x0001,
871 
876 
881  PRM = 0x0010,
882 
890 
894  LaTeX = 0x0020,
895 
901  Description = 0x0040,
902 
910  XML = 0x0080,
911 
917  JSON = 0x0100,
918 
924 
932 
938 
944 
950  };
951 
952 
953 
958 
964  virtual ~ParameterHandler() override = default;
965 
969  ParameterHandler(const ParameterHandler &) = delete;
970 
975  operator=(const ParameterHandler &) = delete;
976 
1011  virtual void
1012  parse_input(std::istream & input,
1013  const std::string &filename = "input file",
1014  const std::string &last_line = "",
1015  const bool skip_undefined = false);
1016 
1038  virtual void
1039  parse_input(const std::string &filename,
1040  const std::string &last_line = "",
1041  const bool skip_undefined = false,
1042  const bool assert_mandatory_entries_are_found = false);
1043 
1052  virtual void
1053  parse_input_from_string(const std::string &s,
1054  const std::string &last_line = "",
1055  const bool skip_undefined = false);
1056 
1064  virtual void
1065  parse_input_from_xml(std::istream &input, const bool skip_undefined = false);
1066 
1074  virtual void
1075  parse_input_from_json(std::istream &input, const bool skip_undefined = false);
1076 
1080  void
1081  clear();
1082 
1083 
1109  void
1110  declare_entry(const std::string & entry,
1111  const std::string & default_value,
1112  const Patterns::PatternBase &pattern = Patterns::Anything(),
1113  const std::string & documentation = "",
1114  const bool has_to_be_set = false);
1115 
1159  void
1160  add_action(const std::string & entry,
1161  const std::function<void(const std::string &value)> &action);
1162 
1178  template <class ParameterType>
1179  void
1180  add_parameter(const std::string & entry,
1181  ParameterType & parameter,
1182  const std::string & documentation = "",
1183  const Patterns::PatternBase &pattern =
1185  const bool has_to_be_set = false);
1186 
1230  void
1231  declare_alias(const std::string &existing_entry_name,
1232  const std::string &alias_name,
1233  const bool alias_is_deprecated = false);
1234 
1238  void
1239  enter_subsection(const std::string &subsection);
1240 
1244  void
1245  leave_subsection();
1246 
1252  bool
1253  subsection_path_exists(const std::vector<std::string> &sub_path) const;
1254 
1260  std::string
1261  get(const std::string &entry_string) const;
1262 
1273  std::string
1274  get(const std::vector<std::string> &entry_subsection_path,
1275  const std::string & entry_string) const;
1276 
1282  long int
1283  get_integer(const std::string &entry_string) const;
1284 
1293  long int
1294  get_integer(const std::vector<std::string> &entry_subsection_path,
1295  const std::string & entry_string) const;
1296 
1300  double
1301  get_double(const std::string &entry_name) const;
1302 
1309  double
1310  get_double(const std::vector<std::string> &entry_subsection_path,
1311  const std::string & entry_string) const;
1317  bool
1318  get_bool(const std::string &entry_name) const;
1319 
1328  bool
1329  get_bool(const std::vector<std::string> &entry_subsection_path,
1330  const std::string & entry_string) const;
1331 
1341  void
1342  set(const std::string &entry_name, const std::string &new_value);
1343 
1354  void
1355  set(const std::string &entry_name, const char *new_value);
1356 
1366  void
1367  set(const std::string &entry_name, const long int new_value);
1368 
1382  void
1383  set(const std::string &entry_name, const double new_value);
1384 
1394  void
1395  set(const std::string &entry_name, const bool new_value);
1396 
1469  std::ostream &
1470  print_parameters(std::ostream &out, const OutputStyle style) const;
1471 
1472 
1473 
1494  void
1495  print_parameters(const std::string &filename,
1496  const OutputStyle style = DefaultStyle) const;
1497 
1512  void
1513  log_parameters(LogStream &out, const OutputStyle style = DefaultStyle);
1514 
1533  void
1535  const OutputStyle style = DefaultStyle);
1536 
1541  std::size_t
1542  memory_consumption() const;
1543 
1549  template <class Archive>
1550  void
1551  save(Archive &ar, const unsigned int version) const;
1552 
1558  template <class Archive>
1559  void
1560  load(Archive &ar, const unsigned int version);
1561 
1562 #ifdef DOXYGEN
1563 
1568  template <class Archive>
1569  void
1570  serialize(Archive &archive, const unsigned int version);
1571 #else
1572  // This macro defines the serialize() method that is compatible with
1573  // the templated save() and load() method that have been implemented.
1574  BOOST_SERIALIZATION_SPLIT_MEMBER()
1575 #endif
1576 
1580  bool
1581  operator==(const ParameterHandler &prm2) const;
1582 
1591  std::set<std::string>
1593 
1599  void
1601 
1611  std::string,
1612  << "The following entry already exists: " << arg1 << ".");
1617  std::string,
1618  std::string,
1619  << "The string <" << arg1
1620  << "> does not match the given pattern <" << arg2 << ">.");
1626  "You can't leave a subsection if you are already at the top level "
1627  "of the subsection hierarchy.");
1632  std::string,
1633  << "You can't ask for entry <" << arg1
1634  << "> you have not yet declared.");
1635 
1643  std::string,
1644  std::string,
1645  << "There are unequal numbers of 'subsection' and 'end' "
1646  "statements in the parameter file <"
1647  << arg1 << ">." << (arg2.size() > 0 ? "\n" + arg2 : ""));
1648 
1654  int,
1655  std::string,
1656  std::string,
1657  << "Line <" << arg1 << "> of file <" << arg2
1658  << ": There is "
1659  "no such subsection to be entered: "
1660  << arg3);
1661 
1668  int,
1669  std::string,
1670  std::string,
1671  << "Line <" << arg1 << "> of file <" << arg2 << ">: " << arg3);
1672 
1679  int,
1680  std::string,
1681  std::string,
1682  std::string,
1683  std::string,
1684  << "Line <" << arg1 << "> of file <" << arg2
1685  << ">:\n"
1686  " The entry value \n"
1687  << " " << arg3 << '\n'
1688  << " for the entry named\n"
1689  << " " << arg4 << '\n'
1690  << " does not match the given pattern:\n"
1691  << " " << arg5);
1692 
1699  "The provided file could not be parsed as a "
1700  "ParameterHandler description.");
1701 
1710  int,
1711  std::string,
1712  std::string,
1713  << "Line <" << arg1 << "> of file <" << arg2
1714  << ">: This line "
1715  "contains an 'include' or 'INCLUDE' statement, but the given "
1716  "file to include <"
1717  << arg3 << "> cannot be opened.");
1718 
1720 
1721 private:
1726  static const char path_separator = '.';
1727 
1731  std::vector<std::string> subsection_path;
1732 
1741  std::unique_ptr<boost::property_tree::ptree> entries;
1742 
1751  std::map<std::string, std::pair<bool, bool>> entries_set_status;
1752 
1758  std::vector<std::unique_ptr<const Patterns::PatternBase>> patterns;
1759 
1766  std::vector<std::function<void(const std::string &)>> actions;
1767 
1776  std::string
1777  get_current_path() const;
1778 
1783  std::string
1784  get_current_full_path(const std::string &name) const;
1785 
1790  std::string
1791  get_current_full_path(const std::vector<std::string> &sub_path,
1792  const std::string & name) const;
1793 
1812  void
1813  scan_line(std::string line,
1814  const std::string &input_filename,
1815  const unsigned int current_line_n,
1816  const bool skip_undefined);
1817 
1829  void
1831  const boost::property_tree::ptree & tree,
1832  const std::vector<std::string> & target_subsection_path,
1833  const ParameterHandler::OutputStyle style,
1834  const unsigned int indent_level,
1835  std::ostream & out) const;
1836 
1838 };
1839 
1850 {
1851  return static_cast<ParameterHandler::OutputStyle>(
1852  static_cast<unsigned int>(f1) | static_cast<unsigned int>(f2));
1853 }
1854 
2071 {
2072 public:
2078  {
2079  public:
2084  virtual ~UserClass() = default;
2085 
2090  virtual void
2091  create_new(const unsigned int run_no) = 0;
2092 
2096  virtual void
2097  run(ParameterHandler &prm) = 0;
2098  };
2099 
2104 
2109  virtual ~MultipleParameterLoop() override = default;
2110 
2132  virtual void
2133  parse_input(std::istream & input,
2134  const std::string &filename = "input file",
2135  const std::string &last_line = "",
2136  const bool skip_undefined = false) override;
2137 
2146 
2150  void
2151  loop(UserClass &uc);
2152 
2157  std::size_t
2158  memory_consumption() const;
2159 
2160 private:
2164  class Entry
2165  {
2166  public:
2173  {
2181  array
2182  };
2183 
2188  : type(array)
2189  {}
2190 
2196  Entry(const std::vector<std::string> &Path,
2197  const std::string & Name,
2198  const std::string & Value);
2199 
2203  void
2204  split_different_values();
2205 
2209  std::vector<std::string> subsection_path;
2210 
2214  std::string entry_name;
2215 
2219  std::string entry_value;
2220 
2225  std::vector<std::string> different_values;
2226 
2231 
2236  std::size_t
2237  memory_consumption() const;
2238  };
2239 
2243  std::vector<Entry> multiple_choices;
2244 
2249  unsigned int n_branches;
2250 
2254  void
2255  init_branches();
2256 
2263  void
2264  init_branches_current_section();
2265 
2269  void
2270  fill_entry_values(const unsigned int run_no);
2271 };
2272 
2273 
2274 // ---------------------- inline and template functions --------------------
2275 template <class Archive>
2276 inline void
2277 ParameterHandler::save(Archive &ar, const unsigned int) const
2278 {
2279  // Forward to serialization
2280  // function in the base class.
2281  ar &static_cast<const Subscriptor &>(*this);
2282 
2283  ar &*entries.get();
2284 
2285  std::vector<std::string> descriptions;
2286 
2287  for (const auto &pattern : patterns)
2288  descriptions.push_back(pattern->description());
2289 
2290  ar &descriptions;
2291 }
2292 
2293 
2294 template <class Archive>
2295 inline void
2296 ParameterHandler::load(Archive &ar, const unsigned int)
2297 {
2298  // Forward to serialization
2299  // function in the base class.
2300  ar &static_cast<Subscriptor &>(*this);
2301 
2302  ar &*entries.get();
2303 
2304  std::vector<std::string> descriptions;
2305  ar & descriptions;
2306 
2307  patterns.clear();
2308  for (const auto &description : descriptions)
2309  patterns.push_back(Patterns::pattern_factory(description));
2310 }
2311 
2312 
2313 template <class ParameterType>
2314 void
2315 ParameterHandler::add_parameter(const std::string & entry,
2316  ParameterType & parameter,
2317  const std::string & documentation,
2318  const Patterns::PatternBase &pattern,
2319  const bool has_to_be_set)
2320 {
2321  static_assert(std::is_const<ParameterType>::value == false,
2322  "You tried to add a parameter using a type "
2323  "that is const. Use a non-const type.");
2324 
2325  declare_entry(entry,
2327  pattern),
2328  pattern,
2329  documentation,
2330  has_to_be_set);
2331 
2332  std::string path = get_current_full_path(entry);
2333  const unsigned int pattern_index =
2334  entries->get<unsigned int>(path + path_separator + "pattern");
2335 
2336  auto action = [&, pattern_index](const std::string &val) {
2338  val, *patterns[pattern_index]);
2339  };
2340  add_action(entry, action);
2341 }
2342 
2344 
2345 #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:439
static const char path_separator
#define DeclException2(Exception2, type1, type2, outsequence)
Definition: exceptions.h:538
static ::ExceptionBase & ExcEntryAlreadyExists(std::string arg1)
void assert_that_entries_have_been_set() const
static ::ExceptionBase & ExcCannotOpenIncludeStatementFile(int arg1, std::string arg2, std::string arg3)
std::string get_current_path() const
static ::ExceptionBase & ExcEntryUndeclared(std::string arg1)
friend class MultipleParameterLoop
static ::ExceptionBase & ExcUnbalancedSubsections(std::string arg1, std::string arg2)
std::ostream & print_parameters(std::ostream &out, const OutputStyle style) const
virtual void parse_input_from_string(const std::string &s, const std::string &last_line="", const bool skip_undefined=false)
void add_parameter(const std::string &entry, ParameterType &parameter, const std::string &documentation="", const Patterns::PatternBase &pattern= *Patterns::Tools::Convert< ParameterType >::to_pattern(), const bool has_to_be_set=false)
void log_parameters(LogStream &out, const OutputStyle style=DefaultStyle)
std::vector< std::string > subsection_path
#define DeclException5( Exception5, type1, type2, type3, type4, type5, outsequence)
Definition: exceptions.h:610
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
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
void declare_entry(const std::string &entry, const std::string &default_value, const Patterns::PatternBase &pattern=Patterns::Anything(), const std::string &documentation="", const bool has_to_be_set=false)
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:515
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
#define DeclExceptionMsg(Exception, defaulttext)
Definition: exceptions.h:493
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:401
std::unique_ptr< boost::property_tree::ptree > entries
static T to_value(const std::string &s, const Patterns::PatternBase &p= *Convert< T >::to_pattern())=delete
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:140
bool get_bool(const std::string &entry_name) const
static ::ExceptionBase & ExcAlreadyAtTopLevel()
std::vector< std::unique_ptr< const Patterns::PatternBase > > patterns
bool operator==(const ParameterHandler &prm2) const
void log_parameters_section(LogStream &out, const OutputStyle style=DefaultStyle)
virtual void parse_input_from_json(std::istream &input, const bool skip_undefined=false)
std::set< std::string > get_entries_wrongly_not_set() const
ParameterHandler::OutputStyle operator|(const ParameterHandler::OutputStyle f1, const ParameterHandler::OutputStyle f2)
void add_action(const std::string &entry, const std::function< void(const std::string &value)> &action)
#define DEAL_II_NAMESPACE_OPEN
Definition: config.h:400
void save(Archive &ar, const unsigned int version) const
std::vector< std::string > different_values
#define DeclException3(Exception3, type1, type2, type3, outsequence)
Definition: exceptions.h:561
std::size_t memory_consumption() const
static ::ExceptionBase & ExcInvalidEntryForPattern(int arg1, std::string arg2, std::string arg3, std::string arg4, std::string arg5)
void serialize(Archive &archive, const unsigned int version)
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)
std::map< std::string, std::pair< bool, bool > > entries_set_status
void run(const Iterator &begin, const typename identity< Iterator >::type &end, Worker worker, Copier copier, const ScratchData &sample_scratch_data, const CopyData &sample_copy_data, const unsigned int queue_length, const unsigned int chunk_size)
Definition: work_stream.h:691
ParameterHandler & operator=(const ParameterHandler &)=delete