parameter_handler.h

Go to the documentation of this file.

// -----------------------------------------------------------------------------
//
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
// Copyright (C) 1998 - 2025 by the deal.II authors
//
// This file is part of the deal.II library.
//
// Detailed license information governing the source code and contributions
// can be found in LICENSE.md and CONTRIBUTING.md at the top level directory.
//
// -----------------------------------------------------------------------------
 
#ifndef dealii_parameter_handler_h
#define dealii_parameter_handler_h
 
 
#include <deal.II/base/config.h>
 
#include <deal.II/base/enable_observer_pointer.h>
#include <deal.II/base/exceptions.h>
#include <deal.II/base/patterns.h>
 
#include <boost/archive/basic_archive.hpp>
#include <boost/property_tree/ptree_fwd.hpp>
#include <boost/property_tree/ptree_serialization.hpp>
#include <boost/serialization/split_member.hpp>
 
#include <map>
#include <memory>
#include <set>
#include <string>
#include <vector>
 
DEAL_II_NAMESPACE_OPEN
 
// forward declarations for interfaces and friendship
#ifndef DOXYGEN
class LogStream;
class MultipleParameterLoop;
#endif
 
class ParameterHandler : public EnableObserverPointer
{
public:
  enum OutputStyle
  {
    DefaultStyle = 0x0000,
 
    Short = 0x0001,
 
    KeepDeclarationOrder = 0x0002,
 
    PRM = 0x0010,
 
    LaTeX = 0x0020,
 
    Description = 0x0040,
 
    XML = 0x0080,
 
    JSON = 0x0100,
 
    ShortPRM = PRM | Short,
 
    ShortXML = XML | Short,
 
    ShortJSON = JSON | Short,
 
    ShortLaTeX = LaTeX | Short,
 
    KeepOnlyChanged = 0x0200,
  };
 
 
 
  ParameterHandler();
 
  virtual ~ParameterHandler() override = default;
 
  ParameterHandler(const ParameterHandler &) = delete;
 
  ParameterHandler &
  operator=(const ParameterHandler &) = delete;
 
  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(const std::string &filename,
              const std::string &last_line                          = "",
              const bool         skip_undefined                     = false,
              const bool         assert_mandatory_entries_are_found = false);
 
  virtual void
  parse_input_from_string(const std::string &s,
                          const std::string &last_line      = "",
                          const bool         skip_undefined = false);
 
  virtual void
  parse_input_from_xml(std::istream &input, const bool skip_undefined = false);
 
  virtual void
  parse_input_from_json(std::istream &input, const bool skip_undefined = false);
 
  void
  clear();
 
 
  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);
 
  void
  mark_as_deprecated(const std::string &entry, const bool is_deprecated = true);
 
  void
  add_action(const std::string                                   &entry,
             const std::function<void(const std::string &value)> &action,
             const bool execute_action = true);
 
  template <typename ParameterType>
  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
  declare_alias(const std::string &existing_entry_name,
                const std::string &alias_name,
                const bool         alias_is_deprecated = false);
 
  void
  enter_subsection(const std::string &subsection,
                   const bool         create_path_if_needed = true);
 
  void
  leave_subsection();
 
  bool
  subsection_path_exists(const std::vector<std::string> &sub_path) const;
 
  std::string
  get_current_path() const;
 
  std::string
  get_current_full_path(const std::string &name) const;
 
  std::string
  get_current_full_path(const std::vector<std::string> &sub_path,
                        const std::string              &name) const;
 
  std::string
  get(const std::string &entry_string) const;
 
  std::string
  get(const std::vector<std::string> &entry_subsection_path,
      const std::string              &entry_string) const;
 
  long int
  get_integer(const std::string &entry_string) const;
 
  long int
  get_integer(const std::vector<std::string> &entry_subsection_path,
              const std::string              &entry_string) const;
 
  double
  get_double(const std::string &entry_name) const;
 
  double
  get_double(const std::vector<std::string> &entry_subsection_path,
             const std::string              &entry_string) const;
  bool
  get_bool(const std::string &entry_name) const;
 
  bool
  get_bool(const std::vector<std::string> &entry_subsection_path,
           const std::string              &entry_string) const;
 
  void
  set(const std::string &entry_name, const std::string &new_value);
 
  void
  set(const std::string &entry_name, const char *new_value);
 
  void
  set(const std::string &entry_name, const long int new_value);
 
  void
  set(const std::string &entry_name, const double new_value);
 
  void
  set(const std::string &entry_name, const bool new_value);
 
  std::ostream &
  print_parameters(std::ostream &out, const OutputStyle style) const;
 
 
 
  void
  print_parameters(const std::string &filename,
                   const OutputStyle  style = DefaultStyle) const;
 
  void
  log_parameters(LogStream &out, const OutputStyle style = DefaultStyle);
 
  void
  log_parameters_section(LogStream        &out,
                         const OutputStyle style = DefaultStyle);
 
  std::size_t
  memory_consumption() const;
 
  template <class Archive>
  void
  save(Archive &ar, const unsigned int version) const;
 
  template <class Archive>
  void
  load(Archive &ar, const unsigned int version);
 
