tparameters.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
---
tparameters.rst (4993B)
---
1 .. include:: ../../global.txt
2
3 .. _sec-pism-defaults:
4
5 PISM's configuration parameters and how to change them
6 ------------------------------------------------------
7
8 PISM's behavior depends on values of many flags and physical parameters (see
9 :ref:`sec-parameter-list` for details). Most of parameters have default values [#]_ which
10 are read from the configuration file |config-file| in the ``lib`` sub-directory.
11
12 It is possible to run PISM with an alternate configuration file using the :opt:`-config`
13 command-line option:
14
15 .. code-block:: none
16
17 pismr -i foo.nc -y 1000 -config my_config.nc
18
19 The file ``my_config.nc`` has to contain *all* of the flags and parameters present in
20 |config-file|.
21
22 The list of parameters is too long to include here; please see the
23 :ref:`sec-parameter-list` for an automatically-generated table describing them.
24
25 Some command-line options *set* configuration parameters; some PISM executables have
26 special parameter defaults. To examine what parameters were used in a particular run, look
27 at the attributes of the ``pism_config`` variable in a PISM output file.
28
29 .. _sec-parameter-studies:
30
31 Managing parameter studies
32 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
33
34 Keeping all PISM output files in a parameter study straight can be a challenge. If the
35 parameters of interest were controlled using command-line options then one can use
36 ``ncdump -h`` and look at the ``history`` global attribute.
37
38 Alternatively, one can change parameter values by using an "overriding" configuration
39 file. The :opt:`-config_override` command-line option provides this alternative. A file
40 used with this option can have a subset of the configuration flags and parameters present
41 in |config-file|. Moreover, PISM adds the ``pism_config`` variable with values used in a
42 run to the output file, making it easy to see which parameters were used.
43
44 Here's an example. Suppose we want to compare the dynamics of an ice-sheet on Earth to the
45 same ice-sheet on Mars, where the only physical change was to the value of the
46 acceleration due to gravity. Running
47
48 .. code-block:: none
49
50 pismr -i input.nc -y 1e5 -o earth.nc <other PISM options>
51
52 produces the "Earth" result, since PISM's defaults correspond to this planet. Next, we
53 create ``mars.cdl`` containing the following:
54
55 .. code-block:: none
56
57 netcdf mars {
58 variables:
59 byte pism_overrides;
60 pism_overrides:constants.standard_gravity = 3.728;
61 pism_overrides:constants.standard_gravity_doc = "m s-2; standard gravity on Mars";
62 }
63
64
65 Notice that the variable name is ``pism_overrides`` and not ``pism_config`` above. Now
66
67 .. code-block:: none
68
69 ncgen -o mars_config.nc mars.cdl
70 pismr -i input.nc -y 1e5 -config_override mars_config.nc -o mars.nc <other PISM options>
71
72 will create ``mars.nc``, the result of the "Mars" run. Then we can use ``ncdump`` to see
73 what was different about ``mars.nc``:
74
75 .. code-block:: diff
76
77 ncdump -h earth.nc | grep pism_config: > earth_config.txt
78 ncdump -h mars.nc | grep pism_config: > mars_config.txt
79 diff -U 1 earth_config.txt mars_config.txt
80 --- earth_config.txt 2015-05-08 12:44:43.000000000 -0800
81 +++ mars_config.txt 2015-05-08 12:44:51.000000000 -0800
82 @@ -734,3 +734,3 @@
83 pism_config:ssafd_relative_convergence_units = "1" ;
84 - pism_config:constants.standard_gravity_doc = "acceleration due to gravity on Earth geoid" ;
85 + pism_config:constants.standard_gravity_doc = "m s-2; standard gravity on Mars" ;
86 pism_config:constants.standard_gravity_type = "number" ;
87 @@ -1057,3 +1057,3 @@
88 pism_config:ssafd_relative_convergence = 0.0001 ;
89 - pism_config:constants.standard_gravity = 9.81 ;
90 + pism_config:constants.standard_gravity = 3.728 ;
91 pism_config:start_year = 0. ;
92
93 .. _sec-saving-pism-config:
94
95 Saving PISM's configuration for post-processing
96 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
97
98 In addition to saving ``pism_config`` in the output file, PISM automatically adds this
99 variable to all files it writes (snap shots, time series of scalar and spatially-varying
100 diagnostic quantities, and backups). This may be useful for post-processing and analysis
101 of parameter studies as the user has easy access to all configuration options, model
102 choices, etc., without the need to keep run scripts around.
103
104 .. rubric:: Footnotes
105
106 .. [#] For ``pismr``, grid parameters ``Mx``, ``My``, that must be set at bootstrapping,
107 are exceptions.
108
109 .. Note: This is because we don't have a way to tell if a parameter value is a
110 default *or* a conscious user choice, but we do know that command-line options
111 are meant to override defaults.
112
113 The desired behavior at bootstrapping is:
114
115 In absence of -Mx and -My use the grid size from the input file. Values set
116 with -Mx and -My override ones read from the input file. The user can set one
117 (or both) -Mx and -My.