Reference documentation for deal.II version Git f39d5fa 2018-06-22 10:03:07 -0500
parameter_handler.h
1 // ---------------------------------------------------------------------
2 //
3 // Copyright (C) 1998 - 2018 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 class LogStream;
41 
800 {
801 private:
805  ParameterHandler(const ParameterHandler &) = delete;
806 
811  operator=(const ParameterHandler &) = delete;
812 
813 public:
819  {
824  Text = 1,
825 
829  LaTeX = 2,
834 
841  XML = 4,
842 
847  JSON = 5,
848 
853  ShortText = 193
854  };
855 
856 
857 
862 
868  virtual ~ParameterHandler() override = default;
869 
898  virtual void
899  parse_input(std::istream & input,
900  const std::string &filename = "input file",
901  const std::string &last_line = "");
902 
946  virtual void
947  parse_input(const std::string &filename, const std::string &last_line = "");
948 
957  virtual void
958  parse_input_from_string(const char *s, const std::string &last_line = "");
959 
967  virtual void
968  parse_input_from_xml(std::istream &input);
969 
977  virtual void
978  parse_input_from_json(std::istream &input);
979 
983  void
984  clear();
985 
986 
1006  void
1007  declare_entry(const std::string & entry,
1008  const std::string & default_value,
1009  const Patterns::PatternBase &pattern = Patterns::Anything(),
1010  const std::string & documentation = std::string());
1011 
1055  void
1056  add_action(const std::string & entry,
1057  const std::function<void(const std::string &value)> &action);
1058 
1068  template <class ParameterType>
1069  void
1070  add_parameter(const std::string & entry,
1071  ParameterType & parameter,
1072  const std::string & documentation = std::string(),
1073  const Patterns::PatternBase &pattern =
1075 
1119  void
1120  declare_alias(const std::string &existing_entry_name,
1121  const std::string &alias_name,
1122  const bool alias_is_deprecated = false);
1123 
1127  void
1128  enter_subsection(const std::string &subsection);
1129 
1133  void
1134  leave_subsection();
1135 
1141  std::string
1142  get(const std::string &entry_string) const;
1143 
1149  long int
1150  get_integer(const std::string &entry_string) const;
1151 
1155  double
1156  get_double(const std::string &entry_name) const;
1157 
1163  bool
1164  get_bool(const std::string &entry_name) const;
1165 
1175  void
1176  set(const std::string &entry_name, const std::string &new_value);
1177 
1188  void
1189  set(const std::string &entry_name, const char *new_value);
1190 
1200  void
1201  set(const std::string &entry_name, const long int &new_value);
1202 
1216  void
1217  set(const std::string &entry_name, const double &new_value);
1218 
1228  void
1229  set(const std::string &entry_name, const bool &new_value);
1230 
1231 
1291  std::ostream &
1292  print_parameters(std::ostream &out, const OutputStyle style) const;
1293 
1311  DEAL_II_DEPRECATED
1312  void
1313  print_parameters_section(std::ostream & out,
1314  const OutputStyle style,
1315  const unsigned int indent_level,
1316  const bool include_top_level_elements = false);
1317 
1323  void
1324  log_parameters(LogStream &out);
1325 
1335  void
1337 
1342  std::size_t
1343  memory_consumption() const;
1344 
1349  template <class Archive>
1350  void
1351  save(Archive &ar, const unsigned int version) const;
1352 
1357  template <class Archive>
1358  void
1359  load(Archive &ar, const unsigned int version);
1360 
1361  BOOST_SERIALIZATION_SPLIT_MEMBER()
1362 
1363 
1366  bool
1367  operator==(const ParameterHandler &prm2) const;
1368 
1378  std::string,
1379  << "The following entry already exists: " << arg1 << ".");
1384  std::string,
1385  std::string,
1386  << "The string <" << arg1
1387  << "> does not match the given pattern <" << arg2 << ">.");
1393  "You can't leave a subsection if you are already at the top level "
1394  "of the subsection hierarchy.");
1399  std::string,
1400  << "You can't ask for entry <" << arg1
1401  << "> you have not yet declared.");
1402 
1410  std::string,
1411  std::string,
1412  << "There are unequal numbers of 'subsection' and 'end' "
1413  "statements in the parameter file <"
1414  << arg1 << ">." << (arg2.size() > 0 ? "\n" + arg2 : ""));
1415 
1421  int,
1422  std::string,
1423  std::string,
1424  << "Line <" << arg1 << "> of file <" << arg2
1425  << ": There is "
1426  "no such subsection to be entered: "
1427  << arg3);
1428 
1435  int,
1436  std::string,
1437  std::string,
1438  << "Line <" << arg1 << "> of file <" << arg2 << ">: " << arg3);
1439 
1446  int,
1447  std::string,
1448  std::string,
1449  std::string,
1450  std::string,
1451  << "Line <" << arg1 << "> of file <" << arg2
1452  << ">:\n"
1453  " The entry value \n"
1454  << " " << arg3 << '\n'
1455  << " for the entry named\n"
1456  << " " << arg4 << '\n'
1457  << " does not match the given pattern:\n"
1458  << " " << arg5);
1459 
1466  "The provided file could not be parsed as a "
1467  "ParameterHandler description.");
1468 
1475  std::string,
1476  std::string,
1477  std::string,
1478  << " The entry value \n"
1479  << " " << arg1 << '\n'
1480  << " for the entry named\n"
1481  << " " << arg2 << '\n'
1482  << " does not match the given pattern:\n"
1483  << " " << arg3);
1484 
1493  int,
1494  std::string,
1495  std::string,
1496  << "Line <" << arg1 << "> of file <" << arg2
1497  << ">: This line "
1498  "contains an 'include' or 'INCLUDE' statement, but the given "
1499  "file to include <"
1500  << arg3 << "> cannot be opened.");
1501 
1503 private:
1508  static const char path_separator = '.';
1509 
1513  std::vector<std::string> subsection_path;
1514 
1523  std::unique_ptr<boost::property_tree::ptree> entries;
1524 
1530  std::vector<std::unique_ptr<const Patterns::PatternBase>> patterns;
1531 
1538  std::vector<std::function<void(const std::string &)>> actions;
1539 
1546  static std::string
1547  collate_path_string(const std::vector<std::string> &subsection_path);
1548 
1557  std::string
1558  get_current_path() const;
1559 
1564  std::string
1565  get_current_full_path(const std::string &name) const;
1566 
1579  void
1580  scan_line(std::string line,
1581  const std::string &input_filename,
1582  const unsigned int current_line_n);
1583 
1595  void
1597  const std::vector<std::string> &target_subsection_path,
1598  const OutputStyle style,
1599  const unsigned int indent_level,
1600  std::ostream & out) const;
1601 
1602  friend class MultipleParameterLoop;
1603 };
1604 
1605 
1606 
1823 class MultipleParameterLoop : public ParameterHandler
1824 {
1825 public:
1831  {
1832  public:
1837  virtual ~UserClass() = default;
1838 
1843  virtual void
1844  create_new(const unsigned int run_no) = 0;
1845 
1849  virtual void
1850  run(ParameterHandler &prm) = 0;
1851  };
1852 
1856  MultipleParameterLoop();
1857 
1862  virtual ~MultipleParameterLoop() override = default;
1863 
1879  virtual void
1880  parse_input(std::istream & input,
1881  const std::string &filename = "input file",
1882  const std::string &last_line = "") override;
1883 
1892 
1896  void
1897  loop(UserClass &uc);
1898 
1903  std::size_t
1904  memory_consumption() const;
1905 
1906 private:
1910  class Entry
1911  {
1912  public:
1919  {
1927  array
1928  };
1929 
1934  : type(array)
1935  {}
1936 
1942  Entry(const std::vector<std::string> &Path,
1943  const std::string & Name,
1944  const std::string & Value);
1945 
1949  void
1950  split_different_values();
1951 
1955  std::vector<std::string> subsection_path;
1956 
1960  std::string entry_name;
1961 
1965  std::string entry_value;
1966 
1971  std::vector<std::string> different_values;
1972 
1977 
1982  std::size_t
1983  memory_consumption() const;
1984  };
1985 
1989  std::vector<Entry> multiple_choices;
1990 
1995  unsigned int n_branches;
1996 
2000  void
2001  init_branches();
2002 
2009  void
2010  init_branches_current_section();
2011 
2015  void
2016  fill_entry_values(const unsigned int run_no);
2017 };
2018 
2019 
2020 // ---------------------- inline and template functions --------------------
2021 template <class Archive>
2022 inline void
2023 ParameterHandler::save(Archive &ar, const unsigned int) const
2024 {
2025  // Forward to serialization
2026  // function in the base class.
2027  ar &static_cast<const Subscriptor &>(*this);
2028 
2029  ar &*entries.get();
2030 
2031  std::vector<std::string> descriptions;
2032 
2033  for (unsigned int j = 0; j < patterns.size(); ++j)
2034  descriptions.push_back(patterns[j]->description());
2035 
2036  ar &descriptions;
2037 }
2038 
2039 
2040 template <class Archive>
2041 inline void
2042 ParameterHandler::load(Archive &ar, const unsigned int)
2043 {
2044  // Forward to serialization
2045  // function in the base class.
2046  ar &static_cast<Subscriptor &>(*this);
2047 
2048  ar &*entries.get();
2049 
2050  std::vector<std::string> descriptions;
2051  ar & descriptions;
2052 
2053  patterns.clear();
2054  for (unsigned int j = 0; j < descriptions.size(); ++j)
2055  patterns.push_back(Patterns::pattern_factory(descriptions[j]));
2056 }
2057 
2058 
2059 template <class ParameterType>
2060 void
2061 ParameterHandler::add_parameter(const std::string & entry,
2062  ParameterType & parameter,
2063  const std::string & documentation,
2064  const Patterns::PatternBase &pattern)
2065 {
2066  static_assert(std::is_const<ParameterType>::value == false,
2067  "You tried to add a parameter using a type "
2068  "that is const. Use a non-const type.");
2069 
2070  declare_entry(entry,
2072  parameter, pattern.clone()),
2073  pattern,
2074  documentation);
2075 
2076  std::string path = get_current_full_path(entry);
2077  const unsigned int pattern_index =
2078  entries->get<unsigned int>(path + path_separator + "pattern");
2079 
2080  auto action = [&, pattern_index](const std::string &val) {
2082  val, patterns[pattern_index]->clone());
2083  };
2084  add_action(entry, action);
2085 }
2086 
2087 DEAL_II_NAMESPACE_CLOSE
2088 
2089 #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:443
static const char path_separator
#define DeclException2(Exception2, type1, type2, outsequence)
Definition: exceptions.h:420
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
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)
virtual void parse_input_from_json(std::istream &input)
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()
static::ExceptionBase & ExcCannotParseLine(int arg1, std::string arg2, std::string arg3)
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:408
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:397
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:459
std::unique_ptr< PatternBase > pattern_factory(const std::string &description)
Definition: patterns.cc:136
virtual void parse_input_from_string(const char *s, const std::string &last_line="")
static::ExceptionBase & ExcAlreadyAtTopLevel()
std::vector< std::unique_ptr< const Patterns::PatternBase > > patterns
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)
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
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:432
static::ExceptionBase & ExcInvalidEntryForPattern(int arg1, std::string arg2, std::string arg3, std::string arg4, std::string arg5)
std::vector< std::function< void(const std::string &)> > actions
virtual ~ParameterHandler() override=default
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="")