# Boundary Conditions

Boundary conditions represent the *super-scale physics*, the forcing of the
(larger-scale) sourrounding system onto the simulated system.
After specifying the boundary segmentation when creating and mapping a
grid, we are able to define the actual conditions applied at
each segment. Like the parameterization data file,
the boundary condition data file is a YAML file. Boundary segments are
associated with their boundary conditions by means of the segment indices.

## Boundary Condition File

The file determines the boundary conditions at certain times for each boundary
segment. Its file path must be given via the key `boundary.file`

in the
config file.

After stating a certain boundary segment, the conditions are listed. The index is the boundary segment index specified in the grid mapping. A boundary condition generally consists of a type, a time interval, and a value. The latter two may be stated as sequences of values. This way, the time interval may be limited, or a boundary condition may be interpolated between the specified times. Certain types of boundary conditions may require additional keys.

```
<boundary-name>:
index: <int>
conditions:
<cond-1>:
time: <scalar or sequence>
type: <string>
value: <scalar or sequence>
# ... more conditions
# ... more boundaries
default:
type: <string>
value: <scalar>
```

### Default Condition

The `default`

boundary condition is the only required condition. It lacks
a time specification and is inserted whenever a boundary condition is missing.
This can happen if a certain time interval remains uncovered by the stated
conditions, or a boundary condition is missing from the file (which is allowed
and will not produce warnings).

### Time Intervals

When stating several boundary conditions on a boundary segment, all but the
(temporally) final condition must have a time *interval*, i.e., the value of
`time`

must be a sequence of two values. The final condition is automatically
extended until the end of the simulation.

Boundary conditions of the same boundary segment must not overlap in time. If you wish one condition to follow exactly after the other, make sure that the end of the first interval matches the start of the second interval exactly.

Boundary conditions whose time intervals start and end with the same time, or lie completely outside the simulation time interval, are ignored. The only exception occurs when computing an initial condition from the stationary problem. In this case, the earliest boundary condition which overlaps with the simulation start time is chosen. In particular, its time interval may only consist of the simulation start time stamp. See the docs of the stationary initial condition type for an example.

Note

DORiE automatically adjusts its time steps to match a change in boundary conditions.

### Value Interpolation

Boundary condition values can be linearly interpolated between the begin and
end time of the condition. To that end, one may use a sequence of two values
as `value`

. The standard time step scheme is second order in time and space
and hence suitable for linear interpolation of boundary conditions.

## Boundary Condition Types

A boundary condition has the following template:

```
time: <scalar or sequence>
type: <string>
value: <scalar or sequence>
# <additional keys>
```

### Dirichlet

A Dirichlet boundary conditions determines the exact value of the solution at the boundary.

- Richards Model
Quantity: Matric head \(h_m \, [\text{m}]\).

Tip

Typical use cases for Dirichlet conditions in a Richards Model include:

Height above a fixed water table at the lower boundary.

Evaporative potential at upper boundary, if \(h_m < z_\text{wt}\), where \(z_\text{wt}\) is the height above the water table.

- Transport Model
Quantity: Total concentration \(C_t\,[\text{kg}\,\text{m}^{-d}]\) or concentration in the water phase \(C_w\,[\text{kg}\,\text{m}^{-d}]\), depending on the value of

`concentration_type`

. The integer \(d\) denotes the spatial dimension.- Variables
`type`

:`Dirichlet`

`value`

: Quantity as specified above.`concentration_type`

**(Transport only)**: Switch between`total`

(\(C_t\)) or`water_phase`

(\(C_w\)) concentration as defined above.

### Neumann

A Neumann boundary condition determines the value of target quantity flux at the boundary.

- Richards Model
Quantity: Water flux \(\mathbf{j}_w \, [\text{ms}^{-1}]\).

Precipitation and evapotranspiration fluxes are typically measured with respect to a flat surface. For modeling these fluxes, the

`horizontal_projection`

key is used, which scales the flux applied to the boundary with its inclination with respect to the direction of gravitational force,\[j_{N, \text{scaled}} = \left| \mathbf{\hat{n}} \cdot \mathbf{\hat{g}} \right| j_N .\]Note

Hydraulic conductivity decreases with water content. Evaporation fluxes must not infinitely exceed the stable limit, or else the solver will inevitably fail.

- Transport Model
Quantity: Solute flux \(\mathbf{j}_s \, [\text{kg}\,\text{m}^{-d+1}\,\text{s}^{-1}]\), where \(d\) indicates the spatial dimensions.

- Variables
`type`

:`Neumann`

`value`

: Flux perpendicular to the surface \(j_N\), in the quantities defined above. Fluxes into the domain are negative, fluxes out of the domain positive.`horizontal_projection`

**(Richards only)**: Boolean if the actual boundary flux should be scaled with the surface inclination against the direction of gravity.

### Outflow

An outflow boundary condition only allows flow out of the domain.

- Richards Model
Quantity: Matric head \(h_m \, [\text{m}]\) .

The outflow boundary condition is a variant of the Dirichlet boundary condition. It applies the specified matric head only if it leads to a net flux out of the domain. Otherwise, the flux is set to zero (no flow boundary condition).

- Transport Model
Quantity: Solute flux \(\mathbf{j}_s \, [\text{kg}\,\text{m}^{-d+1}\,\text{s}^{-1}]\), where \(d\) indicates the spatial dimensions.

The outflow boundary condition allows solute be transported throw the boundary by the water flux. As solute concentration and water flux are only modelled inside the domain, this effectively only allows the solute to leave the domain and be discarded. The boundary condition value is an additional solute flux for which all considerations of a Neumann boundary condition apply (see above).

The total solute flux through the boundary is then given by

\[j_s = \left| \mathbf{j}_s \cdot \mathbf{\hat{n}} \right| + j_N ,\]where \(\mathbf{j}_s = C_w \mathbf{j}_w\) is the solute flux at the boundary, \(\mathbf{\hat{n}}\) is the boundary unit normal vector and \(j_N\) is the flux perpendicular to the surface as specified in the boundary condition

`value`

. This flux is applied in addition to regular seepage through the boundary. It is recommended to set this value to 0 (zero).- Variables
`type`

:`Outflow`

`value`

: Matric head \(h_m\) or solute flux perpendicular to the surface \(j_N\) in quantities defined above, depending on the model.

## Example Files

DORiE provides a set of example files which can be placed into any directory
using the `dorie create`

command of the
Command Line Interface.

Using the default mapping of a rectangular grid, the default boundary condition
file for the Richards model yields a strong infiltration flux at the upper
boundary and a water table at the lower boundary, while all other boundaries
are impermeable. The `horizontal_projection`

parameter ensures that the given
value is the rainfall per unit area in case the surface is tilted or
irregularly shaped.

```
upper:
index: 1
conditions:
heavy_rainfall:
type: Neumann
time: 0
value: -5.55e-6
horizontal_projection: true
lower:
index: 0
conditions:
water_table:
type: Dirichlet
time: 0
value: 0
default:
type: Neumann
value: 0
```

The default boundary condition file for the Transport model yields a constant concentration of solute at the upper boundary, similar to a homogeneous tracer in the fluid. All other boundaries employ outflow conditions.

```
upper:
index: 1
conditions:
tracer:
type: Dirichlet
time: 0
value: 1
concentration_type: water_phase
default:
type: Outflow
value: 0
```