|
| 1 | +# Configuration files |
| 2 | +There are two types of configuration files: |
| 3 | +- Configure gradient output |
| 4 | +- Configure ensemble simulations |
| 5 | + All configuration files are using the [JSON-format](https://ecma-international.org/publications-and-standards/standards/ecma-404/). This makes the configurations human-readable and easy to generate and read thanks to the extensive support in many languages. This code uses [JSON for Modern C++](https://github.com/nlohmann/json) to load the data. |
| 6 | + |
| 7 | +## Configure gradient output |
| 8 | +This configuration is needed whenever a sensitivity analysis is done. It defines which targets, i.e., model state variables, are differentiated using `model_state_variable` and a list of ids of the desired targets. The ids are defined in `include/microphysics/constants.h` and are as follows: |
| 9 | +Target | Index |
| 10 | +---|---- |
| 11 | +Pressure | 0 |
| 12 | +Temperature | 1 |
| 13 | +Vertical ascent velocity | 2 |
| 14 | +Saturation | 3 |
| 15 | +Cloud droplet mixing ratio | 4 |
| 16 | +Rain droplet mixing | 5 |
| 17 | +Water vapor mixing ratio | 6 |
| 18 | +Number of cloud droplets | 7 |
| 19 | +Number of rain droplets | 8 |
| 20 | +Ice mixing ratio | 9 |
| 21 | +Number of ice crystals | 10 |
| 22 | +Snow mixing ratio | 11 |
| 23 | +Number of snow particles | 12 |
| 24 | +Graupel mixing ratio | 13 |
| 25 | +Number of graupel particles | 14 |
| 26 | +Hail mixing ratio | 15 |
| 27 | +Number of hail particles | 16 |
| 28 | +Ice mixing ratio precipitation | 17 |
| 29 | +Snow mixing ratio precipitation | 18 |
| 30 | +Rain mixing ratio precipitation | 19 |
| 31 | +Graupel mixing ratio precipitation | 20 |
| 32 | +Hail mixing ratio precipitation | 21 |
| 33 | +Latent heating | 22 |
| 34 | +Latent cooling | 23 |
| 35 | +Ice particles precipitation | 24 |
| 36 | +Snow particles ratio precipitation | 25 |
| 37 | +Rain droplets ratio precipitation | 26 |
| 38 | +Graupel particles ratio precipitation | 27 |
| 39 | +Hail particles ratio precipitation | 28 |
| 40 | + |
| 41 | +The model parameters for which sensitivities are computed are defined by a list `out_params` by name such as `db_ccn_1` or `dcloud_a_geo`. Note the 'd' which usually indicates a derivative. An overview of all model parameters is available in variable `output_grad_idx` in `include/microphysics/constants.h`. You may define your own model parameters here if you add different physics. An example can be seen with `CCN_AKM` which is a preprocessor instruction for the C++-code that defines a different CCN activation. |
| 42 | +A full example that calculates the sensitivities of water vapor mixing ratio, latent heating and cooling to several parameters is: |
| 43 | +``` |
| 44 | +{ |
| 45 | + "model_state_variable": [ |
| 46 | + 6, 22, 23 |
| 47 | + ], |
| 48 | + "out_params": [ |
| 49 | + "db_ccn_1", |
| 50 | + "db_ccn_2", |
| 51 | + "dc_ccn_1", |
| 52 | + "dc_ccn_2" |
| 53 | + ] |
| 54 | +} |
| 55 | +``` |
| 56 | + |
| 57 | +## Configure ensemble simulations |
| 58 | +The ensemble simulations are organized in segments where each segment defines when the perturbed member is started, how many members there are, which parameters are perturbed and how the perturbation is calculated. While it is technically possible to define multiple segments with different perturbations each, it is easier to create multiple configuration files and run each independently when executing it on a cluster. |
| 59 | +The conditions for the ensembles are asserted and executed in the function `parameter_check()` in `src/microphysics/trajectories.cpp`. |
| 60 | + |
| 61 | +### When to perturb |
| 62 | +The parameter `when_method` defines when to perturb the ensemble member. Possible options are |
| 63 | +- `full_perturbation`: Run the perturbation from the beginning. |
| 64 | +- `repeated_time`: Start the ensemble every `when_value` seconds. |
| 65 | +- `impact_change`: Start an ensemble simulation when the parameter with the highest derivative changes. |
| 66 | +- `sign_flip`: Start an ensemble when the gradient of a predefined target to a predefined parameter changes. See below for setting the parameter and target. |
| 67 | +- `value`: Start an ensemble if the gradient of a predefined target to a predefined parameter reaches a given value defined in `when_value` (within some tolerance). |
| 68 | + Further variables are: |
| 69 | +- `duration`: If `when_method` is not `full_perturbation`, you can limit the length of the ensemble simulation with this variable (in seconds). |
| 70 | +- `amount`: Define the number of ensemble members (including the unperturbed simulation). |
| 71 | +- `params`: A list that defines which parameters are perturbed and how. |
| 72 | + Each entry of `params` must define the parmater to be perturbed, how and by how much it is perturbed: |
| 73 | +- `name`: Name of the parameter to be perturbed such as `a_ccn_1` or `a_geo`. |
| 74 | +- `type`: Type of the parameter such as `model` if it is purely a model parameter such as `a_ccn_1` or the hydrometeor type of the parameter such as `cloud` for `a_geo`. |
| 75 | +- `rand_func`: The random number generator or function to be used. Possible options are: |
| 76 | + - `fixed`: Perturb by a fixed amount where the parameters is increased by the fixed amount for every second member and reduced otherwise. |
| 77 | + - `uniform`: Draw a random number from a uniform distribution. |
| 78 | + - `normal`: Draw from a normal distribution. |
| 79 | +- `sigma`: (We use $p$ for the parameter value in the following) |
| 80 | + - If `rand_func` is `uniform`: The uniform distribution is bound by the [$p - \sigma, p + \sigma$]. |
| 81 | + - If `rand_func` is `normal`: The normal distribution is defined by $\mathcal{N}(p, \sigma)$ where $\sigma$ is the standard deviation. |
| 82 | + - If `rand_func` is `fixed`: The parameter is set to $p - \sigma$ and $p + \sigma$ alternatively for each ensemble member. |
| 83 | +- `sigma_perc`: Same as `sigma` but the perturbation is done by a percentage of the parameter value, e.g., for `rand_func` set to `fixed`, the parameter is set to $p - \sigma_{perc} \cdot p$ and $p + \sigma_{perc} \cdot p$ alternatively. |
| 84 | + |
| 85 | +An example where `dcloud_a_geo` is perturbed by 10% where the ensemble is running from start to end with one member an increased and another with a decreased value: |
| 86 | +``` |
| 87 | +{ |
| 88 | + "segments": [ |
| 89 | + { |
| 90 | + "when_method": "full_perturbation", |
| 91 | + "amount": 3, |
| 92 | + "params": [ |
| 93 | + { |
| 94 | + "name": "a_geo", |
| 95 | + "sigma_perc": 10, |
| 96 | + "type": "cloud", |
| 97 | + "rand_func": "fixed" |
| 98 | + } |
| 99 | + ] |
| 100 | + } |
| 101 | + ] |
| 102 | +} |
| 103 | +``` |
| 104 | +Another example where every 30 minutes an ensemble is started that runs for 30 minutes. There are 64 members with perturbed parameters drawn from a uniform distribution: |
| 105 | +``` |
| 106 | +{ |
| 107 | + "segments": [ |
| 108 | + { |
| 109 | + "when_method": "repeated_time", |
| 110 | + "duration": 1800, |
| 111 | + "when_value": 1800, |
| 112 | + "amount": 65, |
| 113 | + "params": [ |
| 114 | + { |
| 115 | + "name": "a_geo", |
| 116 | + "sigma_perc": 10, |
| 117 | + "type": "cloud", |
| 118 | + "rand_func": "uniform" |
| 119 | + } |
| 120 | + ] |
| 121 | + } |
| 122 | + ] |
| 123 | +} |
| 124 | +``` |
0 commit comments