Reference documentation for deal.II version GIT relicensing-1062-gc06da148b8 2024-07-15 19:20:02+00:00
\(\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\}}\)
Loading...
Searching...
No Matches
parameter_handler.h
Go to the documentation of this file.
1// ------------------------------------------------------------------------
2//
3// SPDX-License-Identifier: LGPL-2.1-or-later
4// Copyright (C) 1998 - 2024 by the deal.II authors
5//
6// This file is part of the deal.II library.
7//
8// Part of the source code is dual licensed under Apache-2.0 WITH
9// LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10// governing the source code and code contributions can be found in
11// LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12//
13// ------------------------------------------------------------------------
14
15#ifndef dealii_parameter_handler_h
16#define dealii_parameter_handler_h
17
18
19#include <deal.II/base/config.h>
20
24
25#include <boost/archive/basic_archive.hpp>
26#include <boost/property_tree/ptree_fwd.hpp>
27#include <boost/property_tree/ptree_serialization.hpp>
28#include <boost/serialization/split_member.hpp>
29
30#include <map>
31#include <memory>
32#include <string>
33#include <vector>
34
36
37// forward declarations for interfaces and friendship
38#ifndef DOXYGEN
39class LogStream;
41#endif
42
855{
856public:
873 {
878 DefaultStyle = 0x0000,
879
884 Short = 0x0001,
885
890
895 PRM = 0x0010,
896
904
908 LaTeX = 0x0020,
909
915 Description = 0x0040,
916
924 XML = 0x0080,
925
931 JSON = 0x0100,
932
938
946
952
958
964 };
965
966
967
972
978 virtual ~ParameterHandler() override = default;
979
984
989 operator=(const ParameterHandler &) = delete;
990
1025 virtual void
1026 parse_input(std::istream &input,
1027 const std::string &filename = "input file",
1028 const std::string &last_line = "",
1029 const bool skip_undefined = false);
1030
1052 virtual void
1053 parse_input(const std::string &filename,
1054 const std::string &last_line = "",
1055 const bool skip_undefined = false,
1056 const bool assert_mandatory_entries_are_found = false);
1057
1066 virtual void
1067 parse_input_from_string(const std::string &s,
1068 const std::string &last_line = "",
1069 const bool skip_undefined = false);
1070
1078 virtual void
1079 parse_input_from_xml(std::istream &input, const bool skip_undefined = false);
1080
1088 virtual void
1089 parse_input_from_json(std::istream &input, const bool skip_undefined = false);
1090
1094 void
1095 clear();
1096
1097
1123 void
1124 declare_entry(const std::string &entry,
1125 const std::string &default_value,
1126 const Patterns::PatternBase &pattern = Patterns::Anything(),
1127 const std::string &documentation = "",
1128 const bool has_to_be_set = false);
1129
1177 void
1178 add_action(const std::string &entry,
1179 const std::function<void(const std::string &value)> &action,
1180 const bool execute_action = true);
1181
1197 template <typename ParameterType>
1198 void
1199 add_parameter(const std::string &entry,
1200 ParameterType &parameter,
1201 const std::string &documentation = "",
1202 const Patterns::PatternBase &pattern =
1204 const bool has_to_be_set = false);
1205
1249 void
1250 declare_alias(const std::string &existing_entry_name,
1251 const std::string &alias_name,
1252 const bool alias_is_deprecated = false);
1253
1257 void
1258 enter_subsection(const std::string &subsection,
1259 const bool create_path_if_needed = true);
1260
1264 void
1266
1272 bool
1273 subsection_path_exists(const std::vector<std::string> &sub_path) const;
1274
1284 std::string
1285 get_current_path() const;
1286
1292 std::string
1293 get_current_full_path(const std::string &name) const;
1294
1300 std::string
1301 get_current_full_path(const std::vector<std::string> &sub_path,
1302 const std::string &name) const;
1303
1309 std::string
1310 get(const std::string &entry_string) const;
1311
1322 std::string
1323 get(const std::vector<std::string> &entry_subsection_path,
1324 const std::string &entry_string) const;
1325
1331 long int
1332 get_integer(const std::string &entry_string) const;
1333
1342 long int
1343 get_integer(const std::vector<std::string> &entry_subsection_path,
1344 const std::string &entry_string) const;
1345
1349 double
1350 get_double(const std::string &entry_name) const;
1351
1358 double
1359 get_double(const std::vector<std::string> &entry_subsection_path,
1360 const std::string &entry_string) const;
1366 bool
1367 get_bool(const std::string &entry_name) const;
1368
1377 bool
1378 get_bool(const std::vector<std::string> &entry_subsection_path,
1379 const std::string &entry_string) const;
1380
1390 void
1391 set(const std::string &entry_name, const std::string &new_value);
1392
1403 void
1404 set(const std::string &entry_name, const char *new_value);
1405
1415 void
1416 set(const std::string &entry_name, const long int new_value);
1417
1431 void
1432 set(const std::string &entry_name, const double new_value);
1433
1443 void
1444 set(const std::string &entry_name, const bool new_value);
1445
1518 std::ostream &
1519 print_parameters(std::ostream &out, const OutputStyle style) const;
1520
1521
1522
1543 void
1544 print_parameters(const std::string &filename,
1545 const OutputStyle style = DefaultStyle) const;
1546
1561 void
1562 log_parameters(LogStream &out, const OutputStyle style = DefaultStyle);
1563
1582 void
1584 const OutputStyle style = DefaultStyle);
1585
1590 std::size_t
1591 memory_consumption() const;
1592
1598 template <class Archive>
1599 void
1600 save(Archive &ar, const unsigned int version) const;
1601
1607 template <class Archive>
1608 void
1609 load(Archive &ar, const unsigned int version);
1610
1611#ifdef DOXYGEN
1617 template <class Archive>
1618 void
1619 serialize(Archive &archive, const unsigned int version);
1620#else
1621 // This macro defines the serialize() method that is compatible with
1622 // the templated save() and load() method that have been implemented.
1623 BOOST_SERIALIZATION_SPLIT_MEMBER()
1624#endif
1625
1629 bool
1630 operator==(const ParameterHandler &prm2) const;
1631
1640 std::set<std::string>
1642
1648 void
1650
1660 std::string,
1661 << "The following entry already exists: " << arg1 << '.');
1666 std::string,
1667 std::string,
1668 << "The string <" << arg1
1669 << "> does not match the given pattern <" << arg2 << ">.");
1675 "You can't leave a subsection if you are already at the top level "
1676 "of the subsection hierarchy.");
1681 std::string,
1682 << "You can't ask for entry <" << arg1
1683 << "> you have not yet declared.");
1684
1692 std::string,
1693 std::string,
1694 << "There are unequal numbers of 'subsection' and 'end' "
1695 "statements in the parameter file <"
1696 << arg1 << ">." << (arg2.size() > 0 ? "\n" + arg2 : ""));
1697
1703 int,
1704 std::string,
1705 std::string,
1706 << "Line <" << arg1 << "> of file <" << arg2
1707 << ">: You are trying to enter a subsection '" << arg3
1708 << "', but the ParameterHandler object does "
1709 << "not know of any such subsection.");
1710
1717 int,
1718 std::string,
1719 std::string,
1720 << "Line <" << arg1 << "> of file <" << arg2 << ">: " << arg3);
1721
1728 int,
1729 std::string,
1730 std::string,
1731 std::string,
1732 std::string,
1733 << "Line <" << arg1 << "> of file <" << arg2
1734 << ">:\n"
1735 " The entry value \n"
1736 << " " << arg3 << '\n'
1737 << " for the entry named\n"
1738 << " " << arg4 << '\n'
1739 << " does not match the given pattern:\n"
1740 << " " << arg5);
1741
1748 "The provided file could not be parsed as a "
1749 "ParameterHandler description.");
1750
1759 int,
1760 std::string,
1761 std::string,
1762 << "Line <" << arg1 << "> of file <" << arg2
1763 << ">: This line "
1764 "contains an 'include' or 'INCLUDE' statement, but the given "
1765 "file to include <"
1766 << arg3 << "> cannot be opened.");
1767
1770private:
1775 static const char path_separator = '.';
1776
1780 std::vector<std::string> subsection_path;
1781
1790 std::unique_ptr<boost::property_tree::ptree> entries;
1791
1800 std::map<std::string, std::pair<bool, bool>> entries_set_status;
1801
1807 std::vector<std::unique_ptr<const Patterns::PatternBase>> patterns;
1808
1815 std::vector<std::function<void(const std::string &)>> actions;
1816
1835 void
1836 scan_line(std::string line,
1837 const std::string &input_filename,
1838 const unsigned int current_line_n,
1839 const bool skip_undefined);
1840
1852 void
1854 const boost::property_tree::ptree &tree,
1855 const std::vector<std::string> &target_subsection_path,
1857 const unsigned int indent_level,
1858 std::ostream &out) const;
1859
1861};
1862
1873{
1874 return static_cast<ParameterHandler::OutputStyle>(
1875 static_cast<unsigned int>(f1) | static_cast<unsigned int>(f2));
1876}
1877
2094{
2095public:
2101 {
2102 public:
2107 virtual ~UserClass() = default;
2108
2113 virtual void
2114 create_new(const unsigned int run_no) = 0;
2115
2119 virtual void
2121 };
2122
2127
2132 virtual ~MultipleParameterLoop() override = default;
2133
2155 virtual void
2156 parse_input(std::istream &input,
2157 const std::string &filename = "input file",
2158 const std::string &last_line = "",
2159 const bool skip_undefined = false) override;
2160
2169
2173 void
2174 loop(UserClass &uc);
2175
2180 std::size_t
2181 memory_consumption() const;
2182
2183private:
2187 class Entry
2188 {
2189 public:
2206
2211 : type(array)
2212 {}
2213
2219 Entry(const std::vector<std::string> &Path,
2220 const std::string &Name,
2221 const std::string &Value);
2222
2226 void
2228
2232 std::vector<std::string> subsection_path;
2233
2237 std::string entry_name;
2238
2242 std::string entry_value;
2243
2248 std::vector<std::string> different_values;
2249
2254
2259 std::size_t
2260 memory_consumption() const;
2261 };
2262
2266 std::vector<Entry> multiple_choices;
2267
2272 unsigned int n_branches;
2273
2277 void
2278 init_branches();
2279
2286 void
2288
2292 void
2293 fill_entry_values(const unsigned int run_no);
2294};
2295
2296
2297// ---------------------- inline and template functions --------------------
2298template <class Archive>
2299inline void
2300ParameterHandler::save(Archive &ar, const unsigned int) const
2301{
2302 // Forward to serialization
2303 // function in the base class.
2304 ar &static_cast<const Subscriptor &>(*this);
2305
2306 ar &*entries.get();
2307
2308 std::vector<std::string> descriptions;
2309
2310 descriptions.reserve(patterns.size());
2311 for (const auto &pattern : patterns)
2312 descriptions.push_back(pattern->description());
2313
2314 ar &descriptions;
2315}
2316
2317
2318template <class Archive>
2319inline void
2320ParameterHandler::load(Archive &ar, const unsigned int)
2321{
2322 // Forward to serialization
2323 // function in the base class.
2324 ar &static_cast<Subscriptor &>(*this);
2325
2326 ar &*entries.get();
2327
2328 std::vector<std::string> descriptions;
2329 ar &descriptions;
2330
2331 patterns.clear();
2332 for (const auto &description : descriptions)
2333 patterns.push_back(Patterns::pattern_factory(description));
2334}
2335
2336
2337template <typename ParameterType>
2338void
2339ParameterHandler::add_parameter(const std::string &entry,
2340 ParameterType &parameter,
2341 const std::string &documentation,
2342 const Patterns::PatternBase &pattern,
2343 const bool has_to_be_set)
2344{
2345 static_assert(std::is_const_v<ParameterType> == false,
2346 "You tried to add a parameter using a type "
2347 "that is const. Use a non-const type.");
2348
2349 declare_entry(entry,
2351 pattern),
2352 pattern,
2353 documentation,
2354 has_to_be_set);
2355
2356 std::string path = get_current_full_path(entry);
2357 const unsigned int pattern_index =
2358 entries->get<unsigned int>(path + path_separator + "pattern");
2359
2360 auto action = [&, pattern_index](const std::string &val) {
2362 val, *patterns[pattern_index]);
2363 };
2364 add_action(entry, action, false);
2365}
2366
2368
2369#endif
std::vector< std::string > subsection_path
std::vector< std::string > different_values
std::size_t memory_consumption() const
virtual void create_new(const unsigned int run_no)=0
virtual void run(ParameterHandler &prm)=0
void fill_entry_values(const unsigned int run_no)
virtual void parse_input(std::istream &input, const std::string &filename="input file", const std::string &last_line="", const bool skip_undefined=false) override
std::size_t memory_consumption() const
virtual ~MultipleParameterLoop() override=default
void loop(UserClass &uc)
std::vector< Entry > multiple_choices
static const char path_separator
std::size_t memory_consumption() const
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 load(Archive &ar, const unsigned int version)
virtual void parse_input(std::istream &input, const std::string &filename="input file", const std::string &last_line="", const bool skip_undefined=false)
virtual void parse_input_from_xml(std::istream &input, const bool skip_undefined=false)
std::string get_current_path() const
ParameterHandler(const ParameterHandler &)=delete
std::vector< std::unique_ptr< const Patterns::PatternBase > > patterns
void enter_subsection(const std::string &subsection, const bool create_path_if_needed=true)
std::ostream & print_parameters(std::ostream &out, const OutputStyle style) const
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
void add_action(const std::string &entry, const std::function< void(const std::string &value)> &action, const bool execute_action=true)
void save(Archive &ar, const unsigned int version) const
long int get_integer(const std::string &entry_string) const
bool get_bool(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)
virtual void parse_input_from_string(const std::string &s, const std::string &last_line="", const bool skip_undefined=false)
std::string get(const std::string &entry_string) const
std::set< std::string > get_entries_wrongly_not_set() const
void set(const std::string &entry_name, const std::string &new_value)
void log_parameters(LogStream &out, const OutputStyle style=DefaultStyle)
void serialize(Archive &archive, const unsigned int version)
std::map< std::string, std::pair< bool, bool > > entries_set_status
std::string get_current_full_path(const std::string &name) const
ParameterHandler & operator=(const ParameterHandler &)=delete
std::vector< std::function< void(const std::string &)> > actions
void log_parameters_section(LogStream &out, const OutputStyle style=DefaultStyle)
std::unique_ptr< boost::property_tree::ptree > entries
bool subsection_path_exists(const std::vector< std::string > &sub_path) const
virtual ~ParameterHandler() override=default
void scan_line(std::string line, const std::string &input_filename, const unsigned int current_line_n, const bool skip_undefined)
double get_double(const std::string &entry_name) const
void declare_alias(const std::string &existing_entry_name, const std::string &alias_name, const bool alias_is_deprecated=false)
bool operator==(const ParameterHandler &prm2) const
std::vector< std::string > subsection_path
void assert_that_entries_have_been_set() const
virtual void parse_input_from_json(std::istream &input, const bool skip_undefined=false)
#define DEAL_II_NAMESPACE_OPEN
Definition config.h:502
#define DEAL_II_NAMESPACE_CLOSE
Definition config.h:503
static ::ExceptionBase & ExcNoSubsection(int arg1, std::string arg2, std::string arg3)
static ::ExceptionBase & ExcCannotOpenIncludeStatementFile(int arg1, std::string arg2, std::string arg3)
static ::ExceptionBase & ExcEntryAlreadyExists(std::string arg1)
static ::ExceptionBase & ExcAlreadyAtTopLevel()
#define DeclException2(Exception2, type1, type2, outsequence)
Definition exceptions.h:539
static ::ExceptionBase & ExcInvalidEntryForPattern(int arg1, std::string arg2, std::string arg3, std::string arg4, std::string arg5)
static ::ExceptionBase & ExcEntryUndeclared(std::string arg1)
#define DeclExceptionMsg(Exception, defaulttext)
Definition exceptions.h:494
static ::ExceptionBase & ExcValueDoesNotMatchPattern(std::string arg1, std::string arg2)
static ::ExceptionBase & ExcUnbalancedSubsections(std::string arg1, std::string arg2)
#define DeclException3(Exception3, type1, type2, type3, outsequence)
Definition exceptions.h:562
#define DeclException1(Exception1, type1, outsequence)
Definition exceptions.h:516
static ::ExceptionBase & ExcCannotParseLine(int arg1, std::string arg2, std::string arg3)
static ::ExceptionBase & ExcInvalidXMLParameterFile()
#define DeclException5( Exception5, type1, type2, type3, type4, type5, outsequence)
Definition exceptions.h:611
std::unique_ptr< PatternBase > pattern_factory(const std::string &description)
Definition patterns.cc:137
ParameterHandler::OutputStyle operator|(const ParameterHandler::OutputStyle f1, const ParameterHandler::OutputStyle f2)
static T to_value(const std::string &s, const Patterns::PatternBase &p= *Convert< T >::to_pattern())=delete