#ifdef DOXYGEN
  template <class Archive>
  void
  serialize(Archive &archive, const unsigned int version);
#else
  // This macro defines the serialize() method that is compatible with
  // the templated save() and load() method that have been implemented.
  BOOST_SERIALIZATION_SPLIT_MEMBER()
#endif
 
  bool
  operator==(const ParameterHandler &prm2) const;
 
  std::set<std::string>
  get_entries_wrongly_not_set() const;
 
  void
  assert_that_entries_have_been_set() const;
 
  DeclException1(ExcEntryAlreadyExists,
                 std::string,
                 << "The following entry already exists: " << arg1 << '.');
 
  DeclException3(ExcEntryIsDeprecated,
                 int,
                 std::string,
                 std::string,
                 << "Line <" << arg1 << "> of file <" << arg2 << ">: "
                 << "Entry <" << arg3 << "> is deprecated.");
 
  DeclException1(ExcEncounteredDeprecatedEntries,
                 std::string,
                 << "The following deprecated entries were encountered:\n\n"
                 << arg1);
 
  DeclException2(ExcValueDoesNotMatchPattern,
                 std::string,
                 std::string,
                 << "The string <" << arg1
                 << "> does not match the given pattern <" << arg2 << ">.");
  DeclExceptionMsg(
    ExcAlreadyAtTopLevel,
    "You can't leave a subsection if you are already at the top level "
    "of the subsection hierarchy.");
 
  DeclException1(ExcEntryUndeclared,
                 std::string,
                 << "You can't ask for entry <" << arg1
                 << "> you have not yet declared.");
 
  DeclException2(ExcUnbalancedSubsections,
                 std::string,
                 std::string,
                 << "There are unequal numbers of 'subsection' and 'end' "
                    "statements in the parameter file"
                 << (arg1.empty() ? "" : (" <" + arg1 + ">")) << "."
                 << (arg2.empty() ? "" : ("\n" + arg2)));
 
  DeclException3(ExcNoSubsection,
                 int,
                 std::string,
                 std::string,
                 << "Line <" << arg1 << ">"
                 << (arg2.empty() ? "" : (" of file <" + arg2 + ">"))
                 << ": You are trying to enter a subsection '" << arg3
                 << "', but the ParameterHandler object does "
                 << "not know of any such subsection.");
 
  DeclException3(ExcCannotParseLine,
                 int,
                 std::string,
                 std::string,
                 << "Line <" << arg1 << ">"
                 << (arg2.empty() ? "" : (" of file <" + arg2 + ">")) << ": "
                 << arg3);
 
  DeclException5(
    ExcInvalidEntryForPattern,
    int,
    std::string,
    std::string,
    std::string,
    std::string,
    << "In line <" << arg1 << ">"
    << (arg2.empty() ? "" : (" of file <" + arg2 + ">")) << ": The value <"
    << arg3 << "> for the parameter entry named <" << arg4
    << "> does not match the pattern expected for this parameter.\n"
       "The expected pattern for this parameter is:\n"
    << arg5);
 
  DeclExceptionMsg(ExcInvalidXMLParameterFile,
                   "The provided file could not be parsed as a "
                   "ParameterHandler description.");
 
  DeclException3(
    ExcCannotOpenIncludeStatementFile,
    int,
    std::string,
    std::string,
    << "Line <" << arg1 << ">"
    << (arg2.empty() ? "" : (" of file <" + arg2 + ">"))
    << ": This line "
       "contains an 'include' or 'INCLUDE' statement, but the given "
       "file to include <"
    << arg3 << "> cannot be opened.");
 
