Reference documentation for deal.II version 9.2.0
\(\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 
846 {
847 public:
864  {
869  DefaultStyle = 0x0000,
870 
875  Short = 0x0001,
876 
881 
886  PRM = 0x0010,
887 
895 
899  LaTeX = 0x0020,
900 
906  Description = 0x0040,
907 
915  XML = 0x0080,
916 
922  JSON = 0x0100,
923 
929 
937 
943 
949 
955  };
956 
957 
958 
963 
969  virtual ~ParameterHandler() override = default;
970 
974  ParameterHandler(const ParameterHandler &) = delete;
975 
980  operator=(const ParameterHandler &) = delete;
981 
1016  virtual void
1017  parse_input(std::istream & input,
1018  const std::string &filename = "input file",
1019  const std::string &last_line = "",
1020  const bool skip_undefined = false);
1021 
1043  virtual void
1044  parse_input(const std::string &filename,
1045  const std::string &last_line = "",
1046  const bool skip_undefined = false,
1047  const bool assert_mandatory_entries_are_found = false);
1048 
1057  virtual void
1058  parse_input_from_string(const std::string &s,
1059  const std::string &last_line = "",
1060  const bool skip_undefined = false);
1061 
1069  virtual void
1070  parse_input_from_xml(std::istream &input, const bool skip_undefined = false);
1071 
1079  virtual void
1080  parse_input_from_json(std::istream &input, const bool skip_undefined = false);
1081 
1085  void
1086  clear();
1087 
1088 
1114  void
1115  declare_entry(const std::string & entry,
1116  const std::string & default_value,
1117  const Patterns::PatternBase &pattern = Patterns::Anything(),
1118  const std::string & documentation = "",
1119  const bool has_to_be_set = false);
1120 
1164  void
1165  add_action(const std::string & entry,
1166  const std::function<void(const std::string &value)> &action);
1167 
1183  template <class ParameterType>
1184  void
1185  add_parameter(const std::string & entry,
1186  ParameterType & parameter,
1187  const std::string & documentation = "",
1188  const Patterns::PatternBase &pattern =
1190  const bool has_to_be_set = false);
1191 
1235  void
1236  declare_alias(const std::string &existing_entry_name,
1237  const std::string &alias_name,
1238  const bool alias_is_deprecated = false);
1239 
1243  void
1244  enter_subsection(const std::string &subsection);
1245 
1249  void
1250  leave_subsection();
1251 
1257  bool
1258  subsection_path_exists(const std::vector<std::string> &sub_path) const;
1259 
1265  std::string
1266  get(const std::string &entry_string) const;
1267 
1278  std::string
1279  get(const std::vector<std::string> &entry_subsection_path,
1280  const std::string & entry_string) const;
1281 
1287  long int
1288  get_integer(const std::string &entry_string) const;
1289 
1298  long int
1299  get_integer(const std::vector<std::string> &entry_subsection_path,
1300  const std::string & entry_string) const;
1301 
1305  double
1306  get_double(const std::string &entry_name) const;
1307 
1314  double
1315  get_double(const std::vector<std::string> &entry_subsection_path,
1316  const std::string & entry_string) const;
1322  bool
1323  get_bool(const std::string &entry_name) const;
1324 
1333  bool
1334  get_bool(const std::vector<std::string> &entry_subsection_path,
1335  const std::string & entry_string) const;
1336 
1346  void
1347  set(const std::string &entry_name, const std::string &new_value);
1348 
1359  void
1360  set(const std::string &entry_name, const char *new_value);
1361 
1371  void
1372  set(const std::string &entry_name, const long int new_value);
1373 
1387  void
1388  set(const std::string &entry_name, const double new_value);
1389 
1399  void
1400  set(const std::string &entry_name, const bool new_value);
1401 
1474  std::ostream &
1475  print_parameters(std::ostream &out, const OutputStyle style) const;
1476 
1477 
1478 
1499  void
1500  print_parameters(const std::string &filename,
1501  const OutputStyle style = DefaultStyle) const;
1502 
1517  void
1518  log_parameters(LogStream &out, const OutputStyle style = DefaultStyle);
1519 
1538  void
1540  const OutputStyle style = DefaultStyle);
1541 
1546  std::size_t
1547  memory_consumption() const;
1548 
1553  template <class Archive>
1554  void
1555  save(Archive &ar, const unsigned int version) const;
1556 
1561  template <class Archive>
1562  void
1563  load(Archive &ar, const unsigned int version);
1564 
1565 #ifdef DOXYGEN
1566 
1570  template <class Archive>
1571  void
1572  serialize(Archive &archive, const unsigned int version);
1573 #else
1574  // This macro defines the serialize() method that is compatible with
1575  // the templated save() and load() method that have been implemented.
1576  BOOST_SERIALIZATION_SPLIT_MEMBER()
1577 #endif
1578 
1582  bool
1583  operator==(const ParameterHandler &prm2) const;
1584 
1593  std::set<std::string>
1595 
1601  void
1603 
1613  std::string,
1614  << "The following entry already exists: " << arg1 << ".");
1619  std::string,
1620  std::string,
1621  << "The string <" << arg1
1622  << "> does not match the given pattern <" << arg2 << ">.");
1628  "You can't leave a subsection if you are already at the top level "
1629  "of the subsection hierarchy.");
1634  std::string,
1635  << "You can't ask for entry <" << arg1
1636  << "> you have not yet declared.");
1637 
1645  std::string,
1646  std::string,
1647  << "There are unequal numbers of 'subsection' and 'end' "
1648  "statements in the parameter file <"
1649  << arg1 << ">." << (arg2.size() > 0 ? "\n" + arg2 : ""));
1650 
1656  int,
1657  std::string,
1658  std::string,
1659  << "Line <" << arg1 << "> of file <" << arg2
1660  << ": There is "
1661  "no such subsection to be entered: "
1662  << arg3);
1663 
1670  int,
1671  std::string,
1672  std::string,
1673  << "Line <" << arg1 << "> of file <" << arg2 << ">: " << arg3);
1674 
1681  int,
1682  std::string,
1683  std::string,
1684  std::string,
1685  std::string,
1686  << "Line <" << arg1 << "> of file <" << arg2
1687  << ">:\n"
1688  " The entry value \n"
1689  << " " << arg3 << '\n'
1690  << " for the entry named\n"
1691  << " " << arg4 << '\n'
1692  << " does not match the given pattern:\n"
1693  << " " << arg5);
1694 
1701  "The provided file could not be parsed as a "
1702  "ParameterHandler description.");
1703 
1713 
1722  int,
1723  std::string,
1724  std::string,
1725  << "Line <" << arg1 << "> of file <" << arg2
1726  << ">: This line "
1727  "contains an 'include' or 'INCLUDE' statement, but the given "
1728  "file to include <"
1729  << arg3 << "> cannot be opened.");
1730 
1732 
1733 private:
1738  static const char path_separator = '.';
1739 
1743  std::vector<std::string> subsection_path;
1744 
1753  std::unique_ptr<boost::property_tree::ptree> entries;
1754 
1763  std::map<std::string, std::pair<bool, bool>> entries_set_status;
1764 
1770  std::vector<std::unique_ptr<const Patterns::PatternBase>> patterns;
1771 
1778  std::vector<std::function<void(const std::string &)>> actions;
1779 
1788  std::string
1789  get_current_path() const;
1790 
1795  std::string
1796  get_current_full_path(const std::string &name) const;
1797 
1802  std::string
1803  get_current_full_path(const std::vector<std::string> &sub_path,
1804  const std::string & name) const;
1805 
1824  void
1825  scan_line(std::string line,
1826  const std::string &input_filename,
1827  const unsigned int current_line_n,
1828  const bool skip_undefined);
1829 
1841  void
1843  const boost::property_tree::ptree & tree,
1844  const std::vector<std::string> & target_subsection_path,
1845  const ParameterHandler::OutputStyle style,
1846  const unsigned int indent_level,
1847  std::ostream & out) const;
1848 
1850 };
1851 
1862 {
1863  return static_cast<ParameterHandler::OutputStyle>(
1864  static_cast<unsigned int>(f1) | static_cast<unsigned int>(f2));
1865 }
1866 
2084 {
2085 public:
2091  {
2092  public:
2097  virtual ~UserClass() = default;
2098 
2103  virtual void
2104  create_new(const unsigned int run_no) = 0;
2105 
2109  virtual void
2110  run(ParameterHandler &prm) = 0;
2111  };
2112 
2117 
2122  virtual ~MultipleParameterLoop() override = default;
2123 
2145  virtual void
2146  parse_input(std::istream & input,
2147  const std::string &filename = "input file",
2148  const std::string &last_line = "",
2149  const bool skip_undefined = false) override;
2150 
2159 
2163  void
2164  loop(UserClass &uc);
2165 
2170  std::size_t
2171  memory_consumption() const;
2172 
2173 private:
2177  class Entry
2178  {
2179  public:
2186  {
2194  array
2195  };
2196 
2201  : type(array)
2202  {}
2203 
2209  Entry(const std::vector<std::string> &Path,
2210  const std::string & Name,
2211  const std::string & Value);
2212 
2216  void
2217  split_different_values();
2218 
2222  std::vector<std::string> subsection_path;
2223 
2227  std::string entry_name;
2228 
2232  std::string entry_value;
2233 
2238  std::vector<std::string> different_values;
2239 
2244 
2249  std::size_t
2250  memory_consumption() const;
2251  };
2252 
2256  std::vector<Entry> multiple_choices;
2257 
2262  unsigned int n_branches;
2263 
2267  void
2268  init_branches();
2269 
2276  void
2277  init_branches_current_section();
2278 
2282  void
2283  fill_entry_values(const unsigned int run_no);
2284 };
2285 
2286 
2287 // ---------------------- inline and template functions --------------------
2288 template <class Archive>
2289 inline void
2290 ParameterHandler::save(Archive &ar, const unsigned int) const
2291 {
2292  // Forward to serialization
2293  // function in the base class.
2294  ar &static_cast<const Subscriptor &>(*this);
2295 
2296  ar &*entries.get();
2297 
2298  std::vector<std::string> descriptions;
2299 
2300  for (const auto &pattern : patterns)
2301  descriptions.push_back(pattern->description());
2302 
2303  ar &descriptions;
2304 }
2305 
2306 
2307 template <class Archive>
2308 inline void
2309 ParameterHandler::load(Archive &ar, const unsigned int)
2310 {
2311  // Forward to serialization
2312  // function in the base class.
2313  ar &static_cast<Subscriptor &>(*this);
2314 
2315  ar &*entries.get();
2316 
2317  std::vector<std::string> descriptions;
2318  ar & descriptions;
2319 
2320  patterns.clear();
2321  for (const auto &description : descriptions)
2322  patterns.push_back(Patterns::pattern_factory(description));
2323 }
2324 
2325 
2326 template <class ParameterType>
2327 void
2328 ParameterHandler::add_parameter(const std::string & entry,
2329  ParameterType & parameter,
2330  const std::string & documentation,
2331  const Patterns::PatternBase &pattern,
2332  const bool has_to_be_set)
2333 {
2334  static_assert(std::is_const<ParameterType>::value == false,
2335  "You tried to add a parameter using a type "
2336  "that is const. Use a non-const type.");
2337 
2338  declare_entry(entry,
2340  parameter, pattern.clone()),
2341  pattern,
2342  documentation,
2343  has_to_be_set);
2344 
2345  std::string path = get_current_full_path(entry);
2346  const unsigned int pattern_index =
2347  entries->get<unsigned int>(path + path_separator + "pattern");
2348 
2349  auto action = [&, pattern_index](const std::string &val) {
2351  val, patterns[pattern_index]->clone());
2352  };
2353  add_action(entry, action);
2354 }
2355 
2357 
2358 #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
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: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
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: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
#define DeclExceptionMsg(Exception, defaulttext)
Definition: exceptions.h:496
#define DEAL_II_NAMESPACE_CLOSE
Definition: config.h:359
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:358
void save(Archive &ar, const unsigned int version) const
void run(const std::vector< std::vector< Iterator >> &colored_iterators, Worker worker, Copier copier, const ScratchData &sample_scratch_data, const CopyData &sample_copy_data, const unsigned int queue_length=2 *MultithreadInfo::n_threads(), const unsigned int chunk_size=8)
Definition: work_stream.h:1185
std::vector< std::string > different_values
#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 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)
static const bool value
#define DEAL_II_DEPRECATED
Definition: config.h:98
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
ParameterHandler & operator=(const ParameterHandler &)=delete