parameter_handler.h

Go to the documentation of this file.

// ---------------------------------------------------------------------
//
// Copyright (C) 1998 - 2020 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE.md at
// the top level directory of deal.II.
//
// ---------------------------------------------------------------------

#ifndef dealii_parameter_handler_h
#define dealii_parameter_handler_h


#include <deal.II/base/config.h>

#include <deal.II/base/exceptions.h>
#include <deal.II/base/patterns.h>
#include <deal.II/base/subscriptor.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 <string>
#include <vector>

DEAL_II_NAMESPACE_OPEN

// forward declarations for interfaces and friendship
#ifndef DOXYGEN
class LogStream;
class MultipleParameterLoop;
#endif

class ParameterHandler : public Subscriptor
{
public:
  enum OutputStyle
  {
    DefaultStyle = 0x0000,

    Short = 0x0001,

    KeepDeclarationOrder = 0x0002,

    PRM = 0x0010,

    Text = PRM,

    LaTeX = 0x0020,

    Description = 0x0040,

    XML = 0x0080,

    JSON = 0x0100,

    ShortPRM = PRM | Short,

    ShortText = ShortPRM,

    ShortXML = XML | Short,

    ShortJSON = JSON | Short,

    ShortLaTeX = LaTeX | Short,
  };



  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
  add_action(const std::string &                                  entry,
             const std::function<void(const std::string &value)> &action);

  template <class 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);

  void
  leave_subsection();

  bool
  subsection_path_exists(const std::vector<std::string> &sub_path) 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 << ".");
  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 << ">." << (arg2.size() > 0 ? "\n" + arg2 : ""));

  DeclException3(ExcNoSubsection,
                 int,
                 std::string,
                 std::string,
                 << "Line <" << arg1 << "> of file <" << arg2
                 << ": There is "
                    "no such subsection to be entered: "
                 << arg3);

  DeclException3(ExcCannotParseLine,
                 int,
                 std::string,
                 std::string,
                 << "Line <" << arg1 << "> of file <" << arg2 << ">: " << arg3);

  DeclException5(ExcInvalidEntryForPattern,
                 int,
                 std::string,
                 std::string,
                 std::string,
                 std::string,
                 << "Line <" << arg1 << "> of file <" << arg2
                 << ">:\n"
                    "    The entry value \n"
                 << "        " << arg3 << '\n'
                 << "    for the entry named\n"
                 << "        " << arg4 << '\n'
                 << "    does not match the given pattern:\n"
                 << "        " << arg5);

  DeclExceptionMsg(ExcInvalidXMLParameterFile,
                   "The provided file could not be parsed as a "
                   "ParameterHandler description.");

  using ExcInvalidEntryForPatternXML DEAL_II_DEPRECATED =
    ExcValueDoesNotMatchPattern;

  DeclException3(
    ExcCannotOpenIncludeStatementFile,
    int,
    std::string,
    std::string,
    << "Line <" << arg1 << "> 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;

  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;

  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 Subscriptor &>(*this);

  ar &*entries.get();

  std::vector<std::string> descriptions;

  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<Subscriptor &>(*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 <class 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<ParameterType>::value == 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.clone()),
                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]->clone());
  };
  add_action(entry, action);
}

DEAL_II_NAMESPACE_CLOSE

#endif