tsaving-diagnostics.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
---
tsaving-diagnostics.rst (5645B)
---
1 .. include:: ../../global.txt
2
3 .. _sec-saving-diagnostics:
4
5 Saving time series of spatially-varying diagnostic quantities
6 -------------------------------------------------------------
7
8 Sometimes it is useful to have PISM save a handful of diagnostic *maps* at some interval
9 like every 10 years or even every month. One can use snapshots (section
10 :ref:`sec-snapshots`), but doing so can easily fill your hard-drive because snapshots are
11 complete (i.e. re-startable) model states. Sometimes you want a *subset* of model
12 variables saved frequently in an output file.
13
14 Use options ``-extra_file``, ``-extra_times``, and ``-extra_vars`` for this. For example,
15
16 .. code-block:: none
17
18 pismr -i foo.nc -y 10000 -o output.nc -extra_file extras.nc \
19 -extra_times 0:10:1e4 -extra_vars velsurf_mag,velbase_mag
20
21
22 will run for 10000 years, saving the magnitude of horizontal velocities at the ice surface
23 and at the base of ice every 10 years. Times are specified using a comma-separated list or
24 a MATLAB-style range. See :numref:`tab-extras` for all the options controlling this
25 feature. The section :ref:`sec-extra_vars` list all the variable choices.
26
27 .. note::
28
29 Some diagnostics are only available if the simulation uses a sub-model that provides
30 them. PISM will stop with an error message if a diagnostic is requested but not
31 available. To print a warning and continue instead of stopping, set
32 :config:`output.extra.stop_missing` to "false".
33
34
35 Note that options :opt:`-extra_times`, :opt:`-save_times`, :opt:`-ts_times` take *dates*
36 if a non-trivial calendar is selected. For example,
37
38 .. code-block:: bash
39
40 pismr ... -extra_times 10 # every 10 years
41 pismr ... -extra_times 2days # every 2 days
42 pismr ... -calendar gregorian -extra_times 1-1-1:daily:11-1-1 # daily for 10 years
43 pismr ... -calendar gregorian -extra_times daily -ys 1-1-1 -ye 11-1-1
44 pismr ... -calendar gregorian -extra_times 2hours -ys 1-1-1 -ye 1-2-1
45
46
47 The step in the range specification can have the form ``Nunit``, for example ``5days``.
48 Units based on "months" and "years" are not supported if a non-trivial calendar is
49 selected.
50
51 In addition to specifying a constant step in ``-extra_times a:step:b`` one can save every
52 hour, day, month, or every year by using ``hourly``, ``daily``, ``monthly`` or ``yearly``
53 instead of a number; for example
54
55 .. code-block:: none
56
57 pismr -i foo.nc -y 100 -o output.nc -extra_file extras.nc \
58 -extra_times 0:monthly:100 -extra_vars dHdt
59
60 will save the rate of change of the ice thickness every month for 100 years. With
61 ``-calendar none`` (the default), "monthly" means "every :math:`\frac 1 {12}` of the
62 year", and "yearly" is "every :math:`3.14\ldots\times10^7`" seconds, otherwise PISM uses
63 month lengths computed using the selected calendar.
64
65 It is frequently desirable to save diagnostic quantities at regular intervals for the
66 whole duration of the run; options :opt:`-extra_times`, :opt:`-ts_times`, and
67 :opt:`-save_times` provide a shortcut. For example, use ``-extra_times yearly`` to save at
68 the end of every year.
69
70 This is especially useful when using a climate forcing file to set run duration:
71
72 .. code-block:: none
73
74 pismr -i foo.nc -surface given -surface_given_file climate.nc \
75 -calendar gregorian -time_file climate.nc \
76 -extra_times monthly -extra_file ex.nc -extra_vars thk
77
78
79 will save ice thickness at the end of every month while running PISM for the duration of
80 climate forcing data in ``climate.nc``.
81
82 Times given using ``-extra_times`` describe the reporting intervals by giving the
83 endpoints of these reporting intervals. The save itself occurs at the end of each
84 interval. This implies, for example, that ``0:1:10`` will produce 10 records at times
85 1,...,10 and *not* 11 records.
86
87 If the file ``foo.nc``, specified by ``-extra_file foo.nc``, already exists then by
88 default the existing file will be moved to ``foo.nc~`` and the new time series will go
89 into ``foo.nc``. To append the time series onto the end of the existing file, use option
90 ``-extra_append``.
91
92 The list of available diagnostic quantities depends on the model setup. For example, a run
93 with only one vertical grid level in the bedrock thermal layer will not be able to save
94 ``litho_temp``, an SIA-only run does not use a basal yield stress model and so will not
95 provide ``tauc``, etc. To see which quantities are available in a particular setup, use
96 the :opt:`-list_diagnostics` option, which prints the list of diagnostics and stops.
97
98 The ``-extra_file`` mechanism modifies PISM's adaptive time-stepping scheme so as to step
99 to, and save at, *exactly* the times requested. By contrast, as noted in subsection
100 :ref:`sec-saving-time-series`, the ``-ts_file`` mechanism does not alter PISM's time-steps
101 and instead uses linear interpolation to save at the requested times in between PISM's
102 actual time-steps.
103
104 .. list-table:: Command-line options controlling extra diagnostic output
105 :name: tab-extras
106 :header-rows: 1
107 :widths: 1,3
108
109 * - Option
110 - Description
111
112 * - :opt:`-extra_file`
113 - Specifies the file to save to; should be different from the output (:opt:`-o`)
114 file.
115
116 * - :opt:`-extra_times`
117 - Specifies times to save at either as a MATLAB-style range :math:`a:\Delta t:b` or a
118 comma-separated list.
119
120 * - :opt:`-extra_vars`
121 - Comma-separated list of variables
122
123 * - :opt:`-extra_split`
124 - Save to separate files, similar to :opt:`-save_split`.
125
126 * - :opt:`-extra_append`
127 - Append variables to file if it already exists. No effect if file does not yet
128 exist, and no effect if :opt:`-extra_split` is set.