Cook Book


This part of the documentation is intended for first-time DORiE users. It explaines the basic usage of the program, how to execute a simulation and how to analyze its results. It will also showcase more complex features like Adaptive Grid Refinement.


Before you start, make sure that DORiE is installed correctly. To analyze DORiE’s results to their full extend, install Paraview. DORiE will create rectangular grids according to user specifications on the fly, using the DUNE GridFactory. For building simplex grids in two or three dimensions, you can use Gmsh. Its .msh files can be read directly into DORiE to run simulations on.

DORiE Input Files

DORiE needs multiple input files to work:

  • Parameter File: (.ini) Supplying static information on the simulation. Have a look at the DORiE Configuration File Guide for more information on the file syntax, or default and possible values.
  • Boundary Condition Datafile: (.bcdat) Specifying the boundary conditions dependent on time and space.Name (and path) of the desired file have to be stated in the Parameter File at key boundary.file. The Boundary Condition Datafile Guide supplies information on how write and use the BC Datafile.
  • Optional Mesh File: (.msh) Representing the grid on which the simulation will run. This file is only required if grid.gridType = simplex is chosen in the Parameter File. The Path to the file and it’s name will then have to be stated at grid.gridFile. Use Gmsh to easily create such a file.

DORiE Output Files

DORiE places its output into the directory defined at output.outputPath.

  • Time Stamp File: (.pvd) Containing the time information for the respective VTK output files. Load this file into Paraview to analyze the entire output of DORiE. This file is always saved in the directory from which DORiE is executed!
  • VTK Output Files: (.vtu) Containing the grid and the solution for a single time step. The solution contains information on the Matric Head (head, scalar), the Volumetric Water Content (theta_w, scalar), the Water Saturation (Theta, scalar), the Volumetric Water Flux (flux, vector), and the Saturated Hydrolic Conductivity (K_0, scalar). The files can be visualized using Paraview or the DORiE VTK Parser.
  • Optional Random Field Data (.h5 or .dat) Information on the Random Field created for a run. If the randomField values match the ones of the saved files, the Random Field is loaded from these files instead of being computed again.
  • Optional Parallel Collection Files (.pvtu) Containing information on combining .vtu-files from different processes, if DORiE was executed in parallel (feature pending).

First Steps

In this section, we will recreate some simulations conducted by Kurt Roth, the results of which are displayed in his Soil Physics Lecture Notes, Chapter 6.3.1.


To keep everything in order, create a new folder for the input and output files. How to get those? Let’s simply make use of the Parameter Scraper!

To create a set of dummy input files, open up a terminal in your newly created folder and execute

dorie create

This will create a parameter.ini file and two BC datafiles, one for each supported spatial dimension. We will tweak these to match the simulations depicted at Figure 6.19. To do so, make sure you understand the Parameter File syntax.

We will only mention parameters relevant for the problems at hand, so leave the ones not appearing in this guide as they are by default!

Output Definition

Let’s begin with the output. We want the program to give us at least some output on what it’s doing, so we should increase verbosity. As output path we chose a new subdirectory which will automatically be created by DORiE. We will first simulate the sand, so we will call our results that way:

verbose = 1
outputPath = ./sand
fileName = sand

Grid Creation

Let’s begin with the spatial extensions. The point of origin in DORiE’s reference frame is located at the lower left (front) point of the domain. In 2D, the x-direction points to the right, and the y-direction upwards. In 3D, the x-direction points to the right, the y-direction points backwards, and the z-direction points upwards. Notice that DORiE does not support negative coordinates!

The simulation by Roth is one dimensional, but DORiE only supports two dimensions. For now, we leave the extension in x-direction at \(1 \, \text{m}\). For the y-direction, we notice that \(y_\text{DORiE} = -z_\text{Roth}\), so we set this extension to \(4 \, \text{m}\).

Now we have to fill a domain of this size with rectangular grid cells by specifying the number of cells into each direction. For the x-direction, we will set this to 1, as the simulation is symmetrical along this axis. For the y-direction, we choose a reasonable resolution of \(2 \, \text{cm}\) per cell, meaning that we need 200 cells in total.

extensions = 1 4
cells = 1 200

Initial Condition

The Initial Condition should be a stable situation (\(\partial h_m / \partial y = -1\)) with a fixed water table (\(h_m = 0 \, \text{m}\)) at the lower (south) boundary.

condition = hydrEquilibrium
headLower = 0
headGradient = -1

Boundary Conditions

The Boundary Condition Datafile supplied by dorie create already contains everything we need.