# 4. 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.

## 4.1. Basics

The random field generator creates a set of random numbers on a physical domain. The random variable $$X$$ itself follows a Gaussian (normal) distribution with mean $$\mu = 0$$ and a selectable variance $$\sigma^2$$,

$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 Configuration File Guide. The module is called via the Command Line Interface.

## 4.2. 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 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.

### 4.2.1. Field Generation

We will alter the work flow of the first tutorial by executing the parameter field generator (PFG) module in the 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:

parfield.ini
[general]
outputFile = field.h5
dataset = miller


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:

parfield.ini
[general]
converter = exponential


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

$f = \exp (x - \sigma^2),$

where $$f$$ is the final dataset value and $$x$$ the corresponing value of the Gaussian random field. The variance scaling can be enabled in the PFG config file:

parfield.ini
[converter.exponential]
varianceScaling = true


Execute the field generator via

dorie pfg parfield.ini


### 4.2.2. Simulation

We now have to insert the resulting field into the simulation. The 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 Miller scaling and specify the file path and dataset path/name. In our current example, we use the default grid of $$100 \times 100$$ cells on a $$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:

richards_param.yml
scaling:
type: Miller
data:
scale_miller:
file: field.h5
dataset: miller
interpolation: nearest


Now execute the simulation:

dorie run config.ini


The following screenshot shows the saturated conductivity field (left) and the flux magnitude after 15 time steps (right).

Input files

 PFG Configuration parfield.ini Configuration config.ini Parameters richards_param.yml

## 4.3. 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 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.

### 4.3.1. Field Generation

To clarify what the resulting field is used for, set the output file and dataset names,

parfield.ini
[general]
outputFile = mapping.h5
dataset = index_map


To compute the mapping dataset from the Gaussian random field for two media with indices $$i_a$$ and $$i_b$$, respectively, the transformation is achieved by “cutting the distribution in half,”

$\begin{split}f = \begin{cases} i_a \quad \text{if } x > 0, \\ i_b \quad \text{else}. \end{cases}\end{split}$

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:

parfield.ini
[general]
converter = binary

[converter.binary]
indices = 0 1


Execute the PFG module,

dorie pfg parfield.ini


### 4.3.2. Simulation

In the simulation configuration file (default: config.ini), select the mapping dataset inside the output H5 file to insert the medium mapping:

config.ini
[grid.mapping]
file = mapping.h5
volume = index_map


Now make sure that the indices chosen for the converter in the parfield.ini have valid parameter set entries in the parameterization file of the Richards model. By default, index 0 maps to sand and index 1 maps to silt:

richards_param.yml
volumes:
sand:
index: 0
richards:
type: MvG
parameters:
alpha: -2.3
n: 4.17
k0: 2.2E-5
theta_r: 0.03
theta_s: 0.31
tau: -1.1

silt:
index: 1
richards:
type: MvG
parameters:
alpha: -0.7
n: 1.3
k0: 1.0E-5
theta_r: 0.01
theta_s: 0.41
tau: 0.0

scaling:
type: None


Execute the simulation:

dorie run config.ini


The following screenshot shows the water content (left) and the flux magnitude (right) after 14 time steps.

Input files

 PFG Configuration parfield.ini Configuration config.ini Parameters richards_param.yml