man-cookbook.rst 6.02 KB
Newer Older
Dion Haefner's avatar
Dion Haefner committed
1 2 3 4 5 6 7 8 9
Cook Book

.. contents::
	:depth: 3

This part of the documentation is intended for first-time DORiE users. It explains 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.
Dion Haefner's avatar
Dion Haefner committed
11 12 13

Before you start, make sure that :doc:`DORiE is installed correctly <man-installation>`. 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 :file:`.msh` files can be read directly into DORiE to run simulations on.
Dion Haefner's avatar
Dion Haefner committed
15 16 17 18 19

DORiE Input Files
DORiE needs multiple input files to work:

20 21
* **Parameter File:** (:file:`.ini`) Supplying static information on the simulation. Have a look at the :doc:`man-config-file` for more information on the file syntax, or default and possible values.
* **Boundary Condition Datafile:** (:file:`.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 :doc:`man-bcfile` supplies information on how write and use the BC Datafile.
Dion Haefner's avatar
Dion Haefner committed
22 23 24 25 26 27
* *Optional* **Mesh File:** (: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:** (: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!
Dion Haefner's avatar
Dion Haefner committed
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
* **VTK Output Files:** (:file:`.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 :ref:`DORiE VTK Parser <plot_vtk>`.
* *Optional* **Random Field Data** (:file:`.h5` or :file:`.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** (:file:`.pvtu`) Containing information on combining :file:`.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 :doc:`Parameter Scraper <python-dorie-parscraper>`!

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

.. code-block:: shell

	dorie create

This will create a :file:`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 :ref:`Parameter File syntax <inifile-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:

.. code-block:: none

	logLevel = info
Dion Haefner's avatar
Dion Haefner committed
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
	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 :math:`1 \, \text{m}`. For the y-direction, we notice that :math:`y_\text{DORiE} = -z_\text{Roth}`, so we set this extension to :math:`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 :math:`2 \, \text{cm}` per cell, meaning that we need 200 cells in total.

.. code-block:: none
	extensions = 1 4
	cells = 1 200

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

.. code-block:: none
	condition = hydrEquilibrium
	headLower = 0
	headGradient = -1

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

Executing the Program

Analyzing Results


.. _Paraview:
.. _Gmsh: