PISM, A Parallel Ice Sheet Model  stable v2.0.4 committed by Constantine Khrulev on 2022-05-25 12:02:27 -0800
Component.hh
Go to the documentation of this file.
1 // Copyright (C) 2008-2018, 2020, 2021 Ed Bueler and Constantine Khroulev
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 #ifndef __Component_hh
20 #define __Component_hh
21 
22 #include <string>
23 #include <set>
24 #include <map>
25 
26 #include "pism/util/io/IO_Flags.hh"
27 #include "pism/util/ConfigInterface.hh"
28 #include "pism/util/Units.hh"
29 #include "pism/util/Logger.hh"
30 #include "pism/util/IceGrid.hh"
31 #include "pism/util/Diagnostic.hh"
32 
33 namespace pism {
34 
35 class MaxTimestep;
36 class File;
37 class IceModelVec;
38 
40 
41 struct InputOptions {
42  InputOptions(InitializationType t, const std::string &file, unsigned int index);
43  //! initialization type
45  //! name of the input file (if applicable)
46  std::string filename;
47  //! index of the record to re-start from
48  unsigned int record;
49 };
50 
52 
53 //! \brief A class defining a common interface for most PISM sub-models.
54 /*!
55  \section pism_components PISM's model components and their interface
56 
57  We've found that many sub-models in PISM share some tasks: they need to be
58  "initialized", "updated", asked for diagnostic quantities, asked to write the
59  model state...
60 
61  Component and its derived classes were created to have a common interface
62  for PISM sub-models, such as surface, atmosphere, ocean and bed deformation
63  models.
64 
65  \subsection pismcomponent_init Initialization
66 
67  Component::init() should contain all the initialization code,
68  excluding memory-allocation. (We might need to "re-initialize" a
69  component.)
70 
71  Many PISM sub-models read data from the same file the rest of PISM reads
72  from. Component::find_pism_input() checks options `-i` and `-bootstrap`
73  options to simplify finding this file.
74 
75  \subsection pismcomponent_output Writing to an output file
76 
77  A PISM component needs to implement the following I/O methods:
78 
79  - define_model_state_impl()
80  - write_model_state_impl()
81 
82  Why are all these methods needed? In PISM we separate defining and writing
83  NetCDF variables because defining all the NetCDF variables before writing
84  data is a lot faster than defining a variable, writing it, defining the
85  second variable, etc. (See http://www.unidata.ucar.edu/software/netcdf/docs/netcdf/Parts-of-a-NetCDF-Classic-File.html#Parts-of-a-NetCDF-Classic-File for a technical explanation.)
86 
87  Within IceModel the following steps are done to write 2D and 3D fields to an
88  output file:
89 
90  - Assemble the list of variables to be written (see
91  IceModel::output_variables()); calls add_vars_to_output()
92  - Create a NetCDF file
93  - Define all the variables in the file (see IceModel::write_variables());
94  calls define_variables()
95  - Write all the variables to the file (same method); calls write_variables().
96 
97  \subsection pismcomponent_timestep Restricting time-steps
98 
99  Implement Component::max_timestep() to affect PISM's adaptive time-stepping mechanism.
100 */
101 class Component {
102 public:
103 
104  /** Create a Component instance given a grid. */
106  virtual ~Component() = default;
107 
108  DiagnosticList diagnostics() const;
110 
111  IceGrid::ConstPtr grid() const;
112 
113  void define_model_state(const File &output) const;
114  void write_model_state(const File &output) const;
115 
116  //! Reports the maximum time-step the model can take at time t.
117  MaxTimestep max_timestep(double t) const;
118 
119 protected:
120  virtual MaxTimestep max_timestep_impl(double t) const;
121  virtual void define_model_state_impl(const File &output) const;
122  virtual void write_model_state_impl(const File &output) const;
123 
124  virtual DiagnosticList diagnostics_impl() const;
125  virtual TSDiagnosticList ts_diagnostics_impl() const;
126 
127  /** @brief This flag determines whether a variable is read from the
128  `-regrid_file` file even if it is not listed among variables in
129  `-regrid_vars`.
130  */
132  virtual void regrid(const std::string &module_name, IceModelVec &variable,
134 protected:
135  //! grid used by this component
137  //! configuration database used by this component
139  //! unit system used by this component
141  //! logger (for easy access)
143 };
144 
145 } // end of namespace pism
146 
147 #endif // __Component_hh
IceGrid::ConstPtr grid() const
Definition: Component.cc:105
const units::System::Ptr m_sys
unit system used by this component
Definition: Component.hh:140
const Config::ConstPtr m_config
configuration database used by this component
Definition: Component.hh:138
const Logger::ConstPtr m_log
logger (for easy access)
Definition: Component.hh:142
Component(IceGrid::ConstPtr g)
Definition: Component.cc:83
virtual TSDiagnosticList ts_diagnostics_impl() const
Definition: Component.cc:101
RegriddingFlag
This flag determines whether a variable is read from the -regrid_file file even if it is not listed a...
Definition: Component.hh:131
@ REGRID_WITHOUT_REGRID_VARS
Definition: Component.hh:131
@ NO_REGRID_WITHOUT_REGRID_VARS
Definition: Component.hh:131
TSDiagnosticList ts_diagnostics() const
Definition: Component.cc:93
virtual void write_model_state_impl(const File &output) const
The default (empty implementation).
Definition: Component.cc:132
virtual ~Component()=default
virtual void define_model_state_impl(const File &output) const
The default (empty implementation).
Definition: Component.cc:127
virtual void regrid(const std::string &module_name, IceModelVec &variable, RegriddingFlag flag=NO_REGRID_WITHOUT_REGRID_VARS)
Definition: Component.cc:151
virtual DiagnosticList diagnostics_impl() const
Definition: Component.cc:97
void define_model_state(const File &output) const
Define model state variables in an output file.
Definition: Component.cc:114
void write_model_state(const File &output) const
Write model state variables to an output file.
Definition: Component.cc:119
const IceGrid::ConstPtr m_grid
grid used by this component
Definition: Component.hh:136
DiagnosticList diagnostics() const
Definition: Component.cc:89
virtual MaxTimestep max_timestep_impl(double t) const
Definition: Component.cc:179
MaxTimestep max_timestep(double t) const
Reports the maximum time-step the model can take at time t.
Definition: Component.cc:175
A class defining a common interface for most PISM sub-models.
Definition: Component.hh:101
std::shared_ptr< const Config > ConstPtr
High-level PISM I/O class.
Definition: File.hh:51
std::shared_ptr< const IceGrid > ConstPtr
Definition: IceGrid.hh:233
Abstract class for reading, writing, allocating, and accessing a DA-based PETSc Vec (2D and 3D fields...
Definition: iceModelVec.hh:202
std::shared_ptr< const Logger > ConstPtr
Definition: Logger.hh:46
Combines the max. time step with the flag indicating if a restriction is active. Makes is possible to...
Definition: MaxTimestep.hh:31
std::shared_ptr< System > Ptr
Definition: Units.hh:47
InputOptions process_input_options(MPI_Comm com, Config::ConstPtr config)
Definition: Component.cc:45
static const double g
Definition: exactTestP.cc:39
InitializationType
Definition: Component.hh:39
@ INIT_BOOTSTRAP
Definition: Component.hh:39
@ INIT_OTHER
Definition: Component.hh:39
@ INIT_RESTART
Definition: Component.hh:39
std::map< std::string, TSDiagnostic::Ptr > TSDiagnosticList
Definition: Diagnostic.hh:346
std::map< std::string, Diagnostic::Ptr > DiagnosticList
Definition: Diagnostic.hh:117
RegriddingFlag
Definition: IO_Flags.hh:70
InitializationType type
initialization type
Definition: Component.hh:44
std::string filename
name of the input file (if applicable)
Definition: Component.hh:46
InputOptions(InitializationType t, const std::string &file, unsigned int index)
Definition: Component.cc:36
unsigned int record
index of the record to re-start from
Definition: Component.hh:48