thow-to.rst - 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
---
thow-to.rst (7235B)
---
1 .. include:: ../global.txt
2
3 .. default-role:: literal
4
5 How do I...?
6 ============
7
8 .. contents::
9
10 Create and use configuration flags and parameters
11 -------------------------------------------------
12
13 - Edit |config-cdl|. Each flag or parameter is stored as a NetCDF attribute and should
14 have a corresponding "`_doc`" attribute describing its meaning and the "`_type`"
15 defining the type. All scalar parameters have to have "`_units`" set as well.
16
17 .. code-block:: none
18
19 pism_config:constants.standard_gravity = 9.81;
20 pism_config:constants.standard_gravity_doc = "acceleration due to gravity on Earth geoid";
21 pism_config:constants.standard_gravity_type = "scalar";
22 pism_config:constants.standard_gravity_units = "meter second-2";
23
24 - One can access these parameters using the `Config` class. `IceModel` and all classes
25 derived from `Component` have an pointer to an instance of this class as a data member
26 `m_config`, so no additional code is necessary to initialize the configuration database.
27
28 To use a scalar parameter, do
29
30 .. code-block:: c++
31
32 double g = m_config->get_number("constants.standard_gravity");
33
34 To use a flag, do
35
36 .. code-block:: c++
37
38 bool compute_age = config->get_flag("age.enabled");
39
40 .. note::
41
42 - It is best to avoid calling `m_config->get_...()` from within loops: looking up a
43 parameter by its name is slow.
44 - Please see :ref:`sec-parameter-list` for a list of flags and parameters currently
45 used in PISM.
46
47 Create and use additional variables
48 -----------------------------------
49
50 Creating IceModelVec instances
51 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
52
53 PISM uses the following classes to manage 2D and 3D fields, their I/O and metadata:
54
55 .. list-table::
56
57 * - `IceModelVec2S`
58 - scalar 2D fields
59 * - `IceModelVec2V`
60 - vector 2D fields such as horizontal velocities; corresponds to 2 NetCDF variables
61 * - `IceModelVec2Int`
62 - 2D masks, such as the grounded/floating mask
63 * - `IceModelVec2T`
64 - 2D time-dependent fields (used to read and store forcing data)
65 * - `IceModelVec3`
66 - scalar 3D fields (usually within the ice)
67
68 Please see the documentation of these classes for more info. The base class `IceModelVec` is
69 a virtual class, so code should use the above derived classes.
70
71 To create a scalar field, for example, one needs to create an instance of `IceModelVec2S`
72 and then set its metadata:
73
74 .. code-block:: c++
75
76 // land ice thickness
77 IceModelVec2S ice_thickness(grid, "thk", WITH_GHOSTS, 2);
78 ice_thickness.set_attrs("model_state", "land ice thickness",
79 "m", "land_ice_thickness");
80 ice_thickness.metadata().set_number("valid_min", 0.0);
81
82 Here `grid` is an `IceGrid` instance, `thk` is the name of the NetCDF variable,
83 `WITH_GHOSTS` means that storage for "ghost" ("halo") points will be allocated, and "2" is
84 the number of ghosts (in other words: required stencil width).
85
86 The `IceModelVec::set_attrs()` call sets commonly used NetCDF variable attributes seen in
87 PISM output files:
88
89 .. list-table::
90
91 * - `pism_intent`
92 - variables that are a part of the model state of a sub-model should have
93 `pism_intent` set to "model_state"
94 * - `long_name`
95 - the (descriptive) long name used for plotting, etc (a free-form string)
96 * - `units`
97 - units used *in the code*; does not have to match units in a file.
98 * - `standard_name`
99 - CF standard name, if defined, or an empty string.
100
101 The `ice_thickness.metadata()` call above allows accessing variable metadata and
102 adding arbitrary attributes. See `VariableMetadata` for details.
103
104 The CF convention covers some attribute semantics, including `valid_min` in this example.
105
106 PISM will automatically convert units from ones present in an input file into internal
107 units defines by the `set_attrs()` call above.
108
109 If you want PISM to save data in units other than internal ones, first set these
110 "glaciological" units:
111
112 .. code-block:: c++
113
114 ice_thickness.metadata().set_string("glaciological_units", "km");
115
116 Read data from a file
117 ---------------------
118
119 There are at least three cases of "reading data from a file":
120
121 1. reading a field stored in an input file on a grid matching the one used by the current
122 run (restarting a run),
123 2. reading a field stored in an input file on a different grid, interpolating onto the
124 current grid (bootstrapping), and
125 3. reading a field stored in a file **other** than the input file using interpolation
126 (assuming that grids are compatible but not identical)
127
128 .. code-block:: c++
129
130 // case 1, using a file name
131 unsigned int time = 0;
132 std::string filename = "filename.nc";
133 ice_thickness.read(filename, time);
134
135 // case 1, using an existing File instance (file is already open)
136 File file(communicator, "guess_mode", filename, PISM_READONLY);
137 ice_thickness.read(file, time);
138
139 RegriddingFlag flag = OPTIONAL;
140 double default_value = 0.0;
141 // cases 2 and 3 (interpolation)
142 ice_thickness.regrid(filename, flag, default_value);
143
144 // cases 2 and 3 (interpolation) using an existing File instance
145 ice_thickness.regrid(file, flag, default_value);
146
147 When interpolating ("regridding") a field, the ``flag`` specifies whether a variable is
148 required (``flag`` is ``CRITICAL`` or ``CRITICAL_FILL_MISSING``) or optional (``flag`` is
149 ``OPTIONAL`` or ``OPTIONAL_FILL_MISSING``). PISM will stop with an error message if a
150 required variable is not found in an input file.
151
152 Flag values of ``CRITICAL_FILL_MISSING`` and ``OPTIONAL_FILL_MISSING`` replaces "missing"
153 values matching the ``_FillValue`` attribute by the default value.
154
155 If ``flag`` is ``OPTIONAL`` or ``OPTIONAL_FILL_MISSING`` PISM will fill the variable with
156 ``default_value`` if it was not found in the file.
157
158 Write data to a file
159 --------------------
160
161 `IceModelVec::define()` will define all spatial dimensions used by a variable. However, we
162 usually need to "prepare" a file by defining the time dimension and appending a value to
163 the time variable.
164
165 .. code-block:: c++
166
167 File file(m_grid->com, m_config->get_string("output.format"),
168 filename, PISM_READWRITE_CLOBBER, m_grid->ctx()->pio_iosys_id());
169
170 io::define_time(file, *m_grid->ctx());
171 io::append_time(file, *m_grid->ctx()->config(), current_time);
172
173 When a file is opened with the mode `PISM_READWRITE_CLOBBER`, PISM checks if this file is
174 present overwrites if it is; to append to an existing file, use `PISM_READWRITE`. To move
175 the file aside (appending "`~`" to the file name), use `PISM_READWRITE_MOVE`.
176
177 A newly-created file is "empty" and contains no records. The `io::append_time()` call
178 creates a record corresponding to the `current_time` (in seconds).
179
180 To write a field to an already "prepared" file, call
181
182 .. code-block:: c++
183
184 precip.write("filename.nc");
185 // or, if the file is already open and a File instance is available:
186
187 precip.write.(file);
188
189 Read scalar forcing data
190 ------------------------
191
192 PISM uses instances of the `ScalarForcing` class to read scalar forcing data; please see
193 `pism::surface::Delta_T` for an example.
194
195
196 Read 2D forcing fields
197 ----------------------
198
199 PISM uses instances of the `IceModelVec2T` class to read 2D forcing fields that
200 vary in time; please see `pism::surface::Given` for an example.