tutorial.rst 8.25 KB
 Lukas Riedel committed Feb 26, 2020 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 ********************** Random Field Generator ********************** DORiE includes the powerful Gaussian random field generator implemented in dune-randomfield _. We will use this generator for two different use cases to conduct simulations on heterogeneous media. Basics ------ The random field generator creates a set of random numbers on a physical domain. The random variable :math:X itself follows a Gaussian (normal) distribution with mean :math:\mu = 0 and a selectable variance :math:\sigma^2, .. math:: X \sim \mathcal{N}(\mu = 0, \sigma^2) The spatial distribution is determined by covariance functions and correlation lengths. Finally, the random number generation itself is pseudo-random, meaning that it is actually deterministic but appears random with respect to most benchmarks. The seed of the generator therefore lets one replicate a random field from an unchanged system configuration. The random field generator is wrapped into a DORiE Python module which obtains the field supplied by the generator and can apply several transformations to it, which are tailored for specific use cases. The module is dubbed "Parameter Field Generator" (PFG) and takes an INI-configuration file (default: parfield.ini) as argument, whose keys are documented in :doc:/manual/config-file. The module is called via the :doc:/manual/cli. Use Case: Miller-Similar Medium ------------------------------- Small-scale heterogeneity in soil media are typically realized via scalings of the parameterization functions, rather than changes of the individual parameters themselves. In this section, we will apply :ref:Miller scaling  to a otherwise homogeneous medium. This scaling is based on geometric similarity: It assumes that the local soil heterogeneity can be described by a varying lengthscale of the soil grains and pores. Field Generation ^^^^^^^^^^^^^^^^ We will alter the work flow of the first tutorial by executing the parameter field generator (PFG) module in the :ref:command line interface  before starting the solver. The default PFG configuration file is called parfield.ini. Enter a clean directory and create it together with the other default input files by using the dorie create command. The PFG module writes a dataset into an H5 file. The file may already exist, in which case a new dataset will be added to it. If a dataset with the intended name already exists, the script throws an error. Let's choose miller as dataset name for the dataset containing the Miller scaling factors: .. literalinclude:: parfield-miller.mini.in :language: ini :lines: 9-11 :emphasize-lines: 3 :caption: parfield.ini The scaling factors of typical Miller-similar media are log-normally distributed. A log-normal distribution is readily obtained from a normal distribution by applying the exponential function to all values. This is achieved in the PFG module by applying the exponential converter to the data: .. literalinclude:: parfield-miller.mini.in :language: ini :lines: 9,12 :emphasize-lines: 2 :caption: parfield.ini Additionally, the exponential converter can apply a scaling to the resulting distribution based on the variance of the original normal distribution. This scaling is required to obtain the same mean conductivity as for the homogeneous medium. The total transformation reads .. math:: f = \exp (x - \sigma^2), where :math:f is the final dataset value and :math:x the corresponing value of the Gaussian random field. The variance scaling can be enabled in the PFG config file: .. literalinclude:: parfield-miller.mini.in :language: ini :lines: 14-15 :emphasize-lines: 2 :caption: parfield.ini Execute the field generator via .. code-block:: bash dorie pfg parfield.ini Simulation ^^^^^^^^^^ We now have to insert the resulting field into the simulation. The :ref:parameterization file  of the Richars model (default name: richards_param.yml) contains a scaling section which defaults to none. Insert the YAML template for the :ref:Miller scaling  and specify the file path and dataset path/name. In our current example, we use the default grid of :math:100 \times 100 cells on a :math:1 \text{m} \times 1 \text{m} domain in both the PFG and the simulation, so we can set the interpolation to nearest, and leave out offset and scale completely: .. literalinclude:: richards_param_miller.yml :language: yaml :lines: 14-20 :emphasize-lines: 2-7 :caption: richards_param.yml Now execute the simulation: .. code-block:: bash dorie run config.ini The following screenshot shows the saturated conductivity field (left) and the flux magnitude after 15 time steps (right). .. image:: https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/wikis/uploads/1e2f4028dc1ed54ccaf3d0f9d477911c/miller.png :alt: ParaView screenshot of simulation result. .. admonition:: Input files ================= ========================================================== PFG Configuration :download:parfield.ini <3-parfield-miller.ini> Configuration :download:config.ini <3-config-miller.ini> Parameters :download:richards_param.yml  ================= ========================================================== Use Case: Heterogeneous Medium ------------------------------ In contrast to the continuous approach of Miller-similarity, soil architecture can feature sharp material interfaces at the scale of interest. To produce random structures with this quality, we can use the parameter field generator (PFG) module to build a :ref:mapping dataset  from a random field. Every integer entry of this dataset will then determine the parameter set of the medium at the respective grid cell. Field Generation ^^^^^^^^^^^^^^^^ To clarify what the resulting field is used for, set the output file and dataset names, .. literalinclude:: parfield-het.mini.in :language: ini :lines: 9-11 :emphasize-lines: 2-3 :caption: parfield.ini To compute the mapping dataset from the Gaussian random field for two media with indices :math:i_a and :math:i_b, respectively, the transformation is achieved by "cutting the distribution in half," .. math:: f = \begin{cases} i_a \quad \text{if } x > 0, \\ i_b \quad \text{else}. \end{cases} Notice that the variance setting has therefore no effect on the resulting distribution. The converter for this and the indices can be readily selected in the PFG configuration file: .. literalinclude:: parfield-het.mini.in :language: ini :lines: 9,12,13-15 :emphasize-lines: 2,5 :caption: parfield.ini Execute the PFG module, .. code-block:: bash dorie pfg parfield.ini Simulation ^^^^^^^^^^ In the simulation configuration file (default: config.ini), select the mapping dataset inside the output H5 file to insert the medium mapping: .. literalinclude:: config-het.mini.in :language: ini :lines: 9-11 :emphasize-lines: 2-3 :caption: config.ini Now make sure that the indices chosen for the converter in the parfield.ini have valid parameter set entries in the :ref:parameterization file  of the Richards model. By default, index 0 maps to sand and index 1 maps to silt: .. literalinclude:: ../../default_files/richards_param.yml :emphasize-lines: 2-3,14-15 :language: yaml :caption: richards_param.yml Execute the simulation: .. code-block:: bash dorie run config.ini The following screenshot shows the water content (left) and the flux magnitude (right) after 14 time steps. .. image:: https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/wikis/uploads/8ddc2e24341b21100aca6a1037009893/heterogeneous.png :alt: ParaView screenshot of simulation result. .. admonition:: Input files ================= ================================================================== PFG Configuration :download:parfield.ini <3-parfield-heterogeneous.ini> Configuration :download:config.ini <3-config-heterogeneous.ini> Parameters :download:richards_param.yml  ================= ==================================================================