tComponent.hh - pism - [fork] customized build of PISM, the parallel ice sheet model (tillflux branch)
(HTM) git clone git://src.adamsgaard.dk/pism
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) LICENSE
---
tComponent.hh (5232B)
---
1 // Copyright (C) 2008-2018 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
39 enum InitializationType {INIT_RESTART, INIT_BOOTSTRAP, INIT_OTHER};
40
41 struct InputOptions {
42 InputOptions(InitializationType t, const std::string &file, unsigned int index);
43 //! initialization type
44 InitializationType 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
51 InputOptions process_input_options(MPI_Comm com, Config::ConstPtr config);
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 <a
86 href="http://www.unidata.ucar.edu/software/netcdf/docs/netcdf/Parts-of-a-NetCDF-Classic-File.html#Parts-of-a-NetCDF-Classic-File">The
87 NetCDF Users' Guide</a> for a technical explanation.)
88
89 Within IceModel the following steps are done to write 2D and 3D fields to an
90 output file:
91
92 - Assemble the list of variables to be written (see
93 IceModel::output_variables()); calls add_vars_to_output()
94 - Create a NetCDF file
95 - Define all the variables in the file (see IceModel::write_variables());
96 calls define_variables()
97 - Write all the variables to the file (same method); calls write_variables().
98
99 \subsection pismcomponent_timestep Restricting time-steps
100
101 Implement Component::max_timestep() to affect PISM's adaptive time-stepping mechanism.
102 */
103 class Component {
104 public:
105
106 /** Create a Component instance given a grid. */
107 Component(IceGrid::ConstPtr g);
108 virtual ~Component();
109
110 DiagnosticList diagnostics() const;
111 TSDiagnosticList ts_diagnostics() const;
112
113 IceGrid::ConstPtr grid() const;
114
115 void define_model_state(const File &output) const;
116 void write_model_state(const File &output) const;
117
118 //! Reports the maximum time-step the model can take at time t.
119 MaxTimestep max_timestep(double t) const;
120
121 protected:
122 virtual MaxTimestep max_timestep_impl(double t) const;
123 virtual void define_model_state_impl(const File &output) const;
124 virtual void write_model_state_impl(const File &output) const;
125
126 virtual DiagnosticList diagnostics_impl() const;
127 virtual TSDiagnosticList ts_diagnostics_impl() const;
128
129 /** @brief This flag determines whether a variable is read from the
130 `-regrid_file` file even if it is not listed among variables in
131 `-regrid_vars`.
132 */
133 enum RegriddingFlag { REGRID_WITHOUT_REGRID_VARS, NO_REGRID_WITHOUT_REGRID_VARS };
134 virtual void regrid(const std::string &module_name, IceModelVec &variable,
135 RegriddingFlag flag = NO_REGRID_WITHOUT_REGRID_VARS);
136 protected:
137 //! grid used by this component
138 const IceGrid::ConstPtr m_grid;
139 //! configuration database used by this component
140 const Config::ConstPtr m_config;
141 //! unit system used by this component
142 const units::System::Ptr m_sys;
143 //! logger (for easy access)
144 const Logger::ConstPtr m_log;
145 };
146
147 } // end of namespace pism
148
149 #endif // __Component_hh