PISM, A Parallel Ice Sheet Model  stable v2.0.4 committed by Constantine Khrulev on 2022-05-25 12:02:27 -0800
ConfigInterface.hh
Go to the documentation of this file.
1 /* Copyright (C) 2015, 2016, 2017, 2018, 2021 PISM Authors
2  *
3  * This file is part of PISM.
4  *
5  * PISM is free software; you can redistribute it and/or modify it under the
6  * terms of the GNU General Public License as published by the Free Software
7  * Foundation; either version 3 of the License, or (at your option) any later
8  * version.
9  *
10  * PISM is distributed in the hope that it will be useful, but WITHOUT ANY
11  * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
12  * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
13  * details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with PISM; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
18  */
19 
20 #ifndef _PISMCONFIGINTERFACE_H_
21 #define _PISMCONFIGINTERFACE_H_
22 
23 #include <memory>
24 #include <set>
25 #include <map>
26 #include <string>
27 #include <vector>
28 
29 #include <mpi.h>
30 
31 #include "Units.hh"
32 
33 namespace pism {
34 
35 class File;
36 class Logger;
37 
38 
39 //! Flag used by `set_...()` methods.
40 /** Meanings:
41  *
42  * - `DEFAULT`: set the default value; has no effect if a parameter was set by a user at the time
43  * of the call
44  * - `FORCE`: forcibly set a parameter; unconditionally overrides previous values
45  * - `USER`: forcibly set a parameter; unconditionally overrides previous values and marks this
46  * parameter as set by the user. This affects future `set_...()` calls using the `DEFAULT` flag
47  * value and results of `parameters_set_by_user()`.
48  */
50 
51 
52 //! A class for storing and accessing PISM configuration flags and parameters.
53 class Config {
54 public:
55  typedef std::shared_ptr<Config> Ptr;
56  typedef std::shared_ptr<const Config> ConstPtr;
57 
58  Config(units::System::Ptr unit_system);
59  virtual ~Config();
60 
61  //! Flag used by `get_...()` methods.
62  /** Meanings:
63  *
64  * - `REMEMBER_THIS_USE` (the default): add the name of a parameter to the list of parameters used
65  * by a model run.
66  * - `FORGET_THIS_USE`: don't add the name of a parameter to the list of used parameters. This is
67  * necessary to be able to get the current value of a parameter to be used as the default when
68  * processing a command-line option.
69  */
71 
72  // Import settings from an override file
73  void import_from(const Config &other);
74 
75  const std::set<std::string>& parameters_set_by_user() const;
76  const std::set<std::string>& parameters_used() const;
77 
78  void read(MPI_Comm com, const std::string &filename);
79  void write(MPI_Comm com, const std::string &filename, bool append = true) const;
80  std::string filename() const;
81 
82  void read(const File &file);
83  void write(const File &file) const;
84 
85  bool is_set(const std::string &name) const;
86 
87  // doubles
88  typedef std::map<std::string, std::vector<double> > Doubles;
89  Doubles all_doubles() const;
90 
91  double get_number(const std::string &name, UseFlag flag = REMEMBER_THIS_USE) const;
92  double get_number(const std::string &name, const std::string &units,
93  UseFlag flag = REMEMBER_THIS_USE) const;
94  std::vector<double> get_numbers(const std::string &name, UseFlag flag = REMEMBER_THIS_USE) const;
95  std::vector<double> get_numbers(const std::string &name, const std::string &units,
96  UseFlag flag = REMEMBER_THIS_USE) const;
97 
98  void set_number(const std::string &name, double value, ConfigSettingFlag flag = CONFIG_FORCE);
99  void set_numbers(const std::string &name, const std::vector<double> &values,
101 
102  // strings
103  typedef std::map<std::string, std::string> Strings;
104  Strings all_strings() const;
105 
106  std::string get_string(const std::string &name, UseFlag flag = REMEMBER_THIS_USE) const;
107  void set_string(const std::string &name, const std::string &value, ConfigSettingFlag flag = CONFIG_FORCE);
108 
109  // flags
110  typedef std::map<std::string, bool> Flags;
111  Flags all_flags() const;
112 
113  std::set<std::string> keys() const;
114 
115  bool get_flag(const std::string& name, UseFlag flag = REMEMBER_THIS_USE) const;
116  void set_flag(const std::string& name, bool value, ConfigSettingFlag flag = CONFIG_FORCE);
117 
118  std::string doc(const std::string &parameter) const;
119  std::string units(const std::string &parameter) const;
120  std::string type(const std::string &parameter) const;
121  std::string option(const std::string &parameter) const;
122  std::string choices(const std::string &parameter) const;
123  // Implementations
124 protected:
125  virtual void read_impl(const File &nc) = 0;
126  virtual void write_impl(const File &nc) const = 0;
127 
128  virtual bool is_set_impl(const std::string &name) const = 0;
129 
130  virtual Doubles all_doubles_impl() const = 0;
131  virtual double get_number_impl(const std::string &name) const = 0;
132  virtual std::vector<double> get_numbers_impl(const std::string &name) const = 0;
133 
134  virtual void set_number_impl(const std::string &name, double value) = 0;
135  virtual void set_numbers_impl(const std::string &name,
136  const std::vector<double> &values) = 0;
137 
138  virtual Strings all_strings_impl() const = 0;
139  virtual std::string get_string_impl(const std::string &name) const = 0;
140  virtual void set_string_impl(const std::string &name, const std::string &value) = 0;
141 
142  virtual Flags all_flags_impl() const = 0;
143 
144  virtual bool get_flag_impl(const std::string& name) const = 0;
145  virtual void set_flag_impl(const std::string& name, bool value) = 0;
146 private:
147  struct Impl;
149 };
150 
152 public:
153  ConfigWithPrefix(Config::ConstPtr c, const std::string &prefix);
154 
155  double get_number(const std::string &name) const;
156  double get_number(const std::string &name, const std::string &units) const;
157 
158  std::string get_string(const std::string &name) const;
159 
160  bool get_flag(const std::string& name) const;
161 
162  void reset_prefix(const std::string &prefix);
163 
164 private:
165  std::string m_prefix;
167 };
168 
169 Config::Ptr config_from_options(MPI_Comm com, const Logger &log, units::System::Ptr unit_system);
170 
171 //! Set configuration parameters using command-line options.
172 void set_config_from_options(units::System::Ptr unit_system, Config &config);
173 
174 //! Set one parameter using command-line options.
175 void set_parameter_from_options(units::System::Ptr unit_system, Config &config, const std::string &name);
176 
177 //! Set one flag parameter using command-line options.
178 void set_flag_from_option(Config &config,
179  const std::string &option,const std::string &parameter);
180 
181 //! Set one scalar parameter using command-line options.
182 void set_number_from_option(units::System::Ptr unit_system, Config &config,
183  const std::string &option, const std::string &parameter);
184 
185 //! Set one free-form string parameter using command-line options.
186 void set_string_from_option(Config &config,
187  const std::string &option, const std::string &parameter);
188 
189 //! Set one keyword parameter using command-line options.
190 void set_keyword_from_option(Config &config,
191  const std::string &option, const std::string &parameter,
192  const std::string &choices);
193 
194 //! Report configuration parameters to `stdout`.
195 void print_config(const Logger &log, int verbosity_threshhold, const Config &config);
196 
197 //! Report unused configuration parameters to `stdout`.
198 void print_unused_parameters(const Logger &log, int verbosity_threshhold,
199  const Config &config);
200 
201 } // end of namespace pism
202 
203 #endif /* _PISMCONFIGINTERFACE_H_ */
void reset_prefix(const std::string &prefix)
bool get_flag(const std::string &name) const
std::string get_string(const std::string &name) const
double get_number(const std::string &name) const
Config::ConstPtr m_config
ConfigWithPrefix(Config::ConstPtr c, const std::string &prefix)
virtual bool is_set_impl(const std::string &name) const =0
std::map< std::string, std::string > Strings
const std::set< std::string > & parameters_used() const
std::shared_ptr< Config > Ptr
bool is_set(const std::string &name) const
std::string choices(const std::string &parameter) const
virtual Strings all_strings_impl() const =0
std::set< std::string > keys() const
std::map< std::string, std::vector< double > > Doubles
void set_string(const std::string &name, const std::string &value, ConfigSettingFlag flag=CONFIG_FORCE)
double get_number(const std::string &name, UseFlag flag=REMEMBER_THIS_USE) const
virtual void set_numbers_impl(const std::string &name, const std::vector< double > &values)=0
Flags all_flags() const
std::vector< double > get_numbers(const std::string &name, UseFlag flag=REMEMBER_THIS_USE) const
virtual void read_impl(const File &nc)=0
std::shared_ptr< const Config > ConstPtr
virtual Flags all_flags_impl() const =0
const std::set< std::string > & parameters_set_by_user() const
virtual void set_flag_impl(const std::string &name, bool value)=0
void read(MPI_Comm com, const std::string &filename)
virtual void set_string_impl(const std::string &name, const std::string &value)=0
std::string units(const std::string &parameter) const
virtual std::vector< double > get_numbers_impl(const std::string &name) const =0
void import_from(const Config &other)
Config(units::System::Ptr unit_system)
void set_flag(const std::string &name, bool value, ConfigSettingFlag flag=CONFIG_FORCE)
virtual std::string get_string_impl(const std::string &name) const =0
std::map< std::string, bool > Flags
std::string get_string(const std::string &name, UseFlag flag=REMEMBER_THIS_USE) const
std::string type(const std::string &parameter) const
virtual ~Config()
virtual Doubles all_doubles_impl() const =0
virtual void set_number_impl(const std::string &name, double value)=0
void write(MPI_Comm com, const std::string &filename, bool append=true) const
bool get_flag(const std::string &name, UseFlag flag=REMEMBER_THIS_USE) const
void set_number(const std::string &name, double value, ConfigSettingFlag flag=CONFIG_FORCE)
std::string option(const std::string &parameter) const
std::string filename() const
Returns the name of the file used to initialize the database.
Strings all_strings() const
virtual void write_impl(const File &nc) const =0
void set_numbers(const std::string &name, const std::vector< double > &values, ConfigSettingFlag flag=CONFIG_FORCE)
Doubles all_doubles() const
std::string doc(const std::string &parameter) const
UseFlag
Flag used by get_...() methods.
virtual double get_number_impl(const std::string &name) const =0
virtual bool get_flag_impl(const std::string &name) const =0
A class for storing and accessing PISM configuration flags and parameters.
High-level PISM I/O class.
Definition: File.hh:51
A basic logging class.
Definition: Logger.hh:40
std::shared_ptr< System > Ptr
Definition: Units.hh:47
Config::Ptr config_from_options(MPI_Comm com, const Logger &log, units::System::Ptr unit_system)
Create a configuration database using command-line options.
void set_number_from_option(units::System::Ptr unit_system, Config &config, const std::string &name, const std::string &parameter)
Sets a configuration parameter from a command-line option.
void set_string_from_option(Config &config, const std::string &name, const std::string &parameter)
Set one free-form string parameter using command-line options.
void set_config_from_options(units::System::Ptr unit_system, Config &config)
Set configuration parameters using command-line options.
void set_flag_from_option(Config &config, const std::string &option, const std::string &parameter_name)
Get a flag from a command-line option.
ConfigSettingFlag
Flag used by set_...() methods.
@ CONFIG_DEFAULT
@ CONFIG_FORCE
void print_unused_parameters(const Logger &log, int verbosity_threshhold, const Config &config)
Report unused configuration parameters to stdout.
void set_parameter_from_options(units::System::Ptr unit_system, Config &config, const std::string &name)
Set one parameter using command-line options.
void set_keyword_from_option(Config &config, const std::string &name, const std::string &parameter, const std::string &choices)
Set a keyword parameter from a command-line option.
void print_config(const Logger &log, int verbosity_threshhold, const Config &config)
Report configuration parameters to stdout.