********* Cook Book ********* .. contents:: :depth: 3 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. Prerequisites ------------- Before you start, make sure that :doc:`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 :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:`quickstart-parameters` 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:`quickstart-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 `. * *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. 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 `! 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 `. *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 [output] 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 :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 [grid] 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 [initial] 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 ----------------- Examples ======== .. _Paraview: http://www.paraview.org/download/ .. _Gmsh: http://gmsh.info