trun-1.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
---
trun-1.rst (5113B)
---
1 .. include:: ../../global.txt
2
3 .. _sec-runscript:
4
5 First run
6 ---------
7
8 Like many Unix programs, PISM allows a lot of command-line options. In fact, because the
9 variety of allowed ice sheet, shelf, and glacier configurations, and included sub-models,
10 is so large, command-line options are covered in sections :ref:`sec-initboot` through
11 :ref:`sec-practical-usage` of this manual.\ [#]_ In practice one often builds scripts to run
12 PISM with the correct options, which is what we show here. The script we use is
13 "``spinup.sh``" in the ``examples/std-greenland/`` subdirectory of ``pism/``.
14
15 Note that initializing ice sheets, usually called "spin-up", can be done by computing
16 approximate steady states with constant boundary data, or, in some cases, by integrating
17 paleo-climatic and long-time-scale information, also applied at the ice sheet boundary, to
18 build a model for the present state of the ice sheet. Both of these possibilities are
19 illustrated in the ``spinup.sh`` script. The spin-up stage of using an ice sheet model may
20 actually require more processor-hours than follow-on "experiment" or "forecast" stages.
21
22 To see what can be done with the script, read the usage message it produces:
23
24 .. code-block:: none
25
26 ./spinup.sh
27
28 The simplest spin-up approach is to use a "constant-climate" model. We take this approach
29 first. To see a more detailed view of the PISM command for the first run, do:
30
31 .. literalinclude:: scripts/run-1-echo.sh
32 :language: bash
33 :lines: 3-
34
35 Setting the environment variable ``PISM_DO`` in this way tells ``spinup.sh`` just to print
36 out the commands it is about to run instead of executing them. The "proposed" run looks
37 like this:
38
39 .. literalinclude:: scripts/run-1-command.sh
40 :language: bash
41 :name: firstcommand
42 :lines: 3-
43
44 Let's briefly deconstruct this run.
45
46 At the front is "``mpiexec -n 4 pismr``". This means that the PISM executable ``pismr`` is
47 run in parallel using four processes (usually one per CPU core) under the `Message Passing
48 Interface <MPI_>`_. Though we are assuming you have a workstation or laptop with at least
49 4 cores, this example will work with 1 to about 50 processors, with reasonably good
50 scaling in speed. Scaling can be good with more processors if we run at higher spatial
51 resolution :cite:`BBssasliding`, :cite:`DickensMorey2013`. The executable name "``pismr``"
52 stands for the standard "run" mode of PISM (in contrast to specialized modes described
53 later in sections :ref:`sec-verif` and :ref:`sec-simp`).
54
55 Next, the proposed run uses option ``-bootstrap`` to start the run by "bootstrapping."
56 This term describes the creation, by heuristics and highly-simplified models, of the
57 mathematical initial conditions required for a deterministic, time-dependent ice dynamics
58 model. Then the options describe a `76 \times 141` point grid in the horizontal,
59 which gives 20 km grid spacing in both directions. Then there are choices about the
60 vertical extent and resolution of the computational grid; more on those later. After that
61 we see a description of the time axis, with a start and end time given: "``-ys -10000 -ye
62 0``".
63
64 Then we get the instructions that tell PISM to read the upper surface boundary conditions
65 (i.e. climate) from a file: "``-surface given -surface_given_file
66 pism_Greenland_5km_v1.1.nc``". For more on these choices, see subsection
67 :ref:`sec-climate-inputs`, and also the :ref:`Climate Forcing Manual
68 <sec-climate-forcing>`.
69
70 Then there are a couple of options related to ice dynamics. First is a minimal "calving"
71 model which removes ice leaving the area covered by ice (or ice-free with the bed above
72 the sea level) according to the input file ("``-front_retreat_file``"); see section
73 :ref:`sec-calving` for this and other calving options). Then there is a setting for
74 enhanced ice softness ("``-sia_e 3.0``"). See section :ref:`sec-rheology` for more on this
75 enhancement parameter, which we also return to later in section :ref:`sec-paramstudy`.
76
77 Then there are longish options describing the fields we want as output, including scalar
78 time series ("``-ts_file ts_g20km_10ka.nc -ts_times -10000:yearly:0``"; see section
79 :ref:`sec-practical-usage`) and space-dependent fields ("``-extra_file ...``"; again see
80 section :ref:`sec-practical-usage`), and finally the named output file ("``-o
81 g20km_10ka.nc``").
82
83 Note that the modeling choices here are reasonable, but they are not the only way to do
84 it! The user is encouraged to experiment; that is the point of a model.
85
86 Now let's actually get the run going:
87
88 .. literalinclude:: scripts/run-1.sh
89 :lines: 3-
90 :language: bash
91
92 The terminating "``&``", which is optional, asks the system to run the command in the
93 background so we can keep working in the current shell. Because we have re-directed the
94 text output ("``&> out.g20km_10ka``"), PISM will show what it is doing in the text file
95 ``out.g20km_10ka``. Using ``less`` is a good way to watch such a growing text-output file.
96 This run should take around 20 minutes.
97
98 .. rubric:: Footnotes
99
100 .. [#] Moreover, every configuration parameter can be set using a command-line option with
101 the same name.