Commit b506eee7 authored by Lukas Riedel's avatar Lukas Riedel

Rewrite cook book introduction and remove first example

parent 72f297ce
*********
Cook Book
*********
.. contents::
:depth: 3
The Cook Book
*************
Introduction
============
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.
This part of the documentation guides through increasingly complicated
use-cases of DORiE. It is intended for users who wish to jump right into using
DORiE, without much knowledge of all its functions. The relevant manual pages
will be linked on the way.
Prerequisites
-------------
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.
DORiE Input Files
-----------------
DORiE needs multiple input files to work:
* **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.
* *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!
* **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 <http://www.iup.uni-heidelberg.de/institut/forschung/groups/ts/soil_physics/students/lecture_notes05>`_, Chapter 6.3.1.
Preparations
------------
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:
You need a working application. You can either use the image shipped via
`Docker Hub <https://hub.docker.com/r/dorie/dorie/>`_ or use a local
installation. See the :doc:`installation manual <man-installation>` for
details. Additionally, install Paraview_ for analyzing the output.
.. code-block:: none
Data I/O
--------
[output]
verbose = 1
outputPath = ./sand
fileName = sand
Let's start with the files required for running DORiE and the data that can
be retrieved!
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!
Input Files
^^^^^^^^^^^
Templates for the required files can conveniently be generated with the
:doc:`CLI <python-dorie-wrapper>`.
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}`.
* :doc:`Configuration File <man-config-file>` (``.ini``):
The main input file for the solver. Template: ``config.ini``
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.
* :ref:`Parameterization Data File <man-parameter_file>` (``.yml``):
Specifies the soil parameterization type(s) and parameters.
Template: ``param.yml``
.. code-block:: none
[grid]
extensions = 1 4
cells = 1 200
* :doc:`Boundary Condition Data File <man-bcfile>` (``.bcdat``):
Specifies the boundary segmentation and the boundary conditions.
Templates: ``2d_infiltr.bcdat``, ``3d_infiltr.bcdat``
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.
* :ref:`GMSH Mesh File <man-grid_gmsh>` (optional): Mesh with possibly
complicated geometry to build an unstructured grid from.
.. code-block:: none
[initial]
condition = hydrEquilibrium
headLower = 0
headGradient = -1
* :ref:`Grid Mapping H5 File <man-grid_mapping-dataset>` (optional):
Used to generate heterogeneous soil architectures and boundary segmentations
for rectangular grids.
Boundary Conditions
^^^^^^^^^^^^^^^^^^^
The Boundary Condition Datafile supplied by ``dorie create`` already contains everything we need.
* :ref:`Scaling Field H5 Files <man-parameter_sclaing>` (optional):
Datasets for interpolating local heterogeneities in the parameterization.
Executing the Program
---------------------
Output Files
^^^^^^^^^^^^
* Time Stamp File (``.pvd``): Lists the time step information and the
respective VTK output files of a single program run. This file is always
saved into the directory from which DORiE was executed.
Analyzing Results
-----------------
* VTK Files (``.vtu``): The output data in unstructured grid format.
It contains multiple datasets:
- ``head``: Matric head
- ``K0``: Saturated conductivity
- ``flux``: Water flux (not reconstructed!)
- ``theta_w``: Volumetric water content
- ``Theta``: Water saturation
Examples
========
* VTK Parallel Collection Files (``.pvtu``): Merging multiple VTK files in case
DORiE is run in parallel.
.. _Paraview: http://www.paraview.org/download/
.. _Gmsh: http://gmsh.info
\ No newline at end of file
.. _Gmsh: http://gmsh.info
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment