Reference documentation for deal.II version Git ee8a81293c 2020-10-19 10:17:29 -0400
\(\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 - 2020 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 
1548  template <class Archive>
1549  void
1550  save(Archive &ar, const unsigned int version) const;
1551 
1556  template <class Archive>
1557  void
1558  load(Archive &ar, const unsigned int version);
1559 
1560 #ifdef DOXYGEN
1561 
1565  template <class Archive>
1566  void
1567  serialize(Archive &archive, const unsigned int version);
1568 #else
1569  // This macro defines the serialize() method that is compatible with
1570  // the templated save() and load() method that have been implemented.
1571  BOOST_SERIALIZATION_SPLIT_MEMBER()
1572 #endif
1573 
1577  bool
1578  operator==(const ParameterHandler &prm2) const;
1579 
1588  std::set<std::string>
1590 
1596  void
1598 
1608  std::string,
1609  << "The following entry already exists: " << arg1 << ".");
1614  std::string,
1615  std::string,
1616  << "The string <" << arg1
1617  << "> does not match the given pattern <" << arg2 << ">.");
1623  "You can't leave a subsection if you are already at the top level "
1624  "of the subsection hierarchy.");
1629  std::string,
1630  << "You can't ask for entry <" << arg1
1631  << "> you have not yet declared.");
1632 
1640  std::string,
1641  std::string,
1642  << "There are unequal numbers of 'subsection' and 'end' "
1643  "statements in the parameter file <"
1644  << arg1 << ">." << (arg2.size() > 0 ? "\n" + arg2 : ""));
1645 
1651  int,
1652  std::string,
1653  std::string,
1654  << "Line <" << arg1 << "> of file <" << arg2
1655  << ": There is "
1656  "no such subsection to be entered: "
1657  << arg3);
1658 
1665  int,
1666  std::string,
1667  std::string,
1668  << "Line <" << arg1 << "> of file <" << arg2 << ">: " << arg3);
1669 
1676  int,
1677  std::string,
1678  std::string,
1679  std::string,
1680  std::string,
1681  << "Line <" << arg1 << "> of file <" << arg2
1682  << ">:\n"
1683  " The entry value \n"
1684  << " " << arg3 << '\n'
1685  << " for the entry named\n"
1686  << " " << arg4 << '\n'
1687  << " does not match the given pattern:\n"
1688  << " " << arg5);
1689 
1696  "The provided file could not be parsed as a "
1697  "ParameterHandler description.");
1698 
1708 
1717  int,
1718  std::string,
1719  std::string,
1720  << "Line <" << arg1 << "> of file <" << arg2
1721  << ">: This line "
1722  "contains an 'include' or 'INCLUDE' statement, but the given "
1723  "file to include <"
1724  << arg3 << "> cannot be opened.");
1725 
1727 
1728 private:
1733  static const char path_separator = '.';
1734 
1738  std::vector<std::string> subsection_path;
1739 
1748  std::unique_ptr<boost::property_tree::ptree> entries;
1749 
1758  std::map<std::string, std::pair<bool, bool>> entries_set_status;
1759 
1765  std::vector<std::unique_ptr<const Patterns::PatternBase>> patterns;
1766 
1773  std::vector<std::function<void(const std::string &)>> actions;
1774 
1783  std::string
1784  get_current_path() const;
1785 
1790  std::string
1791  get_current_full_path(const std::string &name) const;
1792 
1797  std::string
1798  get_current_full_path(const std::vector<std::string> &sub_path,
1799  const std::string & name) const;
1800 
1819  void
1820  scan_line(std::string line,
1821  const std::string &input_filename,
1822  const unsigned int current_line_n,
1823  const bool skip_undefined);
1824 
1836  void
1838  const boost::property_tree::ptree & tree,
1839  const std::vector<std::string> & target_subsection_path,
1840  const ParameterHandler::OutputStyle style,
1841  const unsigned int indent_level,
1842  std::ostream & out) const;
1843 
1845 };
1846 
1857 {
1858  return static_cast<ParameterHandler::OutputStyle>(
1859  static_cast<unsigned int>(f1) | static_cast<unsigned int>(f2));
1860 }
1861 
2078 {
2079 public:
2085  {
2086  public:
2091  virtual ~UserClass() = default;
2092 
2097  virtual void
2098  create_new(const unsigned int run_no) = 0;
2099 
2103  virtual void
2104  run(ParameterHandler &prm) = 0;
2105  };
2106 
2111 
2116  virtual ~MultipleParameterLoop() override = default;
2117 
2139  virtual void
2140  parse_input(std::istream & input,
2141  const std::string &filename = "input file",
2142  const std::string &last_line = "",
2143  const bool skip_undefined = false) override;
2144 
2153 
2157  void
2158  loop(UserClass &uc);
2159 
2164  std::size_t
2165  memory_consumption() const;
2166 
2167 private:
2171  class Entry
2172  {
2173  public:
2180  {
2188  array
2189  };
2190 
2195  : type(array)
2196  {}
2197 
2203  Entry(const std::vector<std::string> &Path,
2204  const std::string & Name,
2205  const std::string & Value);
2206 
2210  void
2211  split_different_values();
2212 
2216  std::vector<std::string> subsection_path;
2217 
2221  std::string entry_name;
2222 
2226  std::string entry_value;
2227 
2232  std::vector<std::string> different_values;
2233 
2238 
2243  std::size_t
2244  memory_consumption() const;
2245  };
2246 
2250  std::vector<Entry> multiple_choices;
2251 
2256  unsigned int n_branches;
2257 
2261  void
2262  init_branches();
2263 
2270  void
2271  init_branches_current_section();
2272 
2276  void
2277  fill_entry_values(const unsigned int run_no);
2278 };
2279 
2280 
2281 // ---------------------- inline and template functions --------------------
2282 template <class Archive>
2283 inline void
2284 ParameterHandler::save(Archive &ar, const unsigned int) const
2285 {
2286  // Forward to serialization
2287  // function in the base class.
2288  ar &static_cast<const Subscriptor &>(*this);
2289 
2290  ar &*entries.get();
2291 
2292  std::vector<std::string> descriptions;
2293 
2294  for (const auto &pattern : patterns)
2295  descriptions.push_back(pattern->description());
2296 
2297  ar &descriptions;
2298 }
2299 
2300 
2301 template <class Archive>
2302 inline void
2303 ParameterHandler::load(Archive &ar, const unsigned int)
2304 {
2305  // Forward to serialization
2306  // function in the base class.
2307  ar &static_cast<Subscriptor &>(*this);
2308 
2309  ar &*entries.get();
2310 
2311  std::vector<std::string> descriptions;
2312  ar & descriptions;
2313 
2314  patterns.clear();
2315  for (const auto &description : descriptions)
2316  patterns.push_back(Patterns::pattern_factory(description));
2317 }
2318 
2319 
2320 template <class ParameterType>
2321 void
2322 ParameterHandler::add_parameter(const std::string & entry,
2323  ParameterType & parameter,
2324  const std::string & documentation,
2325  const Patterns::PatternBase &pattern,
2326  const bool has_to_be_set)
2327 {
2328  static_assert(std::is_const<ParameterType>::value == false,
2329  "You tried to add a parameter using a type "
2330  "that is const. Use a non-const type.");
2331 
2332  declare_entry(entry,
2334  parameter, pattern.clone()),
2335  pattern,
2336  documentation,
2337  has_to_be_set);
2338 
2339  std::string path = get_current_full_path(entry);
2340  const unsigned int pattern_index =
2341  entries->get<unsigned int>(path + path_separator + "pattern");
2342 
2343  auto action = [&, pattern_index](const std::string &val) {
2345  val, patterns[pattern_index]->clone());
2346  };
2347  add_action(entry, action);
2348 }
2349 
2351 
2352 #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 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)
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)
virtual std::unique_ptr< PatternBase > clone() const =0
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:369
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: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:368
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)
#define DEAL_II_DEPRECATED
Definition: config.h:152
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
ExcValueDoesNotMatchPattern ExcInvalidEntryForPatternXML
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