Reference documentation for deal.II version Git 7f58f27 2017-09-20 15:35:49 -0600
parameter_handler.h
1 // ---------------------------------------------------------------------
2 //
3 // Copyright (C) 1998 - 2017 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 at
12 // the top level of the deal.II distribution.
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 #include <deal.II/base/exceptions.h>
22 #include <deal.II/base/subscriptor.h>
23 #include <deal.II/base/patterns.h>
24 
25 #include <boost/property_tree/ptree_fwd.hpp>
26 #include <boost/serialization/split_member.hpp>
27 #include <boost/archive/basic_archive.hpp>
28 #include <boost/property_tree/ptree_serialization.hpp>
29 
30 #include <map>
31 #include <vector>
32 #include <string>
33 #include <memory>
34 
35 DEAL_II_NAMESPACE_OPEN
36 
37 // forward declarations for interfaces and friendship
38 class LogStream;
40 
800 {
801 private:
805  ParameterHandler (const ParameterHandler &) = delete;
806 
810  ParameterHandler &operator= (const ParameterHandler &) = delete;
811 
812 public:
817  {
822  Text = 1,
823 
827  LaTeX = 2,
832 
839  XML = 4,
840 
845  JSON = 5,
846 
851  ShortText = 193
852  };
853 
854 
855 
859  ParameterHandler ();
860 
866  virtual ~ParameterHandler () = default;
867 
896  virtual void parse_input (std::istream &input,
897  const std::string &filename = "input file",
898  const std::string &last_line = "");
899 
943  virtual void parse_input (const std::string &filename,
944  const std::string &last_line = "");
945 
954  virtual void parse_input_from_string (const char *s,
955  const std::string &last_line = "");
956 
964  virtual void parse_input_from_xml (std::istream &input);
965 
969  void clear ();
970 
971 
991  void declare_entry (const std::string &entry,
992  const std::string &default_value,
993  const Patterns::PatternBase &pattern = Patterns::Anything(),
994  const std::string &documentation = std::string());
995 
1038  void add_action (const std::string &entry,
1039  const std::function<void (const std::string &value)> &action);
1040 
1050  template <class ParameterType>
1051  void add_parameter(const std::string &entry,
1052  ParameterType &parameter,
1053  const std::string &documentation = std::string(),
1054  const Patterns::PatternBase &pattern =
1056 
1100  void declare_alias (const std::string &existing_entry_name,
1101  const std::string &alias_name,
1102  const bool alias_is_deprecated = false);
1103 
1107  void enter_subsection (const std::string &subsection);
1108 
1112  void leave_subsection ();
1113 
1119  std::string get (const std::string &entry_string) const;
1120 
1126  long int get_integer (const std::string &entry_string) const;
1127 
1131  double get_double (const std::string &entry_name) const;
1132 
1138  bool get_bool (const std::string &entry_name) const;
1139 
1149  void set (const std::string &entry_name,
1150  const std::string &new_value);
1151 
1162  void set (const std::string &entry_name,
1163  const char *new_value);
1164 
1174  void set (const std::string &entry_name,
1175  const long int &new_value);
1176 
1190  void set (const std::string &entry_name,
1191  const double &new_value);
1192 
1202  void set (const std::string &entry_name,
1203  const bool &new_value);
1204 
1205 
1248  std::ostream &
1249  print_parameters (std::ostream &out,
1250  const OutputStyle style) const;
1251 
1269  void print_parameters_section (std::ostream &out,
1270  const OutputStyle style,
1271  const unsigned int indent_level,
1272  const bool include_top_level_elements = false) DEAL_II_DEPRECATED;
1273 
1279  void log_parameters (LogStream &out);
1280 
1290  void log_parameters_section (LogStream &out);
1291 
1296  std::size_t memory_consumption () const;
1297 
1302  template <class Archive>
1303  void save (Archive &ar, const unsigned int version) const;
1304 
1309  template <class Archive>
1310  void load (Archive &ar, const unsigned int version);
1311 
1312  BOOST_SERIALIZATION_SPLIT_MEMBER()
1313 
1317  bool operator == (const ParameterHandler &prm2) const;
1318 
1328  std::string,
1329  << "The following entry already exists: " << arg1 << ".");
1334  std::string, std::string,
1335  << "The string <" << arg1
1336  << "> does not match the given pattern <" << arg2 << ">.");
1341  "You can't leave a subsection if you are already at the top level "
1342  "of the subsection hierarchy.");
1347  std::string,
1348  << "You can't ask for entry <" << arg1 << "> you have not yet declared.");
1349 
1357  std::string, std::string,
1358  << "There are unequal numbers of 'subsection' and 'end' "
1359  "statements in the parameter file <" << arg1 << ">."
1360  << (arg2.size() > 0 ? "\n" + arg2 : ""));
1361 
1367  int, std::string, std::string,
1368  << "Line <" << arg1 << "> of file <" << arg2 << ": There is "
1369  "no such subsection to be entered: " << arg3);
1370 
1377  int, std::string, std::string, << "Line <" << arg1 <<
1378  "> of file <" << arg2 << ">: " << arg3);
1379 
1386  int, std::string, std::string, std::string, std::string,
1387  << "Line <" << arg1 << "> of file <" << arg2 << ">:\n"
1388  " The entry value \n" << " " << arg3 << '\n' <<
1389  " for the entry named\n" << " " << arg4 << '\n' <<
1390  " does not match the given pattern:\n" << " " <<
1391  arg5);
1392 
1399  "The provided file could not be parsed as a "
1400  "ParameterHandler description.");
1401 
1408  std::string, std::string, std::string,
1409  << " The entry value \n" << " " << arg1 << '\n' <<
1410  " for the entry named\n" << " " << arg2 << '\n' <<
1411  " does not match the given pattern:\n" << " " <<
1412  arg3);
1413 
1421  int, std::string, std::string,
1422  << "Line <" << arg1 << "> of file <" << arg2 << ">: This line "
1423  "contains an 'include' or 'INCLUDE' statement, but the given "
1424  "file to include <" << arg3 << "> cannot be opened.");
1425 
1427 private:
1432  static const char path_separator = '.';
1433 
1437  std::vector<std::string> subsection_path;
1438 
1447  std::unique_ptr<boost::property_tree::ptree> entries;
1448 
1454  std::vector<std::shared_ptr<const Patterns::PatternBase> > patterns;
1455 
1462  std::vector<std::function<void (const std::string &)> > actions;
1463 
1468  static std::string mangle (const std::string &s);
1469 
1473  static std::string demangle (const std::string &s);
1474 
1481  static
1482  std::string
1483  collate_path_string (const std::vector<std::string> &subsection_path);
1484 
1493  std::string get_current_path () const;
1494 
1499  std::string get_current_full_path (const std::string &name) const;
1500 
1513  void scan_line (std::string line,
1514  const std::string &input_filename,
1515  const unsigned int current_line_n);
1516 
1528  void recursively_print_parameters (const std::vector<std::string> &target_subsection_path,
1529  const OutputStyle style,
1530  const unsigned int indent_level,
1531  std::ostream &out) const;
1532 
1533  friend class MultipleParameterLoop;
1534 };
1535 
1536 
1537 
1754 class MultipleParameterLoop : public ParameterHandler
1755 {
1756 public:
1762  {
1763  public:
1768  virtual ~UserClass () = default;
1769 
1774  virtual void create_new (const unsigned int run_no) = 0;
1775 
1779  virtual void run (ParameterHandler &prm) = 0;
1780  };
1781 
1785  MultipleParameterLoop ();
1786 
1791  virtual ~MultipleParameterLoop () = default;
1792 
1808  virtual void parse_input (std::istream &input,
1809  const std::string &filename = "input file",
1810  const std::string &last_line = "") override;
1811 
1820 
1824  void loop (UserClass &uc);
1825 
1830  std::size_t memory_consumption () const;
1831 
1832 private:
1833 
1837  class Entry
1838  {
1839  public:
1846  {
1854  array
1855  };
1856 
1860  Entry () : type (array) {}
1861 
1867  Entry (const std::vector<std::string> &Path,
1868  const std::string &Name,
1869  const std::string &Value);
1870 
1874  void split_different_values ();
1875 
1879  std::vector<std::string> subsection_path;
1880 
1884  std::string entry_name;
1885 
1889  std::string entry_value;
1890 
1895  std::vector<std::string> different_values;
1896 
1901 
1906  std::size_t memory_consumption () const;
1907  };
1908 
1912  std::vector<Entry> multiple_choices;
1913 
1918  unsigned int n_branches;
1919 
1923  void init_branches ();
1924 
1931  void init_branches_current_section ();
1932 
1936  void fill_entry_values (const unsigned int run_no);
1937 };
1938 
1939 
1940 // ---------------------- inline and template functions --------------------
1941 template <class Archive>
1942 inline
1943 void
1944 ParameterHandler::save (Archive &ar, const unsigned int) const
1945 {
1946  // Forward to serialization
1947  // function in the base class.
1948  ar &static_cast<const Subscriptor &>(*this);
1949 
1950  ar & *entries.get();
1951 
1952  std::vector<std::string> descriptions;
1953 
1954  for (unsigned int j=0; j<patterns.size(); ++j)
1955  descriptions.push_back (patterns[j]->description());
1956 
1957  ar &descriptions;
1958 }
1959 
1960 
1961 template <class Archive>
1962 inline
1963 void
1964 ParameterHandler::load (Archive &ar, const unsigned int)
1965 {
1966  // Forward to serialization
1967  // function in the base class.
1968  ar &static_cast<Subscriptor &>(*this);
1969 
1970  ar & *entries.get();
1971 
1972  std::vector<std::string> descriptions;
1973  ar &descriptions;
1974 
1975  patterns.clear ();
1976  for (unsigned int j=0; j<descriptions.size(); ++j)
1977  patterns.push_back (std::shared_ptr<const Patterns::PatternBase>(Patterns::pattern_factory(descriptions[j])));
1978 }
1979 
1980 
1981 template <class ParameterType>
1982 void ParameterHandler::add_parameter(const std::string &entry,
1983  ParameterType &parameter,
1984  const std::string &documentation,
1985  const Patterns::PatternBase &pattern)
1986 {
1987 
1988  static_assert(std::is_const<ParameterType>::value == false,
1989  "You tried to add a parameter using a type "
1990  "that is const. Use a non-const type.");
1991 
1992  declare_entry(entry,
1994  parameter, pattern.clone()),
1995  pattern,
1996  documentation);
1997 
1998  std::string path = get_current_full_path(entry);
1999  const unsigned int pattern_index
2000  = entries->get<unsigned int> (path + path_separator + "pattern");
2001 
2002  auto action = [ &, pattern_index](const std::string &val)
2003  {
2004  parameter =
2005  Patterns::Tools::Convert<ParameterType>::to_value(val, patterns[pattern_index]->clone());
2006  };
2007  add_action(entry, action);
2008 }
2009 
2010 DEAL_II_NAMESPACE_CLOSE
2011 
2012 #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:386
static const char path_separator
#define DeclException2(Exception2, type1, type2, outsequence)
Definition: exceptions.h:605
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
virtual ~ParameterHandler()=default
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)
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()
std::vector< std::shared_ptr< const Patterns::PatternBase > > patterns
static::ExceptionBase & ExcCannotParseLine(int arg1, std::string arg2, std::string arg3)
#define DeclException1(Exception1, type1, outsequence)
Definition: exceptions.h:593
void print_parameters_section(std::ostream &out, const OutputStyle style, const unsigned int indent_level, const bool include_top_level_elements=false) 1
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:582
static std::string mangle(const std::string &s)
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:641
std::unique_ptr< PatternBase > pattern_factory(const std::string &description)
Definition: patterns.cc:79
virtual void parse_input_from_string(const char *s, const std::string &last_line="")
static::ExceptionBase & ExcAlreadyAtTopLevel()
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)
static std::string demangle(const std::string &s)
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=std::string())
std::vector< std::string > different_values
std::vector< std::function< void(const std::string &)> > actions
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:617
static::ExceptionBase & ExcInvalidEntryForPattern(int arg1, std::string arg2, std::string arg3, std::string arg4, std::string arg5)
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="")