ttime.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
---
ttime.rst (9488B)
---
1 .. include:: ../../../global.txt
2
3 .. _sec-time:
4
5 Model time
6 ----------
7
8 :numref:`tab-timeoptions` gives the command-line options which control PISM time. If
9 option ``-ys`` is absent then the start year is read from the input file (if present) or
10 it defaults to zero. The default value for the end year is the start year plus the given
11 (``-y``) run length. If both ``-ys`` and ``-ye`` are used then the run length is set to
12 the difference. Using all three of ``-ys``, ``-y`` and ``-ys`` is not allowed; this
13 generates an error message.
14
15 .. list-table:: Command-line options controlling PISM time
16 :name: tab-timeoptions
17 :header-rows: 1
18 :widths: 20, 80
19
20 * - Option
21 - Description
22 * - :opt:`-y` (years)
23 - Number of model years to run.
24 * - :opt:`-ys` (years)
25 - Model year at which to start the run. Also resets the model
26 time, ignoring any time in the input file.
27 * - :opt:`-ye` (years)
28 - Model year at which to end the run.
29
30 .. _sec-calendars:
31
32 Calendars
33 ^^^^^^^^^
34
35 Most of PISM, and its ice dynamics core in particular, only needs to know the length of
36 the current time-step. Internally PISM stores time in "seconds since a specified moment"
37 and thus PISM generally does not use or need a calendar. [#]_ We refer to PISM internal
38 time as *model time*.
39
40 One can select a calendar for more precise control of the model time, however. A
41 "calendar" is a concept that is part of the `CF Conventions`_. Choosing a calendar is
42 appropriate for runs for specific temporal periods like "the 18th-century" or
43 "1989--2010". The calendar is generally needed because specific knowledge of lengths of
44 months and years is required to use climate data properly or to facilitate model
45 validation.
46
47 PISM uses CalCalcs_ by David W. Pierce to perform calendric computations. This lets us
48 support all the `calendars <CF-Calendars_>`_ defined by the CF Metadata Conventions
49 document except for the ``366_day`` (``all_leap``) calendar.
50
51 Time units in PISM's output files always contain a reference date because it is required
52 by the CF metadata conventions.
53
54 By default PISM uses the ``365_day`` calendar. This is appropriate for runs that do not
55 require precise application of forcing data or reporting on particular dates
56 (paleo-climate runs, for example). In this mode PISM ignores the reference date in time
57 unit specifications (such as "``days since 1969-7-20``"), though the value set using
58 :config:`time.reference_date` configuration parameter is saved in (is passed forward into)
59 output files.
60
61 The calendar setting also affects the year length. In particular, with the default choice
62 of the calendar (``365_day``), ``-y 10`` sets the run duration to
63
64 .. math::
65
66 10 \times 365 \times 24 \times 60 \times 60 = 315360000
67
68 seconds, not `10 \times 365.25 \times 24 \times 60 \times 60` or similar.
69
70 .. note::
71
72 This does **not** affect unit conversion: the factor used to convert `m/s` to
73 `m/\text{year}` does not depend on the calendar choice.
74
75 .. list-table:: Calendars supported by PISM. Please see CalCalcs_ documentation for
76 details
77 :name: tab-calendars
78 :header-rows: 1
79 :widths: 1, 3
80
81 * - Keyword
82 - Meaning
83 * - ``gregorian`` or ``standard``
84 - Mixed Gregorian/Julian calendar used today.
85 * - ``proleptic_gregorian``
86 - Gregorian calendar extended to dates before 1582-10-15.
87 * - ``noleap`` or ``365_day``
88 - Calendar with fixed-length 365-day years
89 * - ``360_day``
90 - Calendar with fixed-length 360-day years divided into 30-day months
91 * - ``julian``
92 - Julian calendar
93 * - ``none``
94 - no calendar
95
96 Selecting a non-trivial (Gregorian, Proleptic Gregorian, or Julian) calendar using the
97 :config:`time.calendar` configuration parameter or the :opt:`-calendar` command-line
98 option enables calendar-based time management; see :numref:`tab-calendars`. The
99 implications of selecting such a calendar are:
100
101 - PISM uses the ``units`` attribute of coordinate variables *literally* (including the
102 reference date) in unit conversions. Please make sure that the :var:`time` variable in
103 all forcing files has the units attribute such as "``days since 2012-1-1``". PISM will
104 stop with an error message if a time variable does not have a reference date in its unit
105 specification.
106
107 - It is important to use units that are a fixed multiple of "seconds", such as "``minutes
108 since 1989-1-1``" or "``days since 1999-12-31``" and avoid "months" and "years". (PISM
109 uses UDUNITS-2 to convert units, and in UDUNITS one month is always interpreted as
110 `\frac{1}{12}\cdot 365.242198781` days.) Please see the `CF Conventions`_ document
111 for details.
112
113 - PISM uses dates in standard output:
114
115 .. code-block:: none
116
117 ...
118 time interval (length) [2012-01-01, 2021-12-31] (10.000 years)
119 ...
120 S 2012-05-26: 0.00011 0.6306 0.00000000 0.00000
121 $v$Eh m (dt=0.10000)
122 S 2012-07-01: 0.00014 0.6306 0.00000000 0.00000
123
124 Just like in the no-calendar mode, run length, run start and run end times are specified
125 using :opt:`-y`, :opt:`-ys` and :opt:`-ye` command-line options, respectively. Arguments
126 of these options are interpreted in a slightly different manner, though:
127
128 - the run length option ``-y`` takes an *integer* argument, interpreted as the number of
129 *calendar* years
130
131 - options ``-ys`` and ``-ye`` take *dates* as arguments.
132
133 For example, either of the following commands sets up a run covering the `21^{st}`
134 century:
135
136 .. code-block:: none
137
138 pismr -calendar gregorian -ys 2001-1-1 -y 100 ...
139 pismr -calendar standard -ys 2001-1-1 -ye 2101-1-1 ...
140
141 (These option combinations are equivalent.)
142
143 It is also possible to run PISM for the duration of the available forcing data using the
144 :opt:`-time_file` option. The command
145
146 .. code-block:: none
147
148 pismr -calendar gregorian -time_file forcing.nc
149
150 will extract the reference date and run length from ``forcing.nc``, respecting time
151 bounds.
152
153 When a non-trivial calendar is selected, spatial and scalar time-series can be saved
154 daily, monthly or yearly using these calendric computations. See sections
155 :ref:`sec-saving-time-series` and :ref:`sec-saving-diagnostics`.
156
157 .. _sec-time-file-restart:
158
159 Re-starting an interrupted run using ``-time_file``
160 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
161
162 If a run using ``-time_file`` gets interrupted but manages to save a backup, re-starting
163 with ``-time_file`` will attempt to re-do the entire run because options ``-y``, ``-ys``,
164 and ``-ye`` are ignored:
165
166 .. code-block:: bash
167
168 # This run gets killed but leaves backup.nc:
169 pismr -i input.nc -time_file time.nc -o output.nc
170 # This WILL NOT start from the time saved in backup.nc
171 # and continue until the end time in time.nc
172 pismr -i backup.nc -time_file time.nc -o output.nc
173
174 In this case we want to set the start time of the run from ``backup.nc``, but use the end
175 time from ``time.nc``. To achieve this, use the option :opt:`-time_file_continue_run`.
176
177 .. code-block:: bash
178
179 # This run gets killed but leaves backup.nc:
180 pismr -i input.nc -time_file time.nc -o output.nc
181 # This WILL continue until the end time in time.nc, starting from backup.nc
182 pismr -i backup.nc -time_file time.nc -o output.nc -time_file_continue_run
183
184 .. _sec-diagnostic-computations:
185
186 Diagnostic computations
187 ^^^^^^^^^^^^^^^^^^^^^^^
188
189 A "diagnostic" computation can be defined as one where the internal state does not evolve.
190 The internal state of PISM is the set of variables read by "``-i``". You can ask PISM to
191 do a diagnostic computation by setting the run duration to a small number such as
192 `0.001` years (about `9` hours). The duration to use depends on the modeling
193 setup, but should be smaller than the maximum time-step allowed by PISM's stability
194 criteria. Such short runs can also be used to look at additional fields corresponding to
195 the current model state.
196
197 As an example, consider these two runs:
198
199 .. code-block:: none
200
201 pisms -y 6000 -o foo.nc
202 pismr -i foo.nc -y 0.001 -o bar.nc -o_size big
203
204 The result of the second (short) run is a NetCDF file ``bar.nc`` which contains the full
205 three-dimensional velocity field in the scalar NetCDF variables ``uvel``, ``vvel``, and
206 ``wvel``, as well as many other variables. The file ``foo.nc`` does not contain many of
207 these fields because it was written with the default output size of ``medium``. The "``-y
208 0.001``" run has diagnostically "filled-in" all the fields which PISM can model at a time
209 step, but the run duration was chosen so as to avoid significant model state evolution
210 during the run.
211
212 This diagnostic mode is often associated to the modeling of ice shelves and ice streams.
213 section :ref:`sec-ross` describes using a short "diagnostic" run to model the Ross ice
214 shelf :cite:`MacAyealetal`. Verification tests I and J, section :ref:`sec-verif`, are
215 diagnostic calculations using the SSA.
216
217 The NetCDF model state saved by PISM at the end of an *evolution* run (i.e. with "``-y
218 Y``" for `Y>0`) does not, under the default ``-o_size medium`` output size, contain
219 the three-dimensional velocity field. Instead, it contains just a few more variables than
220 those which are needed to restart the run with ``-i``. One can force PISM to save all the
221 supported diagnostic quantities at the end of a time-stepping run using the option
222 ``-o_size big``. Or one can go back and do a "``-y small_number``" diagnostic run using
223 ``-o_size big``.
224
225
226 .. rubric:: Footnotes
227
228 .. [#] Note seconds are part of SI units.