parameters.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.