Reference documentation for deal.II version 8.1.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
parameter_handler.h
1 // ---------------------------------------------------------------------
2 // @f$Id: parameter_handler.h 31584 2013-11-08 05:08:26Z bangerth @f$
3 //
4 // Copyright (C) 1998 - 2013 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // The deal.II library is free software; you can use it, redistribute
9 // it, and/or modify it under the terms of the GNU Lesser General
10 // Public License as published by the Free Software Foundation; either
11 // version 2.1 of the License, or (at your option) any later version.
12 // The full text of the license can be found in the file LICENSE at
13 // the top level of the deal.II distribution.
14 //
15 // ---------------------------------------------------------------------
16 
17 #ifndef __deal2__parameter_handler_h
18 #define __deal2__parameter_handler_h
19 
20 
21 #include <deal.II/base/config.h>
23 #include <deal.II/base/subscriptor.h>
24 #include <deal.II/base/std_cxx1x/shared_ptr.h>
25 
26 #include <boost/property_tree/ptree_fwd.hpp>
27 #include <boost/serialization/split_member.hpp>
28 
29 #include <map>
30 #include <vector>
31 #include <string>
32 #include <memory>
33 
34 DEAL_II_NAMESPACE_OPEN
35 
36 //TODO: Allow long input lines to be broken by appending a backslash character
37 
38 
39 // public classes; to be declared below
40 class ParameterHandler;
42 
43 
44 
45 // forward declaration
46 class LogStream;
47 
48 
49 
58 namespace Patterns
59 {
60 
68  {
69  public:
73  virtual ~PatternBase ();
74 
78  virtual bool match (const std::string &test_string) const = 0;
79 
83  virtual std::string description () const = 0;
84 
94  virtual PatternBase *clone () const = 0;
95 
112  virtual std::size_t memory_consumption () const;
113  };
114 
118  PatternBase *pattern_factory (const std::string &description);
119 
138  class Integer : public PatternBase
139  {
140  public:
146  static const int min_int_value;
147 
153  static const int max_int_value;
154 
161  Integer (const int lower_bound = min_int_value,
162  const int upper_bound = max_int_value);
163 
168  virtual bool match (const std::string &test_string) const;
169 
175  virtual std::string description () const;
176 
182  virtual PatternBase *clone () const;
183 
189  static Integer *create (const std::string &description);
190 
191  private:
197  const int lower_bound;
198 
204  const int upper_bound;
205 
209  static const char *description_init;
210  };
211 
231  class Double : public PatternBase
232  {
233  public:
240  static const double min_double_value;
241 
247  static const double max_double_value;
248 
255  Double (const double lower_bound = min_double_value,
256  const double upper_bound = max_double_value);
257 
262  virtual bool match (const std::string &test_string) const;
263 
269  virtual std::string description () const;
270 
276  virtual PatternBase *clone () const;
277 
283  static Double *create (const std::string &description);
284 
285  private:
291  const double lower_bound;
292 
298  const double upper_bound;
299 
303  static const char *description_init;
304  };
305 
314  class Selection : public PatternBase
315  {
316  public:
321  Selection (const std::string &seq);
322 
327  virtual bool match (const std::string &test_string) const;
328 
334  virtual std::string description () const;
335 
341  virtual PatternBase *clone () const;
342 
347  std::size_t memory_consumption () const;
348 
354  static Selection *create (const std::string &description);
355 
356  private:
361  std::string sequence;
362 
366  static const char *description_init;
367  };
368 
369 
378  class List : public PatternBase
379  {
380  public:
386  static const unsigned int max_int_value;
387 
396  List (const PatternBase &base_pattern,
397  const unsigned int min_elements = 0,
398  const unsigned int max_elements = max_int_value,
399  const std::string &separator = ",");
400 
404  virtual ~List ();
405 
411  virtual bool match (const std::string &test_string) const;
412 
417  virtual std::string description () const;
418 
424  virtual PatternBase *clone () const;
425 
431  static List *create (const std::string &description);
432 
437  std::size_t memory_consumption () const;
438 
445  DeclException2 (ExcInvalidRange,
446  int, int,
447  << "The values " << arg1 << " and " << arg2
448  << " do not form a valid range.");
450  private:
455 
459  const unsigned int min_elements;
460 
464  const unsigned int max_elements;
465 
469  const std::string separator;
470 
474  static const char *description_init;
475  };
476 
477 
491  class Map : public PatternBase
492  {
493  public:
499  static const unsigned int max_int_value;
500 
509  Map (const PatternBase &key_pattern,
510  const PatternBase &value_pattern,
511  const unsigned int min_elements = 0,
512  const unsigned int max_elements = max_int_value,
513  const std::string &separator = ",");
514 
518  virtual ~Map ();
519 
524  virtual bool match (const std::string &test_string) const;
525 
530  virtual std::string description () const;
531 
537  virtual PatternBase *clone () const;
538 
544  static Map *create (const std::string &description);
545 
550  std::size_t memory_consumption () const;
551 
558  DeclException2 (ExcInvalidRange,
559  int, int,
560  << "The values " << arg1 << " and " << arg2
561  << " do not form a valid range.");
563  private:
569  PatternBase *value_pattern;
570 
574  const unsigned int min_elements;
575 
579  const unsigned int max_elements;
580 
584  const std::string separator;
585 
589  static const char *description_init;
590  };
591 
592 
605  {
606  public:
611  MultipleSelection (const std::string &seq);
612 
617  virtual bool match (const std::string &test_string) const;
618 
624  virtual std::string description () const;
625 
631  virtual PatternBase *clone () const;
632 
638  static MultipleSelection *create (const std::string &description);
639 
644  std::size_t memory_consumption () const;
645 
652  DeclException1 (ExcCommasNotAllowed,
653  int,
654  << "A comma was found at position " << arg1
655  << " of your input string, but commas are not allowed here.");
657  private:
662  std::string sequence;
663 
667  static const char *description_init;
668  };
669 
674  class Bool : public Selection
675  {
676  public:
680  Bool ();
681 
686  virtual std::string description () const;
687 
693  virtual PatternBase *clone () const;
694 
700  static Bool *create (const std::string &description);
701 
702  private:
706  static const char *description_init;
707  };
708 
712  class Anything : public PatternBase
713  {
714  public:
719  Anything ();
720 
725  virtual bool match (const std::string &test_string) const;
726 
731  virtual std::string description () const;
732 
738  virtual PatternBase *clone () const;
739 
745  static Anything *create (const std::string &description);
746 
747  private:
751  static const char *description_init;
752  };
753 
754 
771  class FileName : public PatternBase
772  {
773  public:
778  enum FileType {input = 0, output = 1};
779 
784  FileName (const FileType type = input);
785 
790  virtual bool match (const std::string &test_string) const;
791 
796  virtual std::string description () const;
797 
803  virtual PatternBase *clone () const;
804 
809 
815  static FileName *create (const std::string &description);
816 
817  private:
821  static const char *description_init;
822  };
823 
824 
837  class DirectoryName : public PatternBase
838  {
839  public:
843  DirectoryName ();
844 
849  virtual bool match (const std::string &test_string) const;
850 
855  virtual std::string description () const;
856 
862  virtual PatternBase *clone () const;
863 
869  static DirectoryName *create (const std::string &description);
870 
871  private:
875  static const char *description_init;
876  };
877 }
878 
879 
1518 {
1519 private:
1524 
1529 
1530 public:
1539  {
1544  Text = 1,
1548  LaTeX = 2,
1553 
1561  XML = 4,
1562 
1567  JSON = 5,
1568 
1574  };
1575 
1576 
1577 
1581  ParameterHandler ();
1582 
1588  virtual ~ParameterHandler ();
1589 
1598  virtual bool read_input (std::istream &input,
1599  const std::string &filename = "input file");
1600 
1612  virtual bool read_input (const std::string &filename,
1613  const bool optional = false,
1614  const bool write_stripped_file = false);
1615 
1622  virtual bool read_input_from_string (const char *s);
1623 
1633  virtual bool read_input_from_xml (std::istream &input);
1634 
1638  void clear ();
1639 
1640 
1660  void declare_entry (const std::string &entry,
1661  const std::string &default_value,
1662  const Patterns::PatternBase &pattern = Patterns::Anything(),
1663  const std::string &documentation = std::string());
1664 
1668  void enter_subsection (const std::string &subsection);
1669 
1674  bool leave_subsection ();
1675 
1682  std::string get (const std::string &entry_string) const;
1683 
1689  long int get_integer (const std::string &entry_string) const;
1690 
1694  double get_double (const std::string &entry_name) const;
1695 
1701  bool get_bool (const std::string &entry_name) const;
1702 
1712  void set (const std::string &entry_name,
1713  const std::string &new_value);
1714 
1725  void set (const std::string &entry_name,
1726  const char *new_value);
1727 
1737  void set (const std::string &entry_name,
1738  const long int &new_value);
1739 
1754  void set (const std::string &entry_name,
1755  const double &new_value);
1756 
1766  void set (const std::string &entry_name,
1767  const bool &new_value);
1768 
1769 
1811  std::ostream &print_parameters (std::ostream &out,
1812  const OutputStyle style);
1813 
1823  void print_parameters_section (std::ostream &out,
1824  const OutputStyle style,
1825  const unsigned int indent_level);
1826 
1832  void log_parameters (LogStream &out);
1833 
1843  void log_parameters_section (LogStream &out);
1844 
1849  std::size_t memory_consumption () const;
1850 
1855  template <class Archive>
1856  void save (Archive &ar, const unsigned int version) const;
1857 
1862  template <class Archive>
1863  void load (Archive &ar, const unsigned int version);
1864 
1865  BOOST_SERIALIZATION_SPLIT_MEMBER()
1866 
1867 
1870  bool operator == (const ParameterHandler &prm2) const;
1871 
1878  DeclException1 (ExcEntryAlreadyExists,
1879  std::string,
1880  << "The following entry already exists: " << arg1);
1884  DeclException2 (ExcValueDoesNotMatchPattern,
1885  std::string, std::string,
1886  << "The string <" << arg1
1887  << "> does not match the given pattern <" << arg2 << ">");
1891  DeclException0 (ExcAlreadyAtTopLevel);
1895  DeclException1 (ExcEntryUndeclared,
1896  std::string,
1897  << "You can't ask for entry <" << arg1 << "> you have not yet declared");
1901  DeclException1 (ExcConversionError,
1902  std::string,
1903  << "Error when trying to convert the following string: " << arg1);
1905 private:
1910  static const char path_separator = '.';
1911 
1921  std::auto_ptr<boost::property_tree::ptree> entries;
1922 
1927  std::vector<std_cxx1x::shared_ptr<const Patterns::PatternBase> > patterns;
1928 
1933  static std::string mangle (const std::string &s);
1934 
1938  static std::string demangle (const std::string &s);
1939 
1943  static bool is_parameter_node (const boost::property_tree::ptree &);
1944 
1948  std::vector<std::string> subsection_path;
1949 
1955  std::string get_current_path () const;
1956 
1961  std::string get_current_full_path (const std::string &name) const;
1962 
1976  bool scan_line (std::string line,
1977  const std::string &input_filename,
1978  const unsigned int lineno);
1979 
1980  friend class MultipleParameterLoop;
1981 };
1982 
1983 
1984 
2202 class MultipleParameterLoop : public ParameterHandler
2203 {
2204 public:
2210  {
2211  public:
2216  virtual ~UserClass ();
2217 
2222  virtual void create_new (const unsigned int run_no) = 0;
2223 
2228  virtual void declare_parameters (ParameterHandler &prm) = 0;
2229 
2233  virtual void run (ParameterHandler &prm) = 0;
2234  };
2235 
2239  MultipleParameterLoop ();
2240 
2246  virtual ~MultipleParameterLoop ();
2247 
2256  virtual bool read_input (std::istream &input,
2257  const std::string &filename = "input file");
2258 
2270  virtual bool read_input (const std::string &FileName,
2271  const bool optional = false,
2272  const bool write_stripped_file = false);
2273 
2278  virtual bool read_input_from_string (const char *s);
2279 
2283  void loop (UserClass &uc);
2284 
2289  std::size_t memory_consumption () const;
2290 
2291 private:
2292 
2296  class Entry
2297  {
2298  public:
2305  {
2306  variant, array
2307  };
2308 
2312  Entry () : type (array) {}
2313 
2319  Entry (const std::vector<std::string> &Path,
2320  const std::string &Name,
2321  const std::string &Value);
2322 
2326  void split_different_values ();
2327 
2331  std::vector<std::string> subsection_path;
2332 
2336  std::string entry_name;
2337 
2341  std::string entry_value;
2342 
2347  std::vector<std::string> different_values;
2348 
2353 
2358  std::size_t memory_consumption () const;
2359  };
2360 
2364  std::vector<Entry> multiple_choices;
2365 
2370  unsigned int n_branches;
2371 
2375  void init_branches ();
2376 
2383  void init_branches_current_section ();
2384 
2388  void fill_entry_values (const unsigned int run_no);
2389 };
2390 
2391 
2392 template <class Archive>
2393 inline
2394 void
2395 ParameterHandler::save (Archive &ar, const unsigned int) const
2396 {
2397  // Forward to serialization
2398  // function in the base class.
2399  ar &static_cast<const Subscriptor &>(*this);
2400 
2401  ar & *entries.get();
2402 
2403  std::vector<std::string> descriptions;
2404 
2405  for (unsigned int j=0; j<patterns.size(); ++j)
2406  descriptions.push_back (patterns[j]->description());
2407 
2408  ar &descriptions;
2409 }
2410 
2411 
2412 template <class Archive>
2413 inline
2414 void
2415 ParameterHandler::load (Archive &ar, const unsigned int)
2416 {
2417  // Forward to serialization
2418  // function in the base class.
2419  ar &static_cast<Subscriptor &>(*this);
2420 
2421  ar & *entries.get();
2422 
2423  std::vector<std::string> descriptions;
2424  ar &descriptions;
2425 
2426  patterns.clear ();
2427  for (unsigned int j=0; j<descriptions.size(); ++j)
2428  patterns.push_back (std_cxx1x::shared_ptr<const Patterns::PatternBase>(Patterns::pattern_factory(descriptions[j])));
2429 }
2430 
2431 
2432 DEAL_II_NAMESPACE_CLOSE
2433 
2434 #endif
std::vector< Entry > multiple_choices
bool scan_line(std::string line, const std::string &input_filename, const unsigned int lineno)
virtual PatternBase * clone() const
static const char path_separator
PatternBase * key_pattern
virtual PatternBase * clone() const
virtual std::string description() const
static const char * description_init
static const char * description_init
virtual bool read_input(std::istream &input, const std::string &filename="input file")
const double upper_bound
static const char * description_init
virtual std::string description() const
std::string get_current_full_path(const std::string &name) const
virtual std::size_t memory_consumption() const
virtual bool read_input_from_string(const char *s)
void loop(ITERATOR begin, typename identity< ITERATOR >::type end, DOFINFO &dinfo, INFOBOX &info, const std_cxx1x::function< void(DOFINFO &, typename INFOBOX::CellInfo &)> &cell_worker, const std_cxx1x::function< void(DOFINFO &, typename INFOBOX::CellInfo &)> &boundary_worker, const std_cxx1x::function< void(DOFINFO &, DOFINFO &, typename INFOBOX::CellInfo &, typename INFOBOX::CellInfo &)> &face_worker, ASSEMBLER &assembler, bool cells_first=true, bool unique_faces_only=true)
Definition: loop.h:255
virtual std::string description() const
static const char * description_init
static const char * description_init
static std::string mangle(const std::string &s)
std::size_t memory_consumption() const
virtual std::string description() const =0
virtual PatternBase * clone() const
static const char * description_init
const std::string separator
static bool is_parameter_node(const boost::property_tree::ptree &)
static Map * create(const std::string &description)
void log_parameters(LogStream &out)
static const unsigned int max_int_value
void set(const std::string &entry_name, const std::string &new_value)
virtual std::string description() const
virtual ~ParameterHandler()
std::size_t memory_consumption() const
PatternBase * pattern_factory(const std::string &description)
void log_parameters_section(LogStream &out)
virtual bool match(const std::string &test_string) const
static const char * description_init
virtual std::string description() const
std::vector< std::string > subsection_path
static const int max_int_value
virtual ~Map()
virtual bool match(const std::string &test_string) const
const unsigned int max_elements
std::size_t memory_consumption() const
virtual ~List()
std::size_t memory_consumption() const
void load(Archive &ar, const unsigned int version)
std::vector< std::string > subsection_path
static const int min_int_value
static FileName * create(const std::string &description)
virtual bool match(const std::string &test_string) const
static const char * description_init
virtual PatternBase * clone() const
const double lower_bound
virtual PatternBase * clone() const =0
void enter_subsection(const std::string &subsection)
FileName(const FileType type=input)
virtual bool read_input_from_xml(std::istream &input)
static Anything * create(const std::string &description)
static const char * description_init
virtual std::string description() const
PatternBase * pattern
ParameterHandler & operator=(const ParameterHandler &)
virtual PatternBase * clone() const
std::vector< std_cxx1x::shared_ptr< const Patterns::PatternBase > > patterns
DeclException1(ExcEntryAlreadyExists, std::string,<< "The following entry already exists: "<< arg1)
static Selection * create(const std::string &description)
Double(const double lower_bound=min_double_value, const double upper_bound=max_double_value)
void save(Archive &ar, const unsigned int version) const
virtual bool match(const std::string &test_string) const
List(const PatternBase &base_pattern, const unsigned int min_elements=0, const unsigned int max_elements=max_int_value, const std::string &separator=",")
MultipleSelection(const std::string &seq)
Map(const PatternBase &key_pattern, const PatternBase &value_pattern, const unsigned int min_elements=0, const unsigned int max_elements=max_int_value, const std::string &separator=",")
virtual std::string description() const
virtual bool match(const std::string &test_string) const
std::string get_current_path() const
static Integer * create(const std::string &description)
static const double min_double_value
DeclException2(ExcInvalidRange, int, int,<< "The values "<< arg1<< " and "<< arg2<< " do not form a valid range.")
virtual bool match(const std::string &test_string) const
static Double * create(const std::string &description)
virtual PatternBase * clone() const
virtual bool match(const std::string &test_string) const =0
virtual PatternBase * clone() const
virtual std::string description() const
DeclException0(ExcAlreadyAtTopLevel)
virtual bool match(const std::string &test_string) const
bool get_bool(const std::string &entry_name) const
static const char * description_init
virtual std::string description() const
DeclException1(ExcCommasNotAllowed, int,<< "A comma was found at position "<< arg1<< " of your input string, but commas are not allowed here.")
static MultipleSelection * create(const std::string &description)
static const double max_double_value
static List * create(const std::string &description)
DeclException2(ExcValueDoesNotMatchPattern, std::string, std::string,<< "The string <"<< arg1<< "> does not match the given pattern <"<< arg2<< ">")
bool leave_subsection()
virtual PatternBase * clone() const
Integer(const int lower_bound=min_int_value, const int upper_bound=max_int_value)
double get_double(const std::string &entry_name) const
virtual PatternBase * clone() const
virtual std::string description() 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())
Selection(const std::string &seq)
static std::string demangle(const std::string &s)
std::vector< std::string > different_values
const unsigned int min_elements
static const unsigned int max_int_value
std::auto_ptr< boost::property_tree::ptree > entries
std::ostream & print_parameters(std::ostream &out, const OutputStyle style)
void print_parameters_section(std::ostream &out, const OutputStyle style, const unsigned int indent_level)
DeclException2(ExcInvalidRange, int, int,<< "The values "<< arg1<< " and "<< arg2<< " do not form a valid range.")
virtual bool match(const std::string &test_string) const
const std::string separator
const unsigned int max_elements
static Bool * create(const std::string &description)
std::size_t memory_consumption() const
const unsigned int min_elements
virtual bool match(const std::string &test_string) const
long int get_integer(const std::string &entry_string) const
virtual PatternBase * clone() const
static DirectoryName * create(const std::string &description)