********************************* Boundary Condition Datafile Guide ********************************* .. contents:: :depth: 3 Overview ======== The boundary condition datafile consists of two parts. First, the spatial segmentation of the boundaries is specified. Then, the actual boundary conditions are stated for all of the specified segments. They include information on the boundary condition type and the associated value, as well as the time from which on the stated condition is applied (time stamp). .. note:: The semantics of the datafile changes if ``boundary.interpolateBCvalues = true`` is invoked in the parameter file. Boundary Condition Types ------------------------ DORiE currently supports four types of boundary conditions: Dirichlet +++++++++ .. object:: dirichlet Set a fixed matric head [m] at the boundary. Neumann +++++++ .. object:: neumann Set a fixed volumetric flux [m/s] at the boundary. Positive values imply fluxes out of the domain, negative values imply fluxes into the domain. Limited Influx ++++++++++++++ .. object:: limited_influx Set a volumetric flux [m/s] at the boundary (Neumann BC). Fluxes into the domain are stopped as soon as the matric head at the respective boundary segment reaches :math:`h_m \geq 0.0 \, \text{m}`. Evaporation +++++++++++ .. object:: evaporation Set a volumetric flux [m/s] (Neumann BC) and a fallback matric head [m] (Dirichlet BC) at the boundary. The Neumann BC is invoked as long as the water content inside the soil can sustain the flux. Before every time step, the numeric flux caused by the given Dirichlet BC is estimated. If it is lower than the given Neumann flux, the Dirichlet BC is applied. Datafile Structure ================== Boundary Segmentation --------------------- :: spatial_resolution_ ... In 2D, the spatial segmentation is fairly simple. The boundary is split into four parts, North, South, West and East. For each of these parts, we specify how many segmentation values will be stated, followed by the values themselves. The segmentation is applied along the respective spatial base vector (e.g. from West to East for the Northern and Southern boundaries). .. note:: ``value_count = 0`` means that the respective boundary is one segment for which an explicit BC has to be specified. To split a northern boundary with a length of 3 m into three equidistant segments, we need to define :: spatial_resolution_north 2 1.0 2.0 .. object:: No Flow Boundary To apply a Neumann BC with flux :math:`j=0 \, \text{ms}^{-1}` to a boundary without any segmentation, set ``value_count = -1``. This boundary will **not** be considered in the `Boundary Condition Specification`_. In 3D, every boundary is defined by two adjacent borders. By segmenting the borders, the boundary is split up into rectangles, for each of which a boundary condition has to be specified. To split a northern boundary of a cubic domain with an edge length of 2 m into four squares, we need to define :: spatial_resolution_north_fb 1 1.0 spatial_resolution_north_we 1 1.0 No Flow Boundaries are possible here as well. Notice that this definition has to be consistent for every boundary. DORiE will throw an error if you try to segment a border of one boundary if the other border is defined as No Flow Boundary. Number of Time Stamps --------------------- :: number_BC_change_times Specify the number of time stamps for which BCs will be defined. .. note:: Every line is counted as one time stamp, even if two subsequent lines define BCs for the same time, as in the case of BC value interpolation. Boundary Condition Specification -------------------------------- The boundary conditions have to be defined **for every segment** and **in every time stamp**. Boundary conditions and their respective values are separated by single whitespaces. All BC specifications for one time stamp have to be stated in the same line. BCs between adjacent borders are not interpolated and thus not steady. These lines follow a simple grammar: .. productionlist:: bc bc_line: time { group }* time: `float` group: ( bc_type1 `float` ) | ( bc_type2 `float` `float` ) bc_type1: "neumann" | "dirichlet" | "limited_influx" bc_type2: "evaporation" The boundary conditions defined here are parsed in the same order as the boundary segments have been specified. In 3D, the rectangular boundary segments are parsed in a tabular fashion, where columns run faster than rows. Columns are defined along the first direction specified in the `Boundary Segmentation`_, and rows are defined along the second direction. .. figure:: figures/quickstart-bcfile-segm1.png :width: 40 % :align: left Spatial segmentation of the northern boundary for the example stated in `Boundary Segmentation`_ (top view). ``x`` points towards the east-west direction and ``y`` towards the front-back direction. Red numbers indicate the order in which the boundary conditions for the respective segment have to be stated. If ``boundary.interpolateBCvalues = true`` is invoked in the parameter file, subsequent BCs **of the same type** will be linearly interpolated. In order to change the BC type for a certain boundary segment, the respective time stamp has to be stated twice: :: 0 neumann -1e-6 [...] 2000 neumann -5e-6 [...] 2000 dirichlet 0.0 [...] This will linearly interpolate the Neumann BC values for :math:`0 \leq t < 2000` between :math:`j(t=0) = -1 \cdot 10^{-6} \, \text{ms}^{-1}` and :math:`j(t=2000) = -5 \cdot 10^{-6} \, \text{ms}^{-1}`, and switch the BC type to Dirichlet at :math:`t=2000`. DORiE will throw an error if you choose subsequent time stamps which cannot be interpolated. Notice that the second line is syntactically valid for disabled interpolation as well, although it has no effect then. Example Files ============= Simple Boundary Condition datafiles can be created with the command ``dorie create``. Exemplary BC File for Infiltration (2D) --------------------------------------- .. include:: default_files/2d_infiltr.bcdat :code: ini Exemplary BC File for Infiltration (3D) --------------------------------------- .. include:: default_files/3d_infiltr.bcdat :code: ini Code Documentation ================== The readout of the boundary condition datafile and the handling of the associated data are managed by a single class. .. doxygenclass:: Dune::Dorie::RectangularGrid :members: :private-members: :undoc-members: