tsaving-snapshots.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-snapshots.rst (5101B)
---
1 .. include:: ../../global.txt
2
3 .. _sec-snapshots:
4
5 Saving re-startable snapshots of the model state
6 ------------------------------------------------
7
8 Sometimes you want to check the model state every 1000 years, for example. One possible
9 solution is to run PISM for a thousand years, have it save all the fields at the end of
10 the run, then restart and run for another thousand, and etc. This forces the adaptive
11 time-stepping mechanism to stop *exactly* at multiples of 1000 years, which may be
12 desirable in some cases.
13
14 If saving exactly at specified times is not critical, then use the ``-save_file`` and
15 ``-save_times`` options. For example,
16
17 .. code-block:: none
18
19 pismr -i foo.nc -y 10000 -o output.nc -save_file snapshots.nc \
20 -save_times 1000:1000:10000
21
22 starts a PISM evolution run, initializing from ``foo.nc``, running for 10000 years and
23 saving snapshots to ``snapshots.nc`` at the first time-step after each of the years 1000,
24 2000, ..., 10000.
25
26 We use a MATLAB-style range specification, :math:`a:\Delta t:b`, where :math:`a,\Delta
27 t,b` are in years. The time-stepping scheme is not affected, but as a consequence we do
28 not guarantee producing the exact number of snapshots requested if the requested save
29 times have spacing comparable to the model time-steps. This is not a problem in the
30 typical case in which snapshot spacing is much greater than the length of a typical time
31 step.
32
33 It is also possible to save snapshots at intervals that are not equally-spaced by giving
34 the ``-save_times`` option a comma-separated list. For example,
35
36 .. code-block:: none
37
38 pismr -i foo.nc -y 10000 -o output.nc -save_file snapshots.nc \
39 -save_times 1000,1500,2000,5000
40
41 will save snapshots on the first time-step after years 1000, 1500, 2000 and 5000. The
42 comma-separated list given to the ``-save_times`` option can be at most 200 numbers long.
43
44 If ``snapshots.nc`` was created by the command above, running
45
46 .. code-block:: none
47
48 pismr -i snapshots.nc -y 1000 -o output_2.nc
49
50 will initialize using the last record in the file, at about :math:`5000` years. By
51 contrast, to restart from :math:`1500` years (for example) it is necessary to extract the
52 corresponding record using ``ncks``
53
54 .. code-block:: none
55
56 ncks -d t,1500years snapshots.nc foo.nc
57
58 and then restart from ``foo.nc``. Note that ``-d t,N`` means "extract the :math:`N`-th
59 record" (counting from zero). So, this command is equivalent to
60
61 .. code-block:: none
62
63 ncks -d t,1 snapshots.nc foo.nc
64
65 Also note that the second snapshot will probably be *around* :math:`1500` years and
66 ``ncks`` handles this correctly: it takes the record closest to :math:`1500` years.
67
68 By default re-startable snapshots contain only the variables needed for restarting PISM.
69 Use the command-line option ``-save_size`` to change what is saved.
70
71 Another possible use of snapshots is for restarting runs on a batch system which kills
72 jobs which go over their allotted time. Running PISM with options ``-y 1500``
73 ``-save_times 1000:100:1400`` would mean that if the job is killed before completing the
74 whole 1500 year run, we can restart from near the last multiple of :math:`100` years.
75 Restarting with option ``-ye`` would finish the run on the desired year.
76
77 When running PISM on such a batch system it can also be useful to save re-startable
78 snapshots at equal wall-clock time (as opposed to model time) intervals by adding the
79 ":opt:`-backup_interval` (hours)" option.
80
81 .. caution::
82
83 If the wall-clock limit is equal to :math:`N` times backup interval for a whole number
84 :math:`N` PISM will likely get killed while writing the last backup.
85
86 It is also possible to save snapshots to separate files using the ``-save_split`` option.
87 For example, the run above can be changed to
88
89 .. code-block:: none
90
91 pismr -i foo.nc -y 10000 -o output.nc -save_file snapshots \
92 -save_times 1000,1500,2000,5000 -save_split
93
94 for this purpose. This will produce files called ``snapshots-year.nc``. This option is
95 generally faster if many snapshots are needed, apparently because of the time necessary to
96 reopen a large file at each snapshot when ``-save_split`` is not used. Note that tools
97 like NCO and ``ncview`` usually behave as desired with wildcards like
98 "``snapshots-*.nc``".
99
100 :numref:`tab-snapshot-opts` lists the options related to saving snapshots of the
101 model state.
102
103 .. list-table:: Command-line options controlling saving snapshots of the model state.
104 :name: tab-snapshot-opts
105 :header-rows: 1
106 :widths: 1,1
107
108 * - Option
109 - Description
110 * - :opt:`-save_file`
111 - Specifies the file to save to.
112 * - :opt:`-save_times`
113 - Specifies times at which to save snapshots, by either a MATLAB-style range
114 :math:`a:\Delta t:b` or a comma-separated list.
115 * - :opt:`-save_split`
116 - Separate the snapshot output into files named ``snapshots-year.nc``. Faster if you
117 are saving more than a dozen or so snapshots.
118 * - :opt:`-save_size` ``[none,small,medium,big,big_2d]``
119 - Similar to ``o_size``, changes the "size" of the file (or files) written; the
120 default is "small"