private:
  static const char path_separator = '.';
 
  std::vector<std::string> subsection_path;
 
  std::unique_ptr<boost::property_tree::ptree> entries;
 
  std::map<std::string, std::pair<bool, bool>> entries_set_status;
 
  std::vector<std::unique_ptr<const Patterns::PatternBase>> patterns;
 
  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,
            const bool         skip_undefined);
 
  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;
 
  friend class MultipleParameterLoop;
};
 
inline ParameterHandler::OutputStyle
operator|(const ParameterHandler::OutputStyle f1,
          const ParameterHandler::OutputStyle f2)
{
  return static_cast<ParameterHandler::OutputStyle>(
    static_cast<unsigned int>(f1) | static_cast<unsigned int>(f2));
}
 
class MultipleParameterLoop : public ParameterHandler
{
public:
  class UserClass
  {
  public:
    virtual ~UserClass() = default;
 
    virtual void
    create_new(const unsigned int run_no) = 0;
 
    virtual void
    run(ParameterHandler &prm) = 0;
  };
 
  MultipleParameterLoop();
 
  virtual ~MultipleParameterLoop() override = default;
 
  virtual void
  parse_input(std::istream      &input,
              const std::string &filename       = "input file",
              const std::string &last_line      = "",
              const bool         skip_undefined = false) override;
 
  using ParameterHandler::parse_input;
 
  void
  loop(UserClass &uc);
 
  std::size_t
  memory_consumption() const;
 
private:
  class Entry
  {
  public:
    enum MultipleEntryType
    {
      variant,
      array
    };
 
    Entry()
      : type(array)
    {}
 
    Entry(const std::vector<std::string> &Path,
          const std::string              &Name,
          const std::string              &Value);
 
    void
    split_different_values();
 
    std::vector<std::string> subsection_path;
 
    std::string entry_name;
 
    std::string entry_value;
 
    std::vector<std::string> different_values;
 
    MultipleEntryType type;
 
    std::size_t
    memory_consumption() const;
  };
 
  std::vector<Entry> multiple_choices;
 
  unsigned int n_branches;
 
  void
  init_branches();
 
  void
  init_branches_current_section();
 
  void
  fill_entry_values(const unsigned int run_no);
};
 
 
// ---------------------- inline and template functions --------------------
template <class Archive>
inline void
ParameterHandler::save(Archive &ar, const unsigned int) const
{
  // Forward to serialization
  // function in the base class.
  ar &static_cast<const EnableObserverPointer &>(*this);
 
  ar &*entries.get();
 
  std::vector<std::string> descriptions;
 
  descriptions.reserve(patterns.size());
  for (const auto &pattern : patterns)
    descriptions.push_back(pattern->description());
 
  ar &descriptions;
}
 
 
template <class Archive>
inline void
ParameterHandler::load(Archive &ar, const unsigned int)
{
  // Forward to serialization
  // function in the base class.
  ar &static_cast<EnableObserverPointer &>(*this);
 
  ar &*entries.get();
 
  std::vector<std::string> descriptions;
  ar                      &descriptions;
 
  patterns.clear();
  for (const auto &description : descriptions)
    patterns.push_back(Patterns::pattern_factory(description));
}
 
 
template <typename ParameterType>
void
ParameterHandler::add_parameter(const std::string           &entry,
                                ParameterType               &parameter,
                                const std::string           &documentation,
                                const Patterns::PatternBase &pattern,
                                const bool                   has_to_be_set)
{
  static_assert(std::is_const_v<ParameterType> == false,
                "You tried to add a parameter using a type "
                "that is const. Use a non-const type.");
 
  declare_entry(entry,
                Patterns::Tools::Convert<ParameterType>::to_string(parameter,
                                                                   pattern),
                pattern,
                documentation,
                has_to_be_set);
 
  std::string        path = get_current_full_path(entry);
  const unsigned int pattern_index =
    entries->get<unsigned int>(path + path_separator + "pattern");
 
  auto action = [&, pattern_index](const std::string &val) {
    parameter = Patterns::Tools::Convert<ParameterType>::to_value(
      val, *patterns[pattern_index]);
  };
  add_action(entry, action, false);
}
 
DEAL_II_NAMESPACE_CLOSE
 
#endif