BASEMENT Reference Manual: Description of Command File Structure and Parameters

Please read the INTRODUCTION first

Input block structure

PROJECT
DOMAIN
PARALLEL
PHYSICAL_PROPERTIES
BASECHAIN_1D
GEOMETRY
HYDRAULICS
PARAMETER
SECTION_COMPUTATION
FRICTION
BOUNDARY
INITIAL
SOURCE
EXTERNAL_SOURCE
INNER_BOUNDARY
TIMESTEP
MORPHOLOGY
PARAMETER
BEDMATERIAL
GRAIN_CLASS
MIXTURE
SOIL_DEF
LAYER
SOIL_ASSIGNMENT
BEDLOAD
PARAMETER
FORMULA
BOUNDARY
SUSPENDED_LOAD
PARAMETER
BOUNDARY
INITIAL
SOURCE
EXTERNAL_SOURCE
INITIAL
SOURCE
EXTERNAL_SOURCE
GRAVITATIONAL_TRANSPORT
OUTPUT
SPECIAL_OUTPUT
BASEPLANE_2D
GEOMETRY
STRINGDEF
MOVABLE_BED
HYDRAULICS
PARAMETER
FRICTION
BOUNDARY
INNER_BOUNDARY
TURBULENCE_MODEL
INITIAL
SOURCE
EXTERNAL_SOURCE
MORPHOLOGY
PARAMETER
BEDMATERIAL
GRAIN_CLASS
MIXTURE
SOIL_DEF
LAYER
SOIL_ASSIGNMENT
FIXED_BED
RETENTION_MODEL
BEDLOAD
FORMULA
PARAMETER
BOUNDARY
DIRECTION
INNER_BOUNDARY
INITIAL
SUSPENDED_LOAD
PARAMETER
BOUNDARY
INITIAL
SOURCE
EXTERNAL_SOURCE
GRAVITATIONAL_TRANSPORT
SOURCE
EXTERNAL_SOURCE
APPARENT_COHESION
TIMESTEP
OUTPUT
SPECIAL_OUTPUT
VEGETATION
GROUNDWATER
FEEDBACK
BIOMASS
PARAMETER
INITIAL
BASESUB
GEOMETRY
ZONE
TIMESTEP
PARAMETER
INITIAL
BOUNDARY
MATERIAL
SOIL_DEF
ZONE
RETENTION_MODEL
SOURCE
EXTERNAL_SOURCE
OUTPUT
SPECIAL_OUTPUT
BASE_EXTERN
BOUNDARY
COUPLINGS
PARAMETER
COUPLING
HYDRAULICS
BEDLOAD
SUSPENSION
SUBSURFACE
COUPLING_LATERAL
CONTROLLER
MONITORED_VARIABLE
MANIPULATED_VARIABLE
INTRODUCTION
In this doc_BASEMENT.html file the input structure of the command file is described. The main purpose of the command file is to ensure a structured and logical definition of a simulation independent of the chosen solvers or model dimensions (1-D/2-D). It is convenient to navigate through this document by clicking on the blue colored links

Block description
This html file contains a full description of all possible blocks and variables within the command file. A general description of a block can be given as follows:
BLOCKNAME compulsory repeatable
Super Blocks: Possible super blocks are listed here
Description: Gives a short description about the use of the block and its features
Inner Blocks: Possible sub blocks are listed here

Variable type comp. condition units default values
Variable_1 string Yes
Variable_2 integer No

Root and super blocks
The command file itself is the root block called BASEMENT of any simulation. Thus the block BASEMENT must not be specified in the command file. On the first level in the command file, there are two super blocks: PROJECT and DOMAIN. The PROJECT - block contains all kind of meta - information as title, author, date, version, etc. The DOMAIN - block includes all sub - blocks for a simulation, namely the program execution mode (PARALLEL), basic physical properties (PHYSICAL_PROPERTIES), different regions for one or two dimensional simulations (BASECHAIN_1D and BASEPLANE_2D), the coupling of different subdomains (COUPLINGS) and flow control (CONTROLLER). The two superblocks BASECHAIN_1D and BASEPLANE_2D contain the setup information for simulations with BASEMENT. Although the 1-D and 2-D solver differ in certain parts concerning the needed information, the rough topics are the same and will be treated as superblocks themselves:
Syntax
Generally, the input file has an object - oriented approach. The main keywords are treated as classes and have keywords as members which can be kind of super classes again. Every such block is enclosed by two curly braces, e.g.

BLOCKNAME
{
variable_name = ...
variable_name = ...
...
    BLOCKNAME
    {
    variable_name = ...
    ...
    variable_list = (var1 var2 var3)
    // this is a comment
    }
...
}

All information within the two brackets{} belongs to the superclass. A listing of variables is always embraced by two normal brackets, even if there is just one element in the list. Note that there must be a space between opening bracket and the first element as at the end of the list between last element and closing bracket. Between elements in the list, there is also at least one space required. Comments can be placed anywhere within the input file. They are indicated with two slashes followed by a space:
//
Every information after the two slashes and the space until the end of line will be ignored. Comments over multiple lines are started by /* and ended by */:
/* comment
over multiple lines */

Auxiliary files
To not overload the command file, auxiliary input files are necessary. One of the most often used auxiliary file is the one describing a time series of a quantity, e.g. a hydrograph used as boundary condition. If the command file is demanding for an auxiliary file, a reference to its type is given in the parameter description. A typical boundary condition for the use within BASECHAIN_1D or BASEPLANE_2D uses the following Syntax:
// this is a comment
value1 value2

Example:
// Time   Q
0.000     10
50000   12
100000 11

The first line contains information about the listed parameters. This line is not read by the program. From the second line on the first row is considered to be the time [sec.] and the second row is the associated value (e.g. discharge).

List of Blocks


BASEMENT
BASEMENT compulsory repeatable
Description: In the logic of the input syntax, the BASEMENT command file represents the encapsulating root block containing the subblocks PROJECT and DOMAIN which define the setup of your simulation.
Inner Blocks: PROJECT
DOMAIN

PROJECT
PROJECT compulsory repeatable
Super Blocks: BASEMENT
Description: Contains some meta information about the setup. This is the onlyblock without further inner blocks.

Variable type comp. condition units default values
title string no - - unnamed_project Chars [a-zA-Z0-9_-] are allowed
author string no - - anonymous_author Chars [a-zA-Z0-9_-] are allowed
date string no - - - -
real_time_factor real no - - - x > 0

Description of Variables

title - The title of the project as a string without any whitespace.
author - Name of the autor without any withespace.
date - Date of creation of the file.
real_time_factor - The real time factor multiplication which allows to execute BASEMENT with a predefined speed. If this factor is set to 1.0, than the simulation is slowed down artificially to run in real time! Be careful when using this factor because it can extremely slow down your simulation.

Example

PROJECT
{
   title = Alpenrhein   // note: Alpenrhein Delta would not work
                        // write Alpenrhein_Delta instead
   author = MeMyselfAndI
   date = 23.2.2010
}
DOMAIN
DOMAIN compulsory repeatable
Super Blocks: BASEMENT
Description: Defines the whole computational area and connects different specific areas.
Inner Blocks: PARALLEL
PHYSICAL_PROPERTIES
BASECHAIN_1D
BASEPLANE_2D
BASESUB
BASE_EXTERN
COUPLINGS
CONTROLLER

Variable type comp. condition units default values
multiregion string no - - unnamed_multiregion Chars [a-zA-Z0-9_-] are allowed

Block Usage

Multriregion is just the name for the overall area, e.g. Rhine river. Specific areas within the Rhine could be Rhinedelta (2D) and Alp-Rhine (1D). The Domain is primarily used to connect different computations and regions with each other.

Description of Variables

multiregion - Name of the whole computation area, including all 1D and 2D regions.

Example

PROJECT
{
   [...]
}
DOMAIN
{
   multiregion = Rhein
   PHYSICAL_PROPERTIES
   {
      [...]
   }
   PARALLEL
   {
      [...]
   }
   BASECHAIN_1D
   {
      [...]
   }
   BASEPLANE_2D
   {
      [...]
   }
   BASESUB
   {
		 [...]
   }   BASE_EXTERN
   {
      [...]
   }
}
PARALLEL
PARALLEL compulsory repeatable
Super Blocks: BASEMENT > DOMAIN
Description: This block defines parameters concerning the parallel execution of BASEMENT. It has to be defined only for simulations on multi-core shared memory systems when multiple cores shall be used.

Variable type comp. condition units default values
number_threads integer no - - 1 -

Description of Variables

number_threads - The number of threads usually equals the number of used cores, although the final mapping of the threads on the cores is managed by the operating system.

Example

PARALLEL
{
   number_threads = 2   // on dual core system
}
PHYSICAL_PROPERTIES
PHYSICAL_PROPERTIES compulsory repeatable
Super Blocks: BASEMENT > DOMAIN
Description: Some universally valid properties for all computational areas to follow are defined here.

Variable type comp. condition units default values
gravity real no - [m/s2] 9.81 x >= 0
viscosity real no - [m2/s] 1e-06 x >= 0
rho_fluid real no - [kg/m3] 1000 x >= 0

Description of Variables

gravity - Acceleration due to gravity
viscosity - Kinematic viscosity
rho_fluid - Fluid density

Example

PHYSICAL_PROPERTIES
{
   gravity = 9.81
   viscosity = 0.000002
   rho_fluid = 1000
}
BASECHAIN_1D
BASECHAIN_1D compulsory repeatable
Super Blocks: BASEMENT > DOMAIN
Description: This block includes all information for a 1D simulation.
Inner Blocks: GEOMETRY
HYDRAULICS
TIMESTEP
MORPHOLOGY
OUTPUT

Variable type comp. condition units default values
region_name string yes - - - Chars [a-zA-Z0-9_-] are allowed

Block Usage

The main block declaring a 1D simulation is called BASECHAIN_1D within the DOMAIN-block. It contains all information about the precise simulation. To ensure a homogeneous input structure, the sub blocks for BASECHAIN_1D and BASEPLANE_2D are roughly the same.
A first distinction is made for geometry, hydraulic and morphologic data as the user is not always interested in both results of fluvial and morphological simulation. The geometry however is independent of the choice of calculation. Inside the two blocks (hydraulics and morphology), the structure covers the whole field of numerical and mathematical information that is required for every computation.
These blocks deal with boundary conditions, initial conditions, sources and sinks, numerical parameters and settings and output-specifications. Be aware of a slightly different behaviour of the sub blocks dependent on the choice of 1D or 2D calculation.

Description of Variables

region_name - Name of the 1D region.

Example

DOMAIN
{
   multiregion = Rhein
   PHYSICAL_PROPERTIES
   {
      [...]
   }
   BASECHAIN_1D
   {
      region_name = Alpenrhein
      GEOMETRY
      {
         [...]
      }
      HYDRAULICS
      {
         [...]
      }
      TIMESTEP
      {
         [...]
      }
      MORPHOLOGY
      {
         [...]
      }
      OUTPUT
      {
         [...]
      }
   }
}
GEOMETRY
GEOMETRY compulsory repeatable
Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D
Description: Defines the problem topography using different input formats.

Variable type comp. condition units default values
type string no - - basement {basement}
file string yes - - - -
cross_section_order whitespace separated list of strings yes - - - -
dump_crosssections boolean no - - no {no, yes}

Description of Variables

type - Data types for cross sections: other types than the 'basement' format are not accepted any more. Please convert your projects to the 'basement' format. You can download python-scripts for the conversion from old 'funin'-type files to the 'basement' format from our website.
file - Name of the topography file containing the data of the cross sections. Within this input file, all cross sections are defined.
cross_section_order - List of names of cross sections defined within the topography file which should be used in the calculation. It is possible to use only some of the cross sections defined in the topography file and/or change their order. Actually within the cross_section_order the active cross sections are defined.
Attention: The first string in the list will be treated internally as upstream and the last string will be the downstream. This will be of further use with the boundary conditions.
dump_crosssections - During the transition from floris to the new bmg format as new grid format, this option is offered to dump a lot of information for each cross section and for each slice. This allows to inspect the internal representation of the cross section and check for any differences between the original 'floris' type file and the converted 'basement' type file (i.e. you should run a simulation using the original floris file and one simulation with the new basement file and compare the dumped cross section data). The resulting files can best be compared using a 'diff' like tool such as http://winmerge.org/.

Example

BASECHAIN_1D
{
   region_name = alpine_rhine
   GEOMETRY
   {
      file = RheinTopo.bmg
      cross_section_order = ( QP84.000 QP84.200 QP84.400 QP84.600 QP85.800 ... )
   }
}
HYDRAULICS
HYDRAULICS compulsory repeatable
Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D
Description: Defines the hydraulic specifications for the simulation. This block contains only further sub blocks but no own variables.
Inner Blocks: PARAMETER
FRICTION
BOUNDARY
INITIAL
SOURCE
INNER_BOUNDARY

Example

HYDRAULICS
{
   BOUNDARY
   {
      [...]
   }
   INNER_BOUNDARY
   {
      [...]
   }
   INITIAL
   {
      [...]
   }
   FRICTION
   {
      [...]
   }
   SOURCE
   {
      [...]
   }
   PARAMETER
   {
      [...]
   }
}
PARAMETER
PARAMETER compulsory repeatable
Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > HYDRAULICS
Description: This block contains general numerical parameters for hydraulic simulations.
Inner Blocks: SECTION_COMPUTATION

Variable type comp. condition units default values
minimum_water_depth real yes - [m] - x > 0
stretch_boundary_elem boolean no - - yes {no, yes}
riemann_solver string no - - roe {roe, upwind, hll}
simulation_scheme string no - - explicit {explicit}

Block Usage

This block contains general numerical parameters for hydraulic simulations, such as the mininum water depth and the rieman solver.

Description of Variables

minimum_water_depth - The water depth for which the channel is considered to be dry. For numerical reasons it is necessary to limit the water depth for which the flow is still computed. This is a small value and can be lowered as long as no numerical problems occur.
stretch_boundary_elem - Boundary elements are usually only half as long in flow direction as internal elements. Therefore, they often dominate the minimal required timestep. If this option is set to 'yes', the length of the boundary elements is artificially doubled for the time step determination such that they stop dominating the time step evaluation. In certain cases such as when you use a controller or two-way coupling or if the grid consists of only a few elements, this may lead to stability issues.
riemann_solver - Three different types of solvers for the Riemann problem can be chosen: the approximate Riemann solvers of Roe or Harten, Lax and van Leer (HLL) or an upwind Riemann solver.
simulation_scheme - Defines the scheme for the time integration of the simulation. At the moment 'explicit' time integratino is the only available scheme. Note: For 'implicit' time integration please refer to BASEMENT version 2.7.

Example

HYDRAULICS
{
   [...]
   PARAMETER
   {
      minimum_water_depth = 0.0001
   }
   [...]
}



HYDRAULICS
{
   [...]
   PARAMETER
   {
      simulation_scheme = explicit
      minimum_water_depth = 0.001
      riemann_solver = roe
      theta = 1
      truncation_interval_area = 0.01
      truncation_interval_discharge = 0.01
      initial_time_step = 100
      iteration_number = 8
      try_limit = 5 
      time_step_reduction = 0.2
   }
}
SECTION_COMPUTATION
SECTION_COMPUTATION compulsory repeatable
Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > HYDRAULICS > PARAMETER
Description: Specifies the mode of section computation and the necessary parameters.

Variable type comp. condition units default values
type string yes - - - {iteration, table}
internal_levees string no - - off {on, off}
precision real yes required if 'type' = 'iteration' [m2] - x > 0
min_interval real yes required if 'type' = 'table' [m] - x > 0
max_interval real yes required if 'type' = 'table' [m] - x > 0

Block Usage

In the block SECTION_COMPUTATION are defined type and parameters for the computation of hydraulic characteristics in a cross section. The available types are 'iteration' (the water level for a given wetted area is calculated iteratively and all other hydraulic parameters are computed at each time step) or 'table' (a table is created at the beginning and during the computation all necessary values are interpolated from the table). For the iteration type the precision of the result has to be indicated. For the table type the maximum and minimum interval between water levels for the computation of the table have to be declared. In case of morphologic simulations, an update of the table is triggered dependend on the change of the soil elevation. This parameter can be set within the MORPHOLOGY->PARAMETER block. Low values for this Parameter will lead to a drastic augmentation of the simulation time as the table is updated every timestep.

Description of Variables

type - Determination type for hydraulic state variables in the cross section.
internal_levees - If this value is set to 'on', the forlands are considered to be wetted only if the waterlevel is higher than both limits of the main channel. This has an influence if there are internal levees in the cross section
precision - The maximum difference between given and calculated wetted area in iterative determination of water surface elevation.
min_interval - Minimum interval between water surface elevations for table calculation.
max_interval - Maximum interval between water surface elevations for table calculation. During initialization,max_interval - min_interval is used as the initial interval to populate the water surface elevation table.

Example

PARAMETER
{
   [...]

   SECTION_COMPUTATION
   {
      type = table
      min_interval = 0.05
      max_interval = 0.2
   }
   SECTION_COMPUTATION
   {
      type = iteration
      precision = 0.001
   }
}
FRICTION
FRICTION compulsory repeatable
Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > HYDRAULICS
Description: The block deals with all influences on the source term in the equations concerning the friction.

Variable type comp. condition units default values
type string no - - strickler {strickler, manning}
default_friction real yes - - - x >= 0
grain_size_friction boolean no - - no {no, yes}
strickler_factor real no used if 'grain_size_friction' = 'no' - 21.1 x > 0
roughness_factor real no used if 'grain_size_friction' = 'no' - 3.0 x > 0

Block Usage

In this block the default type of the friction law (keyword type) and the default value of friction (keyword default_friction) have to be declared. These values will be over written by values declared in the topography file. At the moment, only Strickler is available as friction concept! If there is a MORPHOLOGY and a BEDMATERIAL block, it is also possible to have the program compute a friction considering the grain sizes of the soil. To apply this, the parameter grain_size_friction has to be set to 'yes'. The computation from the d90 of the present grain mixture in the transport active zones (bed bottom) is computed with the relation RI-1.25. The factor is usually 21, but it can be set by the user using the keyword strickler_factor.

Description of Variables

type - Friction laws: 'strickler' for Strickler values, 'manning' for Manning values. No other friction laws are available for 1D at the moment.
default_friction - The default friction is used for all elements where no explicit friction value has been supplied.
grain_size_friction - This option activates the calculation of the bed friction using the grain size. By default, this is set to 'no'. This approach makes only sense when bedload transport is active and therefore, grain sizes are changing in time. However, it is a experimental feature. Furthermore, it is not best suited for calibrating a simulation.
strickler_factor - Factor for the computation of the friction value from the grain diameter: Kstr = strickler_factor/(d90^1/6).
roughness_factor - Factor for the computation of the friction value from the grain diameter: ks = roughness_factor * d90.Default is 3.0.

Example

HYDRAULICS
{
   [...]
   FRICTION
   {
      type = strickler
      default_friction = 30
      grain_size_friction = no
   }
   [...]
}
BOUNDARY
BOUNDARY compulsory repeatable
Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > HYDRAULICS
Description: Defines boundary conditions for hydraulics. For every different condition, a new block BOUNDARY has to be used.

Variable type comp. condition units default values
name string no - - - Chars [a-zA-Z0-9_-] are allowed
string string yes - - - {upstream, downstream}
type string yes - - - {hydrograph, coupling_hydrograph, zero_gradient, coupling_zero_gradient, weir, coupling_weir, wall, gate, coupling_gate, hqrelation, coupling_hqrelation, zhydrograph, coupling_zhydrograph, coupling_connection}
file string no used if 'type' = 'hydrograph' or 'zhydrograph' or 'coupling_zhydrograph' or 'hqrelation' or 'coupling_hqrelation' - - -
precision real no used if 'type' = 'hydrograph' or 'coupling_hydrograph' [m3/s] 0.0001 x > 0
number_of_iterations integer no used if 'type' = 'hydrograph' or 'coupling_hydrograph' - 250 x > 0
slope real no used if 'type' = 'hydrograph' or 'coupling_hydrograph' or 'hqrelation' or 'coupling_hqrelation' per mill - x > 0
zhyd_relaxation_tau real no used if 'type' = 'zhydrograph' or 'coupling_zhydrograph' m/1000m 10.0 x > 0
max_momentum_flux real no used if 'type' = 'zhydrograph' or 'coupling_zhydrograph' - - x > 0
width real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' ; exclusive: 'width_file' [m] - x > 0
width_file string no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' ; exclusive: 'width' - - -
weir_level real no used if 'type' = 'weir' or 'coupling_weir' ; exclusive: 'weir_level_file' [m a.s.l.] - x >= 0
weir_level_file string no used if 'type' = 'weir' or 'coupling_weir' ; exclusive: 'weir_level' - - -
weir_bottom_level real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' [m a.s.l.] - x >= 0
embankement_slope real no used if 'type' = 'weir' or 'coupling_weir' - 999 x > 0
weir_my real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' - 0.65 x >= 0
num_piers real no used if 'type' = 'weir' or 'coupling_weir' - 0.0 x >= 0
c_pier real no used if 'type' = 'weir' or 'coupling_weir' - 0.0 x >= 0
c_abutments real no used if 'type' = 'weir' or 'coupling_weir' - 0.0 x >= 0
calculation_type string no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' - critical {critical, standard}
zweir_fac_a real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' - 0.0 -
zweir_fac_b real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' - 0.0 -
gate_level real no used if 'type' = 'gate' or 'coupling_gate' ; exclusive: 'gate_level_file' [m a.s.l.] - -
gate_level_file string no used if 'type' = 'gate' or 'coupling_gate' ; exclusive: 'gate_level' - - -
gate_bottom_level real no used if 'type' = 'gate' or 'coupling_gate' [m a.s.l.] - x > 0
contraction_factor real no used if 'type' = 'gate' or 'coupling_gate' - 0.62 x >= 0

Block Usage

For each domain hydraulic boundary conditions have to be specified at the up- and downstream cross section. The most common upstream boundary condition is a hydrograph (keyword: hydrograph). But it is also possible to have a wall (keyword: wall). For the lower boundary the boundary condition types are transient flow (keyword: zero_gradient), weir (keyword: weir), rating curve (keyword: hqrelation), a time function of water surface elevation (keyword: zhydrograph), a gate (keyword: gate), or a wall (keyword: wall). Finally, an outflow (downdstream) boundary condition can have more than one type of boundary, e.g. two weirs or a weir and a gate. The fluxes are then calculated for both types of boundary and summed up. For coupled regions the corresponding coupling boundaries have to chosen (e.g.coupling_hydrograph) If there are some instabilities near the boundaries during the simulation, (e.g. because there are only very few elements), we recommend to deactivate the 'stretch_boundary_elem' within the PARAMETER block which is set to 'yes' by default

Description of Variables

name - Unique identifier which is used to define controllers or couplings.
string - 'upstream' or 'downstream' are defined by the first resp. last entry in the cross section order list.
type -
file - Name of input *.txt file; e.g. example.txt
precision - For iterative determination of the wetted area corresponding to discharge: accepted difference between given and calculated discharge. This value becomesactive only if there is supercritical flow at the upper boundary, as a second boundary condition is needed then.
number_of_iterations - Maximum number of iterations allowed for the iterative determination of the wetted area, before the computation is interrupted. This value becomesactive only if there is supercritical flow at the upper boundary, as a second boundary condition is needed then.
slope - Slope of the channel at the boundary, needed for a hydrograph boundary or a hqrelation boundary if the hq relation is not given as a table. For the hydrograph this value becomes activ only if there is supercritical flow, as a second boundary condition.
zhyd_relaxation_tau - Outflow in zhydrograph boundary is calculated in a way to have an exponential relaxation towards the desired water level. The smaller the value, the faster it is tried to reach the waterlevel(what may leed to stability issues).
max_momentum_flux - Maximum possible value of momentum flux of zhydrograph boundary. Used to prevent unrealistic large values.
width - Width of the weir crest or of the gate.
width_file - Name of the file containing the time evolution of the weir width or gate width.
weir_level - Constant level of weir crest.
weir_level_file - Name of the file containing the time evolution of the weir level.
weir_bottom_level - Bottom level of weir cross section (minimal weir level and level for fully opened gate)
embankement_slope - Slope of weir embankments = 1:embankement_slope (symmetric).
A value of 999 corresponds to rectangular embankements.
weir_my - Weir factor according to Poleni.
num_piers - Number of piers at weir cross section.
c_pier - Pier coefficient for calculation of reduced width.
c_abutments - Abutment coefficient for calculation of reduced width.
calculation_type - Type for control of momentum balance at weir:
zweir_fac_a - Scaling factor for weir water level
(calculation_type = critical, zCorr = zCritWeir + F * (z - zCritWeir)):
F = zweir_fac_a + zweir_fac_b * flowdepth
zweir_fac_b - Scaling factor for weir water level
(calculation_type = critical, zCorr = zCritWeir + F * (z - zCritWeir))):
F = zweir_fac_a + zweir_fac_b * flowdepth
gate_level - Level of gate bottom, i.e. top of gate opening.
gate_level_file - Name of the file containing the evolution of the gate level (i.e. top of gate opening) in time.
gate_bottom_level - Level of bottom sill of gate cross section (level for closed gate).
contraction_factor - Gate coefficient &mu considering the reduction of the opening height due to the 'vena contracta'.

Example

HYDRAULICS
{
   BOUNDARY
   {
      type = hydrograph
      string = upstream
      file = discharge_in_time.txt
      precision = 0.001
      number_of_iterations = 50
      slope = 1.2
   }
   BOUNDARY
   {
      type = weir
      string = downstream
      level_file = weirlevel_in_time.txt
      // for constant level in time use e.g. level = 4.2
      width = 13.5
      embankement_slope = 0.04
      poleni_factor = 1.0
   }
   BOUNDARY
   {
      type = wall
      string = upstream
   }
   BOUNDARY
   {
      type = zhydrograph
      string = downstream
      file = downboundintime.txt
   }
   BOUNDARY
   {
      type = zero_gradient
      string = downstream
   }
   BOUNDARY
   {
      type = hqrelation
      string = downstream
      file = downboundary.txt
   }
   BOUNDARY
   {
      type = hqrelation
      string = downstream
      slope = 1.5
   }
   BOUNDARY
   {
      type = gate
      string = downstream
      gate_level = 329.27
      gate_bottom_level = 329.0
      width = 20.0
      contraction_factor = 1.0
      weir_my = 0.65
   }
   [...]
}
INITIAL
INITIAL compulsory repeatable
Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > HYDRAULICS
Description: This block defines the hydraulic initial conditions.

Variable type comp. condition units default values
type string yes - - - {dry, continue, backwater}
file string yes required if 'type' = 'continue' - - -
q_out real yes required if 'type' = 'backwater' [m3/s] - -
WSE_out real yes required if 'type' = 'backwater' [m rel.] - -

Block Usage

This block is used to define the initial condition of the hydraulic state in the channel. An initial wetted area and an ititial discharge have to be specified for each cross section. This can be done setting all values to 0,what means that the channel is dry, computing a backwater curve or giving the initial values in a file. It is recommendable to reach a steady state starting with the initial condition 'dry' or 'backwater' and use the obtained restart file for the main simulation.

Description of Variables

type -
file - Name of the file from which the initial condition is read, e.g. 'inital.dat'. This file can be a restart file generated by a previous simulation. It describes the initial hydraulic state in the channel with the wetted area and the discharge for each cross section. On the first line of the file there is the time definition, e.g #time: 0. The time can be changed by the user. For example the state of a previous simulation can be used as an initial condition for a new simulation. For the new simulation in order to start from time = 0 again, the time has to be set to 0.
q_out - Discharge at the lower boundary at time 0.
WSE_out - Water surface elevation at the lower boundary at time 0.

Example

HYDRAULICS
{
   [...]
   INITIAL
   {
      type = backwater
      q_out = 15.6
      WSE_out = 1.78
   }
   INITIAL
   {
      initial_type = dry
   }
   INITIAL
   {
      type = continue
      initial_file = initial.txt
   }
}
SOURCE
SOURCE compulsory repeatable
Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > HYDRAULICS
Description: This block defines all local sources.
Inner Blocks: EXTERNAL_SOURCE

Block Usage

With the keyword SOURCE are declared the sources and sinks in the computational region.

Example

HYDRAULICS
{
   [...]
   SOURCE
   {
      EXTERNAL_SOURCE
      {
         [...]
      }
   }
   [...]
}
EXTERNAL_SOURCE
EXTERNAL_SOURCE compulsory repeatable
Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > HYDRAULICS > SOURCE
Description: Specifies sources and sinks static or in time for parts or the whole area.

Variable type comp. condition units default values
name string yes - - - Chars [a-zA-Z0-9_-] are allowed
type string yes - - - {off_channel, coupling_off_channel, qlateral, coupling_qlateral, sideweir, coupling_sideweir, bottom_opening}
file string no used if 'type' = 'qlateral' - - -
cross_section string no used if 'type' = 'qlateral' or 'coupling_qlateral' or 'sideweir' or 'coupling_sideweir' or 'bottom_opening' - - -
cross_sections whitespace separated list of 2 strings no used if 'type' = 'off_channel' or 'coupling_off_channel' - - -
side string no - - - {left, right}
weir_crest_height real no used if 'type' = 'sideweir' or 'coupling_sideweir' - - -
weir_crest_length real no used if 'type' = 'sideweir' or 'coupling_sideweir' - - x > 0
poleni real no used if 'type' = 'sideweir' or 'coupling_sideweir' - - 0 <= x <= 1
momentum_sink string no used if 'type' = 'sideweir' or 'coupling_sideweir' or 'bottom_opening' - yes {yes, no}
momentum_factor real no used if 'type' = 'sideweir' or 'coupling_sideweir' or 'bottom_opening' - 1.0 x >= 0
opening_width real no used if 'type' = 'bottom_opening' - -1.0 x >= 0
contraction_coeff real no used if 'type' = 'bottom_opening' - -1.0 0 <= x <= 1
correction_coeff real no used if 'type' = 'bottom_opening' - 1.0 x >= 0

Block Usage

The external source block is used for additional sources, mostly used for lateral inflow and outflow.
If no source block is specified at all, the additional source is set to zero. In case of coupling no source_file has to be specified.

Description of Variables

name - Unique identifier which is used to define controllers or couplings.
type -
file - Name of the file containing the source flow in [m3/s]. The flow can be set negativ in order to simulate a sink.
cross_section - Define a cross section where lateral inflow (or outflow) takes place.
cross_sections - Define two cross section. In between these cross sections a lateral outflow over the channel dyke can take place.
side - Defines if the source acts on the left or right side of the cross section.
weir_crest_height - Absolute sideweir crest elevation [m].
weir_crest_length - Length of the sideweir [m].
poleni - Poleni factor for the sideweir outlfow [-].
momentum_sink - Determines if the source also affects the momentum.
momentum_factor - Factor to control the momentum source term [-]. Default: 1.0.
opening_width - Width of the bottom opening [m].
contraction_coeff - Contraction coefficient of the bottom opening (geometry dependent) [-].
correction_coeff - Correction coefficient of the bottom opening [-]. Default: 1.0

Example

SOURCE
{
   EXTERNAL_SOURCE
   {
      type = qlateral
      cross_section = QP84.200
      side = right
      file = lateral_discharge_in_time.txt
   }
   EXTERNAL_SOURCE
   {
      type = off_channel
      cross_sections = ( QP84.400 QP84.800 )
      side = left
   }
   EXTERNAL_SOURCE
   {
      type = sideweir
      cross_sections = (QP84.400)
      weir_crest_height = 545.2
      weir_crest_length = 12.0
      poleni = 0.325
      momentum_sink = yes
      momentum_factor = 1.0
   }
   EXTERNAL_SOURCE
   {
      type = bottom_opening
      cross_section = (QP84.400)
      opening_width = 2.0
      contraction_coeff = 0.9
      correction_coeff = 1.0
   }
}
INNER_BOUNDARY
INNER_BOUNDARY compulsory repeatable
Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > HYDRAULICS
Description: This block is used to define inner boundaries within a 1D grid. Possible choices are weir and gate.

Variable type comp. condition units default values
type string yes - - - {weir, gate}
cross_section_name_1 string yes - - - -
cross_section_name_2 string yes - - - -
width real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' ; exclusive: 'width_file' [m] - x > 0
width_file string no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' ; exclusive: 'width' - - -
weir_level real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' ; exclusive: 'weir_level_file' [m a.s.l.] - -
weir_level_file string no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' ; exclusive: 'weir_level' - - -
weir_bottom_level real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' [m a.s.l.] - x > 0
embankement_slope real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' - 999 x > 0
weir_my real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' - 0.65 x > 0
num_piers real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' - 0.0 x >= 0
c_pier real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' - 0.0 x >= 0
c_abutments real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' - 0.0 x >= 0
calculation_type string no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' - critical {critical, standard}
zweir_fac_a real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' - 1.0 -
zweir_fac_b real no used if 'type' = 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' - 0.0 -
gate_type string no used if 'type' = 'gate' or 'coupling_gate' - - {sluice_gate, gate_with_flap, radial_gate_with_flap}
gate_my real no used if 'gate_type' = 'gate_with_flap' or 'radial_gate_with_flap' - 0.65 x > 0
gate_level real no used if 'type' = 'gate' or 'coupling_gate' ; exclusive: 'gate_level_file' [m rel.] - -
gate_level_file string no used if 'type' = 'gate' or 'coupling_gate' ; exclusive: 'gate_level' - - -
gate_bottom_level real no used if 'type' = 'gate' or 'coupling_gate' [m a.s.l.] - x > 0
gate_size real no used if 'gate_type' = 'gate_with_flap' or 'radial_gate_with_flap' ; exclusive: 'gate_size_file' [m] - x > 0
gate_size_file string no used if 'gate_type' = 'gate_with_flap' or 'radial_gate_with_flap' ; exclusive: 'gate_size' - - -
contraction_factor real no used if 'gate_type' = 'gate_with_flap' or 'sluice_gate' - 0.62 x >= 0
ehead_reference_location string yes used if 'type' = 'gate' or 'weir' - - -
margin real no used if 'gate_type' = 'radial_gate_with_flap' [m] 0.0 x >= 0
a1 real no used if 'gate_type' = 'radial_gate_with_flap' - 0.6559 -
b1 real no used if 'gate_type' = 'radial_gate_with_flap' - -0.1084 -
a2 real no used if 'gate_type' = 'radial_gate_with_flap' - 0.6559 -
b2 real no used if 'gate_type' = 'radial_gate_with_flap' - -0.1084 -

Block Usage

So called inner boundary conditions are used to model hydraulic structures like a weir or a gate within the computational domain. These conditions compute the flow over an edge using a special formula or relation. Technically, this produces an outflow and a corresponding inflow at the location of the inner boundary.
Accordingly, two cross section strings have to be defined. The two cross section strings are the names of the cross sections between which the boundary is situated The inner boundaries act in both direction - the flow direction is determined from high wse to low wse. Different types of inner boundary conditions are available.

Description of Variables

type -
  • weir: The location of the inner weir is defined by the tag string_name1. However, the geometry does not correspond to the given cross section and has to be defined here, using the tags width, embankement_slope (definition of trapezoidal or rectangular cross section), weir_level and weir_bottom_level (minimum weir_level). For a constant level use weir_level, for changing level in time, use a weir_level_file of type 'BC' with two columns: time and corresponding level. Values are interpolated in time automatically.

    The discharge over the weir is calulated with the Poleni formula, using weir_my as weir coefficient:
    Q = 2/3*b*μ*(2*g)^1/2*(H^3/2)
    Q: discharge;
    b: reduced width;
    μ: weir coefficient;
    H: overtopping flow depth at weir;

    Piers and abutments are considered by reduction of the width:
    b = width - 2 * (num_piers * c_pier + c_abutments) * E0;
    num_piers: number of piers;
    c_pier: loss coefficient of pier;
    c_abutments: loss coefficient of abutments;
    E0: energy head at reference cross section upstream og the weir, considering only flow cross section;

    The calculation_type controls the momentum balance and output:
    critical: calculation of flow area based on critical flow depth at weir;
    standard: calculation of flow area based on overtopping flow depth at weir;

  • gate: The location of the inner gate is defined by the tag string_name1.However, the geometry does not correspond to the given cross section and has a rectangular shape. Tags to define the geometry of the gate are: width, gate_level and gate_bottom_level (level of bottom sill). For varying gate level in time, use the gate_level_file of type BC with two columns: time and corresponding level. Values are interpolated in time automatically.

    The discharge at the sluice gate and the gate with flap is calulated based on Torricelli's law:
    Q = b*μ*a*[2*g*(H - μ*a)]^1/2
    Q : discharge;
    b: width;
    μ: gate coefficient;
    a: gate opening (gate_level - gate_bottom_level);
    H: water depth at gate ( = WSE - gate_bottom_level).

    The vena contracta is considered by the gate coefficient:
    μ = contraction_factor / (1 + (contraction_factor * a / H))^1/2
    For the radial gate with flap a the discharge is calculated differently.
    In the case of uncontrolled underflow (gate is not active), flow over a weir with rectanular geometry is considered. Thus, you may have to define a weir in addition.
    • cross_section_name_1 - This is the name of a cross sectionUsually, the first string is the upstream one.
    cross_section_name_2 - This is the name of a cross section. Usually, the second string is the downstream one.
    width - Width of the weir crest or of the gate.
    width_file - Name of the file containing the time evolution of the weir width or gate width.
    weir_level - Constant level of weir crest.
    weir_level_file - Name of the file containing the time evolution of the weir level.
    weir_bottom_level - Bottom level of weir cross section (minimal weir level and level for fully opened gate)
    embankement_slope - Slope of weir embankments = 1:embankement_slope (symmetric).
    A value of 999 corresponds to rectangular embankements.
    weir_my - Weir factor μ according to Poleni.
    num_piers - Number of piers at weir cross section.
    c_pier - Pier coefficient for calculation of reduced width.
    c_abutments - Abutment coefficient for calculation of reduced width.
    calculation_type - Type for control of momentum balance at weir:
    zweir_fac_a - Scaling factor for weir water level
    (calculation_type = critical, zCorr = zCritWeir + F * (z - zCritWeir)):
    F = zweir_fac_a + zweir_fac_b * flowdepth
    zweir_fac_b - Scaling factor for weir water level
    (calculation_type = critical, zCorr = zCritWeir + F * (z - zCritWeir))):
    F = zweir_fac_a + zweir_fac_b * flowdepth
    gate_type - Type of gate:
  • sluice gate: simple sluice gate
  • gate with flap: gate with flap on top. flap is controlled by the gate size
  • radial gate with flap: radial gate with flap on top. flap is controlled by the gate size If the gate is not active, discharge is calculated based on weir flow. Consider to specify weir_bottom level and weir_my.
    • gate_my - Weir coefficient μ used in discharge formula for flow over gate with flap. Can be used for calibration of the discharge.
    gate_level - Level of gate bottom, i.e. top of gate opening.
    gate_level_file - Name of the file containing the evolution of the gate level (i.e. top of gate opening) in time.
    gate_bottom_level - Level of bottom sill of gate cross section (level for closed gate).
    gate_size - Size of gate is used for definition of the level of the flap;
    level of the flap = gate_level + gate_size
    gate_size_file - Name of the file containing the evolution of the gate size (movement of flap) in time.Specify size in [m].
    contraction_factor - Contraciton factor δ for calculation of gate coefficient considering the reduction of the opening height due to the 'vena contracta'.
    ehead_reference_location - Location (cross section name) of reference energy head. This is the cross section where the water surface is just not affected by the flow acceleration at the weir. Used for computation of critical weir flow and gate flow considering reduction due to piers and abutments.
    margin - Radial gate with flap only:Nonlinear computation of gate coefficient depending on gate opening.gate opening ≤ margin: phi = a2 * pow((gate opening / ehead at ref. location), b2)gate opening > margin (default): phi = a1 * pow((gate opening / ehead at ref. location), b1)
    a1 - Parameter a1 for calculation of gate coefficient phi (see tag margin).
    b1 - Parameter b1 for calculation of gate coefficient phi (see tag margin).
    a2 - Parameter a2 for calculation of gate coefficient phi (see tag margin).
    b2 - Parameter b2 for general calculation of gate coefficient phi (see tag margin).

    Example

    HYDRAULICS
{
   INNER_BOUNDARY
   {
      type = weir
      my = 0.85
      string_name1 = CS1      string_name2 = CS2      file = weirLevel.txt
   }
   INNER_BOUNDARY
   {
      type = gate
      my = 0.7
      string_name1 = CS      string_name2 = CS      file = gateLevel_in_time.txt
   }
   [...]
}
    TIMESTEP
    TIMESTEP compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D
    Description: The TIMESTEP block is used to specify numerical parameters related to the time and timestep for the simulation, as time step, total run time, CFL number etc.

    Variable type comp. condition units default values
    CFL real yes - [-] - 0 < x <= 2
    maximum_time_step real no - [s] 100.0 x > 0
    initial_time_step real no - [s] 0.1 x > 0
    total_run_time real yes - [s] - x > 0
    start_time real no - [s] -1.0 -

    Block Usage

    The only thing that needs to be defined is the total_run_time. All other variables use default values if they dont get specified by the user. Changing these Parameters either leads to faster and more stable simulations or it may make the simulation collapse in the worst case. The most often changed Parameter is the CFL number to change the timestep.

    Description of Variables

    CFL - The CFL (Courant-Friedrichs-Lewy) number influences the stability of the computation (value 0.5-1). It should be as close as possible to 1 and diminished only in case of stability problems. This leads to an increase of numerical diffusion. The CFL should not be set higher than 1 except for computation of bedload with implicit solution of hydraulics. In this case the recommended maximum is 2. In case of stability problems near the boundary conditions, instead of lowering the CFL-number, try to set 'stretch_boundary_elem' to 'no'.
    maximum_time_step - This parameter defines a maximum time step for an explicit simulation.The time step during the simulation cannot exceed this value. Choose it bigger than all computed time steps during the simulation. By default the maximum time step is set to 100.0 s.
    initial_time_step - In the explicit computation this value is used only for the boundary compatibility check of the new calculated time step. This needs an 'old' timestep, which does not exist yet at the very beginning of the simulation. For implicit computations this is the user defined time step, with which the iteration starts. If no solution can be found it will be reduced by the factor time_step_reduction.
    total_run_time - This parameter needs to be specified by the user. When the given time value is reached, the simulation stops all output is written. If the simulation continues from an earlier state, the starting time will be different from zero and the effectively computed time is the difference between the total_run_time and the starting time.
    start_time - This parameter defines the time (in seconds) when the simulation starts. If you want the simulation to start at t = x s, then set this value to x. If start_time is set to a negative value (per default), two cases are distinguished. (a) A restart file is defined. Then the restart time defined in the restart-file will be used. (b) No restart file is defined. Then the simulation starts from t = 0.0 s.

    Example

    BASEPLANE2D
{
   [...]
   TIMESTEP
   {
      CFL = 1.0
      initial_time_step = 0.01
      total_run_time    = 3600.0
      start_time        = 0.0
 // simulation starts at t= 0.0s   }
   [...]
}
    MORPHOLOGY
    MORPHOLOGY compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D
    Description: This Block defines the morphologic specifications for the simulation.
    Inner Blocks: PARAMETER
    BEDMATERIAL
    BEDLOAD
    SUSPENDED_LOAD
    INITIAL
    SOURCE
    GRAVITATIONAL_TRANSPORT

    Block Usage

    Contrary to the HYDRAULICS block, this Block is not compulsory. If Morphology is not specified, sediment transport will be inactive. Furthermore there is no INITIAL block within MORPHOLOGY. Therefore, all bed load is initially at rest by default. The impact of gravitational forces to the topography are treated within the GRAVITATIONAL_TRANSPORT block.

    Example

    MORPHOLOGY
{
   BEDMATERIAL
   {
      [...]
   }
   BEDLOAD
   {
      [...]
   }
   SUSPENDED_LOAD
   {
      [...]
   }
   PARAMETER
   {
      [...]
   }
   INITIAL
   {
      [...]
   }
   SOURCE
   {
      [...]
   }
   GRAVITATIONAL_TRANSPORT
   {
      [...]
   }
}
    PARAMETER
    PARAMETER compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY
    Description: The PARAMETER block for morphology in 1D contains general settings dealing with sediment transport. It contains parameters concerning both bed load and suspended load.

    Variable type comp. condition units default values
    porosity real yes - [%] - 0 <= x <= 100
    wetting_fraction real no - 0.1 0 <= x <= 1
    density real yes - [kg/m3] - x > 0
    control_volume_type string no - - constant {constant, d90}
    control_volume_thickness real no used if 'control_volume_type' = 'constant' [m] 0.1 x > 0
    control_volume_factor real no used if 'control_volume_type' = 'd90' [-] 2.0 x > 0
    max_dz_table real no - [m] 0.1 x > 0
    create_new_layers string no - - off {off, on}
    max_layer_thickness real no used if 'create_new_layers' = 'on' [m] 0.5 x > 0
    min_theta_critic real no - - 0.02 -

    Block Usage

    In this block are defined general parameters for morphological computations which are necessary for both bedload and suspended load transport.

    Description of Variables

    porosity - This is the general bed material porosity in percent.
    wetting_fraction - If this fraction of the level difference of a soil is below the waterlevel, the soil is considered to be wetted.
    density - This is the general density of the sediment.
    control_volume_type - This tag defines how to determine the bed load control volume thickness hm, which is also called active layer or mixing layer thickness. Available types are:
    control_volume_thickness - The thickness of the bed load control volume can be defined. This value is only needed if the type of the bed load control volume is set to constant. The specified thickness is valid for all elements of the simulation. In multiple-grain simulations this can be an important calibration parameter.
    control_volume_factor - This parameter is needed for control_volume_type 'd90'. Therefore, the bedload control volume thickness hm is determined as: hm = control_volume_factor * d90 [m]. Typically, values range between 1 and 3.
    max_dz_table - Maximum modification of bedlevel allowed before the tables (see also SECTION COMPUTATION in HYDRAULICS) are recomputed. Attention: Setting this value to 0.0 may lead to a drastic increase of simulation time as the tables are updated every timestep. This Parameter has only an effect if tables are activated.
    create_new_layers - If this flag is active new sediment layers will be created when sediment is deposed, otherwise the thickness of the existing layer will be increased.
    max_layer_thickness - This is the maximum thickness of newly created soil layers. In case of deposition, if a layer increases in height, the maximum thickness defines when a new soil layer shall automatically be created. Attention: This value must exceed the thickness of the bed-load control volume!
    min_theta_critic - This is the minimally allowed critical theta (shields factor). The minimum critical shields factor is needed out of numerical reasons to prevent division by zero if a formula is used which divides by the critical shields factor (e.g. Wu or Parker transport formulas). (Critical shields factor can get very small or even zero due to the local slope correction. Therefore a minimum allowed critical theta is needed).

    Example

    MORPHOLOGY
{
   [...]
   PARAMETER
   {
      porosity = 37
      density = 2650
      control_volume_thickness = 0.05
		 wetting_fraction = 0.5
      [...]
   }
   [...]
}
    BEDMATERIAL
    BEDMATERIAL compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY
    Description: This block defines the characteristics of the bed material.
    Inner Blocks: GRAIN_CLASS
    MIXTURE
    SOIL_DEF
    SOIL_ASSIGNMENT

    Block Usage

    For sediment transport the sediment type and distribution must be described. The location and quality types of the sediments present in the channel are defined directly in the topography file (B). All data concerning the material of the bed are defined in the block BEDMATERIAL. The GRAIN_CLASS specifies the relevant diameters of the grain. The MIXTURE block allows producing different grain mixtures with the defined diameters. The SOIL_DEF block defines the sub layers and their mixtures. Finally, the SOIL_ASSIGNMENT block is used to assign the different soil definitions to their corresponding areas in the topography.

    Example

    BEDMATERIAL
{
   GRAIN_CLASS
   {
     [...]
   }
   MIXTURE
   {
     [...]
   }
   SOIL_DEF
   {
     [...]
   }
   SOIL_ASSIGNMENT
   {
    [...]
   }
}
    GRAIN_CLASS
    GRAIN_CLASS compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY > BEDMATERIAL
    Description: This block defines the mean diameters of ALL possibly occurring grains of the bed material in millimetres.

    Variable type comp. condition units default values
    diameters whitespace separated list of reals yes - [mm] - -

    Block Usage

    For the description of the sediments, a certain number of grain classes, characterized by their mean grain diameter, have to be defined. In a second step, a certain number of 'grain mixtures' must be defined, which contain some of the existing grain classes in different proportions. If the test samples are available in the shape of a grading curve, the mean value of two given grain diameters can be taken as mean grain diameter of the grain class, and the fraction of the material between the two diameters as fraction of the grain class in the mixture.

    Description of Variables

    diameters - The number of diameters in the list automatically sets the number of grains. For single grain simulations, only one diameter must be defined. The grain sizes must be entered in ascending order from the smallest grain to the largest grain.

    Example

    BEDMATERIAL
{
   GRAIN_CLASS
   {
   // simulation with 5 grain sizes
   diameters = ( 5 21 46 70 150 )
   }
   [...]
}

BEDMATERIAL
{
   GRAIN_CLASS
   {
   // simulation with 1 grain size
   diameters = ( 46 )
   }
   [...]
}
    MIXTURE
    MIXTURE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY > BEDMATERIAL
    Description: This block allows the definition of a grain mixture.

    Variable type comp. condition units default values
    name string yes - - - Chars [a-zA-Z0-9_-] are allowed
    volume_fraction whitespace separated list of reals yes - [%] - [0-100]

    Block Usage

    The fractions of each grain class are filled in a list, in the same order in which they appear in grain class list. Grain classes which do not appear in this mixture have fraction value 0, and cannot be omitted. The sum of the fractions has to be 100. As the MIXTURE block is repeatable, several mixtures can be defined. However, this makes only sense for multi grain size simulations. In case of a single grain simulation (only one mean diameter in GRAIN_CLASS), there will be only one MIXTURE block. A single grain mixture has the volume_fraction = ( 100 ).

    Description of Variables

    name - The name of this mixture is used elsewhere for easy-to-use assignments.
    volume_fraction - According to the number of grain diameters from the GRAIN_CLASS, for each class, the percental fraction of volume has to be specified using a value between 0 and 100 %. The fractions must be written in the order corresponding to the grain class list. If a grain class is not present in a mixture, its fraction value has to be set to 0. All percentual fractions together must sum up to 100.

    Example

    BEDMATERIAL
{
   GRAIN_CLASS
   {
      // simulation with 3 grain sizes
      diameters = (  5  21  46  )
   }
   MIXTURE
   {
      name = mixture1
      volume_fraction = (  30  50  20  )
   }
   MIXTURE
   {
      name = mixture2
      volume_fraction = (  30  40  30  )
   }
   [...]
}
    SOIL_DEF
    SOIL_DEF compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY > BEDMATERIAL
    Description: This block defines the structure of the soil. Every soil layer is defined within a LAYER block. Every layer has an own mixture assigned.
    Inner Blocks: LAYER

    Variable type comp. condition units default values
    name string yes - - - Chars [a-zA-Z0-9_-] are allowed
    d90_armored_layer real no - [mm] - x > 0
    tau_erosion_start real no - [N/m2] -1.0 -

    Block Usage

    A soil consists of one or several layers. Typically, every layer has its own mixture assigned. The LAYER blocks have to be defined within the SOILDEF block ordered by their relative distance to the surface!
    For single grain size simulations, one LAYER block is needed (usually with the only mixture assigned to it) to define the fixed bed by its bottom elevation. If no LAYER block is defined within a SOIL_DEF, a fixed bed without layer on top is assumed at this place.
    Additional, an armoured bed can be defined for a soil optionally. Therefore the d90 of the armoured layer in [mm] (d90_armored_layer) for single grain size simulations or a critical bottom shear stress in [N/m2] (tau_erosion_start) for both, single and multi grain size simulations can be defined. The corresponding critical shear stresses must be exceeded at least once to erode the armoured bed. The definition of a critical shear stress can be useful, for example in the presence of protecting vegetation.

    Description of Variables

    name - This is the name of the soil which can be used elsewhere e.g. for the soil assignment.
    d90_armored_layer - This tag defines a characteristic grain size 'd90' assuming an armoured layer. This grain size is used for the calculation of the dimensionless critical shear stress 'θ critic', which has to be exceeded before erosion is possible. After this threshold value is exceeded once it is not considered any more for the rest of the simulation. The definition of a tag 'd90_armored_layer' is only valid for single grain size simulations with a diameter d. The dimensionless critical shear stress is calculated as: θ critic_armour = θ critic*(d90/d)^(2/3). If d90_armored_layer is set to 0 or undefined, no armoured layer is being used.
    tau_erosion_start - This is a possibility to define a bottom shear stress which has to be exceeded before erosion becomes possible. After that the threshold value is not considered any more for the rest of the simulation. This tag can be used for single grain and multi grain size simulations.

    Example

    BEDMATERIAL
{
   GRAIN_CLASS
   {
      [...]
   }
   MIXTURE
   {
      [...]
   }
   MIXTURE
   {
      [...]
   }
   SOIL_DEF
   {
      name = soil1
      tau_erosion_start = 50.0   // [N/m2]
      LAYER
      {
         [...]
      }
      LAYER
      {
         [...]
      }
   }
   SOIL_DEF
   {
      name = soil2
      d90_armored_layer = 6.8    // [mm]
      LAYER
      {
         [...]
      }
      LAYER
      {
         [...]
      }
   }
   [...]
}
    LAYER
    LAYER compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY > BEDMATERIAL > SOIL_DEF
    Description: This block defines a soil layer. For every soil layer, a new block has to be used. The bottom elevation is relative to the surface topography defined in the geometry file. Therefore, a minus-sign has to be used.

    Variable type comp. condition units default values
    mixture string yes - - - Chars [a-zA-Z0-9_-] are allowed
    bottom_elevation real yes - [m] - x <= 0

    Block Usage

    A layer consists of a mixture and its bottom elevation. The bottom elevation is relative to the surface topography defined in the geometry file. Therefore, a minus-sign has to be used. The LAYER blocks have to be defined ordered by their relative height to the surface, from the uppermost layer to the lowest layer.
    The bottom of the lowest soil layer automatically defines the fixed bed.
    In case of a single grain simulation (only one mean diameter in GRAIN_CLASS), only one LAYER block is needed, which defines the fixed bed. If no LAYER block is defined within a SOIL_DEF block, a fixed bed without a soil layer on top is assumed at this place.

    Description of Variables

    mixture - This is the name of the soil mixture as it is defined in the MIXTURE block.
    bottom_elevation - The bottom elevation is expected to be relative to surface. Therefore, it is always a negative number.

    Example

    SOIL_DEF
{
   name = soil1
   tau_erosion_start = 0.89
   LAYER
   {
      mixture = mixture1       // first soil layer
      bottom_elevation = -0.5  // [m]
   }
   LAYER
   {
      mixture = mixture2       // second soil layer
      bottom_elevation = -1.3  // [m]
   }
   LAYER
   {
      [...]
   }
}
    SOIL_ASSIGNMENT
    SOIL_ASSIGNMENT compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY > BEDMATERIAL
    Description: This block is used to assign the soil definitions to their corresponding areas in the topography.

    Variable type comp. condition units default values
    index whitespace separated list of integers yes - - - -
    soil whitespace separated list of strings yes - - - -
    type string no - - index_table {index_table}

    Block Usage

    To assign the soil definitions the index-technique is used. Every soil is assigned to an index. Note that each material index defined in the mesh must be used.

    Description of Variables

    index - This is a list of integers corresponding to the material indices in the computational mesh. Note that all indices defined in the mesh must be used here.
    soil - This is a list of the SOIL names in the same order as defined in the 'index' tag.
    type - This is the type used for the soil assignment. Currently, only 'index_table' is available.

    Example

    BEDMATERIAL
{
   [...]
   SOIL_DEF
   {
      name = soil_coarse
      [...]
   }
   SOIL_DEF
   {
      name = soil_fine
      [...]
   }
   SOIL_DEF
   {
      name = fixbed
   }
   SOIL_ASSIGNMENT
   {
      type = index_table
      index = ( 1  2  3 )
      soil = ( soil_coarse  soil_fine  fixbed )
   }
}
    BEDLOAD
    BEDLOAD compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY
    Description: Defines all needed data for bed load transport.
    Inner Blocks: PARAMETER
    FORMULA
    BOUNDARY

    Block Usage

    This block has to be inserted if bedload transport has to be computed. If this block does not exist, then no bed load transport will be simulated. It contains BOUNDARY, PARAMETER, and FORMULA blocks.

    Example

    BEDLOAD
{
   [...]
   BOUNDARY
   {
      [...]
   }
   BOUNDARY
   {
      [...]
   }
   PARAMETER
   {
      [...]
   }
   FORMULA
   {
      [...]
   }
}
    PARAMETER
    PARAMETER compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY > BEDLOAD
    Description: This block defines parameters concerning the bedload computation.

    Variable type comp. condition units default values
    upwind real yes - - - 0.5 <= x <= 1
    abrasion string no - - off {off, on}
    hydro_step integer no - - - -
    velocity_area string no - - general {general, main, bottom}

    Block Usage

    This section contains several general parameters needed for bed load simulations.

    Description of Variables

    upwind - Defines which part of the sediment flux on the edge is taken from the upstream cross-section. Recommended 0.5 - 1, depending on the stability of the computation! Modifying this value can help to avoid the numerical problem of jagged deposition pattern.
    abrasion - This flag determines if the reduction of sediment volume due to abrasion is computed.
    hydro_step - With this parameter it is possible to compute the new hydraulic situation only each x time steps. This makes sense only with slow changes of the flow conditions and can be useful for example for long term morphodynamic simulations.
    velocity_area - Defines which part of the cross section area is taken for the computation of the velocity for the bedload transport u = Q/A.

    Example

    BEDLOAD
{
   [...]
   PARAMETER
   {
      upwind = 0.7
   }
}
    FORMULA
    FORMULA compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY > BEDLOAD
    Description: The FORMULA block for morphology in 1D defines general settings related to the bedload transport formula.

    Variable type comp. condition units default values
    bedload_formula string yes - - - {mpm, engelundhansen, mpmh, mpm_multi, ashidamichiue, parker, wilcockcrowe, power_law, rickenmann, smartjaeggi, smartjaeggi_multi, wu, vanrijn}
    bedload_factor real no - - 1.0 -
    bedload_exponent real no used if 'bedload_formula' = 'mpm' or 'mpm_multi' - 1.5 1 <= x <= 2
    theta_critical real no used if 'bedload_formula' = 'mpm' or 'mpmh' or 'mpm_multi' or 'ashidamichiue' or 'rickenmann' or 'smartjaeggi' or 'smartjaeggi_multi' or 'vanrijn' or 'parker' or 'wu' - -1.0 -
    theta_critical_approach string no used if 'bedload_formula' = 'mpm' or 'mpmh' or 'mpm_multi' or 'ashidamichiue' or 'rickenmann' or 'smartjaeggi' or 'smartjaeggi_multi' or 'vanrijn' - theta_critical_vanrijn {theta_critical_vanrijn, theta_critical_yalin}
    theta_critical_hiding string no used if 'bedload_formula' = 'mpm_multi' or 'ashidamichiue' or 'smartjaeggi_multi' - mean {mean, median, geometric, fraction}
    critical_shear_stress_calibration real no used if 'bedload_formula' = 'mpm' or 'mpm_multi' or 'ashidamichiue' or 'mpmh' or 'rickenmann' or 'smartjaeggi' or 'smartjaeggi_multi' or 'vanrijn' - 1.0 0 <= x <= 100
    hiding_exponent real no used if 'bedload_formula' = 'mpmh' or 'wu' or 'parker' - -1E10 -
    power_law_a real no used if 'bedload_formula' = 'power_law' - 1.0 -
    power_law_b real no used if 'bedload_formula' = 'power_law' - 1.0 -
    alpha real no used if 'bedload_formula' = 'smartjaeggi_multi' - 1.05 x >= 1
    d90 real yes required if 'bedload_formula' = 'rickenmann' or 'smartjaeggi' or 'vanrijn' [mm] - x > 0
    d30 real yes required if 'bedload_formula' = 'rickenmann' or 'smartjaeggi' [mm] - x > 0
    angle_of_repose real no - [degree] 30.0 -
    bed_forms real no - - 1.0 x <= 5
    local_slope string no used if 'bedload_formula' = 'mpm' or 'mpm_multi' or 'ashidamichiue' or 'parker' or 'power_law' or 'vanrijn' or 'wu' - on {off, on}
    use_energy_slope string no used if 'bedload_formula' = 'smartjaeggi' or 'smartjaeggi_multi' - on {on, off}

    Block Usage

    This block defines the settings related to the bedload transport formula. Most of them use a default value, therefore it is not neccessary to set them all in the beginning. The only variable that must be set is the bedload formula which shall be used. Check the info botton for detailed information on the tags.

    Description of Variables

    bedload_formula - The following bedload transport formulas can be selected (see Reference Manual RI):
    The choice of the transport formula depends on different factors (i.e. slope, morphology, validity of formula, personal preferences etc.). For single grain simulations 'mpm', 'engelundhansen', 'rickenmann', 'smartjaeggi', 'vanrijn', and 'power_law' can be used, for multi-grain simulations 'mpmh', 'mpm_multi', 'ashidamichiue'', 'parker', 'wilcockcrowe', 'smartjaeggi_multi', and 'wu' can be used.
    bedload_factor - This factor is multiplied with the bedload transport computed by the bedload formula and can be used as a calibration parameter.
    bedload_exponent - The bedload exponent is used for mpm and mpm_multi bedload transport formula. The original value is 1.5. The corrected version of Wong and Parker (2006) applies bedload_exponent = 1.6. Values other than that are not recommended!
    theta_critical - The critical Shields parameter (dimensionless critical shear stress) is an important calibration factor.
    If theta_critical is specified by the user, this value is constant over the whole simulation. If this parameter is not specified explicitely, the value is determined according to the transformed Shields diagramm defined in 'theta_critical_approach'. Critical Shields parameter is determined from the tranformed Shields diagram for 'mpm', 'mpm_multi', 'mpmh', 'rickenmann', 'smartjaeggi', 'smartjaeggi_multi', and 'vanrijn'. Constant default value are used for 'wu = 0.03', and 'parker = 0.0386'.
    theta_critical_approach - This tag is used if no tag 'theta_critical' is defined or if certain material indices are missing.The following approaches to determine critical Shields paramter (transformed Shields diagram based on dimensionless grain diameter D*) can be selected:
    theta_critical_hiding - This tag is used if no tag 'theta_critical' is defined or if certain material indices are missing. This tag defines which characteristic grain size diameter is used to determine the critical Shields parameter used for the approach defined in 'theta_critical_approach'. The resulting critical Shields parameter theta_c is applied on the hiding function F of Ashida and Michiue, such that the critical Shields parameter of grain class i is calculated as: theta_ci = F*theta_critical. The reference critical Shields parameter can be determined based on: The default is set to 'mean' as proposed by Egiazaroff (1965). However, Ashida and Michiue (1972) proposed a fix value of 0.05. To use a fix value, define critical Shields parameter using the tag 'theta_critical', where for each material index a critical Shields parameter can be defined. Note: This tag is only used for bed load formula 'mpm_multi', and 'smartjaeggi_multi' using the hiding function according to Ashida and Michiue.
    critical_shear_stress_calibration - Factor used to modify the critical shear stress returned by the Shields diagram. It can only be used for transport formulas which determine the critical shear stress from the Shields-diagram.
    hiding_exponent - This is the exponent of the hiding-exposure function in Hunziker's, Wu's, or Parker's non-uniform bed load formula. This factor is generally set to a negative number. Default values are -0.6 for Wu's formula,and -0.0951 in Parker's formula. NB for Hunziker formulation: leave the default value (unset value)for the original formulation from the Authors (Eq. 11 in Hunziker and Jaeggi 2002),or set a custom hiding exponent factor (negative value).Changing this exponent primarily influences the grain sorting process. Major change of this value will probably result in instabilities.
    power_law_a - This is the linear factor 'a' for the power law transport formula (a*u^b). By default, it is set to 1.0.
    power_law_b - This is the exponent b for the power law transport formula (a*u^b). By default, it is set to 1.0.
    alpha - The coefficient of alpha is used instead of the term (d90/d30)^(0.2) of the original (single grain) Smart & Jaeggi transport formula. By default, it is set to 1.05.
    d90 - This is the characteristic diameter d90 of the bed material. This parameter is mandatory for the 'rickenmann', 'smartjaeggi' and 'vanrijn' bed load transport formula.
    d30 - This is the characteristic diameter d30 of the bed material. This parameter is mandatory for the 'rickenmann' and 'smartjaeggi' bed load transport formula.
    angle_of_repose - The angle of repose of the bedmaterial in degrees is considered to be the same in the whole region. It plays a role in the modification of the critical shear stress depending on the bed slope.
    bed_forms - This factor is applied in case of bed forms to determine the effective bottom shear stress θ'; from the bottom shear stress θ. This factor must be set to a value smaller or equal 1.0. If the factor is set to a positive number, then it is assumed constant over the whole domain and simulation time. If the factor is set to a negative number, then it is determined dynamically by the program. See chapter RI-2.2 for more information.
    local_slope - This flag determines if the critical Shields paramter is corrected due to local bed slope (gravitational influence). If local_slope is considered, the critical Shields paramter is decreased or increased if there is a slope in flow direction or a counter slope, respectively. Note: This local_slope correction makes no sense for bedload transport formulas which correct for local slope or which are valid for higher slopes (e.g. 'smartjaeggi' or 'rickenmann')! It could make sense for example for 'mpm' and other formulas when applied to rivers with high and/or changing slopes.
    use_energy_slope - This flag determines the slope calcualtion for the bed load transport formula of 'smartjaeggi' and 'smartjaeggi_multi'. The slope can either be determined from the energy slope (use_energy_slope = on) or from the bed slope (use_energy_slope = off).

    Example

    BEDLOAD
{
   [...]
   FORMULA
   {
      bedload_formula = mpm
      bedload_factor = 0.5
   }
}
    BOUNDARY
    BOUNDARY compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY > BEDLOAD
    Description: This block contains information about a boundary condition for bedload transport.

    Variable type comp. condition units default values
    name string no - - - Chars [a-zA-Z0-9_-] are allowed
    type string yes - - - {sediment_discharge, coupling_sediment_discharge, IOUp, IODown, coupling_IODown, wall, transport_capacity, bed_load_function, sediment_grain_discharge}
    string string yes - - - {upstream, downstream}
    file string yes required if 'type' = 'sediment_discharge' or 'bed_load_function' - - -
    multiFile string no - - - -
    mixture string yes required if 'type' = 'sediment_discharge' or 'transport_capacity' or 'bed_load_function' - - -
    factor real no - - - -

    Block Usage

    In this section are defined the upper und lower boundary for the bed load transport.

    Description of Variables

    name - Unique identifier which is used to define controllers or couplings.
    type -
    string - Defines if the boundary condition is at the upstream or downstream end.
    file - Name of the file containing the time dependent sediment inflow in the case of a boundary of type 'sediment_discharge'.
    multiFile - Name of the file containing the time dependent sediment inflow of all grain class in separate columns in the case of a boundary of type 'sediment_grain_discharge'.
    mixture - Mixture of the material passing the boundary.
    factor - This factor can be used to modify the inflowing discharge when the boundary condition 'transport_capacity' or 'IOUp' is used.

    Example

    BEDLOAD
{
   [...]
   BOUNDARY
   {
      type = sediment_discharge
      string = upstream
      file = upstream_discharge.txt
      mixture = mixture2
   }
   BOUNDARY
   {
      type = IODown
      string = downstream
   }
   [...]
}
    SUSPENDED_LOAD
    SUSPENDED_LOAD compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY
    Description: In this block all information needed for suspended load transport simulation is described.
    Inner Blocks: PARAMETER
    BOUNDARY
    INITIAL
    SOURCE

    Block Usage

    Defines all needed data for suspended transport. If this block does not exist, then no suspended transport will be simulated.

    Example

    SUSPENDED_LOAD
{
   [...]
   INITIAL
   {
      [...] 
   }
   BOUNDARY
   {
      [...] 
   }
   BOUNDARY
   {
      [...]
   }
   PARAMETER
   {
      [...]
   }
   SOURCE
   {
      [...]
   }
}
    PARAMETER
    PARAMETER compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY > SUSPENDED_LOAD
    Description: The PARAMETER block for suspended load in 1D contains general settings dealing with suspended transport.

    Variable type comp. condition units default values
    local_slope string no - - on {off, on}
    scheme string yes - - - {upwindSuspension, mdpm, quick, quickest, holly}
    diffusion_factor real no - [-] - x >= 0
    diffusion_factor_dynamic real no - - 1.0 -
    sediment_exchange string yes - - - {on, off}
    use_transport_type_factor string yes required if 'sediment_exchange' = 'on' - no {yes, no}
    transport_type_factor string yes required if 'sediment_exchange' = 'on' - vanrijn {vanrijn, bagnold}
    pickup_factor real yes required if 'sediment_exchange' = 'on' - 1.0 -
    sink_velocity_type string no - - vanrijn {vanrijn, wuwang, zhang, user_defined_settling_velocities}
    settling_velocities whitespace separated list of reals yes required if 'sink_velocity_type' = 'user_defined_settling_velocities' [mm/s] - -
    exchange_type string yes required if 'sediment_exchange' = 'on' - concentrations {concentrations, shear_stresses}
    concentration_type string yes required if 'sediment_exchange' = 'on' - vanrijn {vanrijn, zyserman, constant_factor}
    factor_for_near_bed_concentration real yes required if 'concentration_type' = 'constant_factor' - 1.0 -
    factor_depth_reference_height real yes required if 'concentration_type' = 'vanrijn' - 0.1 -
    factor_m real yes required if 'exchange_type' = 'shear_stresses' - - -
    factor_n real yes required if 'exchange_type' = 'shear_stresses' - - -
    tk real yes required if 'exchange_type' = 'shear_stresses' - - -
    shape_factor real no - - - -

    Block Usage

    The section PARAMETER contains several general parameters needed for suspended load simulations.

    Description of Variables

    local_slope - This flag determines if the gravitational influence of the local slope within the elements should be considered for suspended-load transport. If it is considered, the suspended-load is increased if there is a slope in flow direction, or the bedload is reduced if there is a counter slope.
    scheme - The numerical scheme used for advection computation. The following schemes are available:
    diffusion_factor - The factor representing the constant eddy diffusivity Γ can be given here. If it's not given, it is computed by the program according to (RII-1.115).
    diffusion_factor_dynamic - This is a calibration parameter for the dynamical computed turbulent viscosity (eddy viscosity averaged over depth). This factor ϑ is multiplied with the turbulent viscosity:

    ν = ϑ · κ/6 · h· u*

    Per default the factor ϑ is set to 1.0.
    sediment_exchange - Defines if there is exchange of sediment with the river bed (deposition/entrainment). Sediment exchange can only be used with the QUICK or QUICKEST scheme - it is not applicable to MDPM or Holly-Preissmann scheme. The MDPM scheme is a front tracking scheme which can be used for pollutant transport only. By default, there is no sediment exchange which corresponds to a pollutant transport case.
    use_transport_type_factor - If both bed load and suspended load transport are taken into account and sediment exchange is possible, the so-called transport type factor φ can be used. This is a factor for every grain class to weight both fluxes, i.e. bed load flux Qb,corr and suspended load flux Qs,corr are:

    Qb,corr = (1 - φ) · Qb
    Qs,corr = w · (φ · β · f · CE - CD)

    For a detailed description please read Chapter 3.2.3.4 in the Reference Manual on page R II 3.2-17. If there is not enough material in the active layer to cover the transport capacities of bed load and suspended load, suspended load is preferred (and bed load uses the remaining soil material). By default the transport type factor is not being used ('no'). If set to 'yes', the transport is splitted between bed load and suspended load according to the approach of Van Rijn or Bagnold which can be chosen via the flag 'transport_type_factor'.
    transport_type_factor - There are basically two approaches to determine how the sediment transport can be splitted into suspended load transport and bed load transport. Both approaches result in the transport type factor φ which depends on the settling velocity w and shear velocity u* and is therefore grain size-specific. If not specified (by default) an approach presented by Van Rijn (1984) is used (RII-1.181). There is the possibility to use a similar approach derrived by Bagnold (1966).
    pickup_factor - This is an important calibration factor for the pick-up rate during suspended load transport. It is multiplied linearly with the computed pick-up rate. By default it is set to 1.0.
    sink_velocity_type - There are many different (semi-)empirical formulas for the settling velocity of a sediment particles. BASEMENT allows to use either the formula provided by Van Rijn (1984), Wu & Wang (2006) or Zhang (1961). Additionally, absolute values of settling velocities can be defined by the user. These values can be defined within the tag 'settling_velocities'. By default the approach of Van Rijn (1984) is used.
    settling_velocities - Here, the settling velocities must be assigned for each grain class, no matter if it is in suspension or not.
    exchange_type - There are two typical approaches that describe how the sediment exchange rate between soil and suspension can be computed [RI Chapter 2.2.3]:
    concentration_type - The reference concentration for entrainment can be computed using the approach of Van Rijn (1984) - which is used as default - the approach of Zyserman & Fredsøe (1994) or by simply defining the ratio of the reference concentration and the depth-averaged concentration. The appropriate choose of the type of reference concentration can have a huge impact on the results and therefore might be an important calibration parameter!
    factor_for_near_bed_concentration - This factor defines the ratio of the near-bed suspended sediment concentration and the depth-averaged suspended sediment concentration:

    factor = Ca / Caverage

    A factor of 2.0 implies that the concentration near the bed is twice as high as on average in the cross section. The default value is 1.0, i.e. the assumption that there is no concentration gradient over depth but a uniform distribution.
    factor_depth_reference_height - If the reference concentration for entrainment is computed according to Van Rijn, then the reference height a can be chosen. It is defined as follows:

    reference_height = factor_depth_reference_height · water_depth

    The reference concentration is computed using the 'reference_height'. By default, the 'factor_depth_reference_height' is set to 0.1. This factor is only used if 'concentration_type' is set to 'vanrijn'.
    factor_m - This is a calibration factor which is used if sediment exchange is computed following the approach using shear stresses. M is used to calibrate the erosion rate (entrainment rate). Xu (1998) suggests to choose M in the order of 10e-5 up to 10e-3. M has the dimension of kg/(m2 · s).
    factor_n - This is a calibration factor which is used if sediment exchange is computed following the approach using shear stresses. n is used to calibrate the erosion rate (entrainment rate). Xu (1998) suggests to choose n between 1 and 4. n is a dimensionless parameter.
    tk - This is a calibration factor which is used if sediment exchange is computed following the approach using shear stresses. Tk is used to calibrate the deposition rate. Westrich and Juraschek (1985) suggested to choose a value of 0.0018.
    shape_factor - The Corey shape factor describes the irregularity of the shapes of sediment particles in natural rivers. It makes use of the characteristic lengths a, b and c (the longest, the intermediate and the shortest axes) and is given by

    S = c / sqrt(a · b)

    A spherical particle would have a Corey shape factor of 1.0. Naturally worn particles have a Corey shape factor of usually between 0.3 and 0.9. A value of 0.7 (corresponding to sand particles) is set by default.

    Example

    SUSPENDED_LOAD
{
   [...]
   PARAMETER
   {
      scheme = mdpm 
      diffusion_factor = 0.1
      sediment_exchange = on
   }
   [...]
}
    BOUNDARY
    BOUNDARY compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY > SUSPENDED_LOAD
    Description: Defines boundary conditions for suspended load. If no boundary condition is specified for part of or the whole boundary, an infinite wall is assumed.

    Variable type comp. condition units default values
    name string no - - - Chars [a-zA-Z0-9_-] are allowed
    type string yes - - - {suspension_discharge, coupling_suspension_discharge, out_down, coupling_out_down, wall}
    string string yes - - - {upstream, downstream}
    file string yes required if 'type' = 'suspension_discharge' - - -
    mixture string yes required if 'type' = 'suspension_discharge' - - -

    Block Usage

    For every different condition, a new block BOUNDARY has to be used. It is distinguished between upstream and downstream boundary conditions. At the upstream, inflow conditions are valuable. They need a mixture assigned in any case of multi grain size or single grain size simulations. Downstream boundary conditions are for suspension outflow, they don't need any mixture assigned. (In case of coupling no boundary_file and no boundary_mixture are needed).

    Description of Variables

    name - Unique identifier which is used to define controllers or couplings.
    type -
    string - Defines if the boundary is at the upstream or downstream end.
    file - Name of the file containing times and corresponding concentrations of the inflow water.
    mixture - Name of the inflowing mixture.

    Example

    SUSPENDED_LOAD
{
   [...]
   BOUNDARY
   {
      type = suspension_discharge
      file = cVar7.txt
      string = upstream
      mixture = unique
   }
   BOUNDARY
   {
      type = out_down
      string = downstream
   }
   [...]
}
    INITIAL
    INITIAL compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY > SUSPENDED_LOAD
    Description: Unlike for bed load, for suspended load it is necessary to specify initial conditions. The initial concentrations have to be defined for each cross section. This is done in a separate file, similar to the initial condition file for hydraulics.

    Variable type comp. condition units default values
    type string yes - - - {file, global_value}
    file string yes required if 'type' = 'file' - - -
    concentration real yes required if 'type' = 'global_value' [-] - x >= 0
    mixture string yes required if 'type' = 'global_value' - - -

    Description of Variables

    type - There are two ways to define the initial concentrations of suspended sediments:
    file - Name of the file containing the initial conditions. This file describes the initial situation of suspended material in the channel with the concentration and the mixture type for each cross section. On the first line of the file there is the time definition, e.g #time: 0. The time can be changed by the user. For example the state of a previous simulation can be used as an initial condition for a new simulation. For the new simulation in order to start from time = 0 again, the time has to be set to 0.
    concentration - initial volume concentration (m3 sediment per m3 water) [-] for all cross sections
    mixture - initial mixture of suspended load for all cross sections

    Example

    SUSPENDED_LOAD
{
   [...]
   INITIAL
   {
      file = initialC.txt
   }
   [...]
}

File Example:
         C [m3/m3]  Mixture Name
'Qp1a'   0.001      unique
'Qp1b'   0.001      unique
'Qp1c'   0.001      unique
'Qp1d'   0.001      unique
'Qp1e'   0.001      unique
    SOURCE
    SOURCE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY > SUSPENDED_LOAD
    Description: The SOURCE block for suspended load in 1D contains external sources for lateral suspended load inflow.
    Inner Blocks: EXTERNAL_SOURCE

    Block Usage

    It is possible to define a time depending addition or subtraction of suspended sediment or pollutant in [m3/s]. The time evolution of the volume is stored in a normal boundary file (without pores!). The declaration of the sources is introduced by the keyword SOURCE Each sources is described in a EXTERNAL_SOURCE block.

    Example

    SUSPENDED_LOAD
{
   [...]
   SOURCE
   {
      EXTERNAL_SOURCE
      {
         [...]
      }
      EXTERNAL_SOURCE
      {
         [...]
      }
   }
   [...]
}
    EXTERNAL_SOURCE
    EXTERNAL_SOURCE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY > SUSPENDED_LOAD > SOURCE
    Description: The external source block is used for additional lateral sources beneath the boundary conditions.

    Variable type comp. condition units default values
    name string no - - - Chars [a-zA-Z0-9_-] are allowed
    type string yes - - - {sediment_discharge, coupling_sediment_discharge}
    file string yes required if 'type' = 'sediment_discharge' - - -
    mixture string yes required if 'type' = 'sediment_discharge' - - -
    cross_section string yes - - - -

    Block Usage

    An external source for suspended load acts exactly on one cross-section. An input file for sediment discharge can be used for the definition of inflow and outflow (sink / negative discharge). The source_mixture has to be specified in any case, also if the source_file defines a pure sink. If no source block is specified at all, the additional source is set to zero. (In case of coupling no source_file and no source_mixture are needed).

    Description of Variables

    name - Unique identifier which is used to define controllers and couplings.
    type - Defines the type of source discharge.
    file - Name of the file containing the boundary condition data: time and corresponding concentration [0-1].
    mixture - Name of a predfined mixture which characterizes the suspended sediment source.
    cross_section - Name of the cross section to which the source is applied.

    Example

    SUSPENDED_LOAD
   {
   [...]
   SOURCE
   {
      EXTERNAL_SOURCE
      {
         type = suspended_discharge
         file = source_in_time.txt
         cross_section = QP84.200
         mixture = mixture2
      }
   }
   [...]
}
    INITIAL
    INITIAL compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY
    Description: This block defines the inital conditions for the morphology. The definition of this block is mandatory.

    Variable type comp. condition units default values
    type string yes - - - {initial_mesh, continue}
    file string no used if 'type' = 'continue' - - -

    Description of Variables

    type - This is the type of initial conditions for morphological simulations:
    a) 'initial_mesh'. This type means that the given mesh file is used as initial condition for the bed topography.
    b) 'continue'. The simulation is restarted from a restart-file obtained by a previous run ('hot-start'). The restart file contains the final topography from the former simulation with its layers and soil compositions.
    file - This is the name of a sediment restart file from a previous simulation with sediment transport.

    Example

    INITIAL
{
   type = continue
   file = Rhein_sed.dat      // restart file
}
 or 
INITIAL
{
   type = initial_mesh
}
    SOURCE
    SOURCE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY
    Description: The SOURCE block contains only external sources for sediment transport.For each such external source, a new inner EXTERNAL_SOURCE block has to be defined.
    Inner Blocks: EXTERNAL_SOURCE

    Block Usage

    The SOURCE block contains the external sources for sediment transport.

    Example

    MORPHOLOGY
{
   [...]
   SOURCE
   {
      EXTERNAL_SOURCE
      {
         [...]
      }
      EXTERNAL_SOURCE
      {
         [...]
      }
   }
   [...]
}
    EXTERNAL_SOURCE
    EXTERNAL_SOURCE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY > SOURCE
    Description: The external source block is used for additional lateral sources beneath the boundary conditions, e.g. unloading of bed load or lateral sediment inflow.

    Variable type comp. condition units default values
    name string no - - - Chars [a-zA-Z0-9_-] are allowed
    type string yes - - - {sediment_discharge, coupling_sediment_discharge, dredge, bed_load_function}
    file string yes required if 'type' = 'sediment_discharge' or 'bed_load_function' - - -
    mixture string yes required if 'type' = 'sediment_discharge' or 'bed_load_function' - - -
    grain_classes whitespace separated list of integers yes required if 'type' = 'dredge' - - -
    cross_section string yes - - - -
    dredge_level real yes required if 'type' = 'dredge' [m.a.s.l] - -
    dredge_trigger_height real yes required if 'type' = 'dredge' [m] - x >= 0
    maximum_dredge_rate real no used if 'type' = 'dredge' [m3/s] 1E32 x >= 0
    erode_below_fixed_bed string no used if 'type' = 'sediment_discharge' - no {yes, no}
    print_volumes string no used if 'type' = 'sediment_discharge' or 'dredge' - no {yes, no}

    Block Usage

    Note, that an external source for bed load acts exactly on one cross-section. An input file for sediment discharge can be used for the definition of inflow and outflow (sink / negative discharge) in [m3/s] without porosity taken into account. The source_mixture has to be specified in any case also if the source_file defines a pure sink. If no source block is specified at all, the additional source is set to zero. (In case of coupling no source_file and no source_mixture are needed).

    Description of Variables

    name - Unique identifier which is used to define controllers or couplings.
    type - Type of the external sediment source:
    file - Name of the file containing the time dependent sediment discharge for the source.
    mixture - Mixture of the sediment added by a 'sediment_discharge' or 'bed_load_function' source.
    grain_classes - defines for each grain class if it can be dredged (1) or not (0).
    cross_section - Name of the cross section to which the external sediment source is applied.
    dredge_level - indicates the bed level which is aimed at due to dredging.
    dredge_trigger_height - this is the trigger height of sediment deposition for the start of the dregding. If the deposition above the dredge level (difference between mean bottom level and the dredge level) exceeds the trigger value, the dredging is executed.Dredging is performed until the defined 'dredge_level' is reached.
    maximum_dredge_rate - maximum dredge rate which is used for dredging.
    erode_below_fixed_bed - Setting this parameter to 'yes' allows negative sediment sources (sinks) to erode below the fixed bed. This option may lead to unclear behaviour and may violate the sediment continuity. Do not use it if you are not absolutely sure what you are doing. This special option works only for 'sediment_discharge' sources and if the control volume is set to a constant value.
    print_volumes - Setting this parameter to 'yes' creates additional ascii-output containing the integrated amount of added / removed sediment volumes. The volumes are given in m3 exluding sediment porosity.

    Example

    BEDLOAD
{
   [...]
   SOURCE
   {
      EXTERNAL_SOURCE
      {
         type = sediment_discharge
         file = source_in_time.txt
         cross_section = QP84.200
         mixture = mixture2
      }
      EXTERNAL_SOURCE
      {
         type = sediment_discharge
         file = another_source_in_time.txt
         cross_section = QP84.800
         mixture = mixture1
      }
      EXTERNAL_SOURCE
      {
         type = bed_load_function
         file = BedLoadFunction.txt
         cross_section = QP84.800
         mixture = mixture1
	        side = left
      }
      EXTERNAL_SOURCE
      {
         type = dredge
         cross_section = 'P9120_95'
         grain_classes = ( 0 0 1 1 1 1 1 1 )
         dredge_level = 393.44
         dredge_trigger_height = 0.05
         maximum_dredge_rate = 0.01
 //m3/s         print_volumes = yes
 // print dredged volumes to file
      }
   }
   [...]
}
    GRAVITATIONAL_TRANSPORT
    GRAVITATIONAL_TRANSPORT compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > MORPHOLOGY
    Description: The GRAVITATIONAL_TRANSPORT block for morphology in 1D deals with transport due to longitudinal slope failures. Use this block to enable slope failures in cases slopes between elements within the domain. This approach bases on a failure-angle which determine when a slope failure takes place.

    Variable type comp. condition units default values
    failure_angle real yes - [Degree] - x >= 0
    threshold_angle real no - [Degree] 0.1 x >= 0
    cycle_step integer no - - 5 x >= 0
    max_iterations integer no - - 10 x >= 0

    Description of Variables

    failure_angle - A slope failure occurs if the slope between two elements exceeds this critical failure angle.
    threshold_angle - A threshold angle above critical angle that must be exceeded for gravitational transport calculations. Mainly for prevention of unnecessary iterations and should not be changed from recommended value.
    cycle_step - Specifies the cycle steps for which gravitational transport shall be calculated. For example, a value of 5 forces the computations to be done after every 5 cycles of the sediment routine.
    max_iterations - Abort criteria for gravitational transport calculation. Specifies the maximum number of iterations which may be performed for gravitational transport calculations. (The larger the number the faster the slope failure will take place.)

    Example

    GRAVITATIONAL_TRANSPORT
{
    failure_angle = 30 
    threshold_angle = 0.1 
    max_iterations = 20 
    cycle_step = 1 
}
    OUTPUT
    OUTPUT compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D
    Description: This block specifies the desired output data.
    Inner Blocks: SPECIAL_OUTPUT

    Variable type comp. condition units default values
    output_time_step real yes - [s] - x >= 0
    console_time_step real no - [s] - x >= 0
    restart_time_step real no - [s] 1E32 x >= 0

    Block Usage

    In 1D, some default output files contain all information about geometry and other variables along the flow direction. The output is written according to the output time step setting. For temporal outputs, one has to specify a SPECIAL_OUTPUT where several variables are listed versus the time for a chosen cross-section. Additionally, it is possible to extract minimal and maximal values or the sum of variables over the time.

    Description of Variables

    output_time_step - Time step for default output file 'region_name_out.txt'. Be aware that small output time step can lead to large default output file.
    console_time_step - Time step for the console output
    restart_time_step - Time step for writing default restart files. Setting it to small values may result in very large number restart files! If the value is not set, than it is set per default to a very large number (1E32). This implies that only the last time step of the simulation is written to the restart file.

    Example

    BASECHAIN_1D
{
   [...]
   OUTPUT
   {
      output_time_step = 10.0
      console_time_step = 1.0
      SPECIAL_OUTPUT
      {
         [...]
      }
      SPECIAL_OUTPUT
      {
         [...]
      }
   }
   [...]
}
    SPECIAL_OUTPUT
    SPECIAL_OUTPUT compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASECHAIN_1D > OUTPUT
    Description: Besides the default output, some extra output can be defined.

    Variable type comp. condition units default values
    type string yes - - - {monitor, tecplot_all, tecplot_all_bin, mixtures, delta_v_sed, delta_v_water, transport_diagram, delta_v_suspension, BASEviz, matlab, tecplot_flux, matlab_flux}
    output_time_step real yes - [s] - x >= 0
    cross_sections whitespace separated list of strings yes required if 'type' = 'monitor' - - -
    A whitespace separated list of strings no - - - valid entries are {'time', 'max', 'min'}
    b whitespace separated list of strings no - - - valid entries are {'time', 'max', 'min'}
    Q whitespace separated list of strings no - - - valid entries are {'time', 'max', 'min', 'sum'}
    Qb whitespace separated list of strings no - - - valid entries are {'time', 'max', 'min', 'sum'}
    TC whitespace separated list of strings no - - - valid entries are {'time', 'max', 'min', 'sum'}
    GT whitespace separated list of strings no - - - valid entries are {'time', 'max', 'min', 'sum'}
    wse whitespace separated list of strings no - - - valid entries are {'time', 'max', 'min'}
    energy_line whitespace separated list of strings no - - - valid entries are {'time', 'max', 'min'}
    v whitespace separated list of strings no - - - valid entries are {'time', 'max', 'min'}
    c whitespace separated list of strings no - - - valid entries are {'time', 'max', 'min', 'sum'}
    F whitespace separated list of strings no - - - valid entries are {'time', 'max', 'min'}
    h whitespace separated list of strings no - - - valid entries are {'time', 'max', 'min'}
    geometry whitespace separated list of strings no - - - valid entries are {'time', 'max', 'min'}
    geometry_bin whitespace separated list of strings no - - - valid entries are {'time', 'max', 'min'}
    variable string no used if 'type' = 'BASEviz' - depth {depth, wse, velocity, tau}
    show gridlines boolean no used if 'type' = 'BASEviz' - no {no, yes}
    write_jpeg_image_time real no used if 'type' = 'BASEviz' - -1.0 -
    BASEextern string no used if 'type' = 'monitor' - - -
    output_single_file boolean no used if 'type' = 'monitor' - no {no, yes}

    Block Usage

    Either one chooses the tecplot_all output type for an exhaustive output. However, this option could produce too much data. In this case, one may choose specifically what data for which cross-section shall be written to an output file. This may include minimum, maximum, summation and whole time series for the principal variables as the wetted area, discharge, sediment discharge, water surface elevation, velocities and concentration. Each such information for each cross-section will be written into an own file. For graphical output of the simulation results during run-time with the BASEviz visualization choose the BASEviz output type.

    Description of Variables

    type - Defines the type of the special output. The following optional outputs can be generated:
    output_time_step - The output is printed for the given intervals.
    cross_sections - Names of the cross sections for which the monitoring point output has to be created.
    A - Wetted area of the cross section.
    b - Mean bottom level of the cross section.
    Q - Discharge in [m3/s].
    Qb - Bedload discharge in [m3/s].
    TC - Bedload transport capacity in [m3/s] without porosity.
    GT - Gravitational sediment transport in [m3/s].
    wse - Water suface elevation.
    energy_line - Energy line.
    v - Velocity.
    c - Concentration.
    F - Froude number [-], calculated as F = v/(g·R)0.5 with v = Q/A [m/s] and R = A/L [m]

    v = flow velocity [m/s]
    R = hydraulic radius [m]
    Q = discharge [m3/s]
    A = flow area [m2]
    L = wetted perimeter [m]
    h - mean (average) flow depth [m], calculated as h = A/w

    A = flow area [m2]
    w = water surface width [m]
    geometry - Writes the geometry of the cross section to an ascii Tecplot file.
    geometry_bin - Writes the geometry of the cross section to a binary Tecplot file.
    variable - Output (plot) of a specified variable
    show gridlines - Enable or disable gridline plotting.
    write_jpeg_image_time - This option determines if the BASEviz visualization shall render JPEG images.If this time is set to a value > 0.0 than each time intervall a JPEG image is created. Please note that the rendering depends on the visualization window. It is therefore recommended to deactive the help (press 'h') and to first maximize the BASEviz-Window and then hide the window. By default, the time to a negative value which means that no images are rendered.
    BASEextern - Parameter specifies the name of a defined BASEextern sub-domain within the domain. Setting this parameter results in data sending over tcp/ip instead of output to file. This option may be useful for coupling with external programs. You must provide interface at the external program which receives the send data.
    output_single_file - Parameter specifies if monitoring output is written to a single file or multiple files.

    Example

    BASECHAIN_1D
{
   [...]
   OUTPUT
   {
      output_time_step = 10.0
      console_time_step = 1.0
      SPECIAL_OUTPUT
      {
         type = monitor
         output_time_step = 10.0
         cross_sections = ( QP84.200  QP86.600 )
         A = (  min max  )
         Q = (  sum  time  )
         Qb = ( sum )
         TC = ( sum  time )
         GT = ( sum  time )
         V = ( time )
         topology_bin = ( time )
      }
      SPECIAL_OUTPUT
      {
         type = monitor
         output_time_step = 35.0
         cross_sections = (  QP82.100  )
         A = (  time  )
         Q = (  sum  time  )
         output_single_file = no
      }
      SPECIAL_OUTPUT
      {
         type = tecplot_all
         output_time_step = 50.0
      }
      SPECIAL_OUTPUT
      {
         type = BASEviz
         variable = depth
         show_gridlines = yes
      }
   }
   [...]
}
    BASEPLANE_2D
    BASEPLANE_2D compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN
    Description: This block includes all information for a 2D simulation.
    Inner Blocks: GEOMETRY
    HYDRAULICS
    MORPHOLOGY
    TIMESTEP
    OUTPUT
    VEGETATION

    Variable type comp. condition units default values
    region_name string yes - - - Chars [a-zA-Z0-9_-] are allowed

    Block Usage

    The main block declaring a 2D simulation is called BASEPLANE_2D within the DOMAIN-block. It contains all information about the precise simulation. To ensure a homogeneous input structure, the sub blocks for BASEPLANE_2D and BASECHAIN_1D are roughly the same. A first distinction is made for geometry, hydraulic and morphologic data as the user is not always interested in both results of fluvial and sedimentologic simulation. The geometry however is independent of the choice of calculation. Inside the two blocks (hydraulics and morphology), the structure covers the whole field of numerical and mathematical information that is required for every computation. These blocks deal with boundary conditions, initial conditions, friction, sources and sinks, numerical parameters and settings and output-specifications. Be aware of a slightly different behaviour of the sub blocks dependent on the choice of 2D or 1D calculation.
    The only variable to declare is the name of the region.

    Description of Variables

    region_name - The name of the region has to be specified. It may be used for coupled simulations.

    Example

    DOMAIN
{
   multiregion = Rhein
   PHYSICAL_PROPERTIES
   {
      [...]
   }
   BASEPLANE_2D
   {
      region_name = RheinDelta
      GEOMETRY
      {
         [...]
      }
      HYDRAULICS
      {
         [...]
      }
      MORPHOLOGY
      {
         [...]
      }
      VEGETATION
      {
         [...]
      }
      TIMESTEP
      {
         [...]
      }
      OUTPUT
      {
         [...]
      }
   }
}
    GEOMETRY
    GEOMETRY compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D
    Description: Defines the topography for this 2D-simulation. The type of input format and the name of the geometry input file have to be specified.
    Inner Blocks: STRINGDEF
    MOVABLE_BED

    Variable type comp. condition units default values
    type string yes - - - {2dm}
    file string yes - - - -

    Block Usage

    The GEOMETRY block is used for 2D-simulations to define the Input-file containing the computational grid. The type and the name of the mesh-file have to be defined. At the moment, the only supported format for 2D grids is .2dm.which can be produced by several grid generators, e.g.: - SMS (commercial, aquaveo.com) - Janet (commercial, smileconsult.de) - Blue Kenue (free, www.nrc-cnrc.gc.ca/eng/ibp/chc/software/kenue/blue-kenue.html) - ... Furthermore, cross-sections for e.g. boundary definitions are defined using the inner block STRINGDEF. The inner block STRINGDEF is used only for 2D simulations to define connected node strings, e.g. for cross-string or boundary definitions. These definitions are of various uses, mostly for the definition of boundary conditions. A way of defining element attributes in 2D is the use of a material index. When importing an .2dm-geometry type mesh, every cell can be assigned such an index (an integer number). This index can be used to assign the following attributes:The possible use of a material index is explained in the corresponding sections. The inner block MOVABLE_BED can be used to enforce changes in the bed elevation with time.

    Description of Variables

    type - The only supported file type for 2D-grids is '2dm' at the moment. This requires a file with the .2dm-format.
    file - Filename of the gridfile.

    Example

    BASEPLANE_2D
{
   region_name = RhineDelta
   GEOMETRY
   {
      type = sms
      file = mesh.2dm
   }
   [...]
}
    STRINGDEF
    STRINGDEF compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > GEOMETRY
    Description: Defines a successive string of edges represented by an array of node indices from the 2D-input file. Can be used to assign edge-specific stuff like boundary conditions or the definition of cross-strings for output observation. Be aware to use continuous strings!

    Variable type comp. condition units default values
    name string yes - - - Chars [a-zA-Z0-9_-] are allowed
    node_ids whitespace separated list of integers yes - - - -
    upstream_direction string yes - - - {right, left}

    Block Usage

    Every STRINGDEF needs a unique name assigned. This name will be used later, e.g. at the definition of boundary conditions to specify the desired STRINGDEF. The node_ids are the node numbers taken from the 2D mesh file. The whole string needs the nodes to be in an ordered and successive row. At least two nodes have to be specified in order to get a working STRINGDEF.

    Description of Variables

    name - Unique name for the String.
    node_ids - List of nodes within brackets. Must contain at least two nodes. The node numbers can be obtained from the grid file.
    upstream_direction - For this stringdef, you must define the upstream direction in order to allow for some meaningful outputs of type 'stringdef_history'. The direction is defined depending on the definition of the stringdef. Starting from the first node in the stringdef-definition looking in direction to the second node determines the right or left side.

    Example

    BASEPLANE_2D
{
   region_name = RhineDelta
   GEOMETRY
   {
      type = 2dm
      file = mesh.2dm
      STRINGDEF
      {
         name = cross-section1
         node_ids = (  12 22 25 72 92  )
			upstream_direction = left
      }
      STRINGDEF
      {
         name = boundary1
         node_ids = (  112 212 215 712 192  )
			upstream_direction = right
      }
      STRINGDEF
      {
         name = boundary2
         node_ids = (  13 23 35 73 93  )
			upstream_direction = left
      }
   }
   [...]
}
    MOVABLE_BED
    MOVABLE_BED compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > GEOMETRY
    Description: A moving geometrical boundary condition.
    Defines nodes of the hydraulic grid that move (vertically only) with time. The movement can be regarded as 'enforced' erosion or aggradation.

    Variable type comp. condition units default values
    file string yes - - - -

    Block Usage

    This MOVABLE_BED block needs a single text file assigned, where the information about the moving nodes is given.

    Description of Variables

    file - Filename of the ascii-file containing the information about the moving bed.
    For each node, whose elevation is enforced to change in time, a time series must be defined. Nodes, that are not mentioned in the file, are not touched and stay at the same elevation.

    Arrangment of the text file:Example:
    0   id1   id2   id3   id4   id5   ...
t1  elv   elv   elv   elv   elv   ...
t2  elv   elv   ...
t3  ...
...

    Example

    BASEPLANE_2D
{
   region_name = RhineDelta
   GEOMETRY
   {
      type = 2dm
      file = mesh.2dm
      MOVABLE_BED
      {
         file = moving_nodes1.txt
      }
   }
   [...]
}
    HYDRAULICS
    HYDRAULICS compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D
    Description: Defines the hydraulic specifications for the simulation. This block contains only further sub blocks but no own variables.
    Inner Blocks: PARAMETER
    FRICTION
    BOUNDARY
    INNER_BOUNDARY
    TURBULENCE_MODEL
    INITIAL
    SOURCE

    Example

    HYDRAULICS
{
   BOUNDARY
   {
      [...]
   }
   INNER_BOUNDARY
   {
      [...]
   }
   INITIAL
   {
      [...]
   }
   SOURCE
   {
      [...]
   }
   FRICTION
   {
      [...]
   }
   PARAMETER
   {
      [...]
   }
}
    PARAMETER
    PARAMETER compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > HYDRAULICS
    Description: The PARAMETER block for hydraulics is used to specify general numerical parameters for the simulation, as time step, total run time, CFL number, solver type etc.

    Variable type comp. condition units default values
    minimum_water_depth real no - [m] 0.05 x >= 0
    riemann_solver string no - - exact {exact, hll, hllc}
    riemann_tolerance real no used if 'riemann_solver' = 'exact' [m] 1.0e-6 x > 0
    simulation_scheme string no - - exp {exp}
    velocity_update_partial string no - - volume_area {volume_area, depth}
    dynamic_depth_solver string no - - on {off, on}
    dynamic_depth_solver_precision real no - [m] 0.005 -
    geo_min_area_ratio real no - [-] 0.05 -
    geo_max_angle_quadrilateral real no - [-] 45 -
    geo_min_aspect_ratio real no - [-] 0.06 -

    Block Usage

    The only thing that needs to be defined is the total_run_time. All other variables use default values if they dont get specified by the user. Changing the hydraulic Parameters either leads to faster and more stable simulations or it may make the simulation collapse. The most often changed Parameters are the CFL number to change the timestep and the minimum_water_depth to prevent division by zero.

    Description of Variables

    minimum_water_depth - This parameter is a key element in shallow waters simulation. The definition of a minimal water depth avoids division by zero which would lead to numerical instabilities. Every cell with water depth below this value will be treated as dry and no fluxes will be calculated until the cell reaches a water depth above the minimum_water_depth. Increasing this parameter leads to a more stable simulation with the prize of reduced accuracy and vice versa.
    riemann_solver - Different solvers for the Riemann problem are applicable. At the moment the use of the exact solver is strongly recommended.
    riemann_tolerance - The exact Riemann solver performs an iterative solution of an analytical equation for the depth. The tolerance determines the minimal deviation between two successive iterations. The default value should usually not be changed.
    simulation_scheme - The keyword 'exp' indicates an explicit time integration scheme (Euler method). An implicit time integrator has not yet been implemented in 2D.
    velocity_update_partial - The velocity calculation from the momentum fluxes requires a division by the water depth. In partially wetted elements this may result in unphysical high velocities, because the water depths can become very small. To prevent these high velocities, a representative depth is calculated by dividing the water volume by the wetted area. Set 'volume_area' for this improved treatement in partially wetted elements (default behaviour) or set 'depth' for the formerly implemented method (which may lead to high velocities).
    dynamic_depth_solver - There are two possibilities for the choice of the dephts for the formulation of the riemann problem. Both options must not be the same because the bed surface within a cell can vary over the cell if the topography is irregular.By setting this option to 'on' both approaches are used depending on the situation. First, the differences in the water elevations (delta_wse) and the differences in the water depths at the cell centers (delta_depth) are calculated. Then, if 'delta_wse' > 'delta_depth' the riemann problem is formulated with the depths at the edge. Else, the riemann problem is formulated with the depths at the cell centre. Setting the parameter to 'on' (default) reduces the mesh dependance of the results in some situations and is recommended.
    dynamic_depth_solver_precision - This tag is only used if 'dynamic_depth_solver' = on. Only if the difference in water surface elevation between the left and right element is larger than this value the dynamic depth solver is applied as described in the tag 'dynamic_depth_solver'. Usually the default value should not to be changed.
    geo_min_area_ratio - Set the minimum area ratio (i.e. element's area divided by the average element area)for which is checked during the geometry checks at the beginning of a simulation. The default value should usually not be changed.
    geo_max_angle_quadrilateral - Set the maximum angle for ambiguous quadrilateral elements (i.e. the angle between the plane normal vectors of the two triangles which result by splitting the quadrilateral along a break line) for which is checked during the geometry checks at the beginning of a simulation. The default value should usually not be changed.
    geo_min_aspect_ratio - Set the aspect ratio for which is checked during the geometry checks at the beginning of a simulation. The default value should usually not be changed.

    Example

    HYDRAULICS
{
   [...]
   PARAMETER
   {
      simulation_scheme = exp
      riemann_solver = exact
      CFL = 1.0
      initial_time_step = 0.01
      minimum_time_step = 0.0001
      total_run_time    = 3600.0
      minimum_water_depth = 0.05
      riemann_tolerance = 1E-6
   }
   [...]
}
    FRICTION
    FRICTION compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > HYDRAULICS
    Description: The FRICTION block defines everything that is related to the Friction term of the Shallow water equations. Friction values are often used to calibrate a numerical model.

    Variable type comp. condition units default values
    type string yes - - - {manning, strickler, chezy, darcy, yalin, bezzola}
    default_friction real yes - [s/m^(1/3)] Manning, [m^(1/3)/s] Strickler, [m] equivalent sand roughness. - x >= 0
    input_type string no - - - {index_table}
    index whitespace separated list of integers yes required if 'input_type' = 'index_table' - - -
    friction whitespace separated list of reals yes required if 'input_type' = 'index_table' - - -
    wall_friction string yes - - - {on, off}
    wall_friction_factor real no used if 'wall_friction' = 'on' - - x > 0
    grain_size_friction string no - - no {no, yes}
    strickler_factor real no used if 'grain_size_friction' = 'yes' - 21.1 x > 0
    fixed_bed_d90 real no used if 'grain_size_friction' = 'yes' [mm] 10.0 x > 0
    roughness_factor real no used if 'grain_size_friction' = 'yes' - 3.0 x > 0

    Block Usage

    Friction values can be calculated using different approaches as e.g. Manning/Strickler, Chezy, etc. or directly from the grain size.Friction values are assigned to all cells of the 2D grid. If a cell is not given an explicit friction value, the default_friction value is used. Different friction values can be assigned to distinct cells using the material index technique. Every cell of the 2D mesh can be assigned a material index (an integer number). This index is then used to define common properties (like friction values) of all cells with the same index. When simulating flows that interact with the wall boundary condition (like in a flume), the impact of the wall friction can be taken into account or switched off.

    Description of Variables

    type - The desired friction law must be specified. There is no default. The follwoing friction laws can be chosen:
    All vailable friction laws are valid only for fully turbulent flow in hydraulically rough channels.
    default_friction - This is the default friction coefficient used for all elements where no friction is defined. This coefficient has to correspond to the chosen type of friction, e.g. 0.03 for Manning's [s/m^(1/3)] or 33 for Strickler's [m^(1/3)/s] coefficient.If all elements have the same friction coefficient, no further definitions are needed. If several different friction coefficients shall be used, they can be assigned to their corresponding elements using the material index technique (see tag 'input_type').
    input_type - When different friction values for distinct areas in the mesh are needed, the technique of the material index has to be used. This option indicates the use of the material index technique. The only available choice is 'index_table'.
    index - This tag expects a list with all the material indices (integer numbers) used. The ordering within the list must correspond to the ordering for the 'friction'. This tag is only active if 'input_type = index_table' is selected.
    friction - This tag expects a list with friction coefficients corresponding to the material indices. The ordering within the list must correspond to the ordering for the 'index'. This tag is only active if 'input_type = index_table' is selected.
    wall_friction - Enables or disables wall friction at boundary conditions using walls. By default, wall friction is activated.
    wall_friction_factor - This is the friction coefficient for side wall friction. If this parameter is not specified, the same friction values as for the bed are used.
    grain_size_friction - This option activates the calculation of the bed friction using the grain size. By default, this is set to 'no'. This approach makes only sense when bedload transport is active and therefore, grain sizes are changing in time. However, it is a experimental feature. Furthermore, it is not best suited for calibrating a simulation.
    strickler_factor - This is the factor for the computation of the friction value from the grain diameter: k_strickler = strickler_factor/(d90)^(1/6) It allows a minimal calibration of a simulation using grain size friction. By default, it is set to 21.1.
    fixed_bed_d90 - This parameter is only needed if 'grain_size_friction' is active. If the friction value is determined from the grain size distribution, a special treatment is needed in case of erosion down to the fixed bed. In such a case no sediment and no grain size distribution is present. Therefore, this user defined d90-value is used to calculate the friction and is expected in [mm].
    roughness_factor - This is the factor for the computation of the friction value from the grain diameter: ks = d90*roughness_factor. By default, it is set to 3.

    Example

    [...]
FRICTION
{
   type = manning
   default_friction = 0.033
   input_type = index_table
   index = ( 1 2 )
   friction = ( 0.033 0.038 )
   wall_friction = off		// disables wall friction
}
[...]
    BOUNDARY
    BOUNDARY compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > HYDRAULICS
    Description: Defines boundary conditions for hydraulics.

    Variable type comp. condition units default values
    name string no - - - Chars [a-zA-Z0-9_-] are allowed
    string_name string yes required if 'type' = 'hydrograph' or 'coupling_hydrograph' or 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' or 'wall' or 'zero_gradient' or 'coupling_zero_gradient' or 'hqrelation' or 'coupling_hqrelation' or 'zhydrograph' or 'coupling_zhydrograph' - - Chars [a-zA-Z0-9_-] are allowed
    type string yes - - - {hydrograph, coupling_hydrograph, weir, coupling_weir, gate, coupling_gate, wall, zero_gradient, coupling_zero_gradient, hqrelation, coupling_hqrelation, zhydrograph, coupling_zhydrograph, pore_pressures_coupling}
    file string no used if 'type' = 'hydrograph' or 'weir' or 'coupling_weir' or 'gate' or 'coupling_gate' or 'zhydrograph' or 'coupling_zhydrograph' or 'hqrelation' or 'coupling_hqrelation' - - -
    my real no - [-] - 0 < x <= 1
    slope real no used if 'type' = 'hydrograph' or 'coupling_hydrograph' or 'hqrelation' or 'coupling_hqrelation' per mill - x >= 0
    max_interval real no used if 'type' = 'hydrograph' or 'coupling_hydrograph' [m] 20 x >= 0
    number_of_iterations integer no used if 'type' = 'hydrograph' or 'coupling_hydrograph' - 5000 x > 0
    weighting_type string no used if 'type' = 'hydrograph' or 'coupling_hydrograph' or 'hqrelation' or 'coupling_hqrelation' - conveyance {conveyance, area}
    wall_flux boolean no used if 'type' = 'hqrelation' or 'coupling_hqrelation' - no {no, yes}
    inflow_possible boolean no used if 'type' = 'zhydrograph' or 'coupling_zhydrograph' - yes {no, yes}
    zero_velocity boolean no used if 'type' = 'zhydrograph' or 'coupling_zhydrograph' - no {no, yes}
    dynamic_slope boolean no used if 'type' = 'hydrograph' or 'hqrelation' - no {no, yes}
    dynamic_slope_xref real no used if 'dynamic_slope' = 'yes' [m] 18000.0 -
    precision real no used if 'type' = 'hydrograph' or 'coupling_hydrograph' [m] -1.0 -
    wse_calc_method string no used if 'type' = 'hydrograph' or 'coupling_hydrograph' or 'hqrelation' or 'coupling_hqrelation' - average {average, local}
    conveyance_type string no used if 'type' = 'hqrelation' or 'coupling_hqrelation' - tables {tables, edge}

    Block Usage

    The implementation of a boundary condition requires the specification of a user defined cross section string in the STRINGDEF block. If no boundary condition is specified for part of or the whole boundary, a wall of infinite height is assumed. For every different boundary condition, a new block BOUNDARY has to be used.

    Description of Variables

    name - Every boundary condition may be given a name which can be used further for coupling or controller.
    string_name - This is the name of a cross section string defined in the STRINGDEF blocks for which this boundary condition holds.
    type -
    file - Filename of the file containing:
    my - My is the Poleni factor used for weir and gate boundary conditions. It is used to calibrate a weir or a gate to a desired behaviour. In case of no my is set by the user, it will be computed dynamically dependent on upstream and downstream water levels of the weir/gate.
    slope - This is the average slope at the boundary cross section. It is used for the calculation of an h-Q iteration for the boundary conditions 'hydrograph' and 'hqrelation'. The slope does not neccessarily have to be the same as measured in reality. Very small as well as large values for the slope may lead to unexpected behaviour. It is strongly recommended to choose a slope such that subcritical flow conditions are obtained.
    max_interval - This parameter is used for the calculation of the h-Q tables in case of a hydrograph boundary condition. It is the maximal height above the highest point of a cross section. The default value should usually not be changed.
    number_of_iterations - This parameter is used for the calculation of the h-Q tables in case of a hydrograph boundary condition. It is the maximum number of iterations for the determination of the h-Q tables. The default value should usually not be changed.
    weighting_type - A hydrograph inflow boundary as well as the h-Q outflow boundary need to split up the total discharge to the distinct edges using a weighting method. The choice is between weighting according to 'conveyance' and 'area'. Default is 'conveyance'. area weighting is recommended if bedload enters the inflow section, because this weighting type leads to constant velocities along the cross section.
    wall_flux - This option handles the behaviour of partially wetted elements near a h-Q boundary condition. (The option has only an effect if no file is specified for the h-Q relation.)In the normal case, the fluxes across the edges of a partially wetted element are calculated like a zero-gradient. This is the default behaviour (wall_flux = off). Setting wall_flux = on leads to a flux calculation as if there was a wall near a partially wetted element. The default value should usually not be changed.
    inflow_possible - This option enables or disables inflowing discharges for a zhydrograph (is always off in coupling).
    zero_velocity - This parameter specifies if the velocites at the outer ghost cell shall be set to zero. If the boundary represents a lake, reservoir, etc., than this option should be set to 'yes'.If the parameter is set to 'no', it is assumed that the velocities at the outer ghost cellequal the outgoing velocities at the last element.
    dynamic_slope - This bool defines dynamic slope adjustment due to erosion and deposition at upstream 'hydrograph' boundary. Note that for downstream 'hqrelation' boundary, this works only in combination with dynamic slope defined for upstream 'hydrograph' boundary
    dynamic_slope_xref - Longitudinal reference to determine dynamic slope
    precision - This is the precision in meters for the h-Q iterations. The iteration is stopped if the difference between two iterations is below this value. If this parameter is not specified explicitely, a default value in form of a negative number is used. By default, this leads to a dynamic precision of 0.1 * minimum_water_depth.
    wse_calc_method - This option determines how the water surface elevation at a boundary with discharge or hq-relation condition is evaluated. The default option 'average' takes the average over all adjacent elements, the option 'local' takes the wse from the adjacent element. Usually, this option should not be changed.
    conveyance_type - The outflow over each edge is weighted with the local conveyance. Thereby the conveyance can either be calculated from a 1D approach with a 1D-table (default), or it can be calculated seperately for each edge without 1D considerations. Usually, this option should not be changed.

    Example

    HYDRAULICS
{
   BOUNDARY
   {
      type = hydrograph
      string_name = boundary1    // as defined in STRINGDEF
      file = discharge_in_time.txt
      slope = 1 // per mill
      weighting_type = conveyance // default
   }
   BOUNDARY
   {
      type = weir
      string_name = other_bndry  // as defined in STRINGDEF
      file = weirlevel_in_time.txt
   }
   BOUNDARY
   {
      type = weir
      my = 0.6                   // constant Poleni factor
      string_name = other_bndry  // as defined in STRINGDEF
      file = weirlevel_in_time.txt
   }
   BOUNDARY
   {
      type = zero_gradient
      string_name = third_bndry  // as defined in STRINGDEF
   }
   BOUNDARY
   {
      type = hqrelation
      string_name = outflow_section
      file = hq_relation.txt
      // OR
      slope = 1.25 // per mill
   }
   BOUNDARY
   {
      type = gate
      string_name = yetanotherstring
      file = gate_elevation_in_time.txt
      my = 0.6
   }
   BOUNDARY
   {
      type = zhydrograph
      string_name = outflow_section
      file = wse_reservoir.txt
   }
   [...]
}
    INNER_BOUNDARY
    INNER_BOUNDARY compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > HYDRAULICS
    Description: This block is used to define inner boundaries within a 2D grid. Possible choices are weir and gate.

    Variable type comp. condition units default values
    type string yes - - - {gate, weir, hqrelation}
    string_name1 string yes - - - Chars [a-zA-Z0-9_-] are allowed
    string_name2 string yes - - - Chars [a-zA-Z0-9_-] are allowed
    file string yes - - - -
    my real no - [-] - 0 < x <= 1
    momentum_factor real no used if 'type' = 'gate' or 'hqrelation' [-] 1.0 -

    Block Usage

    Additionally to the normal boundary conditions, there may be need of hydraulic structures like a weir or a gate within the computational domain. These conditions compute the flow over an edge using a special formula for either a weir or a gate. Technically, this produces at the same time an outflow and a corresponding inflow into the same computational grid.
    To define such an inner boundary condition, contrary to the normal boundary, two cross section strings (defined in a STRINGDEF) have to be defined for either weir or gate. Both STRINGDEF's must contain the same number of nodes in the same order (direction)! The inner boundaries act in both direction - the flow direction is determined from high wse to low wse. However, it is recommended to declare string1 as the 'outflow string' and string2 as the 'inflow string' as one would expect it from the model setup. An exception is the HQ-relation boundary, which acts only in one direction!

    If inner boundaries and sediment transport computations are combined, the problem arises that sediment masses are not transported over the inner boundary but stop in front of the innerboundary structure. This behaviour is undesired in some scenarios. A solution, allowing for sediment continuity, is the use of 'dredge sources' which can be used to let the sediments pass the inner boundary.

    Description of Variables

    type -
    string_name1 - This is the name of a cross section string defined in a STRINGDEF block. Usually, the first string corresponds to the expected outflow boundary.
    string_name2 - This is the name of a cross section string defined in a STRINGDEF block. Usually, the second string corresponds to the expected inflow boundary.
    file - This is the filename of the file that contains the weir/gate level at different moments in time. Usually, this is a .txt-file. In case of a 'hQ-relation', this file contains water depths h (first column) and discharges Q (second column)
    my - This factor is often called 'Poleni-factor'. It is mulitplied to the discharge formula and allows a certain calibration of a weir/gate. In case of no my is set by the user, it will be computed dynamically dependent on upstream and downstream water levels of the weir/gate.
    momentum_factor - This is an advanced feature. Usually it needs not to be changed. This factor is multiplied to the momentum terms (except the pressure terms) for the incoming water flow at the inner gate. Reducing it to zero means, that the water enters without momentum (e.g. sharp drop).

    Example

    HYDRAULICS
{
   INNER_BOUNDARY
   {
      type = weir
      my = 0.85
      string_name1 = weir_in   // as defined in STRINGDEF
      string_name2 = weir_out
      file = weirLevel.txt
   }
   INNER_BOUNDARY
   {
      type = gate
      my = 0.7
      string_name1 = gate_in   // as defined in STRINGDEF
      string_name2 = gate_out
      file = gateLevel_in_time.txt
   }
   INNER_BOUNDARY
   {
      type = hqrelation
      string_name1 = gate_in   // must be upstream STRINGDEF
      string_name2 = gate_out  // must be downstream STRINGDEF
      file = hq_table.txt      // table containing wse and Q
   }
   [...]
}
    TURBULENCE_MODEL
    TURBULENCE_MODEL compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > HYDRAULICS
    Description: This block handles everything related to inner viscous friction and turbulence.

    Variable type comp. condition units default values
    type string yes - - - {algebraic}
    kinematic_viscosity real no - [m2/s] 0.000001307 x >= 0
    eddy_viscosity_type string no - - dynamic {dynamic, constant}
    eddy_viscosity real yes required if 'eddy_viscosity_type' = 'constant' [m2/s] - x >= 0
    turbulence_factor real no used if 'eddy_viscosity_type' = 'dynamic' [-] 1 -
    boundary_gradient string no - - zerogradient {zerogradient, zerovelocity}

    Block Usage

    In situations where strong gradients of the velocity occur, it may be useful to activate the turbulence model. For example, this is the case in problems with laminar separation, sudden widenings or contractions of the flow. The algebraic turbulence model is the only type available at the moment. For this model, either a constant eddy viscosity or a dynamic eddy viscosity can be chosen. If eddy_viscosity_type is 'constant', then the value of eddy_viscosity for turbulent viscosity is used throughout the whole domain. If eddy_viscosity_type is 'dynamic' or not defined within the command file, then the dynamic eddy viscosity is set to active. Dynamic eddy viscosity depends on the local water depth and velocity and is therefore different for each element. To increase the effect of dynamic eddy viscosity, the dimensionless turbulence_factor can be set to any positive number. Usual values are around 1 to 5. For the effect of inner Friction, the kinematic viscosity with unit [m2/s] has to be set. Usually, the kinematic viscosity is much smaller than the turbulent eddy viscosity, therefore, there is only a small effect of inner friction.

    Description of Variables

    type - This is the choice of the turbulence model type. Currently, the only option is 'algebraic'.
    kinematic_viscosity - The kinematic viscosity is a property of a fluid and characterizes the losses du to inner friction. For water, the value is very small. By default, it is set to 0.000001307.
    eddy_viscosity_type - This is the choice of the turbulent eddy viscosity type. The turbulent eddy viscosity is not a physical property but rather a parameter that characterizes the strength of turbulence in a flow. Usual values range in the order of 0.1 to 1 dependent on the size of the expected eddies. If 'constant' is selected, then the same eddy viscosity is used anywhere in the computational grid. On the other hand, if 'dynamic' is chosen, then a dynamic eddy viscosity will be used which depends on the local velocities and thus is not constant throughout the grid.
    eddy_viscosity - The turbulent viscosity to be used throughout the computational grid.
    turbulence_factor - This factor amplifies the effect of dynamic eddy viscosity. This can be useful when slow velocities lead to small dynamic eddy viscoities. Usual values are around 1 to 5.
    boundary_gradient - To calculate the velocity gradients in boundary elements, two methods can be chosen: Default method is a 'zero-gradient', where the virtual element on the other side of the boundary has the same value as the boundary element itself. Another choice is a 'zero-velocity' approach, where velocities in the virtual elements are set to 0.

    Example

    HYDRAULICS
{
   TURBULENCE_MODEL
   {
      // for a constant eddy viscosity
      type = algebraic
      kinematic_viscosity = 0.000001307    	// m2/s
      eddy_viscosity_type = constant
      eddy_viscosity = 0.1			// m2/s
   }
   [...]
}

HYDRAULICS
{
   TURBULENCE_MODEL
   {
      // for a dynamic eddy viscosity
      type = algebraic
      kinematic_viscosity = 0.000001307    	// m2/s
      turbulence_factor = 5.0
   }
   [...]
}
    INITIAL
    INITIAL compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > HYDRAULICS
    Description: Defines initial conditions for hydraulics in 2D. If no initial condition is specified for parts or the whole domain, the initial conditions is set to dry.

    Variable type comp. condition units default values
    type string yes - - - {dry, continue, index_table}
    file string yes required if 'type' = 'continue' - - -
    restart_solution_time real no used if 'type' = 'continue' [s] -1.0 x >= -1
    index whitespace separated list of integers yes required if 'type' = 'index_table' [-] - -
    u whitespace separated list of reals yes required if 'type' = 'index_table' [m/s] - -
    v whitespace separated list of reals yes required if 'type' = 'index_table' [m/s] - -
    wse whitespace separated list of reals yes required if 'type' = 'index_table' [m] - -
    h whitespace separated list of reals yes required if 'type' = 'index_table' [m] - -
    saturations_lower_upper whitespace separated list of reals no - - - -
    saturations_z_lower_upper whitespace separated list of reals no - - - -

    Block Usage

    There are different possibilities to define the initial condition:
    a) dry bed
    b) initial values for depth or water surface elevation and velocity based on the material index of the mesh file
    c) continuing from an old simulation The keywords dry, index_table and continue indicate which type of initial condition is defined.
    For a dry bed, nothing else has to be specified.
    User defined initial values, the material index technique is used to assign the major variables depth/wse and velocities.
    Continue from an old simulation needs the continue-file from this old simulation.

    Description of Variables

    type -
    file - This is the filename of a continue-file. This file must be given in the binary CGNS format. (To view or edit the CGNS file there exist special programs in the web (ADFVIEWER))
    restart_solution_time - This time specifies the time at which the solution is read from the restart file. This parameter is needed because the restart file can contain different solutions at different times. If a negative time is given, than the last available solution is chosen from the restart file. For the given time a solution must exists in the restart file. If this is not the case, than all available times will be listed for the user to choose from. Pleas note: If you don't have a clue which time to enter, than just enter any time. The program will then show an parser error and list all available times from which you can choose.
    index - This is a list of integers representing the material indices defined in the computational mesh (.2dm file).
    u - This is a list of values for the velocity in x-direction (u) corresponding to the list of material indices.
    v - This is a list of values for the velocity in y-direction (v) corresponding to the list of material indices.
    wse - This is a list of values for the water surface elevation (wse) corresponding to the list of material indices.
    h - This is a list of values for the water depth (h) corresponding to the list of material indices.
    saturations_lower_upper - Effective saturation values corresponding to the lower and upper z-elevations over the whole mesh.
    saturations_z_lower_upper - Lower and upper elevations for which the given effective water saturations are specified.

    Example

    HYDRAULICS
{
   [...]
   INITIAL
   {
      type = index_table
      index = (  1    2    3   4    5    )
      wse =   (  12.1 15.0 0.0 0.54 2.3  )
      u   =   (  0.0  -3.2 1.5 0.0  5.6  )
      v   =   (  0.0  0.0  2.1 3.0  0.1  )
   }
   [...]
}

HYDRAULICS
{
   [...]
   INITIAL
   {
      type = continue
      file = beispiel_old.sim
      restart_solution_time = 100234.344 // fetch the solution from this time step
   }
   [...]
}
    SOURCE
    SOURCE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > HYDRAULICS
    Description: The SOURCE block is a container for EXTERNAL_SOURCE blocks. They are used for additional sources or sinks, sometimes used instead of flux boundary conditions.
    Inner Blocks: EXTERNAL_SOURCE

    Example

    HYDRAULICS
{
   [...]
   SOURCE
   {
      EXTERNAL_SOURCE
      {
         [...]
      }
      EXTERNAL_SOURCE
      {
         [...]
      }
   }
   [...]
}
    EXTERNAL_SOURCE
    EXTERNAL_SOURCE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > HYDRAULICS > SOURCE
    Description: The external source block is used for additional sources to model inflow or outtake of water without using a boundary condition.

    Variable type comp. condition units default values
    name string no - - - Chars [a-zA-Z0-9_-] are allowed
    type string yes - - - {source_discharge, coupling_source_discharge}
    file string no - - - -
    element_ids whitespace separated list of integers no - - - -
    index whitespace separated list of integers no - - - -

    Block Usage

    The available source type 'source_discharge' acts as a sink when delivered with negative values in the file. All external sources act on one or more computational cells whose element number(s) have to be listed in an element_ids list. The specified source will then be partitioned among the corresponding cells weighted with their areas. For each different external source, a new block has to be created. The input format for the file is of file type BC: two columns with time and corresponding source discharge. To couple subdomains via discharge source, please use a coupling_discharge_source.In this case no file has to be given.

    Description of Variables

    name - The name of an external source is used when sources are coupled to each other.
    type - The usual case is a 'source_discharge'. To couple sources of different domains together, 'coupling_source_discharge' has to be used.
    file - This is the filename of a .txt-file that describes the discharge in time. first column is time in seconds, second column is the corresponding discharge. negative discharge produces an outtake of fluid.
    element_ids - This requires a list of element numbers (from the grid) for which the external source is applied.
    index - This requires a list of material index (from the grid) for which the external source is applied.

    Example

    SOURCE
{
   [...]
   EXTERNAL_SOURCE
   {
      type = source_discharge
      element_ids = (  45  ) // only one element also needs brackets
      file = discharge1_in_time.txt
   }
   EXTERNAL_SOURCE
   {
      type = source_discharge
      element_ids = (  12  14  18  )
      file = another_discharge.txt
   }
}
    MORPHOLOGY
    MORPHOLOGY compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D
    Description: Defines the morphologic specifications for a simulation with bedload and/or suspended transport.
    Inner Blocks: PARAMETER
    BEDMATERIAL
    BEDLOAD
    INITIAL
    SUSPENDED_LOAD
    GRAVITATIONAL_TRANSPORT
    SOURCE
    APPARENT_COHESION

    Block Usage

    Contrary to hydraulics, this block is not compulsory. If MORPHOLOGY is not specified, all kind of sediment transport will be inactive. To activate bedload transport, the BEDLOAD block has to be specified. To activate suspended load transport, the SUSPENDED_LOAD block has to be specified. All information about the bed soil is defined within the BEDMATERIAL block. Initial conditions for the morphology are treated in the INITIAL block Sediment in- or outtakes from the soil during the simulation are defined within the SOURCE block.The impact of gravitational forces to the topography are treated within the GRAVITATIONAL_TRANSPORT block. Various global parameters for both, bedload and suspension can be set within the PARAMETER block. If apparent cohesion effects shall be considered in the model for the bank failures and the sediment transport, than you need to set up the APPARENT_COHESION block.

    Example

    MORPHOLOGY
{
   BEDMATERIAL
   {
      [...]
   }
   INITIAL
   {
      [...]
   }
   BEDLOAD
   {
      [...]
   }
   SUSPENDED_LOAD
   {
      [...]
   }
   GRAVITATIONAL_TRANSPORT
   {
      [...]
   }
   SOURCE
   {
      [...]
   }
   PARAMETER
   {
      [...]
   }
   APPARENT_COHESION
   {
      [...]
   }
}
    PARAMETER
    PARAMETER compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY
    Description: The PARAMETER block for hydraulics is used to specify general settings dealing with sediment properties.

    Variable type comp. condition units default values
    porosity real no - [%] 37 0 <= x <= 100
    density real no - [kg/m3] 2650 x > 0
    control_volume_type string no - - constant {constant, borah, d90}
    control_volume_thickness whitespace separated list of reals no used if 'control_volume_type' = 'constant' [m] - -
    control_volume_thickness_index whitespace separated list of integers no - - - -
    control_volume_factor real no used if 'control_volume_type' = 'd90' [-] 2.0 x > 0
    control_volume_initial string no - - soildef {soildef, gessler}
    create_new_layers string no - - off {off, on}
    max_layer_thickness real no used if 'create_new_layers' = 'on' [m] 0.5 x > 0
    new_layer_factor real no used if 'create_new_layers' = 'on' [m] 0.2 0 < x <= 0.5
    min_theta_critic real no - - 0.02 -
    local_slope_angle_repose real no - [Degree] 30.0 -
    strong_coupling string no - - off {off, on}
    strong_coupling_iter integer no used if 'strong_coupling' = 'on' [-] 3 x > 0
    distortion_offset real no - [m] 0 -
    distortion_time_interval real no - [s] -1 -
    distortion_index whitespace separated list of integers no - - - -

    Block Usage

    All variables use default values if they dont get specified by the user.

    Description of Variables

    porosity - This is the general bed material porosity in percent.
    density - This is the general density of the sediment.
    control_volume_type - This tag defines how to determine the bed load control volume thickness hm, which is also called active layer or mixing layer thickness. Available types are: For more details, please refer to the reference manual.
    control_volume_thickness - This tag defines the thickness of the bed load control volume, also referred to as active layer, cooresponding to the material index defined in tag 'control_volume_thickness_index'. This tag is only needed for bed load control volume type 'constant'. Note that this is an important calibration parameter for multi-grain simulation.
    control_volume_thickness_index - This tag defines a list with material indices (integer numbers) corresponding to tag 'control_volume_thickness'. These two lists must have the same lenght. If a material index defined in the mesh is missing, constant control volume thickness is set to 3*dmax, where dmax is the maximum grain size diameter defined.
    control_volume_factor - This parameter is needed for control_volume_type 'd90'. Therefore, the bedload control volume thickness hm is determined as: hm = control_volume_factor * d90 [m]. Typically, values range between 1 and 3.
    control_volume_initial - This tag defines the initial grain size distribution (GSD) in the bed load control volume. Available types are:
    create_new_layers - If this parameter is set to 'on', new soil layers can be generated during bed aggradation. If it is set to 'off', then no soil layers are generated dynamically.
    max_layer_thickness - This is the maximum thickness of the sublayer below the control volume. When 'max_layer_thickness' is exceeded due to deposition, new soil layers are created.
    new_layer_factor - This factor is used for creating new layers. The height of the new layer is determined as: new_layer_factor * max_layer_thickness. For example, if this factor is set to 0.5, the new layer height will be half of the height of max_layer_thickness. However, if this factor is set to a small value, the new layer will start growing from this small value. Note that the control volume is always part of the uppermost layer. Therefore, in case of small new_layer_factor the control volume is small too and will increase as the layer grows.
    min_theta_critic - This is the minimally allowed critical theta (shields factor).The minimum critical shields factor is needed out of numerical reasons to prevent division by zero if a formula is used which divides by the critical shields factor, e.g. Wu or Parker transport formulas. (Critical shields factor can also get very small or even zero due to the local slope correction. Therefore a minimum allowed critical theta is needed).
    local_slope_angle_repose - This is the angle used in the horizontal local slope correction formulation for the angle of repose. It is used only if the 'local_slope_flowdirection' is used in bed- or suspended load transport simulations. The critical shear stress is either reduced or increased due to a slope in flow direction. If no bed slope is present, the critical shear stress is not modified. If the bed slope anlge approaches the 'local_slope_anlge_repose' the critical shear stress is reduced to zero.
    strong_coupling - If this parameter is set to 'on', than the hydraulics and sediment transport are calculated iteratively.The same time step is calculated repeatedly with different hydraulic values, to ensure that the changes inbed morphology are considered in the hydraulics. This procedure is time consuming, not fully mass conservative and in most cases not needed!If it is set to 'off', than a quasi-steady coupling approach is applied for hydraulic and sediment calculations. The hydraulic variables are assumed to be constant over the time step.This assumption is in most cases valid and it is strongly recommended NOT to apply strong coupling to prevent excessive computational costs!
    strong_coupling_iter - This parameter specifies the number of internal iterations if 'strong coupling' is applied. At the moment only a fixed number of iterations can be specified.
    distortion_offset - This is the offset in [m] for a random grid perturbation
    distortion_time_interval - This is the time interval in [s] for a random grid distortion with offset. A negative number as input will disable the distortion.
    distortion_index - This tag expects a list with all the material indices (integer numbers) where distortion is applied. This tag is only active if 'distortion_time_interval > 0'. If this list is emty, then no distortion is applied.

    Example

    MORPHOLOGY
{
   [...]
   PARAMETER
   {
      porosity = 37
      density = 2650
      control_volume_type = constant
      control_volume_thickness = 0.05 // [m]
      create_new_layers = off
   }
   [...]
}
    BEDMATERIAL
    BEDMATERIAL compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY
    Description: This block defines the characteristics of the bed material. It contains only inner blocks.
    Inner Blocks: GRAIN_CLASS
    MIXTURE
    SOIL_DEF
    SOIL_ASSIGNMENT
    FIXED_BED
    RETENTION_MODEL

    Block Usage

    The GRAIN_CLASS specifies the relevant diameters of the grain. The MIXTURE block allows to define different grain mixtures using the mean diameters. The SOIL_DEF block defines all soil layers of a soil. Finally, the SOIL_ASSIGNMENT block is used to assign the different soil definitions to their corresponding areas within the topography.

    Example

    MORPHOLOGY
{
   BEDMATERIAL
   {
      GRAIN_CLASS
      {
         [...]
      }
      MIXTURE
      {
         [...]
      }
      MIXTURE
      {
         [...]
      }
      SOIL_DEF
      {
         [...]
      }
      SOIL_DEF
      {
         [...]
      }
      SOIL_ASSIGNMENT
      {
         [...]
      }
      RETENTION_MODEL
      {
         [...]
      }
   }
}
    GRAIN_CLASS
    GRAIN_CLASS compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > BEDMATERIAL
    Description: This block defines the mean diameters of ALL possibly occurring grains of the bed material in millimetres.

    Variable type comp. condition units default values
    diameters whitespace separated list of reals yes - [mm] - -

    Block Usage

    For the description of the sediments, a certain number of grain classes, characterized by their mean grain diameter, have to be defined. In a second step, a certain number of 'grain mixtures' must be defined, which contain some of the existing grain classes in different proportions. If the test samples are available in the shape of a grading curve, the mean value of two given grain diameters can be taken as mean grain diameter of the grain class, and the fraction of the material between the two diameters as fraction of the grain class in the mixture.

    Description of Variables

    diameters - The number of diameters in the list automatically sets the number of grains. For single grain simulations, only one diameter must be defined. The grain sizes must be entered in ascending order from the smallest grain to the largest grain.

    Example

    BEDMATERIAL
{
   GRAIN_CLASS
   {
   // simulation with 5 grain sizes
   diameters = ( 5 21 46 70 150 )
   }
   [...]
}

BEDMATERIAL
{
   GRAIN_CLASS
   {
   // simulation with 1 grain size
   diameters = ( 46 )
   }
   [...]
}
    MIXTURE
    MIXTURE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > BEDMATERIAL
    Description: This block allows the definition of a grain mixture.

    Variable type comp. condition units default values
    name string yes - - - Chars [a-zA-Z0-9_-] are allowed
    volume_fraction whitespace separated list of reals yes - [%] - [0-100]

    Block Usage

    The fractions of each grain class are filled in a list, in the same order in which they appear in grain class list. Grain classes which do not appear in this mixture have fraction value 0, and cannot be omitted. The sum of the fractions has to be 100. As the MIXTURE block is repeatable, several mixtures can be defined. However, this makes only sense for multi grain size simulations. In case of a single grain simulation (only one mean diameter in GRAIN_CLASS), there will be only one MIXTURE block. A single grain mixture has the volume_fraction = ( 100 ).

    Description of Variables

    name - The name of this mixture is used elsewhere for easy-to-use assignments.
    volume_fraction - According to the number of grain diameters from the GRAIN_CLASS, for each class, the percental fraction of volume has to be specified using a value between 0 and 100 %. The fractions must be written in the order corresponding to the grain class list. If a grain class is not present in a mixture, its fraction value has to be set to 0. All percentual fractions together must sum up to 100.

    Example

    BEDMATERIAL
{
   GRAIN_CLASS
   {
      // simulation with 3 grain sizes
      diameters = (  5  21  46  )
   }
   MIXTURE
   {
      name = mixture1
      volume_fraction = (  30  50  20  )
   }
   MIXTURE
   {
      name = mixture2
      volume_fraction = (  30  40  30  )
   }
   [...]
}
    SOIL_DEF
    SOIL_DEF compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > BEDMATERIAL
    Description: This block defines the structure of the soil. Every soil layer is defined within a LAYER block. Every layer has an own mixture assigned.
    Inner Blocks: LAYER

    Variable type comp. condition units default values
    name string yes - - - Chars [a-zA-Z0-9_-] are allowed
    d90_armored_layer real no - [mm] - x > 0
    tau_erosion_start real no - [N/m2] -1.0 -

    Block Usage

    A soil consists of one or several layers. Typically, every layer has its own mixture assigned. The LAYER blocks have to be defined within the SOILDEF block ordered by their relative distance to the surface!
    For single grain size simulations, one LAYER block is needed (usually with the only mixture assigned to it) to define the fixed bed by its bottom elevation. If no LAYER block is defined within a SOIL_DEF, a fixed bed without layer on top is assumed at this place.
    Additional, an armoured bed can be defined for a soil optionally. Therefore the d90 of the armoured layer in [mm] (d90_armored_layer) for single grain size simulations or a critical bottom shear stress in [N/m2] (tau_erosion_start) for both, single and multi grain size simulations can be defined. The corresponding critical shear stresses must be exceeded at least once to erode the armoured bed. The definition of a critical shear stress can be useful, for example in the presence of protecting vegetation.

    Description of Variables

    name - This is the name of the soil which can be used elsewhere e.g. for the soil assignment.
    d90_armored_layer - This tag defines a characteristic grain size 'd90' assuming an armoured layer. This grain size is used for the calculation of the dimensionless critical shear stress 'θ critic', which has to be exceeded before erosion is possible. After this threshold value is exceeded once it is not considered any more for the rest of the simulation. The definition of a tag 'd90_armored_layer' is only valid for single grain size simulations with a diameter d. The dimensionless critical shear stress is calculated as: θ critic_armour = θ critic*(d90/d)^(2/3). If d90_armored_layer is set to 0 or undefined, no armoured layer is being used.
    tau_erosion_start - This is a possibility to define a bottom shear stress which has to be exceeded before erosion becomes possible. After that the threshold value is not considered any more for the rest of the simulation. This tag can be used for single grain and multi grain size simulations.

    Example

    BEDMATERIAL
{
   GRAIN_CLASS
   {
      [...]
   }
   MIXTURE
   {
      [...]
   }
   MIXTURE
   {
      [...]
   }
   SOIL_DEF
   {
      name = soil1
      tau_erosion_start = 50.0   // [N/m2]
      LAYER
      {
         [...]
      }
      LAYER
      {
         [...]
      }
   }
   SOIL_DEF
   {
      name = soil2
      d90_armored_layer = 6.8    // [mm]
      LAYER
      {
         [...]
      }
      LAYER
      {
         [...]
      }
   }
   [...]
}
    LAYER
    LAYER compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > BEDMATERIAL > SOIL_DEF
    Description: This block defines a soil layer. For every soil layer, a new block has to be used. The bottom elevation is relative to the surface topography defined in the geometry file. Therefore, a minus-sign has to be used.

    Variable type comp. condition units default values
    mixture string yes - - - Chars [a-zA-Z0-9_-] are allowed
    bottom_elevation real yes - [m] - x <= 0

    Block Usage

    A layer consists of a mixture and its bottom elevation. The bottom elevation is relative to the surface topography defined in the geometry file. Therefore, a minus-sign has to be used. The LAYER blocks have to be defined ordered by their relative height to the surface, from the uppermost layer to the lowest layer.
    The bottom of the lowest soil layer automatically defines the fixed bed.
    In case of a single grain simulation (only one mean diameter in GRAIN_CLASS), only one LAYER block is needed, which defines the fixed bed. If no LAYER block is defined within a SOIL_DEF block, a fixed bed without a soil layer on top is assumed at this place.

    Description of Variables

    mixture - This is the name of the soil mixture as it is defined in the MIXTURE block.
    bottom_elevation - The bottom elevation is expected to be relative to surface. Therefore, it is always a negative number.

    Example

    SOIL_DEF
{
   name = soil1
   tau_erosion_start = 0.89
   LAYER
   {
      mixture = mixture1       // first soil layer
      bottom_elevation = -0.5  // [m]
   }
   LAYER
   {
      mixture = mixture2       // second soil layer
      bottom_elevation = -1.3  // [m]
   }
   LAYER
   {
      [...]
   }
}
    SOIL_ASSIGNMENT
    SOIL_ASSIGNMENT compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > BEDMATERIAL
    Description: This block is used to assign the soil definitions to their corresponding areas in the topography.

    Variable type comp. condition units default values
    index whitespace separated list of integers yes - - - -
    soil whitespace separated list of strings yes - - - -
    type string no - - index_table {index_table}

    Block Usage

    To assign the soil definitions the index-technique is used. Every soil is assigned to an index. Note that each material index defined in the mesh must be used.

    Description of Variables

    index - This is a list of integers corresponding to the material indices in the computational mesh. Note that all indices defined in the mesh must be used here.
    soil - This is a list of the SOIL names in the same order as defined in the 'index' tag.
    type - This is the type used for the soil assignment. Currently, only 'index_table' is available.

    Example

    BEDMATERIAL
{
   [...]
   SOIL_DEF
   {
      name = soil_coarse
      [...]
   }
   SOIL_DEF
   {
      name = soil_fine
      [...]
   }
   SOIL_DEF
   {
      name = fixbed
   }
   SOIL_ASSIGNMENT
   {
      type = index_table
      index = ( 1  2  3 )
      soil = ( soil_coarse  soil_fine  fixbed )
   }
}
    FIXED_BED
    FIXED_BED compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > BEDMATERIAL
    Description: The fixed bed level is the elevation where no more erosion is possible (unerodable rock). Usually, the fixed bed level is determined automatically as the lowest elevation of all soil layers. In most cases, therefore no FIXED_BED block is needed at all.

    Variable type comp. condition units default values
    type string yes - - - {meshfile, nodes}
    file string yes required if 'type' = 'meshfile' - - -
    node_ids whitespace separated list of integers yes required if 'type' = 'nodes' - - -
    zb_fix whitespace separated list of reals yes required if 'type' = 'nodes' - - -

    Block Usage

    The FIXED_BED block is not mandatory, because the bottom of the lowest layer in the soil definition automatically defines the rock elevation.
    However, a FIXED_BED block may be inserted optionally to define the rock level independently from the soil layers and in more detail, separately for each node. There are two ways onhow to define fixed bed elevations here.
    It can be set in the form of an additional mesh file in .2dm format in which the nodal elevations are the fixed rock elevations. The mesh file must have the same structure as the simulation meshfile.
    Another possibility is to define the fixed bed elevations specifically for nodes using a node list. The fixed bed elevations must be given in absolute values. If a given value is below or equal to -100.0 than the surface bed elevation is used as fixed bed.

    Description of Variables

    type - This is the type of Input for the fixed bed elevation. The two possibilities are input from file ('meshfile') or by a list of nodes ('nodes').
    file - This is the name of a grid file containing the fixed bed levels as topography.
    node_ids - This is a list of nodes which are not adjacent.
    zb_fix - This is a list of fixed bed values in [m] above sea level. If a fixed bed value is ≤ -100, then the surface bed elevation is used.

    Example

    BEDMATERIAL
{
   [...]
   FIXED_BED
   {
      type = meshfile
      file = fixed_bed_mesh.2dm
   }
   [...]
}
BEDMATERIAL
{
   [...]
   FIXED_BED
   {
      type = nodes
      node_ids = ( 12 22 25 72 92 )
      zb_fix = ( 312.2 313 313.56 -100 -100 )
      // the "-100" values set the fixed bed elevation
      // to the surface elevation
   }
}
    RETENTION_MODEL
    RETENTION_MODEL compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > BEDMATERIAL
    Description: This block defines soil retention model and its parameters needed to asses the apparent cohesion effects of the soil.

    Variable type comp. condition units default values
    type string yes - - - {van_genuchten, brooks_corey}
    lambda real yes required if 'type' = 'brooks_corey' [-] - x > 0
    l real yes required if 'type' = 'brooks_corey' [-] - x > 0
    n real yes required if 'type' = 'van_genuchten' [-] - x > 0
    alpha real yes required if 'type' = 'van_genuchten' [1/m] - x > 0
    hs real no - [m] -0.001 x <= 0

    Block Usage

    For the description of the soil properties and pore-distributions one can define empirical relationships. These empirical formulas are needed to describe the relationship between the water saturation and the capillary pressure. This relationship is needed to assess effects of apparent cohesion in the numerical model.

    Description of Variables

    type - Two different analytical models to describe the retention curve can be specified. These are a modified version of the 'van Genuchten' model and the 'Brooks-Corey' model. At the moment the use of the van Genuchten model is recommended.
    lambda - Dimensionless soil parameter used for the Brooks-Corey model.
    l - Dimensionless soil parameter used for the Brooks-Corey model.
    n - Dimensionless soil parameter for the van Genuchten model.
    alpha - Dimensionless soil parameter for the van Genuchten model.
    hs - This parameter specifies the air-entry pressure head of the soil. It characterizes the negative pressure which is needed to drain the largest pores of the soil. It therefore can be seen as description of the largest pores of the soil and as the threshold describing the transition from the saturated zone to the unsaturated zone.

    Example

    BEDMATERIAL
{
   RETENTION_MODEL
   {
   type = van_genuchten
   hs = 0.001
   alpha = 6
   n = 2.1
   }
   [...]
}

BEDMATERIAL
{
   RETENTION_MODEL
   {
   type = brooks_corey
   lambda = 2
   }
   [...]
}
    BEDLOAD
    BEDLOAD compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY
    Description: Defines all needed data for bed load transport. If this block does not exist, no bed load transport will be simulated.
    Inner Blocks: FORMULA
    PARAMETER
    BOUNDARY
    DIRECTION
    INNER_BOUNDARY

    Block Usage

    The bedload block contains only inner blocks. No variables have to be set.

    Example

    MORPHOLOGY
{
   BEDMATERIAL
   {
      [...]
   }
   BEDLOAD
   {
      PARAMETER
      {
         [...]
      }
      FORMULA
      {
         [...]
      }
      DIRECTION
      {
         [...]
      }
      BOUNDARY
      {
         [...]
      }
   }
}
    FORMULA
    FORMULA compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > BEDLOAD
    Description: The FORMULA block for morphology in 2D defines general settings related to the bedload transport formula.

    Variable type comp. condition units default values
    bedload_formula string yes - - - {mpm, engelundhansen, mpmh, mpm_multi, ashidamichiue, parker, wilcockcrowe, rickenmann, smartjaeggi, smartjaeggi_multi, wu, power_law, vanrijn}
    bedload_factor real no - - 1.0 -
    bedload_exponent real no used if 'bedload_formula' = 'mpm' or 'mpm_multi' - 1.5 1 <= x <= 2
    theta_critical_index whitespace separated list of integers no used if 'bedload_formula' = 'mpm' or 'mpmh' or 'mpm_multi' or 'ashidamichiue' or 'rickenmann' or 'smartjaeggi' or 'smartjaeggi_multi' or 'parker' or 'wu' or 'vanrijn' - - -
    theta_critical whitespace separated list of reals no used if 'bedload_formula' = 'mpm' or 'mpmh' or 'mpm_multi' or 'ashidamichiue' or 'rickenmann' or 'smartjaeggi' or 'smartjaeggi_multi' or 'vanrijn' or 'parker' or 'wu' - - -
    theta_critical_approach string no used if 'bedload_formula' = 'mpm' or 'mpmh' or 'mpm_multi' or 'ashidamichiue' or 'rickenmann' or 'smartjaeggi' or 'smartjaeggi_multi' or 'vanrijn' - theta_critical_vanrijn {theta_critical_vanrijn, theta_critical_yalin}
    theta_critical_hiding string no used if 'bedload_formula' = 'mpm_multi' or 'ashidamichiue' or 'smartjaeggi_multi' - mean {mean, median, geometric, fraction}
    local_slope_correction string no - - local_slope_vanrijn {local_slope_vanrijn, local_slope_chen, no_local_slope}
    critical_shear_stress_calibration real no used if 'bedload_formula' = 'mpm' or 'mpm_multi' or 'ashidamichiue' or 'mpmh' or 'rickenmann' or 'smartjaeggi' or 'vanrijn' - 1.0 0 <= x <= 100
    hiding_exponent real no used if 'bedload_formula' = 'mpmh' or 'wu' or 'parker' - - -
    power_law_a real no used if 'bedload_formula' = 'power_law' - 1.0 -
    power_law_b real no used if 'bedload_formula' = 'power_law' - 1.0 -
    alpha real no used if 'bedload_formula' = 'smartjaeggi_multi' - 1.05 x >= 1
    d90 real yes required if 'bedload_formula' = 'rickenmann' or 'smartjaeggi' or 'vanrijn' [mm] - x > 0
    d30 real yes required if 'bedload_formula' = 'rickenmann' or 'smartjaeggi' [mm] - x > 0
    bedforms_type string no - - no_bedforms {no_bedforms, user_defined_bedforms, mpm_bedforms, slope_dependent_bedforms}
    bedforms_index whitespace separated list of integers yes required if 'bedforms_type' = 'user_defined_bedforms' - - -
    bedforms_factor whitespace separated list of reals yes required if 'bedforms_type' = 'user_defined_bedforms' - - -
    slope_dependent_bedforms_factor real yes required if 'bedforms_type' = 'slope_dependent_bedforms' [-] - 0 < x <= 1
    slope_limit_bedforms real yes required if 'bedforms_type' = 'slope_dependent_bedforms' [-] - 0 < x <= 1

    Block Usage

    This block defines the settings related to the bedload transport formula. Most of them use a default value, therefore it is not neccessary to set them all in the beginning. The only variable that must be set is the bedload formula which shall be used. Check the info botton for detailed information on the tags.

    Description of Variables

    bedload_formula - The following bedload transport formulas can be selected (see Reference Manual RI):
    The choice of the transport formula depends on different factors (i.e. slope, morphology, validity of formula, personal preferences etc.). For single grain simulations 'mpm', 'engelundhansen', 'rickenmann', 'smartjaeggi', 'vanrijn', and 'power_law' can be used, for multi-grain simulations 'mpmh', 'mpm_multi', 'ashidamichiue', 'parker', 'wilcockcrowe', 'smartjaeggi_multi', and 'wu' can be used.
    bedload_factor - This is an important calibration factor for bedload transport.
    It is multiplied linearly with the calculated transport capacity of the empirical bedload formula. By default, it is set to 1.0.
    bedload_exponent - The bedload exponent is used for mpm and mpm_multi bedload transport formula. The original value is 1.5. The corrected version of Wong and Parker (2006) applies bedload_exponent = 1.6. Values other than that are not recommended!
    theta_critical_index - This tag expects a list with material indices (integer numbers). To each listed material index a user defined theta critical can be assigned in the tag 'theta_critical'.If certain indices defined in the mesh are not used the critical Shields parameter is determined from transformed Shields diagramm defined in 'theta_critical_approach'.
    theta_critical - The critical Shields parameter (dimensionless critical shear stress) is an important calibration factor.
    If theta_critical is specified by the user, this value is constant over the whole simulation. If this parameter is not specified explicitely or for missing material indices, critical Shields parameter is determined according to the transformed Shields diagramm defined in 'theta_critical_approach'. Critical Shields parameter is determined from the tranformed Shields diagram for 'mpm', 'mpm_multi', 'ashidamichiue', 'mpmh', 'rickenmann', 'smartjaeggi', 'smartjaeggi_multi', and 'vanrijn'. Constant default value are used for 'wu = 0.03', and 'parker = 0.0386'.
    theta_critical_approach - This tag is used if no tag 'theta_critical' is defined or if certain material indices are missing.The following approaches to determine critical Shields paramter (transformed Shields diagram based on dimensionless grain diameter D*) can be selected:
    theta_critical_hiding - This tag is used if no tag 'theta_critical' is defined or if certain material indices are missing. This tag defines which characteristic grain size diameter is used to determine the critical Shields parameter used for the approach defined in 'theta_critical_approach'. The resulting critical Shields parameter theta_c is applied on the hiding function F of Ashida and Michiue, such that the critical Shields parameter of grain class i is calculated as: theta_ci = F*theta_critical. The reference critical Shields parameter can be determined based on: The default is set to 'mean' as proposed by Egiazaroff (1965). However, Ashida and Michiue (1972) proposed a fix value of 0.05. To use a fix value, define critical Shields parameter using the tag 'theta_critical', where for each material index a critical Shields parameter can be defined. Note: This tag is only used for bed load formula 'mpm_multi', 'ashidamichiue', and 'smartjaeggi_multi' using the hiding function according to Ashida and Michiue.
    local_slope_correction - The following corrections for the critical Shields paramter due to local bed slope can be selected:
    critical_shear_stress_calibration - Factor used to modify the critical shear stress returned by the Shields diagram. It can only be used for transport formulas which determine the critical shear stress from the Shields-diagram.
    hiding_exponent - This is the exponent of the hiding-exposure function in Hunziker's, Wu's, or Parker's non-uniform bed load formula. This factor is generally set to a negative number. Default values are -0.6 for Wu's formula,and -0.0951 in Parker's formula. NB for Hunziker formulation: leave the default value (unset value)for the original formulation from the Authors (Eq. 11 in Hunziker and Jaeggi 2002),or set a custom hiding exponent factor (negative value).Changing this exponent primarily influences the grain sorting process. Major change of this value will probably result in instabilities.
    power_law_a - This is the linear factor 'a' for the power law transport formula (a*u^b). By default, it is set to 1.0.
    power_law_b - This is the exponent b for the power law transport formula (a*u^b). By default, it is set to 1.0.
    alpha - The alpha factor is used for the extention of the original Smart & Jaeggi (single grain) transport formula to a multi grain approach. Alpha replaces the term (d90/d30)^(0.2) in the original Smart & Jaeggi formula and has a default value of 1.05.
    d90 - This is the characteristic diameter d90 of the bed material. This parameter is mandatory for the 'rickenmann', 'smartjaeggi' and 'vanrijn' bed load transport formula.
    d30 - This is the characteristic diameter d30 of the bed material. This parameter is mandatory for the 'rickenmann' and 'smartjaeggi' bed load transport formula.
    bedforms_type - Here the user defines weather or how to take bedforms into account. Bedforms reduce the effective bottom shear stress, which is used for sediment transport. Bedforms (e.g. riffles, dunes) induce form friction losses and therefore only a fraction of the bed shear stress is available for bed load transport. The reduction factor for the effective bottom shear stress can be considered with:
  • a slope dependent bedforms approach, where a reduction factor of the shear stress is applied only See chapter RI-2.1.2 for more information. For single grain simulations the Meyer-Peter Mueller approach (mpm_bedforms) is using d90 = 3*dm for the estimation of the bed roughness.
    • bedforms_index - This tag is used for user defined bedforms and expects a list with all required material indices (integer numbers). A reduction factor for the bottom shear stress can then be assigned to each material index in 'bedforms_factor'.
    bedforms_factor - This tag expects a list with bedform reduction coefficients corresponding to the material indices. The order of the list must correspond to the order in the list 'bedforms_index'. The value of the 'bedforms_factor' is the reduction factor of the calculated bottom shear stress, which is used for transport calculations.
    slope_dependent_bedforms_factor - This tag expects a reduction factor, which is applied only for slopes below a certain bed slope, whichis defined in the tag 'slope_limit_bedforms'. This can be useful for morphological modelling with bank erosion, where bedforms should be considered only on the river bed and not on the river banks.
    slope_limit_bedforms - This tag expects the slope below which the reduction factor 'slope_dependent_bedforms_factor' is valid. This can be useful for morphological modelling with bank erosion, where bedforms should be considered only on the river bed and not on the river banks.

    Example

    BEDLOAD
{
		[...]
		FORMULA
		{
			bedload_formula = mpm // Meyer-Peter and Mueller formula 
			bedload_factor = 0.5 // reduces the bedload transport rate
			bedforms_type = mpm_bedforms
   }
}
    PARAMETER
    PARAMETER compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > BEDLOAD
    Description: The PARAMETER block for morphology in 2D contains general settings dealing with bedload transport.

    Variable type comp. condition units default values
    upwind_index whitespace separated list of integers no - - - -
    upwind whitespace separated list of reals no - - - -
    bedload_routing_start real no - [s] 0.0 -
    limit_bedload_wetted string no - - on {off, on}
    use_real_edge_lengths string no - - off {off, on}
    use_cell_averaged_bedload_flux string no - - off {off, on}

    Block Usage

    This block defines general parameters related to bedload simulation. If nothing is defined, all tags use default values. Therefore, it is not neccessary to set them all in the beginning. See the explanations for the parameters for further information.

    Description of Variables

    upwind_index - This tag expects a list with all material indices (integer numbers). Therefore, for each material index an upwind factor can be assigned used for the sediment flux calculation.
    upwind - This tag expects a list with upwind factors corresponding to the material indices. Therefore, the ordering should corresponds to the indices within 'upwind_index'. If this tag is not defined or an index is left out, the upwind factor is set by default to 0.8. Note that in case of use_cell_averaged_bedload_flux = off, this tag is only relevant for non-uniform (multigrain) bed load transport.
    bedload_routing_start - This indicates, at what time sediment transport is started during a simulation. A value of 0.0 means bed load transport from the beginning.
    limit_bedload_wetted - This option limits the bed load transport to sediment-elements which are surrounded completely by fully wetted elements. This behaviour is active by default. Setting it to 'off' may lead to aggradation near partially wetted elements.
    use_real_edge_lengths - This flag determines whether the bedload is calculated over the real edge lengths (3d) instead of over the plane projections (default). Activating this feature may give better results in strongly irregular tropographies. But at the moment is NOT recommended to activate this paramter.
    use_cell_averaged_bedload_flux - This flag determines the approach for bedload flux computation on the edge of the sediment cell (edgeV). Per default ('off'), the bedload flux is directly projected from the hydraulic cell on edgeV. If set to 'on', an averaged bedload flux for the sediment cell is computed. This has the advantage, that upwinding is possible. The default method is computational less expensive. However, no upwinding is possible. Both methods show similar diffusivity.

    Example

    BEDLOAD
{
   [...]
   PARAMETER
   {
      bedload_routing_start = 0.0 
      upwind = ( 1.0 0.6 0.6 ) 
		 upwind_index = ( 1 2 3 ) 
   }
}
    BOUNDARY
    BOUNDARY compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > BEDLOAD
    Description: Defines boundary conditions for the bed load transport.

    Variable type comp. condition units default values
    name string no - - - Chars [a-zA-Z0-9_-] are allowed
    type string yes - - - {sediment_discharge, coupling_sediment_discharge, transport_capacity, IOUp, IODown, coupling_IODown}
    string_name string yes - - - Chars [a-zA-Z0-9_-] are allowed
    file string yes required if 'type' = 'sediment_discharge' - - -
    mixture string yes required if 'type' = 'sediment_discharge' or 'transport_capacity' or 'IOUp' - - -
    factor real no used if 'type' = 'transport_capacity' - 1.0 -
    fraction_boundary real no used if 'type' = 'IOUp' or 'IODown' - 1.0 x <= 1

    Block Usage

    For every boundary condition, a new block BOUNDARY has to be defined. At the upstream boundaries a sediment inflow can be specified. This type of boundary needs a mixture assigned, in any case, even if single grain computations are performed. IOUp and IODown are special boundaries designed to facilitate the determination of the equilibrium bed load transport. (In case of coupling no file and no mixture must be defined).
    Please note: Instead of using an inflow boundary, alternatively also an EXTERNAL_SOURCE can be used to specify an inflow of sediment material in the simulation domain. This is sometimes helpful when the hydraulics near the boundary does not reach a critical velocity to activate bedload transport. The sediment is then inserted into the grid a little bit more downstream where the flow is fully developed.

    Description of Variables

    name - Unique identifier which is used for the coupling of domains.
    type - This is the type of the boundary condition. If one does not specify any boundary condition, no transport over the boundary will occur and a wall is assumed.

    Upstream bedload boundary conditions

    Downstream
    string_name - This is the name of a cross string defined in the STRINGDEF block. It defines where the boundary conditions acts.
    file - This is the file name containing the sediment inflow in [m3/s]. The file needs 2 columns, time and inflow.
    mixture - This is the name of the desired mixture for the sediment inflow.
    factor - Factor to calibrate the 'transport_capacity' boundary.The inflowing equilibrium sediment is multiplied with this factor.
    fraction_boundary - This factor can be used for 'IOUp' and 'IODown' boundary conditions. The calculated in/outflow is multiplied by this value. For an outflow boundary, this leads to a small aggradation at the outflow bound which leads sometimes to a more stable behaviour in some cases. By default, the factor is set to 1.0 for 'IOUp' and 0.9 for 'IODown'.

    Example

    BEDLOAD
{
   [...]
   BOUNDARY
   {
      type = sediment_discharge
      string_name = inflow_cross_section
      file = discharge.txt
      mixture = mixture2
   }
 or
   BOUNDARY
   {
      type = transport_capacity
      string_name = inflow_cross_section
      mixture = mixture2
      factor = 0.9
   }
 or
   BOUNDARY
   {
      type = IODown
      string_name = outflow_cross_section
   }
   [...]
}
    DIRECTION
    DIRECTION compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > BEDLOAD
    Description: The DIRECTION block for bedload in 2D contains general settings dealing with the adaptation of the bedload transport direction.

    Variable type comp. condition units default values
    lateral_transport_type string yes - - - {lateral_bed_slope, curvature_effect_static, curvature_effect_dynamic}
    lateral_index whitespace separated list of integers yes - - - -
    radius_calculation_type string yes required if 'lateral_transport_type' = 'curvature_effect_dynamic' - - {water_surface_elevation, velocity_vectors}
    radius_static whitespace separated list of reals yes required if 'lateral_transport_type' = 'curvature_effect_static' [m] - -
    lateral_transport_factor real no used if 'lateral_transport_type' = 'lateral_bed_slope' [-] 1.5 0 < x <= 4
    curvature_transport_factor_type string no used if 'lateral_transport_type' = 'curvature_effect_static' or 'curvature_effect_dynamic' - fix {fix, dynamic}
    curvature_transport_factor real no used if 'curvature_transport_factor_type' = 'fix' [-] 7.0 0 < x <= 20
    dynamic_prefactor real no used if 'curvature_transport_factor_type' = 'dynamic' [-] 1.0 0 < x <= 2
    initial_radius real no used if 'lateral_transport_type' = 'curvature_effect_dynamic' [m] 10000.0 -100000 <= x <= 100000
    min_abs_radius real no used if 'lateral_transport_type' = 'curvature_effect_dynamic' [m] 100.0 0 < x <= 100000
    min_abs_radius_use string no used if 'lateral_transport_type' = 'curvature_effect_dynamic' - significance_value {significance_value, min_value}
    update_timestep_radius real no used if 'lateral_transport_type' = 'curvature_effect_dynamic' [s] 60.0 x > 1
    lateral_transport_exponent real no used if 'lateral_transport_type' = 'lateral_bed_slope' [-] 0.5 0 <= x <= 2
    scale_lateral_transport string no used if 'lateral_transport_type' = 'lateral_bed_slope' - yes {yes, no}

    Block Usage

    This block defines the use of lateral bed load. There are basically two types of lateral bedload transport: (i) Lateral bedlaod transport due to lateral bed slope with respect to flow direction and (ii) Latearal bedload transport due to curvature effect.See the explanations for the parameters for further information.

    Description of Variables

    lateral_transport_type - The following lateral bedload transport types can be selected (References are given in the Reference Manual RI):
    lateral_index - This tag provides a list containing material indices, where the relevant lateral transport type is applied. If an existing material index is not in this list, then no lateral transport of this type is considered.
    radius_calculation_type - This tag defines the caluculation type for the radius of the river bend/curvature. This tag has only an effect if 'curvature_effect_dynamic' is selected.
    radius_static - This tag provides a list with the corresponding values of the radius of the river bend/curvature matching with material indices defined in the tag 'lateral_index'. The radius is defined positive in counter-clockwise direction of the curvature and negative in clockwise direction of the curvature. This values are used for static calculation of the river bend/curvature effect on bedload transport direction.
    lateral_transport_factor - This factor is used to determine the intensity of the lateral bed slope effect (Ikeda). Typically, values range between 1.2 and 2.4. Note that this factor has only an effect if tag 'lateral_bed_slope' is activated.
    curvature_transport_factor_type - This tag defines weather the curvature transport factor is assumed to be a fix value or determined dynamically based on local roughness. This tag is only used for 'curvature_effect_static' or 'curvature_effect_dynamic'.
    curvature_transport_factor - This tag defines an empirical factor used for calculation of curvature effect with fix prefactor. Engelund (1974) proposed a value of 7.0 for rivers, Rozovskii (1961) proposed a value of 11.0 for laboratory channels. This tag is only applied if tag 'curvature_transport_factor_type' = fix.
    dynamic_prefactor - This tag defines a calibration factor used for calculation of dynamic curvature transport factor based on local roughness. For natural channels 'dynamic_prefactor' = 1.0. However, for laboratory channels 'dynamic_prefactor' is more around 0.5 (stronger curvature effect). Note, that this tag applies only if tag 'curvature_transport_factor_type' = dynamic.
    initial_radius - This tag defines an initial radius to start the simulation. Usually for the first time step a large value is applied (no river bend/curvature effect). This tag is only used for dynamic calculations of the radius.
    min_abs_radius - This tag defines the minimal absolute radius that can occur or can be expected during simulation. Therefore, unrealistic small (positive or negative) values for the radius are prevented. This tag is only used for dynamic calculations of the radius.
    min_abs_radius_use - This tag defines how the tag 'min_abs_radius' is used:
    update_timestep_radius - This tag defines the update time intervall for dynamic radius calculation during simulation. Be aware that too small values can slow down the simulation. This tag has only an effect for dynamic calculation of the curvature radius.
    lateral_transport_exponent - This tag defines an empirical exponent used for calculation of lateral transport due to lateral bed slope. Typically, values range between 0.0 and 1.0. This tag has only an effect if tag 'lateral_bed_slope' is activated.
    scale_lateral_transport - Setting this tag to 'no' means that bed load transport on laterally inclined bed slope not only changes transport direction, but also increases in magnitude (not recommended). However, default behaviour is to change only bed load transport direction. This tag is only used if tag 'lateral_bed_slope' is activated.

    Example

    BEDLOAD
{
   [...]
   DIRECTION
   {
      type = lateral_bed_slope 
      lateral_index = ( 1 2 3 4) 
      lateral_transport_factor = 1.5 
      lateral_transport_exponent = 0.5 
   }
   DIRECTION
   {
      type = curvature_effect_static 
      lateral_index = ( 1 3 ) 
      radius_static = ( -100 150 ) 
		 curvature_transport_factor = 7.0 
   }
   DIRECTION
   {
      type = curvature_effect_dynamic 
		 radius_calculation_type = velocity_vectors 
      lateral_index = ( 2 ) 
		 curvature_transport_factor_type = dynamic 
		 initial_radius = 10000.0 
   }
   DIRECTION
   {
      type = curvature_effect_dynamic 
		 radius_calculation_type = water_surface_elevation 
      lateral_index = ( 4 ) 
		 curvature_transport_factor_type = fix 
		 curvature_transport_factor = 11.0 
		 initial_radius = 10000.0 
   }
}
    INNER_BOUNDARY
    INNER_BOUNDARY compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > BEDLOAD
    Description: This block is used to define bedload inner boundaries within a 2D grid.

    Variable type comp. condition units default values
    type string yes - - - {open, weir}
    string_name1 string yes - - - Chars [a-zA-Z0-9_-] are allowed
    string_name2 string yes - - - Chars [a-zA-Z0-9_-] are allowed
    file string no - - - -

    Block Usage

    Additionally to the normal boundary conditions, there may be need of hydraulic structures like a weir where also bedload transport can take place. These conditions compute the bedload flux over an edge under different conditions. Technically, this produces at the same time an outflow and a corresponding inflow into the same computational grid.
    To define such an inner boundary condition, contrary to the normal boundary, two cross section strings (defined in a STRINGDEF) have to be defined. Both STRINGDEF's must contain the same number of nodes in the same order (direction)! It is recommended to declare string1 as the 'outflow string' and string2 as the 'inflow string'.

    Description of Variables

    type -
    string_name1 - This is the name of a cross section string defined in a STRINGDEF block. Usually, the first string corresponds to the expected outflow (i.e. upstream) boundary.
    string_name2 - This is the name of a cross section string defined in a STRINGDEF block. Usually, the second string corresponds to the expected inflow (i.e. downstream) boundary.
    file - This is the filename of the file that contains the weir/gate level at different moments in time. Usually, this is a .txt-file. In case of a 'hQ-relation', this file contains water depths h (first column) and discharges Q (second column)

    Example

    BEDLOAD
{
   INNER_BOUNDARY
   {
      type = weir
      string_name1 = weir_in   // as defined in STRINGDEF
      string_name2 = weir_out
      file = weirLevel.txt
   }
   INNER_BOUNDARY
   {
      type = open
      string_name1 = gate_in   // as defined in STRINGDEF
      string_name2 = gate_out
   }
   [...]
}
    INITIAL
    INITIAL compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY
    Description: This block defines the inital conditions for the morphology. The definition of this block is mandatory.

    Variable type comp. condition units default values
    type string yes - - - {initial_mesh, continue}
    file string no used if 'type' = 'continue' - - -
    restart_solution_time real no used if 'type' = 'continue' [s] -1.0 x >= -1

    Description of Variables

    type - This is the type of initial conditions for bedload transport:
    a) 'initial_mesh'. This type means that the given mesh file is used as initial condition for the bed topography.
    b) 'continue'. The simulation is restarted from a restart-file obtained by a previous run. The restart solution time must be specified. (The mesh file is loaded and the z elevationsand the actual mixtures in the elements are then updated with values of the restart file.
    file - This is the name of a sediment restart file from a previous simulation with sediment transport. This file must be given in the CGNS format.
    restart_solution_time - This time specifies the time at which the solution is read from the file. This parameter is needed because the restart file can contain different solutions at different times. If a negative time is given, than the last available solution is chosen from the restart file. For the given time a solution must exists in the restart file. If you don't have a clue what to enter, than just enter any number, than all available times will be listed for the user to choose from.

    Example

    INITIAL
{
   type = continue
   file = Rhein_sed.sim      // restart file
   restart_solution_time = 10023.345 
}
    SUSPENDED_LOAD
    SUSPENDED_LOAD compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY
    Description: Defines all needed data for suspended transport. If this block does not exist, then no suspended transport will be simulated.
    Inner Blocks: PARAMETER
    BOUNDARY
    INITIAL
    SOURCE

    Example

    SUSPENDED_LOAD
{
   [...]
   INITIAL
   {
      [...] 
   }
   BOUNDARY
   {
      [...] 
   }
   BOUNDARY
   {
      [...]
   }
   PARAMETER
   {
      [...]
   }
   SOURCE
   {
      [...]
   }
}
    PARAMETER
    PARAMETER compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > SUSPENDED_LOAD
    Description: The PARAMETER block for suspended load in 2D contains general settings dealing with suspended transport.

    Variable type comp. condition units default values
    scheme string yes - - - {mdpm, upwind}
    diffusion string yes - - - {off, constant, dynamic}
    diffusion_factor real yes required if 'diffusion' = 'constant' - - -
    diffusion_factor_dynamic real yes required if 'diffusion' = 'dynamic' - 1.0 -
    sediment_exchange string yes - - - {off, on}
    use_transport_type_factor string yes required if 'sediment_exchange' = 'on' - - {yes, no}
    transport_type_factor string yes required if 'sediment_exchange' = 'on' - vanrijn {vanrijn, bagnold}
    number_susp_fractions integer no - - 1 x >= 1
    pickup_factors whitespace separated list of reals yes required if 'sediment_exchange' = 'on' - ( 1.0 ) -
    factor_depth_reference_height real yes required if 'sediment_exchange' = 'on' - 0.1 -
    adaption_length_factor real yes required if 'sediment_exchange' = 'on' - 1.0 -
    sink_velocity_type string yes required if 'sediment_exchange' = 'on' - vanrijn {vanrijn, wuwang, zhang, user_defined_settling_velocities}
    settling_velocities whitespace separated list of reals yes required if 'sink_velocity_type' = 'user_defined_settling_velocities' [mm/s] - -
    corey_shape_factor real yes required if 'sink_velocity_type' = 'wuwang' - 0.7 -
    concentration_type string yes required if 'sediment_exchange' = 'on' - vanrijn {vanrijn, zyserman}
    limit_pickup_to_bedload string yes required if 'sediment_exchange' = 'on' - off {on, off}
    theta_critical_from_bedload string yes required if 'sediment_exchange' = 'on' - - {yes, no}
    local_slope_correction string no - - local_slope_vanrijn {local_slope_vanrijn, local_slope_chen, no_local_slope}
    exchange_type string yes required if 'sediment_exchange' = 'on' - concentrations {concentrations, shear_stresses}
    factor_m real yes required if 'exchange_type' = 'shear_stresses' - 0.00001 -
    factor_n real yes required if 'exchange_type' = 'shear_stresses' - 1.0 -
    tk real yes required if 'exchange_type' = 'shear_stresses' - 0.0018 -
    shear_stress_deposition_conc string yes required if 'exchange_type' = 'shear_stresses' - reference {reference, actual}
    ref_conc_factor real yes required if 'shear_stress_deposition_conc' = 'reference' - 1.0 x > 0

    Description of Variables

    scheme - This is the type of the numerical scheme used for the computation of advective fluxes. The choices are:
    diffusion - This option defines if and what kind of diffusion factor shall be used.Choices are 'off', 'constant' and 'dynamic'. If set to 'off', there is no calculation of diffusive terms, resulting in less computational time being used. 'constant' requires the definition of a constant value for eddy diffusivity. 'dynamic' calculates the eddy diffusion factor lambda dependent on the actual hydraulic discharge.
    diffusion_factor - The factor representing the constant eddy diffusivity Γ can be given here. If it's not given, it is computed by the program according to (RII-1.115).
    diffusion_factor_dynamic - This is a calibration parameter for the dynamical computed turbulent viscosity (eddy viscosity averaged over depth). This factor ϑ is multiplied with the turbulent viscosity:

    ν = ϑ · κ/6 · h· u*

    Per default the factor ϑ is set to 1.0.
    sediment_exchange - This option defines whether there is exchange of suspended sediment with the river bed (deposition/entrainment) or not. If set to 'off', there is no exchange with the river bed. This corresponds to the calculation of the Advection and Diffusion of a Pollutant.
    use_transport_type_factor - This option defines if the transport type factor shall be used. If set to 'yes', the bed load transport will be reduced if the suspension transport increases. If set to 'no', the bed load transport is calculated independently from the suspension transport.
    transport_type_factor - Name of the approach for the computation of the transport type factor. This factor determines which portion of the sediment transport Shall be transportet as suspension load (the rest is bed-load). By default (if not specified), Van Rijn is used. The 'bagnold' approach is similar, but needs larger shear stresses for incipien motion.
    number_susp_fractions - This number determines the amount of grain classes used for suspended load. By default, it is set to 1, which corresponds to a 'single grain suspended load'. This parameter is of importance when using multi-grain simulations. Assuming, the simulation uses five grain classes defined in the GRAIN_CLASS block of BEDMATERIAL and bedload as well as suspended load is desired. In most cases, the bedload uses fractions of grain sizes which will hardly ever be part of suspended load because of their large diameters. In this case, e.g. setting the 'number_susp_fractions = 2' will only use the first two fractions defined in GRAIN_CLASS for suspended load. The bedload however will use all five fractions. This results in a gain of simulation time as the equations for Advection and Diffusion will only be solved for the two fractions instead of all five. Note: number_susp_fractions has to be at least 1 and at maximum equal to the number of fractions within the GRAIN_CLASS block.
    pickup_factors - The rate of suspension entry according to the suggestion by Bennet and Nordin (1977) may strongly depend on the so-called 'reference concentration for suspension entry'. Two formulas for this 'reference concentration' are provided: the approach of Van Rijn (1984) and the approach of Zyserman (1994). Both formulas sometimes differ significantly. The pickup factors can be used to cover that as they multiply the computed pickup rate of every grain class with the corresponding pickup factor. The pickup factors must be set for every grain class in suspension.
    To use the original approaches of Van Rijn or Zyserman, they should be set to 1.0 for every grain class in suspension. The pickup factors might be important calibration factors.
    factor_depth_reference_height - At the reference height the reference concentration is calculated.
    This reference height factor is multiplied with the water depth (factor * depth). By default it is set to 0.1.
    adaption_length_factor - This is an important calibration factor for the pick-up rate during suspension transport.
    It is multiplied linearly with the calculated pick-up rate. By default, it is set to 1.0.
    sink_velocity_type - There are many different (semi-)empirical formulas for the settling velocity of a sediment particles. BASEMENT allows to use either the formula provided by Van Rijn (1984), Wu & Wang (2006) or Zhang (1961). Additionally, absolute values of settling velocities can be defined by the user. These values can be defined within the tag 'settling_velocities'. By default the approach of Van Rijn (1984) is used.
    settling_velocities - Here, the settling velocities must be assigned for each grain class, no matter if it is in suspension or not.
    corey_shape_factor - The Corey shape factor describes the irregularity of the shapes of sediment particles in natural rivers. It makes use of the characteristic lengths a, b and c (the longest, the intermediate and the shortest axes) and is given by
    S = c / sqrt(a*b)
    A spherical particle would have a Corey shape factor of 1.0. Naturally worn particles have a Corey shape factor of usually between 0.3 and 0.9. A value of 0.7 (corresponding to sand particles) is set by default.
    concentration_type - Name of the formula for the computation of the near bed computation which is used to calculate exchange of suspended material with the soil. Possible choices are 'vanrijn' for the approach of Van Rijn or 'zysermann' for the approach of Zysermann and Fredsoe. By default (if not specified), Van Rijn is used.
    limit_pickup_to_bedload - This flag which determines if pick-up rate shall be limited to the bed-load capacity of the grain multiplied with the transport type factor.
    theta_critical_from_bedload - This option defines how to determine the critical dimensionless shear stress 'theta'. If set to 'yes', theta is taken as it was determined in the bed-load calculations of the last time step (this is only possible if suspension AND bed-load are active!!!). If set to 'no', theta is determined separately (neglecting hiding&exposure and other settings from the bed-load calculations).
    local_slope_correction - The following corrections for the critical Shields paramter due to local bed slope can be selected:
    exchange_type - There are two typical approaches that describe how the sediment exchange rate between soil and suspension can be computed [RI Chapter 2.2.3]:
    factor_m - This is a calibration factor which is used if sediment exchange is computed following the approach using shear stresses. M is used to calibrate the erosion rate (entrainment rate). Xu (1998) suggests to choose M in the order of 10e-5 up to 10e-3. M has the dimension of kg/(m2 · s).
    factor_n - This is a calibration factor which is used if sediment exchange is computed following the approach using shear stresses. factor_n is used to calibrate the erosion rate (entrainment rate). Xu (1998) suggests to choose n between 1 and 4. factor_n is a dimensionless parameter.
    tk - This is a calibration factor which is used if sediment exchange is computed following the approach using shear stresses. Tk is used to calibrate the deposition rate. Westrich and Juraschek (1985) suggested to choose a value of 0.0018.
    shear_stress_deposition_conc - There are two typical approaches that describe how the sediment exchange rate between soil and suspension can be:
    ref_conc_factor - his is a calibration factor which is used if sediment exchange is computed following the approach using shear stresses. ref_conc_factor is used to calibrate the deposition rate in case that the reference conentration is used.ref_conc_factor is a dimensionless parameter.

    Example

    SUSPENDED_LOAD
{
   [...]
   PARAMETER
   {
      number_susp_fractions = 1
      scheme = upwind 
      diffusion = constant
      diffusion_factor = 0.1
      sediment_exchange = on
   }
   [...]
}
    BOUNDARY
    BOUNDARY compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > SUSPENDED_LOAD
    Description: This block defines boundary conditions for suspended load.

    Variable type comp. condition units default values
    name string no - - - Chars [a-zA-Z0-9_-] are allowed
    type string yes - - - {suspension_discharge, out_down, wall}
    string_name string yes - - - Chars [a-zA-Z0-9_-] are allowed
    file string yes required if 'type' = 'suspension_discharge' - - -
    mixture string yes required if 'type' = 'suspension_discharge' - - -

    Block Usage

    If no boundary condition is specified for part of or the whole boundary, an infinite wall is assumed. For every different condition, a new block BOUNDARY has to be used.
    It is distinguished between upstream and downstream boundary conditions. At the upstream, inflow conditions are valuable. They need a mixture assigned in any case of multi grain size or single grain size simulations. Downstream boundary conditions are for outflow, they don't need any mixture assigned.

    Description of Variables

    name - This is the name of the suspension boudary conditions. This is used for coupling of different domains. however, coupling for suspended transport is not implemented yet, therefore this parameter is useless.
    type -
    string_name - This is the name of the cross section defined in a STRINGDEF block to define where the boudnary condition shall act.
    file - Name of the file containing the evolution of sediment discharge in time for a inflow 'suspension_discharge' boundary condition.
    mixture - This is the name of the mixture that shall be used for an inflow 'suspension_discharge' boundary condition.

    Example

    SUSPENDED_LOAD
{
   [...]
   BOUNDARY 
   {
      type = suspension_discharge
      file = cVar.txt
      string = upstream
      mixture = unique
   } 
   BOUNDARY 
   { 
      type = out_down 
      string = downstream 
   }
   [...]
}
    INITIAL
    INITIAL compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > SUSPENDED_LOAD
    Description: This block is used to define initial conditions for the suspended load transport. Every element can be assigned an initial concentration.

    Variable type comp. condition units default values
    type string yes - - - {clear_water, index_table, continue}
    file string yes required if 'type' = 'continue' - - -
    index whitespace separated list of integers yes required if 'type' = 'index_table' - - -
    concentration whitespace separated list of reals yes required if 'type' = 'index_table' - - -
    mixture whitespace separated list of strings yes required if 'type' = 'index_table' - - -
    restart_solution_time real no used if 'type' = 'continue' [s] -1.0 x >= -1

    Block Usage

    For suspended load it is necessary to specify initial concentrations. The initial concentrations may be defined for each element. This can be done by using the material_indices orby using a file generated from a previous simulation or by using the clear_water option which sets all concentrations to 0.

    Description of Variables

    type - There are three ways to define the initial concentrations.
    file - Name of the file containing the concentrations for each element. This is the same file as for the hydraulic restart named 'scenario_restart.cgns' from a previous simulation.
    index - List of available material indices
    concentration - List of concentrations for the corresponding indices
    mixture - List of mixtures for the corresponding indices
    restart_solution_time - This time specifies the time at which the solution is read from the file. This parameter is needed because the restart file can contain different solutions at different times. If a negative time is given, than the last available solution is chosen from the restart file. (For the given time a solution must exists in the restart file. If this is not the case, than all available times will be listed for the user to choose from.)

    Example

    SUSPENDED_LOAD
{
   [...]
   INITIAL
   {
      type = continue
      file = initialC.txt 
      restart_solution_time = 1000234.23
   }
   [...]
}

SUSPENDED_LOAD
{
   [...]
   INITIAL
   {
      type = index_table
      index = ( 1 2 )
      concentration = ( 0 0.001 )
      mixture = ( unique unique )
   } 
   [...]
}
    SOURCE
    SOURCE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > SUSPENDED_LOAD
    Description: The SOURCE block for suspended load contains external sources for local suspended load inflow. For each such external source, a new inner EXTERNAL_SOURCE block has to be defined.
    Inner Blocks: EXTERNAL_SOURCE

    Example

    SUSPENDED_LOAD
{
   [...]
   SOURCE
   {
      EXTERNAL_SOURCE
      {
         [...]
      }
      EXTERNAL_SOURCE
      {
         [...]
      }
   }
   [...]
}
    EXTERNAL_SOURCE
    EXTERNAL_SOURCE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > SUSPENDED_LOAD > SOURCE
    Description: The external source block is used for additional sources of suspended material in the region. The region is defined by the element numbers that shall be affected. An input file for the suspension addition is used for the definition of the inflow. The input file defines the total volume discharge of the additional suspended material in [m3/s]. The total volume will then be broken into parts for every grain class fraction according to the mixture for this external source. Negative sources (outtake) are ignored without warning at the moment. Note: An external source for suspended material goes directly into the fluid phase. If you want to add an external source (positive or negative) which goes/comes directly into/from the soil, use an external source within the BEDLOAD block. If an element is dry, its part of the total source will be neglected, as the fluid phase doesnt exist at that moment. Therefore, only a part of the total suspended volume will effectively be added to the fluid phase. In the extreme case where all elements are dry, no suspended external source will be added to the fluid phase.

    Variable type comp. condition units default values
    name string no - - - Chars [a-zA-Z0-9_-] are allowed
    type string yes - - - {suspended_discharge}
    file string yes - - - -
    mixture string yes - - - -
    element_ids whitespace separated list of integers yes - - - -

    Description of Variables

    name - This is the name of the external source. It will be used for coupling between domains. However, coupling for suspended material is not implemented yet.
    type - The only choice for the type of the source is 'suspended_discharge'.
    file - This is the name of the file containing the time and corresponding total volume [m3] for the suspended source. Negative values are not allowed as it is not possible to take out suspended material from the fluid phase.
    mixture - This is the name of the mixture of the external source. The mixture must correspond to a suspended mixture in the sense that only the first n grainclasses are affected with n = number_susp_fractions from the PARAMETER block. If there are more grain diameters than n, the rest of the mixture must have 0 contribution.
    element_ids - This is a list of element numbers where the external source shall act.

    Example

    SUSPENDED_LOAD
{
   [...]
   SOURCE
   {
      EXTERNAL_SOURCE
      {
         type = suspended_discharge
         file = source_in_time.txt
         element_ids = (  12  14  18  )
         mixture = mixture2
      }
   }
   [...]
}
    GRAVITATIONAL_TRANSPORT
    GRAVITATIONAL_TRANSPORT compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY
    Description: The GRAVITATIONAL_TRANSPORT block for morphology in 2D deals with transport due to slope failures.Use this block to enable slope failures in cases of steep elements within the domain.This approach bases on failure-angley which determine when a slope failure takes place.

    Variable type comp. condition units default values
    index whitespace separated list of integers yes - - - -
    angle_failure_dry whitespace separated list of reals yes - - - [Degree]
    angle_failure_wetted whitespace separated list of reals yes - - - [Degree]
    angle_failure_deposited whitespace separated list of reals yes - - - [Degree]
    gravity_transport_on_cells string no - - all {all, fully wetted, partially wetted}
    max_delta_z real no - [m] 0.001 x > 0
    cycle_step integer no - - 5 x >= 0
    min_changed_volume real no - [m3] 0.01 x >= 0
    max_iterations integer no - - 10 x >= 0
    angle_wetted_criterion string no - - fully_wetted {fully_wetted, partially_wetted}
    only_subsurface_angle string no - - no {yes, no}
    check_hydrostatic_stabilization string no - - no {yes, no}
    stabilization_height real no - [m] 0.00 x >= 0

    Description of Variables

    index - List of material indizes for elements. At least one indizes must be specified.The gravitational transport is limited to elements which have one of the given indizes.For each index in the list the failure-angles have to be specified separately.
    angle_failure_dry - If this critical angle is exceeded for any element, a slope failure occurs. This critical angle can be larger than the angle of repose due to negative pore pressures, and corresponds to the maximum possible slope angle. Partially saturated elements have a failure angle that ranges between this angle and the 'angle_failure_wetted' (which is similar to the angle of repose) as a function of saturation level. Partially saturated elements can be representative of river banks or reservoir dams. Deposited material is treated separately, see tag 'angle_failure_deposited'.
    angle_failure_wetted - If this critical angle (which should be similar to the angle of repose) is exceeded for wetted or completely dry elements, a slope failure occurs . Note that this angle applies only for wetted or completely dry elements (deposited material is treated separately, see tag 'angle_failure_deposited').
    angle_failure_deposited - If this critical angle is exceeded for deposited material a slope failure occurs. Note that this angle applies to material which was deposited after transport occured or a slope failed. This angle might be set to a smaller value than the angle of repose (can be used for the sliding of the material after slope collapse, e.g. for dam breach modelling.
    gravity_transport_on_cells - The gravitational transport can be applied to all elements or limited to elements which are fully or partially wetted. Per default it is set to 'all'.
    max_delta_z - Threshold of deposition height [m]. If the deposition is larger than this threshold, the failure-angle for deposited material is applied.Usually this value should not have to be adjusted.
    cycle_step - Specifies the cycle steps for which gravitational transport shall be calculated. For example, a value of 5 forces the computations to be doneafter every 5 cycles of the sediment routine.
    min_changed_volume - Abort criteria for gravitational transport calculation. If sum of changes in transported sediment volume [m3] gets smaller than this volume the calculations are stopped for this time step.
    max_iterations - Abort criteria for gravitational transport calculation. Specifies the maximum number of iterations which may be performed for gravitational transport calculations. (The larger the number the faster the slope failure will take place.)
    angle_wetted_criterion - This parameter determines under which conditions the critical angle for wetted cells is applied.Per default it is set to 'fully_wetted'. But in dam break simulations it is recommended to use the 'partially_wetted' option.

    Example

    GRAVITATIONAL_TRANSPORT
{
    index = ( 1 2 ) 
    angle_failure_dry = ( 60.0 60.0 ) 
    angle_failure_wetted = ( 30.0 30.0 ) 
    angle_failure_deposited = ( 10.0 10.0 ) 
    max_iterations = 20 
    cycle_step = 1 
    min_changed_volume = 0.001 // [m3]
}
    SOURCE
    SOURCE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY
    Description: The SOURCE block for morphology in 2D contains external sources or sinks which can be attached to any computational element(s) with the corresponding node_id(s). an external source is used to add or remove bedmaterial to/from the soil. For each different external source, a new inner block EXTERNAL_SOURCE has to be defined.
    Inner Blocks: EXTERNAL_SOURCE

    Example

    MORPHOLOGY
{
   [...]
   SOURCE
   {
      EXTERNAL_SOURCE
      {
         [...]
      }
      EXTERNAL_SOURCE
      {
         [...]
      }
   }
   [...]
}
    EXTERNAL_SOURCE
    EXTERNAL_SOURCE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY > SOURCE
    Description: The EXTERNAL_SOURCE block is used for additional sources or sinks for bedload.

    Variable type comp. condition units default values
    name string no - - - Chars [a-zA-Z0-9_-] are allowed
    type string yes - - - {sediment_discharge, coupling_sediment_discharge, dredge}
    file string yes required if 'type' = 'sediment_discharge' - - -
    mixture string yes required if 'type' = 'sediment_discharge' - - -
    node_ids whitespace separated list of integers no - - - -
    elem_ids whitespace separated list of integers no - - - -
    index whitespace separated list of integers no - - - -
    dredge_node_ids_redist whitespace separated list of integers yes required if 'type' = 'dredge' - - -
    dredge_elem_ids_redist whitespace separated list of integers yes required if 'type' = 'dredge' - - -
    dredge_level_absolute real no used if 'type' = 'dredge' [m.a.s.l] -1.0 -
    dredge_height_relative real no used if 'type' = 'dredge' [m] -1.0 -
    dredge_trigger_height real yes required if 'type' = 'dredge' [m] - x >= 0
    dredge_rate_max real no used if 'type' = 'dredge' [m3/s] 1E32 x >= 0

    Block Usage

    If no source block is specified, the additional source is set to zero and no sediment enters the computational domain as source. The specified source or sink in [m3/s] is distributed over all given nodes or elements. (In case of coupling no file and no mixture have to be defined).
    Please note that also for single grain size simulations, the definition of a mixture is still needed. In case of a sediment sink, the definition of the mixture must also be given.

    Description of Variables

    name - Unique identifier which is used to define couplings between domains.
    type - This is the type of the external source.
    file - This is the name of the file with the source values listed over time. The file needs two columns, time and corresponding sediment inflow [m3/s]. (ATTENTION: the inflow is expected to be specified without porosity!)
    mixture - This is the name of the mixture for the sediment source.
    node_ids - This is a list of the node ids where the source or sink shall take place. Another possibility is to define element ids or use material index.
    elem_ids - This is a list of (hydraulic) element ids where the source or sink shall take place. Another possibility is to define node ids or use material index.
    index - This is the material index where the external sediment source or sink is located. Another possibility is to define element ids or node ids.
    dredge_node_ids_redist - Optional. This is a list of node ids where dredged sediment volume of the dredge source shall be re-distributed to. Another possibility is to define element ids.
    dredge_elem_ids_redist - Optional. This is a list of (hydraulic) element ids where dredged sediment volume of the dredge source shall be re-distributed to. Another possibility is to define node ids.
    dredge_level_absolute - indicates the absolute bed level which is aimed at due to dredging. This elevation is used for all defined elements.
    dredge_height_relative - indicates the relative sediment height over the original bed level is aimed at due to dredging. This elevation may vary from element to element.
    dredge_trigger_height - this is the trigger height of sediment deposition for the start of the dregding. If the deposition above the dredge level (difference between mean bottom level and the dredge level) exceeds the trigger value, the dredging is executed.Dredging is performed until the defined 'dredge_level' is reached.
    dredge_rate_max - maximum dredge rate which is used for dredging.

    Example

    MORPHOLOGY
{
   [...]
   SOURCE
   {
      EXTERNAL_SOURCE
      {
         type = sediment_discharge
         file = source_in_time.txt
         node_ids = ( 34 35 36 37 38 39 40 )
         mixture = mixture1
      }
      EXTERNAL_SOURCE
      {
         type = sediment_discharge
         file = another_source_in_time.txt
         elem_ids = ( 256 500 325 690 740 695)
         mixture = mixture3
      }
      EXTERNAL_SOURCE
      {
         type = sediment_discharge
         file = source_in_time.txt
         index = ( 2 )
         mixture = mixture2
      }
      EXTERNAL_SOURCE
      {
         type = dredge
         absolute_dredge_level = 393.44
 		delta_z_start = 0.5
         maximum_dredge_rate = 0.01
      }
   }
   [...]
}
    APPARENT_COHESION
    APPARENT_COHESION compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > MORPHOLOGY
    Description: The APPARENT_COHESION block for morphology in 2D deals with approximating effects of apparent cohesion. Apparent cohesion can influence the slope stabilities and therefore effects the bank failure algorithm. Further, apparent cohesion influences the particle stability and therefore effects the bed-load transport and the suspended-load transport. These effects can be considered heuristically and need some calibration using the parameters given in this block.

    Variable type comp. condition units default values
    saturation_threshold_deposition real no - [-] 0.0 0 <= x < 1
    angle_deposition_delta real no - [Degree] 2.0 x >= 0
    local_slope_angle_repose_cohesion real no - [Degree] 30.0 -
    height_above_bed real no - [-] 2.0 x > 0
    factor_tau_suc real no - [-] 0.1 -
    factor_tau_suc2 real no - [-] 0.1 -
    deposition_threshold real no - [m] 1E-5 x > 0
    inverse_apparent string no - - off {off, on}

    Description of Variables

    saturation_threshold_deposition - Specifies the saturation threshold from which the deposition angle is linearly reduced. If the value is set to zero, than the deposition angle is reduced from dry conditions linearly up to fully saturated conditions. It is recommended to set this value to 0.0 (default).
    angle_deposition_delta - Specifies the maximum amount (in degree) of which the deposition angle can be reduced. The conceptual idea is to reduce the deposition angle due to the additional momentum caused by the increased weight due to the water contained in the material. Setting this value to 5 degree, e.g., means that for fully saturated conditions the deposition angle is reduced for 5 degrees.
    local_slope_angle_repose_cohesion - This is the angle used in the lateral local slope correction formulation for the angle of repose. The critical shear stress is either reduced or increased due to a slope lateral to the flow direction.This angle does not affect the gravitational transport failure angles.
    height_above_bed - This a special calibration parameter used for the determination of the additional resistance of particles to the erosion due to apparent cohesion effects. It specifies the assumed height of the particles over the bed in terms of multiples of the height ks. This parameter usually should not be changed.
    factor_tau_suc - This is the main calibration parameter used for the determination of the additional resistance of particles to the erosion due to apparent cohesion effects. The theoretical apparent cohesion will be reduced by this factor in order to compensate for effects of infiltration during erosion and other effects.
    factor_tau_suc2 - This is the main calibration parameter used for the determination of the additional resistance of particles to the erosion due to apparent cohesion effects. The theoretical apparent cohesion will be reduced by this factor in order to compensate for effects of infiltration during erosion and other effects.
    deposition_threshold - For deposited material no apparent cohesion effects are considered. This parameter specifies how large the deposition height shall be at which apparent cohesion effects are no longer considered. This parameter should be in the range of the erosion depths occuring during one time step.
    inverse_apparent - If this parameter is set to 'off', the critical shear stress is increased due to apparent cohesion. As a consequence, the sediment transport is reduced. This is the default behaviour and is recommended. If it is set to 'ob', then the critical shear stress is reduced if no apparent cohesion acts .As a consequence, the sediment transport is increased.

    Example

    APPARENT_COHESION
{
    saturation_threshold_deposition = 0.0 
    angle_deposition_delta = 2 
    local_slope_angle_repose_cohesion = 30
    height_above_bed = 2.0
    factor_tau_suc = 5.0
    deposition_threshold = 1E-5
    inverse_apparent = off
}
    TIMESTEP
    TIMESTEP compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D
    Description: The TIMESTEP block is used to specify numerical parameters related to the time and timestep for the simulation, as time step, total run time, CFL number etc.

    Variable type comp. condition units default values
    CFL real no - [-] 1.0 0 < x <= 2
    minimum_time_step real no - [s] 0.001 x > 0
    maximum_time_step real no - [s] 100.0 x > 0
    initial_time_step real no - [s] 1.0 x > 0
    total_run_time real yes - [s] - x > 0
    start_time real no - [s] -1.0 -
    ignore_wave_celerity string no - - off {off, on}
    maximum_waterdepth real yes required if 'ignore_wave_celerity' = 'on' [m] 0.0 x >= 0
    morph_cycle string no - - off {off, constant, dynamic}
    cycle_step real yes required if 'morph_cycle' = 'constant' [-] 1.0 x >= 0
    cycle_step_file string yes required if 'morph_cycle' = 'dynamic' - - -

    Block Usage

    The only thing that needs to be defined is the total_run_time. All other variables use default values if they dont get specified by the user. Changing these Parameters either leads to faster and more stable simulations or it may make the simulation collapse in the worst case. The most often changed Parameter is the CFL number to change the timestep.

    Description of Variables

    CFL - Courant-Friedrichs-Lewy number. This parameter is used to control the time step. The CFL-number is defined as the ratio between spatial resolution and time step. Values must be smaller than 1.0. By default, it is set to 1.0. Reducing the CFL number results in smaller timesteps and more stable simulations. As a drawback, the simulation as a whole needs more time. (Basement allows setting this value larger than 1.0, but the stability is no longer guaranteed in this case!).
    minimum_time_step - This option throws a warning on the console during the simulation, if the actual time step is lower than the minimum time step defined here. It's just some additional info. There is no possibility to influence the time step using this option. Use the CFL number if you want to in-/decrease the time step. By default, it is set to 0.001 s.
    maximum_time_step - This parameter defines a maximum time step size for the simulation. The time step size during the simulation cannot exceed this number. By default the maximum time step is set to 100.0 s. Normally, this timestep is used at the beginning of a simulation when starting from a dry state.
    initial_time_step - This parameter only influences the time step of a simulation during no-flow conditions (when the CFL criterion is not applicable, e.g. at a completely dry state). To avoid numerical instability, it should be large enough to wet some dry cells (e.g. boundary cells), but small enough to ensure the accuracy of the numerical scheme. By default, it is set to 1.0 s.
    total_run_time - This parameter needs to be specified by the user. When the given time value is reached, the simulation stops all output is written. If the simulation continues from an earlier state, the starting time will be different from zero and the effectively computed time is the difference between the total_run_time and the starting time.
    start_time - This parameter defines the time (in seconds) when the simulation starts. If you want the simulation to start at t = x s, then set this value to x. If start_time is set to a negative value (per default), two cases are distinguished. (a) A restart file is defined. Then the restart time ('restart_solution_time') defined in the initial conditions block will be used. (b) No restart file is defined. Then the simulation starts from t = 0.0 s.
    ignore_wave_celerity - This option ('ignore_wave_celerity = on') enables the calculation of the numerical timestep (based on CFL condition) without considering the wave celerity c = sqrt(g*h). This might be useful to avoid small numerical time steps in the case of high water depths, e.g. river flowing in a lake. As a result, time steps are getting larger compared to the original case. Be aware that using this option may lead to instabilities in the hydraulic solutions.It is highly recommended to set a 'maximum_waterdepth' different to 0.0.
    maximum_waterdepth - In the case of 'ignore_wave_celerity = on', this value is used for the calculation of the wave celerity (c = sqrt(g*h)).Hence, the calcualtion of the numerical time step is independent from the actual water depth. Generally, a small 'maximum_waterdepth' increases the numerical timestep. The 'maximum_waterdepth' should be set to the expected water depth in the flowing part of the simulation (e.g. depth in the river).
    morph_cycle - This specifies the cycle steps for hydrodynamic routing. This is helpful when dealing with very long simulations including bedload and/or suspension. Assuming we have a quasi-stationary flow from the hydraulics, the bedload is calculated again and again using the quasi-stationary solution of the hydraulics. The hydraulic part is updated anyways after the defined number of hydrosteps. This approach can decrease the calculation time. However, it should only be used when the hydraulics can be regarded as quasi-stationary.
    For example, a value of 5 forces the hydrodynamic routine to be computed after every 5 cycles of the sediment routine.
    To get a maximum speedup using the cycle_step, some test runs are required. First, set the cycle_step to a number which is way too high, like 1000000. The resulting RTS value can be regarded as the speed limit that can be reached at all. Now, decrease the cycle_step value, e.g. setting it to 1000. Most probably, the RTS value is the same as before. Continue decreasing the cycle_step until the RTS is getting down. This value for the cycle_step is then the 'optimal choice'. It is as low as possible yet delivering the maximum speedup.
    cycle_step_file - This is the filename of a .txt-file that describes the cycle step as a function in time. first column is time in seconds, second column is the corresponding hydrostep. Make sure to define stepwise functions to avoid interpolation between hydrosteps.

    Example

    BASEPLANE2D
{
   [...]
   TIMESTEP
   {
      CFL = 1.0
      initial_time_step = 0.01
      minimum_time_step = 0.0001
      total_run_time    = 3600.0
      start_time        = 0.0
 // simulation starts at t= 0.0s   }
   [...]
}
    OUTPUT
    OUTPUT compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D
    Description: This block contains all sub-blocks which define the desired output data.
    Inner Blocks: SPECIAL_OUTPUT

    Variable type comp. condition units default values
    console_time_step real yes - [s] - x >= 0
    restart_time_step real no - [s] 1E32 x >= 0
    reference_time string no - - - Chars [a-zA-Z0-9_-] are allowed

    Block Usage

    A numerical simulation produces a lot of output data. Most of the times, not all output is of interest to the user. Writing the output to a hard disk costs time that better be used for calculations. Therefore, the user has to define explicitely what output shall be written.
    ATTENTION! If no special output is defined in the output block, the simulation will do all the calculations but there will be NO output of these results!
    Every desired output has to be defined in an own SPECIAL_OUTPUT block. The usage is described at the SPECIAL_OUTPUT.
    The OUTPU block itself has only two parameters to set general timesteps for console output and the output of restart files.

    Description of Variables

    console_time_step - The console time step defines the time step of the console output during simulation. Setting it to small values may slow down the simulation.
    restart_time_step - The restart time step defines the time interval after which a new solution is written to the restart file. Setting it to small values may result in very large restart files! If the value is not set, than it is set per default to a very large number (1E32). This implies that only the last time step of the simulation is written to the restart file.
    reference_time - The reference time is used for special outputs in SMS format. It defines the time when your simulation starts.The reference time is expected to be entered in the following way:

    DAY-MONTH-YEAR-HOURS-MINUTES-SECONDS

    Example: 26th of March 2014 at 16 hours 32 minutes 20 seconds would be
    26-03-2014-16-32-20 or 26-3-2014-16-32-20.

    Note: Please use 26-03-2014-00-00-00 instead of 25-03-2014-24-00-00. Also write zeros (e.g. for seconds) so that there are always six values separated by a hyphen (-).

    Example

    BASEPLAIN_2D
{
   [...]
   OUTPUT
   {
      output_time_step = 10.0
      console_time_step = 1.0
      SPECIAL_OUTPUT
      {
         [...]
      }
      SPECIAL_OUTPUT
      {
         [...]
      }
   }
   [...]
}
    SPECIAL_OUTPUT
    SPECIAL_OUTPUT compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > OUTPUT
    Description: The Special Output block defines a desired output of a simulation.

    Variable type comp. condition units default values
    type string yes - - - {node_centered, element_centered, BASEviz, node_history, element_history, stringdef_history, edge_history, boundary_history, balance, avs_ucd, sediment_grid}
    output_time_step real yes - [s] - x >= 0
    values whitespace separated list of strings yes required if 'type' = 'node_centered' or 'element_centered' - - valid entries are {'depth', 'velocity', 'wse', 'z_element', 'concentration', 'susp_load', 'susp_net_deposition_rate', 'friction', 'tau', 'abs_velocity', 'susp_grain_conc', 'theta_critical', 'specific_discharge', 'susp_total_pickup', 'susp_total_deposition', 'susp_grain_pickup', 'susp_grain_deposition', 'saturation', 'pore_pressure', 'external_source_discharge', 'radius_curvature', 'radius_curvature_abs', 'momentum', 'abs_momentum', 'water_table', 'biomass', 'carrying_cap', 'source_bed', 'source_friction', 'source_wall_friction', 'source_internal_friction', 'balance_discharge_fluxes', 'balance_momentum_fluxes', 'grain_size', 'grain_bedload', 'z_node', 'deltaz', 'bedload_vec', 'sediment_sum'}
    format string yes required if 'type' = 'node_centered' or 'element_centered' - - {ascii, sms, tecplot, shape, vtk}
    binary boolean no used if 'format' = 'tecplot' - no {no, yes}
    ids_instead_coords boolean no used if 'format' = 'ascii' - no {no, yes}
    split_file boolean no used if 'format' = 'tecplot' or 'vtk' - no {no, yes}
    flush_all_num_steps integer no used if 'type' = 'node_history' or 'element_history' or 'stringdef_history' or 'boundary_history' or 'edge_history' output steps 0 x >= 0
    history_one_file boolean no used if 'type' = 'node_history' or 'element_history' or 'stringdef_history' or 'boundary_history' or 'edge_history' - no {no, yes}
    element_ids whitespace separated list of integers yes required if 'type' = 'element_history' - - -
    element_values whitespace separated list of strings yes required if 'type' = 'element_history' - - valid entries are {'depth', 'velocity', 'wse', 'z_element', 'concentration', 'susp_load', 'susp_net_deposition_rate', 'friction', 'tau', 'abs_velocity', 'susp_grain_conc', 'theta_critical', 'specific_discharge', 'susp_total_pickup', 'susp_total_deposition', 'susp_grain_pickup', 'susp_grain_deposition', 'saturation', 'pore_pressure', 'external_source_discharge', 'radius_curvature', 'radius_curvature_abs', 'momentum', 'abs_momentum', 'water_table', 'biomass', 'carrying_cap', 'source_bed', 'source_friction', 'source_wall_friction', 'source_internal_friction', 'balance_discharge_fluxes', 'balance_momentum_fluxes'}
    node_ids whitespace separated list of integers yes required if 'type' = 'node_history' - - -
    node_values whitespace separated list of strings yes required if 'type' = 'node_history' - - valid entries are {'grain_size', 'grain_bedload', 'z_node', 'deltaz', 'bedload_vec', 'sediment_sum'}
    stringdefs whitespace separated list of strings yes required if 'type' = 'stringdef_history' - - -
    stringdef_values whitespace separated list of strings yes required if 'type' = 'stringdef_history' - - valid entries are {'Q', 'Qsed', 'conc', 'u', 'wse', 'zbed', 'energy_head'}
    edge_ids whitespace separated list of strings yes required if 'type' = 'edge_history' - - -
    edge_values whitespace separated list of strings yes required if 'type' = 'edge_history' - - valid entries are {'u2h', 'v2h', 'gh2', 'depth', 'u_norm', 'v_tang', 'susp_upper_C', 'susp_fluxAAx'}
    boundary_values whitespace separated list of strings yes required if 'type' = 'boundary_history' - - valid entries are {'Q', 'Qsed'}
    balance_values whitespace separated list of strings yes required if 'type' = 'balance' - - valid entries are {'sediment', 'timestep', 'water_volume'}
    variable string no used if 'type' = 'BASEviz' - depth {depth, wse, velocity, tau, bedload, bedelevation}
    wse3D string no used if 'type' = 'BASEviz' - off {off, on}
    vectors string no used if 'type' = 'BASEviz' - off {off, on}
    gridlines string no used if 'type' = 'BASEviz' - off {off, on}
    vectors_scaling_factor real no used if 'type' = 'BASEviz' - 1.0 -
    write_jpeg_image_time real no used if 'type' = 'BASEviz' - -1.0 -
    value_range whitespace separated list of 2 reals no used if 'type' = 'BASEviz' - - -
    BASEextern string no used if 'type' = 'node_centered' or 'element_centered' or 'node_history' or 'element_history' or 'stringdef_history' or 'edge_history' or 'boundary_history' - - -
    ids whitespace separated list of 2 reals no used if 'type' = 'node_centered' or 'element_centered' - - -
    threshold_wse real no - - -1000000 -

    Block Usage

    Every distinct output needs a new SPECIAL_OUTPUT block. For every output, an own output time step can be defined. This allows to have some very frequent output while another output is done rather seldom.
    There are many different kind of output data:
    scalar data (depth, wse, tau, etc.) and vector data like velocity can be produced for different postprocessing programs like tecplot, SMS or AVS. This data can be on the nodes or on the elements of the grid. General data like maximal, minimal and time-integrated values of some parameters as well as time series of discharges, wse, ... but also stuff like the timestep and the elements responsible for the time step can be defined to be an ouput. Furthermore, the graphical output of the simulation results during run-time can be set in a SPECIAL BLOCK (codeword BASEviz).
    Important parameters for this block are 'type' and 'output_time_step'. They must be defined for every choice of output. Dependent on the chosen type, other options may have to be defined.
    The many different possibilities for the output are described within the description of the variables. Please do also have a look at the Examples below and the Test Cases on the website to get a feeling of the possibilities.
    Output and Parallelization: Please note that the output is written asynchronically. Therefore, if you write a lot of data or if you use the BASEviz view, you should dedicate a processor entirely to the output display. You can do this by reducing the number of processors dedicated to the simulation within the PARALLEL block.

    Description of Variables

    type - There are different types for the output. Dependent on the choice, further parameters may be needed.
    output_time_step - This parameter defines the interval in [s] for which the output shall be written. Choosing '0' produces an output at every timestep. Frequent output may slow down the simulation dramatically!
    values - These are the variables which can be written either on the nodes or on the element centers of the grid. It is indicated in the following list whether the data is a scalar or a vector and where it is calculated during the simulation.
    It is also possible to generate contour plots of maximal, minimal and time-integrated values. The syntax is then e.g. max[wse] integrate[depth] min[friction] and holds for all kind of values. Be aware that this can slow down your simulation dramatically.
    format - This option provides a choice between different formats for the output of salar or vector data on the mesh.
    binary - This option enables the writing in binary format. By default, it is set to 'no', producing 'human-readable' data. Note that the binary files can (according to tecplot) only be read by Tecplot 2009 (March 2009) and newer. Users with older tecplot versions should use the 'no' option, leading to ascii tecplot data files.
    ids_instead_coords - This option provides the choice between two different idsmsentification types of nodes or elements respectively. By default, it is set to 'no', writing the coordinates of the nodes or of the element center. If set to 'yes', the external ID's (the one given by the input grid .2dm) are written instead of the coordinates.
    split_file - This option provides the possibility to split the binary- or ascii-file into multiple files each containing ONE output variable. By default, it is set to 'no', writing all variables into one single binary- or ascii-file. If set to 'yes', one file will be written for each output variable.
    flush_all_num_steps - If > 0, the output is flushed all N steps to disk. If this value is too small, you may slow down the simulation as it waits until all output has been flushed to disk.
    history_one_file - If set to 'yes', the time history outputs are written to one file instead of separate files.
    element_ids - This is a list of element indices for the use with output type 'element_history'.
    element_values - This is a list with all desired temporal output variables for an 'element_history'.
    It is also possible to generate contour plots of maximal, minimal and time-integrated values. The syntax is then e.g. max[wse] integrate[depth] min[friction]. This holds for all kind of values.
    node_ids - This is a list of node indices for the use with output type 'node_history'.
    node_values - This is a list with all desired temporal output variables for a 'node_history'.
    It is also possible to generate contour plots of maximal, minimal and time-integrated values. The syntax is then e.g. max[deltaz] integrate[deltaz] min[z_node]. This holds for all kind of values.
    stringdefs - This is a list of STRINGDEF names for the use with output type 'stringdef_history'.
    stringdef_values - This is a list with all desired temporal output variables for a 'stringdef_history'.
    To generate maximal, minimal and time-integrated values use the syntax max[Q], min[Q], and integrate[Q], repectively. This can be used for all possible variables. Note 1: Integrated values makes sense for Q, conc, and Qsed. Note 2: In order to obtain reasonable results your stringdef should be chosen wisely. Therefore we recommend to insert the stringdef as a breakline within your mesh, normal to your expected flow field (e.g. cross section). Note 3: The resulting values of a stringdef_history are interpolated and therefore only approximations. The values have to be interpolated on the hydraulic edges, and in some cases mean values are calculated (e.g. Qsed, u, wse, energy_head).Note 4: stringdef_values Q and Qsed for stringdefs defined at the boundary the output 'boundary_values' is recommended.
    edge_ids - This is a list of node indices for the use with output type 'edge_history'.Every edge is defined by two nodes. The format for an edge is nodeindex1:nodeindex2, e.g. 23:34 Several edges are defined by a list of the described format.
    edge_values - This is a list with all desired temporal output variables for a 'edge_history'. Most output represents the distinct terms of the shallow water equations.
    It is also possible to generate contour plots of maximal, minimal and time-integrated values. The syntax is then e.g. max[depth] integrate[depth] min[depth]. This holds for all kind of values.
    boundary_values - This is a list with all desired temporal output variables over all boundaries.
    It is also possible to generate contour plots of maximal, minimal and time-integrated values. The syntax is then e.g. max[Q] integrate[Q] min[Q]. This holds for all kind of values.
    balance_values - This option produces an output with temporal changes of global properties. Therefore, no index is needed. Only the desired output has to be specified.
    variable - This option sets the default behaviour for the BASEviz visualisation. It can be switched anytime during the runtime, therefore there is usually no need to define this parameter. Possible variables which can be plotted are 'depth', 'wse', 'velocity', 'tau', 'bedload' and 'bedelevation'. By default, the depth is used.
    wse3D - This option sets the default behaviour of the water surface elevation in 3D for the BASEviz visualisation. It can be switched anytime during the runtime, therefore there is usually no need to define this parameter. By default, the 3D wse is set to off.
    vectors - This option sets the default behaviour of the vector visualisation for the BASEviz type. It can be switched anytime during the runtime, therefore there is usually no need to define this parameter. By default, vectors are set to off.
    gridlines - This option sets the default behaviour for the gridlines for the BASEviz visualisation. It can be switched anytime during the runtime, therefore there is usually no need to define this parameter. By default, the gridlines are set to off.
    vectors_scaling_factor - This option sets the default behaviour for the vector scaling of the BASEviz visualisation. It can be switched anytime during the runtime, therefore there is usually no need to define this parameter. If vectors are too small, increase this value. By default, the scaling factor is set to 1.0.
    write_jpeg_image_time - This option determines if the BASEviz visualization shall render JPEG images.If this time is set to a value > 0.0 than each time intervall a JPEG image is created. Please note that the rendering depends on the visualization window. It is therefore recommended to deactive the help (press 'h') and to first maximize the BASEviz-Window and then hide the window. By default, the time to a negative value which means that no images are rendered.
    value_range - This option sets the value range for the BASEviz default variable. if this is undefined, the value range is determined dynamically during the runtime. The range is given by a list of the minimum and maximum value, e.g. ( 0.0 3.65 ). By default, a dynamic value range is used.
    BASEextern - Parameter specifies the name of a defined BASEextern subdomain within the domain. Setting this parameter results in data sending over tcp/ip instead of output to file. This option may be useful for coupling with external programs. You must provide interface at the external program which recieves the send data.
    ids - Write output values only for the given element- or node-ids. By giving a list of id-numbers the output size can be significantly reduced. which is useful in case of sending the data over network (TCP/IP). This option is only used for external coupling if a BASEextern sub-domain is specified.
    threshold_wse - This parameter can be used to set a threshold for the output of the water surface elevation. If no water is present than the water surface elevation is set per default to the bed elevation of the topography. This behaviour can be changed by specifying a threshold for the water surface elevation (e.g. 0.0). If a threshold is given, the water surface elevation at dry locations is set to this threshold value.

    Example

    BASEPLAIN_2D
{
   [...]
   OUTPUT
   {
      console_time_step = 10.0
      SPECIAL_OUTPUT
      {
         type = BASEviz
         variable = depth
         output_time_step = 100.0
         gridlines = off
         vectors = on	
      }
      SPECIAL_OUTPUT
      {
         type = node_centered
         values = ( depth velocity max[wse] )
         output_time_step = 10.0
         format = 2dm
         binary = no
      }
      SPECIAL_OUTPUT
      {
         type = element_centered
         values = ( depth velocity )
         output_time_step = 10.0
         format = tecplot
         binary = yes
      }
      SPECIAL_OUTPUT
      {
         type = element_history
         element_values = ( wse depth tau )
         element_ids = ( 233 432 )
         output_time_step = 10.0
         flush_all_num_steps = 1
         history_one_file = yes
      }
      SPECIAL_OUTPUT
      {
         type = node_history
         node_values = ( grain_size deltaz )
         node_ids = ( 23 45 98 486 )
         output_time_step = 10.0
      }
      SPECIAL_OUTPUT
      {
         type = balance	// only for sediment transport
         balance_values = ( sediment timestep )
         output_time_step = 5.0
      }
   }
}
    VEGETATION
    VEGETATION compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D
    Description: Defines the vegetation specifications for the simulation.
    Inner Blocks: GROUNDWATER
    FEEDBACK
    BIOMASS
    PARAMETER
    INITIAL

    Example

    VEGETATION
{
   GROUNDWATER     {
       [...]
     }
   BIOMASS     {
       [...]
     }
   PARAMETERS     {
       [...]
     }
   FEEDBACKS     {
       [...]
     }
   INITIAL     {
       [...]
     }
}
    GROUNDWATER
    GROUNDWATER compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > VEGETATION
    Description: The GROUNDWATER block for vegetation defines general settings related to the groundwater interpolation.

    Variable type comp. condition units default values
    offset real no - [m] 0 -
    maximum_distance real no - [m] 100 -
    maximum_distance_increase real no - [m] 10 -
    power_distance real no - - 1 -
    minimum_points_within integer no - - 3 -
    time_Zw whitespace separated list of reals yes - - - -

    Block Usage

    This block defines the settings related to the groundwater for vegetation.

    Description of Variables

    offset - Offset, given in [m], of the mean groundwater level (Zw). This parameter can be used to vertically shift the position of Zw obtained by the IDW method.Positive values will rise Zw up, negative values will lower it.
    maximum_distance - Parameter of IDW interpolator: defines the length of the radius in which the algorithm will search for wet elements needed for the interpolation.
    maximum_distance_increase - Parameter of IDW interpolator: if the algorithm will not find any wet elements in the defined radius, it increases such distance by maximum_distance_increase until it will find a correct number of wet elements to interpolate.
    power_distance - Parameter of IDW interpolator: power of the inverse distance used in the method. A linear model can be obtained with power of one.The default value is 1 and must be positive.
    minimum_points_within - Parameter of IDW interpolator: minimum number of elements needed for the interpolation within the defined maximum_distance.
    time_Zw - This requires a list of times [s] at which the algorithm computes the mean groundwater level (Zw).

    Example

    VEGETATION
{
		[...]
		GROUNDWATER
		{
			maximum_distance = 100   
			maximum_distance_increase = 10  
			time_Zw = [0 10 20]
   }
}
    FEEDBACK
    FEEDBACK compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > VEGETATION
    Description: The FEEDBACK block for vegetation defines general settings related to the interactions between hydromorphodynamics and vegetation.

    Variable type comp. condition units default values
    theta_critic_veg real no - - 0.047 -
    theta_critic_grain real no - - 0.047 -
    ks_grain real yes - [m^{1/3}s^{-1}] - -
    ks_veg real yes - [m^{1/3}s^{-1}] - -
    z_uprooting real yes - [m] - -
    z_burial real yes - [m] - -

    Block Usage

    This block defines the settings related to the feedback between hydromorphodynamics and vegetation.

    Description of Variables

    theta_critic_veg - Shields critical parameter due to vegetation. Assumed when the biomass equals its maximum value.
    theta_critic_grain - Shields critical parameter for the grain, in absence of vegetation. Must be equal to the one defined in the MORPHOLOGY block.
    ks_grain - Strikler coefficient for the grain, in absence of vegetation. This is the value used to limit sediment transport due to vegetation as well.
    ks_veg - Strikler coefficient for the vegetation.
    z_uprooting - Soil depth at which uprooting occurs. Plant is removed (B=0) when the cell elevation changes exceed the z_uprooting. This value must be > 0.
    z_burial - Sediment deposition needed to kill vegetation due to burial. Not implemented yet.

    Example

    VEGETATION
{
		[...]
		FEEDBACK
		{
   }
}
    BIOMASS
    BIOMASS compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > VEGETATION
    Description: The BIOMASS block for vegetation defines general settings related to the vegetation biomass.

    Variable type comp. condition units default values
    growth_rate real yes - [s^{-1}] - -
    lambda_1 real yes - [m^{-1}] - -
    lambda_2 real yes - [m^{-1}] - -
    z_0 real yes - [m] - -
    maximum_carrying_capacity real no - - 1 -
    time_veg_growth whitespace separated list of reals yes - - - -

    Block Usage

    This block defines the settings related to the vegetation biomass.

    Description of Variables

    growth_rate - Grow rate for the logistic function. The timestep of vegetation growth is the same of morphological calculations.
    lambda_1 - Parameter for Marani et al. (see Reference Manual) function lambda_1.
    lambda_2 - Parameter for Marani et al. (see Reference Manual) function lambda_2.
    z_0 - Parameter for Marani et al. (see Reference Manual) function z_0. It represents a (relative) distance from the mean groundwater level Zw. Positive values are located above Zw, negative values below it. Important: z_0 reported in the Manual for the Marani's equation refers to Zw+z_0.
    maximum_carrying_capacity - Maximum carrying capacity for the logistic function. To have dimensionless quantities for the biomass, set the maximum carrying capacity to 1 (dafault).
    time_veg_growth - This requires a list of times. Such times define beginning and end of the vegetation growth [ex. (0--->growth-->10 12--->growth--->22 ...)]. Must be at least a list with 2 times.

    Example

    VEGETATION
{
		[...]
		BIOMASS
		{
   }
}
    PARAMETER
    PARAMETER compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > VEGETATION
    Description: The GENERAL settings for the vegetation module.

    Variable type comp. condition units default values
    only_hydro integer no - - 0 -

    Block Usage

    GENERAL settings.

    Description of Variables

    only_hydro - Input code: 1 if no MORPHOLOGY block is activated (if you run hydrodynamic simulations).0 if both HYDRAULICS and MORPHOLOGY blocks are activated.

    Example

    VEGETATION
{
		[...]
		PARAMETER
		{
   }
}
    INITIAL
    INITIAL compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASEPLANE_2D > VEGETATION
    Description: This block defines the inital conditions for the vegetation. The definition of this block is mandatory.

    Variable type comp. condition units default values
    type string yes - - - {continue, index_table}
    file string no used if 'type' = 'continue' - - -
    restart_solution_time real no used if 'type' = 'continue' [s] -1.0 x >= -1
    indexGrow whitespace separated list of integers yes required if 'type' = 'continue' - - -
    index whitespace separated list of integers yes required if 'type' = 'index_table' - - -
    B real yes required if 'type' = 'index_table' - - x >= 0

    Description of Variables

    type - This is the type of initial conditions for vegetation:
    a) 'bare_soil'. This type means that the given mesh file is used as initial condition for the bed topography.
    b) 'continue'. The simulation is restarted from a restart-file obtained by a previous run.
  • index_table: The initial conditions for B can be set manually using the material index technique. The restart solution time must be specified. (The mesh file is loaded and the biomass valuesin the elements are then updated with values of the restart file.
    • file - This is the name of a restart file from a previous simulation with vegetation. This file must be given in the CGNS format.
    restart_solution_time - This time specifies the time at which the solution is read from the file. This parameter is needed because the restart file can contain different solutions at different times. If a negative time is given, than the last available solution is chosen from the restart file. For the given time a solution must exists in the restart file. If you don't have a clue what to enter, than just enter any number, than all available times will be listed for the user to choose from.
    indexGrow - This is a list of integers representing the material indices defined in the computational mesh (.2dm file), where vegetation can grow.
    index - This is a list of integers representing the material indices defined in the computational mesh (.2dm file), where vegetation can grow.
    B - This is a list of values for the vegetation biomass corresponding to the list of material indices.

    Example

    INITIAL
{
   type = continue
   file = Vegetation_Q100.cgns      // restart file
   restart_solution_time = 1000 
}
    BASESUB
    BASESUB compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN
    Description: This block includes all information for a subsurface LBM simulation.
    Inner Blocks: GEOMETRY
    TIMESTEP
    PARAMETER
    INITIAL
    BOUNDARY
    MATERIAL
    SOURCE
    OUTPUT

    Variable type comp. condition units default values
    region_name string yes - - - Chars [a-zA-Z0-9_-] are allowed

    Block Usage

    The main block declaring a subsurface simulation is called BASESUB within the DOMAIN-block. It contains all information about the precise simulation. The GEOMETRY block deals with the structured 3D lattice and the cell sizes. The PARAMETER block allows to set simulation parameters and the selection of the appropriate calculation method. The INITIAL and BOUNDARY blocks are used to set the initial conditions and one or multiple boundary conditions.

    Description of Variables

    region_name - The name of the region has to be specified. It may be used for coupled simulations.

    Example

    DOMAIN
{
   multiregion = something
   BASESUB
   {
      region_name = embankment
      GEOMETRY
      {
         [...]
      }
      TIMESTEP
      {
         [...]
      }
      PARAMETER
      {
         [...]
      }
      INITIAL
      {
         [...]
      }
      BOUNDARY
      {
         [...]
      }
      MATERIAL
      {
         [...]
      }
      SOURCE
      {
         [...]
      }
      OUTPUT
      {
         [...]
      }
   }
}
    GEOMETRY
    GEOMETRY compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASESUB
    Description: Defines the cubic mesh for this 3D-simulation. The cube dimensions and coordinates have to be specified.
    Inner Blocks: ZONE

    Variable type comp. condition units default values
    ref_coordinates whitespace separated list of reals yes - - - -
    base_vector_i whitespace separated list of reals yes - - - -
    base_vector_j whitespace separated list of reals yes - - - -
    cell_size real yes - [m] - -
    no_cells_i integer yes - [-] - -
    no_cells_j integer yes - [-] - -
    no_cells_k integer yes - [-] - -

    Block Usage

    The GEOMETRY block is used for 3D-simulations to define 3D lattice for the LBM simulation Two .2dm meshes can be specified which define a inner region, where the simulation takes place. The outer regions are set inactive and are not used for the simulation.

    Description of Variables

    ref_coordinates - Reference point of lower, left edge of groundwater lattice. Coordinates (xref, yref, zref) are expected.
    base_vector_i - Base vector in i-direction of sub-surface Lattice. Coordinates (i_x, i_y, i_z) are expected.
    base_vector_j - Base vector in i-direction of sub-surface Lattice. Coordinates (j_x, j_y, j_z) are expected.
    cell_size - Size (length) of cubic cells
    no_cells_i - Number of cells of domain in i-direction
    no_cells_j - Number of cells of domain in j-direction
    no_cells_k - Number of cells of domain in vertical k-direction

    Example

    BASESUB
{
   region_name = dike_bddy
   GEOMETRY
   {
      cell_size = 1.0
      ref_coordinates = (0.0 0.0 0.0)
      base_vector_i = (1.0 0.0 0.0)
      base_vector_j = (0.0 1.0 0.0)
  	 cell_size = 1.0
   }
   [...]
}
    ZONE
    ZONE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASESUB > GEOMETRY
    Description: Defines a 3-D zone within the lattice of the model.

    Variable type comp. condition units default values
    name string yes - - - -
    type string yes - - - {meshes, block, default}
    inactive string no - - yes {yes, no}
    ymin real yes required if 'type' = 'block' - - -
    ymax real yes required if 'type' = 'block' - - -
    x_values whitespace separated list of reals yes required if 'type' = 'block' - - -
    z_values whitespace separated list of reals yes required if 'type' = 'block' - - -
    mesh string yes required if 'type' = 'meshes' - - -
    mesh_direction string yes required if 'type' = 'meshes' - above {above, below}
    material_index whitespace separated list of integers yes required if 'type' = 'meshes' - - -

    Block Usage

    The ZONE block is used to define zones within the 3-D lattice with specific material propertiese. The cells in the zone can also be de-activated, so that they are excluded from the simulation. A default-zone contains all cells of the mesh, unless other zones are specified. By block-definitions or by using .2dm surface meshes one can define the 3-D extends of the zone.

    Description of Variables

    name - Name of the zone. A zone is a part of the 3-D mesh with specific material properties.
    type - The type of the zone definition. Three types are possible:
    inactive - This parameter defines if the cells within the zone shall be set to 'inactive'-state. If it is set to 'yes' no calculations are performed within this zone.
    ymin - Y-coordinate, which defines the extent of the block in y-direction. This is the minimum y-coordinate.
    ymax - Y-coordinate, which defines the extent of the block in y-direction. This is the maximum y-coordinate.
    x_values - X-values of a polygon, which defines the block outline in the 'xz' plane.
    z_values - Z-values of a polygon, which defines the block outline in the 'xz' plane.
    mesh - Filename of the .2dm gridfile, which describes are surface through the 3-D mesh. All cells below or above the surface can be associated with the zone.
    mesh_direction - This parameter specifies if the cells 'above' or 'below' the given 'mesh' (.2dm-file) are associtated with this zone. Setting this paramter to 'below', leads to the association of all cells underlying the mesh to the zone.
    material_index - From the given mesh, used for the zone definition, only the cells are used which are within the given range of material index values.

    Example

    BASESUB
{
   region_name = dyke
   GEOMETRY
   {
		  ZONE
       {
         name = zone1
         type = default
   //per default, all parts of the mesh are associated with zone1
       }
       ZONE
       {
         name = zone1
         type = meshes
         mesh = upper.2dm
         mesh_direction = above
 		inactive = yes
       }
   }
   [...]
}
    TIMESTEP
    TIMESTEP compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASESUB
    Description: The TIMESTEP block is used to specify numerical parameters related to the time and timestep for the simulation.

    Variable type comp. condition units default values
    time_step real yes - [s] - x > 0
    total_run_time real yes - [s] - x > 0
    start_time real no - [s] -1.0 -

    Block Usage

    The only thing that needs to be defined is the total_run_time and the time step size. The restart time is an optional parameter. Changing these Parameters either leads to faster and more stable simulations or it may make the simulation collapse in the worst case.

    Description of Variables

    time_step - Time step size of the simulation. Large time step sizes will lead to faster simulations, but can decrease the accuracy and increase the diffusion. Try to find the smallest numbers for which the simulation is stable in order to get the most accurate results.
    total_run_time - This parameter needs to be specified by the user. When the given time value is reached, the simulation stops all output is written. If the simulation continues from an earlier state, the starting time will be different from zero and the effectively computed time is the difference between the total_run_time and the starting time.
    start_time - This parameter defines the time (in seconds) when the simulation starts. If you want the simulation to start at t = x s, then set this value to x. If the value is negative AND a restart of an old simulation is made, then the end-time of the old simulation is set as start time.

    Example

    BASEsub
{
   [...]
   TIMESTEP
   {
      time_step = 1.0
      total_run_time = 1000
      restart_time = 0.0
   }
   [...]
}
    PARAMETER
    PARAMETER compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASESUB
    Description: The PARAMETER block for sub-surface LBM simulations defining simulation parameters as time step, total run time, etc.

    Variable type comp. condition units default values
    type string no - - theta {theta, mixed}
    cs_factor real no - [-] 3.0 x > 0
    theta_s real no - [-] 1.0 -
    theta_r real no - [-] 0.0 -
    activate_cells string no - - yes {yes, no}

    Block Usage

    Changing the simulation parameters can either lead to more stable or simulations or the break down of the simulation.Significant parameters controlling the stability of the method are the time step and the cs-factor.

    Description of Variables

    type - Type of LBM approach, either effective saturation formulation 'theta' or 'mixed.Use the 'theta' formulation for homogeneous soils, because it is more stable. Use the 'mixed' formulation for heterogeneous soils, but be cautios of instabilities.
    cs_factor - A free chosable, dimensionless factor influencing the simulation stability. Larger values may lead to more stable but less accurate simulations.
    theta_s - Maximum water content of the soil, equals the soil porosity.
    theta_r - Residual water content of the soil.
    activate_cells - This parameter determines if cells may be activated during simulations, if material is deposited. It is only used for coupled simulations with BASEplane and sediment transport.

    Example

    BASESUB
{
   [...]
   PARAMETER
   {
      cs_factor = 100.0
      theta_s = 0.49
      theta_r = 0.05
   }
   [...]
}
    INITIAL
    INITIAL compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASESUB
    Description: Defines initial conditions for subsurface LBM simulations. Initial conditions can either be constant values / hydrostatic distribution, or a restart from an old simulation result.

    Variable type comp. condition units default values
    type string yes - - - {theta, pressure, hydrostatic, continue}
    file string yes required if 'type' = 'continue' - restart_sub.sim -
    restart_start_time real no used if 'type' = 'continue' [s] 0.0 x >= -1
    value real yes used if 'type' = 'theta' or 'pressure' or 'hydrostatic' [-/m] - -

    Block Usage

    There are different possibilities to define the initial condition:
    a) constant values (moisture content or pore pressure)
    b) hydrostatic pressure distribution
    c) continuing from an old simulation (hot start) The keywords 'theta', 'pressure', 'hydrostatic' or 'continue' indicate which type of initial condition is defined.
    Hot start from an old simulation needs the continue-file from the old simulation.

    Description of Variables

    type -
    file - This is the filename of a continue-file. This file must be given in ASCII format.
    restart_start_time - This parameter allows to define a start time for the restart of the simulation. The simulation is started beginning from the specified time.
    value - Value for initial condition. Can either be a saturation [-] or a pressure head [m], depending upon what is set as 'type'.

    Example

    BASESUB
{
   [...]
   INITIAL
   {
      type = theta
      value = 0.2
      restart_start_time = 0.0
   }
   [...]
}
    BOUNDARY
    BOUNDARY compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASESUB
    Description: Defines boundary conditions for subsurface model.

    Variable type comp. condition units default values
    type string yes - - - {bounce_back, pressure, saturation, hydrostatic, zero_gradient, seepage, coupling_baseplane}
    face string yes required if 'type' = 'bounce_back' or 'pressure' or 'saturation' or 'hydrostatic' or 'zero_gradient' or 'seepage' - - {west, east, north, south, back, front}
    from_to1 whitespace separated list of reals yes required if 'type' = 'bounce_back' or 'pressure' or 'saturation' or 'hydrostatic' or 'zero_gradient' or 'seepage' - - -
    from_to2 whitespace separated list of reals yes required if 'type' = 'bounce_back' or 'pressure' or 'saturation' or 'hydrostatic' or 'zero_gradient' or 'seepage' - - -
    file string no - - - -
    depth_min real no used if 'type' = 'coupling_baseplane' [-] 0.01 -
    z_reduction real no used if 'type' = 'coupling_baseplane' [-] 0.0 -
    material_index whitespace separated list of integers no used if 'type' = 'coupling_baseplane' - - -
    name string yes required if 'type' = 'coupling_baseplane' - - -

    Block Usage

    If no boundary condition is specified for part of or the whole boundary, a bounce-back boundary is assumed. For every different boundary condition, a new block BOUNDARY has to be used.

    Description of Variables

    type -
    face - Defines the face of the cubic mesh, where the boundary shall be applied.
    from_to1 - Specification of boundary region which is given as rectangle. Coordinate range at axis 1. Sequence of coordinates = xz, yz, xy.
    from_to2 - Specification of boundary region which is given as rectangle. Coordinate range at axis 2. Sequence of coordinates = xz, yz, xy.
    file - Filename of the file containing the time series
    depth_min - Minimum depth for the baseplane sub-domain which is used for the determination of the hydrostatic boundary conditions.
    material_index - Material indices of 2-D elements which shall be used for coupling with the subsurface model.
    name - Unique name of boundary needed for coupling.

    Example

    HYDRAULICS
{
   BOUNDARY
   {
      type = pressure
      face = west
		 from_to1 = ( 0.0 1.0 )
 	 from_to2 = ( 0.0 1.0 )
      file = pressure_in_time.txt
   }
   [...]
}
    MATERIAL
    MATERIAL compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASESUB
    Description: This block defines the characteristics of the material. It contains only inner blocks.
    Inner Blocks: SOIL_DEF

    Block Usage

    The SOIL_DEF block defines all different zones with different soils.

    Example

    MATERIAL
{
   SOIL
   {
   }
}
    SOIL_DEF
    SOIL_DEF compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASESUB > MATERIAL
    Description: This block defines the structure of the soil zone and its material properties.
    Inner Blocks: ZONE
    RETENTION_MODEL

    Variable type comp. condition units default values
    kf real yes - [m/s] - x >= 0
    zone string no - - - -

    Block Usage

    The 3D lattice can consists of one or several soil zones. Typically, each soil zone can have its own material properites and conductivity. 2D surface meshes (*.2dm) can be used to define the 3D zone region, lying in between these meshes.

    Description of Variables

    kf - The hydraulic conductivity of the soil [m/s].
    zone - Name of the soil zone, where the kf-value and the retention model are applied to.

    Example

    MATERIAL
{
   SOIL_DEF
   {
      zone = zone1 
      kf = 0.00001 
      RETENTION_MODEL
      {
         [...]
      }
   }
   [...]
}
    ZONE
    ZONE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASESUB > MATERIAL > SOIL_DEF
    Description: Defines a 3-D zone within the lattice of the model.

    Variable type comp. condition units default values
    name string yes - - - -
    type string yes - - - {meshes, block, default}
    inactive string no - - yes {yes, no}
    ymin real yes required if 'type' = 'block' - - -
    ymax real yes required if 'type' = 'block' - - -
    x_values whitespace separated list of reals yes required if 'type' = 'block' - - -
    z_values whitespace separated list of reals yes required if 'type' = 'block' - - -
    mesh string yes required if 'type' = 'meshes' - - -
    mesh_direction string yes required if 'type' = 'meshes' - above {above, below}
    material_index whitespace separated list of integers yes required if 'type' = 'meshes' - - -

    Block Usage

    The ZONE block is used to define zones within the 3-D lattice with specific material propertiese. The cells in the zone can also be de-activated, so that they are excluded from the simulation. A default-zone contains all cells of the mesh, unless other zones are specified. By block-definitions or by using .2dm surface meshes one can define the 3-D extends of the zone.

    Description of Variables

    name - Name of the zone. A zone is a part of the 3-D mesh with specific material properties.
    type - The type of the zone definition. Three types are possible:
    inactive - This parameter defines if the cells within the zone shall be set to 'inactive'-state. If it is set to 'yes' no calculations are performed within this zone.
    ymin - Y-coordinate, which defines the extent of the block in y-direction. This is the minimum y-coordinate.
    ymax - Y-coordinate, which defines the extent of the block in y-direction. This is the maximum y-coordinate.
    x_values - X-values of a polygon, which defines the block outline in the 'xz' plane.
    z_values - Z-values of a polygon, which defines the block outline in the 'xz' plane.
    mesh - Filename of the .2dm gridfile, which describes are surface through the 3-D mesh. All cells below or above the surface can be associated with the zone.
    mesh_direction - This parameter specifies if the cells 'above' or 'below' the given 'mesh' (.2dm-file) are associtated with this zone. Setting this paramter to 'below', leads to the association of all cells underlying the mesh to the zone.
    material_index - From the given mesh, used for the zone definition, only the cells are used which are within the given range of material index values.

    Example

    BASESUB
{
   region_name = dyke
   GEOMETRY
   {
		  ZONE
       {
         name = zone1
         type = default
   //per default, all parts of the mesh are associated with zone1
       }
       ZONE
       {
         name = zone1
         type = meshes
         mesh = upper.2dm
         mesh_direction = above
 		inactive = yes
       }
   }
   [...]
}
    RETENTION_MODEL
    RETENTION_MODEL compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASESUB > MATERIAL > SOIL_DEF
    Description: This block defines soil retention model and its parameters needed to asses the apparent cohesion effects of the soil.

    Variable type comp. condition units default values
    type string yes - - - {van_genuchten, brooks_corey}
    lambda real yes required if 'type' = 'brooks_corey' [-] - x > 0
    l real yes required if 'type' = 'brooks_corey' [-] - x > 0
    n real yes required if 'type' = 'van_genuchten' [-] - x > 0
    alpha real yes required if 'type' = 'van_genuchten' [1/m] - x > 0
    hs real no - [m] -0.001 x <= 0

    Block Usage

    For the description of the soil properties and pore-distributions one can define empirical relationships. These empirical formulas are needed to describe the relationship between the water saturation and the capillary pressure. This relationship is needed to assess effects of apparent cohesion in the numerical model.

    Description of Variables

    type - Two different analytical models to describe the retention curve can be specified. These are a modified version of the 'van Genuchten' model and the 'Brooks-Corey' model. At the moment the use of the van Genuchten model is recommended.
    lambda - Dimensionless soil parameter used for the Brooks-Corey model.
    l - Dimensionless soil parameter used for the Brooks-Corey model.
    n - Dimensionless soil parameter for the van Genuchten model.
    alpha - Dimensionless soil parameter for the van Genuchten model.
    hs - This parameter specifies the air-entry pressure head of the soil. It characterizes the negative pressure which is needed to drain the largest pores of the soil. It therefore can be seen as description of the largest pores of the soil and as the threshold describing the transition from the saturated zone to the unsaturated zone.

    Example

    BEDMATERIAL
{
   RETENTION_MODEL
   {
   type = van_genuchten
   hs = 0.001
   alpha = 6
   n = 2.1
   }
   [...]
}

BEDMATERIAL
{
   RETENTION_MODEL
   {
   type = brooks_corey
   lambda = 2
   }
   [...]
}
    SOURCE
    SOURCE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASESUB
    Description: The SOURCE block is a container for EXTERNAL_SOURCE blocks. They are used for additional sources or sinks, sometimes used instead of flux boundary conditions.
    Inner Blocks: EXTERNAL_SOURCE

    Example

    BASESUB
{
   [...]
   SOURCE
   {
      EXTERNAL_SOURCE
      {
         [...]
      }
      EXTERNAL_SOURCE
      {
         [...]
      }
   }
   [...]
}
    EXTERNAL_SOURCE
    EXTERNAL_SOURCE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASESUB > SOURCE
    Description: The external source block is used for additional sources to model inflow or outtake of water without using a boundary condition.

    Variable type comp. condition units default values
    value real yes - [m2/s] - x >= 0
    x_values whitespace separated list of reals yes - - - -
    y_values whitespace separated list of reals yes - - - -

    Block Usage

    The available source type 'source_discharge' acts as a sink when delivered with negative values in the file. All external sources act on one or more computational cells whose element number(s) have to be listed in an element_ids list. The specified source will then be partitioned among the corresponding cells weighted with their areas. For each different external source, a new block has to be created. The input format for the file is of file type BC: two columns with time and corresponding source discharge. To couple subdomains via discharge source, please use a coupling_discharge_source.In this case no file has to be given.

    Description of Variables

    value -

    Example

    SOURCE
{
   [...]
   EXTERNAL_SOURCE
   {
      value = 0.05
      xvalues = ( 0.0 1.0 ) 
      yvalues = ( 0.0 1.0)  
   }
}
    OUTPUT
    OUTPUT compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASESUB
    Description: This block contains all sub-blocks which define the desired output data.
    Inner Blocks: SPECIAL_OUTPUT

    Variable type comp. condition units default values
    output_time_step real yes - [s] - x >= 0
    console_time_step real yes - [s] - x >= 0
    restart_time_step real no - [s] 1E32 x >= 0

    Block Usage

    A numerical simulation produces a lot of output data. Most of the times, not all output is of interest to the user. Writing the output to a hard disk costs time that better be used for calculations. Therefore, the user has to define explicitely what output shall be written.
    ATTENTION! If no special output is defined in the output block, the simulation will do all the calculations but there will be NO output of these results!
    Every desired output has to be defined in an own SPECIAL_OUTPUT block. The usage is described at the SPECIAL_OUTPUT.
    The OUTPU block itself has only two parameters to set general timesteps for console output and the output of restart files.

    Description of Variables

    output_time_step - This parameter defines the time interval after which a new restart-file shall be written. Restart files can get a certain time to be written, therefore it makes sense to choose a sufficiently large timestep to avoid slowing down the calculations.
    console_time_step - The console time step defines the time interval after which a console output during the simulation is displayed. Setting it to 0 may slow down the simulation dramatically.
    restart_time_step - The restart time defines the time which a new solution is written to the restart file. Setting it to small values may result in very large restart files! If the value is not set, than it is set per default to a very large number (1E32). This implies that only the last time step of the simulation is written to the restart file.

    Example

    BASESUB
{
   [...]
   OUTPUT
   {
      output_time_step = 10.0
      console_time_step = 1.0
   }
   [...]
}
    SPECIAL_OUTPUT
    SPECIAL_OUTPUT compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASESUB > OUTPUT
    Description: The Special Output block defines a desired output of a simulation.

    Variable type comp. condition units default values
    type string yes - - - {cut_plane, cut_line, seepage_line}
    output_time_step real yes - [s] - x >= 0
    values whitespace separated list of strings yes required if 'type' = 'cut_plane' or 'cut_line' - - valid entries are {'hlb', 'theta', 'lambda', 'velocity_x', 'velocity_y', 'velocity_total', 'velocity'}
    format string yes required if 'type' = 'cut_plane' or 'cut_line' or 'seepage_line' - - {ascii, tecplot, qgis}
    cut_plane string yes used if 'type' = 'cut_plane' or 'cut_line' or 'seepage_line' - - {xz, yz, xy}
    cut_plane_position real yes used if 'type' = 'cut_plane' or 'cut_line' or 'seepage_line' - - -
    cut_line_position_z real no used if 'type' = 'cut_line' - - -
    cut_line_position_y real no used if 'type' = 'cut_line' - - -
    cut_line_position_x real no used if 'type' = 'cut_line' - - -

    Block Usage

    Every distinct output needs a new SPECIAL_OUTPUT block. For every output, an own output time step can be defined.

    Description of Variables

    type - There are different types for the output. Dependent on the choice, further parameters may be needed.
    output_time_step - This parameter defines the interval in [s] for which the output shall be written. Choosing '0' produces an output at every timestep. Frequent output may slow down the simulation dramatically!
    values - These are the variables which can be written either on the nodes or on the element centers of the grid. It is indicated in the following list whether the data is a scalar or a vector and where it is calculated during the simulation.
    format - This option provides a choice between different formats for the output of salar or vector data on the mehs.
    cut_plane - This option defines the orientation of the plane which is 'cut' through the 3D mesh.It can be chosen between the x-z plane ('xz'), the y-z plane ('yz') and the x-y plane ('xy').(For type = seepage_line, no x-y plane output is supported)
    cut_plane_position - This option defines at which location along the corresponding axis, the cut shall be places.
    cut_line_position_z - This parameter defines whether an additional cut at the given z-location shall be made. Works only with type 'cut_plane' and only for ASCII-scalar-output.
    cut_line_position_y - This parameter defines whether an additional cut at the given z-location shall be made. Works only with type 'cut_plane' and only for ASCII-scalar-output.
    cut_line_position_x - This parameter defines whether an additional cut at the given z-location shall be made. Works only with type 'cut_plane' and only for ASCII-scalar-output.

    Example

    BASE_SUB
{
   [...]
   OUTPUT
   {
      output_time_step = 10.0
      console_time_step = 10.0
      SPECIAL_OUTPUT
      {
         type = cut_plane
         values = (hlb theta)
         output_time_step = 100.0
         cut_plane = xz
         cut_position = 20	
      }
      SPECIAL_OUTPUT
      {
         type = seepage_line
         output_time_step = 10.0
         cut_plane = xz
         cut_position = 20	
      }
   }
}
    BASE_EXTERN
    BASE_EXTERN compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN
    Description: This block includes all information for a 2D simulation.
    Inner Blocks: BOUNDARY

    Variable type comp. condition units default values
    region_name string yes - - - Chars [a-zA-Z0-9_-] are allowed
    fixed_time_step string no - - on Chars [a-zA-Z0-9_-] are allowed, {off, on}
    port integer no - - - -
    ip string no - - - -

    Block Usage

    The main block declaring an external sub-domain is called BASE_EXTERN within the DOMAIN-block. It contains all information about needed for the coupling with an external program. Parameters must be specified for the TCP/IP connection. Boundaries can be defined which then can be coupled with corresponding boundaries of the BASEplane oder BASEchain sub-domains. Per default, BASEMENT runs as server application and must be started first and waits for the incoming request. If the connecting succeeds, the programs start running and BASEMENT will send data continuously over this connection. The external program must take care to read the data from the stream and extract the information from the XML data packets. Some basic operations: 1.) Receive data from BASEMENT To receive data from BASEMENT an external sub-domain must be defined in the command file. If no ip-adress is selected and no port is given, than the 'localhost' and the default port 5000 are chosen. In the BASEMENT sub-domain a SPECIAL_OUTPUT block must be specified and connected with the external boundary using the parameter 'BASEextern = ...'.All output data, assigned to this external sub-domain, will be send over a socket to the specified address and can be read from the socket stream. 2.) Send data to BASEMENT Again an external sub-domain BASE_EXTERN must be defined in the command file. This external sub-domain must have at least one boundary condition defined, which must be connected with a boundary condition of another BASEMENT sub-domain. This requires a COUPLING block to be defined. The external model must wrap its data into data packets in XML-format (see UI manual) and send the data over the socket stream. BASEMENT reads the data and organizes the synchronization, i.e. it waits until new data is available. Please be aware that the external coupling feature is in early experimental stage!

    Description of Variables

    region_name - The name of the external region has to be specified. This name is needed identify the external sub-domain in the coupling process and for the output over TCP/IP.
    fixed_time_step - Enforce a fixed time step for the BASEextern subdomain within the local-time-stepping algorithm.
    port - This parameters represents the port number of the external program which shall be coupled with Basement. If Basement runs as server application (default) no port number must be specified, else it is obligatory!.
    ip - This parameter represents the ip-address of the external program which shall be coupled with Basement. If Basement runs as server application (default) no ip-adress number must be specified, else it is obligatory!.

    Example

    BASE_EXTERN
{
   region_name = rainfall_runoff
   BOUNDARY
   {
      name = external_boundary
      type = discharge
   }
}
    BOUNDARY
    BOUNDARY compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > BASE_EXTERN
    Description: Defines boundary conditions for BASEextern subdomain.

    Variable type comp. condition units default values
    name string no - - - Chars [a-zA-Z0-9_-] are allowed
    type string yes - - - {discharge}

    Block Usage

    The implementation of a boundary condition requires the specification of the type of boundary condition. For example, a water outflow of a rainfall-runoff model be specified here as an 'discharge' boundary. This boundary must be named and can be coupled with other boundaries of other sub-domains in the coupling process.For every different boundary condition, a new block BOUNDARY has to be used.

    Description of Variables

    name - Every boundary condition may be given a name which can be used further for coupling.
    type - At the moment only a discharge boundary is possible, but special and more complex boundary conditions may be implemented.

    Example

    BOUNDARY
{
   type = discharge
   name = external_inflow 
}
    COUPLINGS
    COUPLINGS compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN
    Description: This block includes all information for the coupling of two or more sub-domains.
    Inner Blocks: PARAMETER
    COUPLING
    COUPLING_LATERAL

    Block Usage

    The main block declaring coupled simulations of two or more sub-domains is called COUPLINGS within the DOMAIN-block. It contains all information about the coupling mechanism and procedures. The usage of couplings requires at least two sub-domains to be defined within the DOMAIN. All COUPLING-blocks between the sub-domains have to be defined within this block. Alternative, for lateral 1-D / 2-D couplings COUPLING_LATERAL blocks may be defined.

    Example

    DOMAIN
{
   multiregion = Rhein
   PHYSICAL_PROPERTIES
   {
      [...]
   }
   // definition of sub-domains
   BASECHAIN_1D
   {
      [...]
   }
   BASEPLANE_2D
   {
      [...]
   }
   // definition of couplings
   COUPLINGS
   {
      PARAMETER
      {
         [...]
      }
      COUPLING
      {
         [...]
      }
      COUPLING_LATERAL
      {
         [...]
      }
   }
}
    PARAMETER
    PARAMETER compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > COUPLINGS
    Description: The PARAMETER block for the couplings contains general settings dealing with coupling mechanisms.

    Variable type comp. condition units default values
    max_time_level string no - - 32 {1, 2, 4, 8, 16, 32}
    factor_time_step_reduction real no - - 1.0 0 <= x <= 1
    server string no - - yes {yes, no}
    ip_address string no used if 'server' = 'yes' - localhost -
    port integer no used if 'server' = 'yes' - 5000 -
    max_buffer integer no - - 2000 -
    packet_size integer no - - 1000 -
    log_network string no - - off {on, off}

    Description of Variables

    max_time_level - This parameter sets the maximum time level of the sub-domains in the local-time-stepping algorithm. If it is chosen to 1 than all sub-domains run with the same minimum time step size. Values larger than 1 allow the sub-domains to have differt time step sizes, which can increase the efficiency of the simulation. Possible values are [1,2,4,8,16,32].
    factor_time_step_reduction - Using the local-time-stepping algorithm, the CFL criteria is not strictly guaranteed if the flow conditions change abruptly. Therefore a general reduction of the time step size can be set, to prevent violations of the CFL criteria and to prevent oscillations in the coupled simulations.
    server - If Basement is coupled with external programs over tcp&/ip it must be specified if Basement runs as server- oder client-application. Per default Basement runs as a server-application.
    ip_address - IP-Address on which Basement runs as a server. If the external coupling runs on a common pc this is typically 'localhost'.
    port - Port number used for coupling over tcp/ip with external programs. If Basement runs as server-application this parameter must be set and all data from external programs must be send to this port-number.
    max_buffer - Maximum buffer specifying maximum length of send char array. If very much data must be send over network, you probably need to increase this value.
    packet_size - When data is send over tcp/ip the data must be split in several packets. This value is only a recommendation but must not actually be used by the OS. Usually this parameter has not to be changed. It must be smaller than 'max_buffer'.
    log_network - If Basement is coupled with external programs over tcp&/ip all sent and recieved data can be logged into a file. Per default the logging is set 'off' and it should be turned on only for debugging.

    Example

    COUPLINGS
{
   PARAMETER
   {
      max_time_level = 1.0  // [1,2,4,8,16,32]
      factor_time_step_reduction = 0.8
   }
   COUPLING
   {
      [...]
   }
   [...]
}
    COUPLING
    COUPLING compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > COUPLINGS
    Description: Defines a coupling type which connects two or three sub-domains via their boundary conditions or external sources.
    Inner Blocks: HYDRAULICS
    BEDLOAD
    SUSPENSION
    SUBSURFACE

    Variable type comp. condition units default values
    type string yes - - - {sequential, junction, bifurcation, riemann, confluence_wse, external}
    upstream_subdomain string yes required if 'type' = 'sequential' or 'bifurcation' or 'riemann' - - -
    downstream_subdomain string yes required if 'type' = 'sequential' or 'junction' or 'riemann' or 'confluence_wse' - - -
    two_way_coupling boolean no used if 'type' = 'sequential' or 'junction' or 'split' - no {no, yes}
    average_steps integer no - - 1 -
    print_series boolean no - - no {no, yes}
    upstream_subdomain1 string yes required if 'type' = 'junction' or 'confluence_wse' - - -
    upstream_subdomain2 string yes required if 'type' = 'junction' or 'confluence_wse' - - -
    downstream_subdomain1 string yes required if 'type' = 'bifurcation' - - -
    downstream_subdomain2 string yes required if 'type' = 'bifurcation' - - -
    factor_bifurcation real yes required if 'type' = 'bifurcation' - - 0 <= x <= 1
    momentum_factor_up real yes required if 'type' = 'riemann' - 1.0 -
    espilon real no - - 1E-6 -
    momentum_factor_down real yes required if 'type' = 'riemann' - 1.0 -
    external_subdomain string yes required if 'type' = 'external' - - -
    basement_subdomain string yes required if 'type' = 'external' - - -
    iter_exchange integer yes required if 'type' = 'external' [-] 1 -
    tau real no used if 'type' = 'confluence_wse' [s] 10 -
    check string yes required if 'two_way_coupling' = 'yes' - yes -

    Block Usage

    For every coupling between sub-domains a new COUPLING block has to be defined. Two sub-domains may also have multiple couplings defined (e.g. in case of multiple boundary conditions). Within the COUPLING block some specifications of the coupling type can be made and it defines if the coupling shall comprise only hydraulics or also sediment transport.

    Description of Variables

    type - type of the coupling
    upstream_subdomain - upstream region name
    downstream_subdomain - downstream region name
    two_way_coupling - defines if WSE is handed over to upstream sub-domain
    average_steps - exchanged discharges are averaged over this number of previous time steps (damps oscillations)
    print_series - print time series of exchanged values of the coupled boundaries
    upstream_subdomain1 - upstream region name
    upstream_subdomain2 - upstream region name
    downstream_subdomain1 - downstream region name
    downstream_subdomain2 - downstream region name
    factor_bifurcation - defines the fraction of the exchanged values which receives the downstream_subdomain1
    momentum_factor_up - The exchanged momentum between the subdomains is multiplied with this factor.
    espilon - Internal parameter, please do not change.
    momentum_factor_down - The exchanged momentum between the subdomains is multiplied with this factor.
    external_subdomain - Name of BASEextern subdomain, representing the external program, or different module (sub-surface flow model), which shall be used for coupling with BASEMENT.
    basement_subdomain - Name of the BASEMENT subdomain which shall be coupled with a BASEextern subdomain or different module (sub-surface flow model).
    iter_exchange - Number of iterations after which data is exchanged with BASEextern-subdomain or different module (sub-surface flow model).
    tau - Time [s] which is needed to adjust water level of subdomain to water level at junction. The larger the value the more damped is the behaviour.
    check - The program generally checks if the upstream sub-domains are ahead in time before the downstream sub-domains can be executed. However, this check can become problematic in case of 2way coupling if the sub-domains form a 'short circuit' or a connected in a complex way. In such situations it may happen that this check get stuck in an infinite loop. It is possible for the user to de-activate this check for a coupling by setting this parameter to 'no'. Be aware that this is dangerous and may lead to program crashes or dead-locks in some situations.

    Example

    //Example sequential coupling:
COUPLINGS
   {
   PARAMETER
   {
      [...]
   }
   COUPLING
   {
      type = sequential
      upstream_subdomain = regionA
      downstream_subdomain = regionB
      two_way_coupling = off  // no influence from downstream
      average_steps = 3  // average exchanged Q over 3 time steps
      print_series = no
      HYDRAULICS
      {
         [...]
      }
      BEDLOAD
      {
         [...]
      }
      SUSPENSION
      {
         [...]
      }
   }
   [...]
}

//Example junction coupling:
COUPLINGS
{
   COUPLING
   {
      type = junction
      upstream_subdomain1 = regionA
      upstream_subdomain2 = regionB
      downstream_subdomain = regionC
      two_way_coupling = off  // no influence from downstream
      HYDRAULICS
      {
         [...]
      }
      BEDLOAD
      {
         [...]
      }
      SUSPENSION
      {
         [...]
      }
   }
   [...]

//Example coupling with external program:
COUPLINGS
{
    COUPLING
    {
      type = external      external_subdomain = BASEexternSubdomain
      basement_subdomain = BASEMENTSubdomain
      HYDRAULICS
      {
        [...]
      }
}
   [...]
    HYDRAULICS
    HYDRAULICS compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > COUPLINGS > COUPLING
    Description: Defines the interfaces of a coupling. Two or three coupling interfaces (=boundaries or external sources) must be specified by which the coupling takes places.

    Variable type comp. condition units default values
    upstream_interface string no - - - -
    downstream_interface string no - - - -
    upstream_interface1 string no - - - -
    upstream_interface2 string no - - - -
    downstream_interface1 string no - - - -
    downstream_interface2 string no - - - -
    external_interface string no - - - -
    basement_interface string no - - - -

    Description of Variables

    upstream_interface - name of upstream boundary/source
    downstream_interface - name of downstream boundary/source
    upstream_interface1 - name of upstream boundary/source 1, Only needed for 'confluence_wse' or 'junction' coupling.
    upstream_interface2 - name of upstream boundary/source 2, Only needed for 'confluence_wse' or 'junction' coupling.
    downstream_interface1 - name of downstream boundary/source 1, Only needed for 'bifurcation' coupling.
    downstream_interface2 - name of downstream boundary/source 2, Only needed for 'bifurcation' coupling.
    external_interface - name of interface of the BASEextern subodmain or different model (sub-surface model). This 'external_interface' does not take part in the local-time-stepping algorithm (lts). Only needed for 'external' coupling.
    basement_interface - name of interface of the BASEMENT subdomain. For example, use this interface for coupling with external programs or different model (sub-surface model). Only needed for 'external' coupling.

    Example

    COUPLINGS
{
   COUPLING
   {
      type = sequential
      upstream_subdomain = regionA
      downstream_subdomain = regionB
      HYDRAULICS
      {
         upstream_interface = weirA
         downstream_interface = hydrographB
      }
   }
}
    BEDLOAD
    BEDLOAD compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > COUPLINGS > COUPLING
    Description: Defines the interfaces of a coupling. Two or three coupling interfaces (=boundaries or external sources) must be specified by which the coupling takes places.

    Variable type comp. condition units default values
    upstream_interface string no - - - -
    downstream_interface string no - - - -
    upstream_interface1 string no - - - -
    upstream_interface2 string no - - - -
    downstream_interface1 string no - - - -
    downstream_interface2 string no - - - -
    external_interface string no - - - -
    basement_interface string no - - - -

    Description of Variables

    upstream_interface - name of upstream boundary/source
    downstream_interface - name of downstream boundary/source
    upstream_interface1 - name of upstream boundary/source 1, Only needed for 'confluence_wse' or 'junction' coupling.
    upstream_interface2 - name of upstream boundary/source 2, Only needed for 'confluence_wse' or 'junction' coupling.
    downstream_interface1 - name of downstream boundary/source 1, Only needed for 'bifurcation' coupling.
    downstream_interface2 - name of downstream boundary/source 2, Only needed for 'bifurcation' coupling.
    external_interface - name of interface of the BASEextern subodmain or different model (sub-surface model). This 'external_interface' does not take part in the local-time-stepping algorithm (lts). Only needed for 'external' coupling.
    basement_interface - name of interface of the BASEMENT subdomain. For example, use this interface for coupling with external programs or different model (sub-surface model). Only needed for 'external' coupling.

    Example

    COUPLINGS
{
   COUPLING
   {
      type = sequential
      upstream_subdomain = regionA
      downstream_subdomain = regionB
      HYDRAULICS
      {
         upstream_interface = weirA
         downstream_interface = hydrographB
      }
      BEDLOAD
      {
         upstream_interface = IODownA
         downstream_interface = sediment_dischargeB
      }
   }
}
    SUSPENSION
    SUSPENSION compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > COUPLINGS > COUPLING
    Description: Defines the interfaces of a coupling. Two or three coupling interfaces (=boundaries or external sources) must be specified by which the coupling takes places.

    Variable type comp. condition units default values
    upstream_interface string no - - - -
    downstream_interface string no - - - -
    upstream_interface1 string no - - - -
    upstream_interface2 string no - - - -
    downstream_interface1 string no - - - -
    downstream_interface2 string no - - - -
    external_interface string no - - - -
    basement_interface string no - - - -

    Description of Variables

    upstream_interface - name of upstream boundary/source
    downstream_interface - name of downstream boundary/source
    upstream_interface1 - name of upstream boundary/source 1, Only needed for 'confluence_wse' or 'junction' coupling.
    upstream_interface2 - name of upstream boundary/source 2, Only needed for 'confluence_wse' or 'junction' coupling.
    downstream_interface1 - name of downstream boundary/source 1, Only needed for 'bifurcation' coupling.
    downstream_interface2 - name of downstream boundary/source 2, Only needed for 'bifurcation' coupling.
    external_interface - name of interface of the BASEextern subodmain or different model (sub-surface model). This 'external_interface' does not take part in the local-time-stepping algorithm (lts). Only needed for 'external' coupling.
    basement_interface - name of interface of the BASEMENT subdomain. For example, use this interface for coupling with external programs or different model (sub-surface model). Only needed for 'external' coupling.

    Example

    COUPLINGS
{
   COUPLING
   {
      type = sequential
      upstream_subdomain = regionA
      downstream_subdomain = regionB
      HYDRAULICS
      {
         upstream_interface = weirA
         downstream_interface = hydrographB
      }
      SUSPENSION
      {
         upstream_interface = IODownA
         downstream_interface = suspension_dischargeB
      }
   }
}
    SUBSURFACE
    SUBSURFACE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > COUPLINGS > COUPLING
    Description: Defines the interfaces of a coupling. Two or three coupling interfaces (=boundaries or external sources) must be specified by which the coupling takes places.

    Variable type comp. condition units default values
    upstream_interface string no - - - -
    downstream_interface string no - - - -
    upstream_interface1 string no - - - -
    upstream_interface2 string no - - - -
    downstream_interface1 string no - - - -
    downstream_interface2 string no - - - -
    external_interface string no - - - -
    basement_interface string no - - - -

    Description of Variables

    upstream_interface - name of upstream boundary/source
    downstream_interface - name of downstream boundary/source
    upstream_interface1 - name of upstream boundary/source 1, Only needed for 'confluence_wse' or 'junction' coupling.
    upstream_interface2 - name of upstream boundary/source 2, Only needed for 'confluence_wse' or 'junction' coupling.
    downstream_interface1 - name of downstream boundary/source 1, Only needed for 'bifurcation' coupling.
    downstream_interface2 - name of downstream boundary/source 2, Only needed for 'bifurcation' coupling.
    external_interface - name of interface of the BASEextern subodmain or different model (sub-surface model). This 'external_interface' does not take part in the local-time-stepping algorithm (lts). Only needed for 'external' coupling.
    basement_interface - name of interface of the BASEMENT subdomain. For example, use this interface for coupling with external programs or different model (sub-surface model). Only needed for 'external' coupling.

    Example

    COUPLINGS
{
   COUPLING
   {
      type = no_LTS
      basesub = regionA
      baseplane = regionB
      SUBSURFACE
      {
         subsurface_interface = bs_exchange
         baseplane_interface = bp_exchange
      }
   }
}
    COUPLING_LATERAL
    COUPLING_LATERAL compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > COUPLINGS
    Description: A lateral coupling is a special coupling type, which can be used to couple a 1-D river channel model with a 2-D floodplain model. Along the 1-D river channel a list of coupling interfaces between cross sections (1-D) and mesh boudnary edges (2-D) can be defined. If the water surface elevation in the 1-D river model exceeds the dyke height at the specified side, than water can overflow over the 1-D dyke into the 2-D sub-domain or vice versa. The overtopping discharge is calculated using a weir formula, whereas for 1-D to 2-D a side weir is assumed.To determine the height of the 1-D dyke and the 1-D water surface elevation at the edge location, i.e. where the water overtopps, these data are interpolated by the program linearly between the corresponding two cross sections.
    The coupling connections between the cross sections and the 2-D mesh elements are defined within an additional text file. Thereby each 1-D cross section can have multiple connections with 2-D mesh elements. Each row of the text file defines one connection. The text file expects four columns to be given, separated by an empty space or tab. (1. column: name of the cross section., 2. column: side of the connection (left dyke = 0, right dyke = 1), 3. and 4. columns: node numbers which define an boundary edge of a 2-D element.) It is also possible to let the program search automatically for these connections, based on geometrical considerations (search radius).If this option is activated, couplings are generated in the needed format and saved into the file 'lateral_couplings_created.dat'. This option is, however, only possible if the 1-D cross sections are geo-referenced, i.e. global coordinates and orientation angles must be set for the 1-D cross sections.(Please note, that an additional file 'lateral_couplings_stats.shp' is written which contains the essential data for the user to check for correctness. Using GIS-programs you can easily check graphically if the connections were generated in a correct way and if manual corrections are necessary.)

    Variable type comp. condition units default values
    basechain string yes - - - -
    baseplane string yes - - - -
    connections_filename string yes required if 'connections_automatic' = 'no' - - -
    c_m real no - - 0.66 -
    momentum_sink string no - - yes {yes, no}
    momentum_factor real no - - 1.0 x >= 0
    suppressed_overfall boolean no - - no {no, yes}
    connections_automatic boolean no - - no {no, yes}
    connections_index whitespace separated list of integers yes required if 'connections_automatic' = 'yes' - - -
    connections_distance real yes required if 'connections_automatic' = 'yes' [m] 10.0 -
    weir_from_dyke1D boolean yes - - - {no, yes}
    weir_determination_nodes boolean no used if 'weir_from_dyke1D' = 'no' - no {no, yes}
    damping_factor real no - [-] 0.5 0 <= x < 1
    factor_adjust real no - - 1.0 -
    print_series boolean no - - no {no, yes}

    Block Usage

    For every lateral coupling a new COUPLING_LATERAL block has to be defined. Within the COUPLING_LATERAL block some specifications of the coupling parameters can be made. At the moment only hydraulic simulations are possible using the this coupling type. It is also possible to let the program determine the connections between the model automatically, based on geometrical considerations.

    Description of Variables

    basechain - 1-D channel flow model. This 1-D model represents the 1-D flow within the river channel.
    baseplane - 2-D floodplain model. This 2-D model represents the floodplain which is coupled laterally with the river channel.
    connections_filename - Name of file which defines the couplings between 1-D cross sections and 2-D edges as given by the user.The file must have 4 columns: 'name_of_cross_section' 'node_nr1' 'node_nr2' 'direction', wherease the direction is 0 for the left dike and 1 for the right dike of the cross section. (Left and right dike are defined as left or right in downstream flow direction.) This file is only used if the parameter 'lateral_connection_automatic' is set to 'no' (default). In the other case, the connections are generated automatically.
    c_m - Empircal de Marchi coefficient in weir formula with frontal flow (2D -> 1D).
    momentum_sink - Determines if the source also affects the momentum.
    momentum_factor - Factor to control the momentum source term [-]. Default: 1.0.
    suppressed_overfall - This flag indicates whether in the case of a supressed overfall a reduction factor should be taken into account for calculating the overfall discharge coefficient 'my'. If it is set to 'yes', then the user-specified discharge coefficient is multiplied with an additional reduction factor. The reduction is calculated for a sharp crested weir according to Fig.8.10 in Aigner and Bollrich (2021). If it is set to 'no', then weir discharge coefficient is not affected in the case of a suppressed overfall, i.e. the reduction factor takes a constant value of 1.0.
    connections_automatic - This flag determines if the lateral coupling connections between 1-D cross sections and 2-D edges (at the boundary of the 2-D mesh) shall be find and created automatically.If it is set to 'yes', then couplings are automatically created and stored to file. Afterwards, the program terminates without starting a simulation. If it is set to 'no', then connections are taken from a user provided file.Per default this flag is set to 'no' and the user must provide a file.The connections are created by determining the minimum distance between the 1-D cross section and the midpoint of the 2-D edges.At those 1-D cross sections and 2-D edges with minimum distance a connection is created. The user can provide a limiting distance 'lateral_connection_distance' which must not be exceeded for a connection to be created.Furthermore, the user must supply material indices to determine a zone where these connections shall be created.The created connections are written to the file 'lateral_connections_created.dat' to allow also for manual corrections or adaptations.This file can then be used as in a second step as input for the simulation with the tag 'connections_filename'.In addition, the shape-file 'lateral_connections_stats.shp' is created for easy graphical checks of the created connections.
    connections_index - Parameter for automatic creation of coupling connections at lateral coupling, used only if the flag 'lateral_connection_automatic' is set to 'yes'.It describes a list of material indices of elements defining a zone where the couplings shall be created. Only for this zone connections are created between the 1-D cross sections and 2-D edges.
    connections_distance - Parameter for automatic creation of coupling connections at lateral coupling, used only if the flag 'lateral_coupling_automatic' is set to 'yes'.A connection is created if the distance between the 2-D edge (midpoint) to the left or right dikeof the 1-D cross section is smaller than this given value. It allows to prevent the creation of connections over too large distances.
    weir_from_dyke1D - This flag indicates whether the weir height for lateral exchange is determined from interpolated values of the 1-D dyke heights or from the elevations of the 2-D edges. If it is set to 'yes', then the weir height is determined from the dyke heights of the 1-D cross sections by interpolation. If it is set to 'no', then the weir height is determined from the elevations of the 2-D edges. Generally, taking the heights from the 2-D edges is more accurate and can consider local properties (like a short gap in the dam). Therefore, if the 2-D mesh is an accurate representation of the terrain surface, including strutures like dams, then the parameter should be set to 'no'.
    weir_determination_nodes - This flag is only used if 'weir_from_dyke1D' is set to 'no', i.e. in case that the the weir overfall heights are determined from the 2-D edge heights. This parameter determines how cases are treated, where the elements show an 'uphill' tendency, i.e. that element centers and its nodal elevations are higher than the elevation of the edge. If it is set to 'yes', then the weir height is set to the centre elevation of the element (for such uphill elements) If it is set to 'no', then the weir height is set to the maximum nodal elevation of the element (only for such uphill elements).
    damping_factor - This flag determines the damping factor which is applied for the lateral coupling. The change of flow direction (1-D --> 2-D, 2-D --> 1-D) can cause slight oscillations at this coupling type. By averaging the water levels of the 1-D- and 2-D-subdomains, these oscillations can be damped. If the parameter is set to '0.0', than no damping is applied. If the parameter is set to '0.5', than the water levels are averaged with the values of the last time step (default).
    factor_adjust - General adjustment factor to reduce or increase all exchanged discharges in lateral coupling. This is an advanced parameter, which should only be altered if stability problems occur.
    print_series - print time series of exchanged values of the coupled boundaries

    Example

    //Example lateral coupling from given text file:
 COUPLING_LATERAL
 {
    basechain = region1D
    baseplane = region2D
    connections_automatic = no
    connections_filename = connections.dat  // file with defined couplings
    c_m = 0.66
    weir_from_dyke1D = no
 }

//Example of automatic generation of coupling connections: 
 COUPLING_LATERAL
{
    basechain = region1D
    baseplane = region2D
    connections_automatic = yes
    connections_index = ( 1 2 )
    connections_distance = 20
    weir_from_dyke1D = no
}
    CONTROLLER
    CONTROLLER compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN
    Description: This block defines a controller object, which can be used to dynamically enforce some target, such as maintaining a certain water surface elevation or keeping the flow over a weir fixed.It can also be used to change boundary conditions like inflow, gate/weir-elevation during the runtime of a simulation.
    Inner Blocks: MONITORED_VARIABLE
    MANIPULATED_VARIABLE

    Variable type comp. condition units default values
    name string yes - - - Chars [a-zA-Z0-9_-] are allowed
    type string yes - - - {PID, HID}
    output boolean no - - no {no, yes}
    output_time_step real no used if 'output' = 'yes' [s] 0 x >= 0

    Block Usage

    Choose your controller type between HID and PID first.
    A HID-controller (Human Interface Device) allows for changing the time series for boundary conditions during the runtime of a simulation.
    A PID-controller (Proportional Integral Derivative) is used if you want to control e.g. a weir or gate automatically to enforce a given target (like a certain water surface elevation at some point or a certain discharge at some cross section. The foundations of the PID controller and its implementation are described in subsection 7 in the first section of the User manual.
    You can define several CONTROLLER blocks, e.g. a HID and two PID's. When the type of controller is set, add the subblocks for MANIPULATED and MONITORED variables.
    MONITORED variables are shown in the graphic user interface (e.g. a plot of the actual discharge over a weir).
    In case of a PID-controller, MONITORED variables are used to define a certain target (e.g. constant water surface elevation in element nr. xy). More important, for a PID controller, the MONITORED variable is used to define the PID-coefficients of the controller to reach the target by altering the MANIPULATED variable.
    For a HID-controller, the MANIPULATED variable allows for an interaction during the runtime (e.g. changing the inflow discharge or a weir level using the graphic user interface).
    For a PID-controller, the MANIPULATED variable is used to define the variable which can can be manipulated to reach the target and also the limitations imposed on the manipulated variable.

    Description of Variables

    name - Name of the controller. This name is used to name the output-files.
    type - Type of controller object. Choose between PID and HID.
    A human interface device (HID) controller allows for interactively changing the boundary conditions (e.g. controlling the discharge for inflow or the elevation of a weir/gate-crest) during runtime).
    A classical proportional-integral-derivative (PID) controller is used to control the behaviour of a boundary condition such that one ore several targets are reached (e.g. controlling a weir in order to reach a target water surface elevation or controlling a gate in order to reach a target discharge).
    output - Write all monitored and manipulated variables to a file named controller_'name'.txt.
    output_time_step - The output time step defines the time interval after which an output of monitored and manipulated variables is written to file. By default, it is set to 0 which may lead to large output files as every timestep will be written.

    Example

    // complete controller example: 2D weir with Q-dependent target water level
CONTROLLER {
   name = Weir1ctrl
   type = PID
   // this variable monitors the target water level
   MONITORED_VARIABLE {
      name = targetlevel
      // PID coefficients relating this monitored variable to 
      // the weirmanipulator        
      coefficients = weirmanipulator:(-1.5 -0.05 -5.0)
      // target level depends on the water flow monitored by 'flowmeasure'
      // the target_level.txt relates measured discharge to target discharge 
      root_value = qseries:flowmeasure:target_level.txt
      // measure water level at element 3003 of region
      // straightchannel
      position = straightchannel.3003
      // measure the water surface level
      type = wse
      // no delay, immediate input into the controller
      delay = 0
   }
   // this variable monitors the inflow. the target level above
   // depends on the inflow measured here
   MONITORED_VARIABLE {
      name = flowmeasure
      root_value = 0
      // position is stringdef flowmeasure1 in region
      // straightchannel
      position = straightchannel.flowmeasure1
      type = Q
      delay = 0
   }
   // manipulate the weir to achieve target 
   MANIPULATED_VARIABLE {
      name = weirmanipulator
      position = straightchannel.middle1_1
      // weir is initially at 501.5 [m]
      start_value = 501.5
      // weir level change is 1 mm per second
      max_change_rate = 0.001
      // weir level must be between 500 and 505
      range = (500 505)
   }
}
    MONITORED_VARIABLE
    MONITORED_VARIABLE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > CONTROLLER
    Description: This block defines a monitored variable for a PID- or HID-controller.

    Variable type comp. condition units default values
    name string yes - - - Chars [a-zA-Z0-9_-] are allowed
    coefficients tagged list no - - - -
    type enum yes - - - {Q, wse}
    root_value_type enum no - - fixed_value {discharge_series, discharge_time_table, fixed_value, time_series}
    root_value real no used if 'root_value_type' = 'fixed_value' - 0.0 -
    root_value_series_file string yes required if 'root_value_type' = 'time_series' or 'discharge_series' or 'discharge_time_table' - - -
    root_value_qseries_varname string yes required if 'root_value_type' = 'discharge_series' or 'discharge_time_table' - - -
    position string yes - - - -
    delay real no - - 0.0 x >= 0
    time_average_sec real no - - 0.0 x >= 0

    Block Usage

    Monitored variables will always be plotted during the runtime of the simulation in an extra window independent on the controller type.
    You can either monitor a water surface elevation in an element or a discharge through a cross section. A simple definition of a monitored value consists of a name, the position and the type (Q,wse).

    In combination with a PID-controller, a monitored value needs also the PID-coefficients to be defined. There are several possibilites to create quite complex controllers:
    A simple controller is e.g. a controlled weir which tries to reach a fixed water surface elevation as target. The 'root_value_type' would be set to 'fixed_value' or 'time_series' for fixed targets varying in time.
    A slightly more complex controller would be a discharge-dependent target, e.g. a gate which has a discharge through the gate as target but the value of the target is not fixed but dependent on the measured discharge somewhere else. For such a controller, two monitored variables are needed: one for the discharge which decides for the target and one for the discharge through the gate. The 'root_value_type' for the monitored gate would be set to 'discharge_series' and a file would link the measured discharge to some target discharge. Additionally, the 'root_value_qseries_varname' needs to be linked to the name of the monitored variable for the measured discharge. Sounds complicated? Check out the example in the controller block help.

    The correct determination of the coefficients is the key point and very crucial for a correct operation of the controller. A simple approach to make a first guess for the coefficients of a PID controller is given by the following rule of thumb:
    1. Determine the correct sign of the coefficients. Example: If you like to control a water surface elevation with a weir, then the weir must be lowered when the water level exceeds the target. So the sign of all coefficients must be negative.
    2. Determine the correct magnitude of the P-element (and set I and D to 0). Example: How many centimetres do you have to lower a weir if the water level is 1cm too high. The value here depends strongly on the reservoir size and weir width. If the value is too small, the water level can not be controlled. If the value is too big, the system might start to oscillate.
    3. Then define the I-coefficient. For hydraulic simulations, the I-coefficient is commonly two magnitudes lower than the P-coefficient. A too high value leads to oscillations, a too low value prevents the system to reach its equilibrium state within finite time.

    Description of Variables

    name - Unique name of the monitored variable. This name may be used by other monitored variables which depend on this measurement.
    coefficients - List of PID-coefficients. Length and meaning depend on controller type. (P, PI, PD, PID, ...) The tag corresponds to the name of the manipulated variable to which the monitored variable is related via the coefficients.
    Example for the syntax: coefficients = name_of_manipulated_variable:( Pvalue Ivalue Dvalue )
    Relations to different manipulated variables are possible. This is why the coefficients-tag is repeatable.
    type - Type of monitored variable. Q is the discharge, wse is the water surface elevation
    root_value_type - The root_value_type is only needed for PID-controllers.
    Basically, a PID-controller needs at least one target to reach, e.g. a certain wse or discharge. This target relates to the monitored variable. A controller tries to minimize the difference between measured (monitored) value and the target value. Therefore, it is called 'root' (0).
    There are different types of targets: fixed, time-dependent, discharge-dependent, etc. :
    1. 'fixed_value' is used if the target remains constant during the simulation, e.g. a constant wse or discharge which shall be reached by the controller. For sure the easiest one.
    2. 'time_series' is used if the target depends on the time. You will have to provide a file with time and corresponding target value for wse or discharge.
    3. 'discharge_series' is used if the target value depends on a measured discharge within another monitored variable. You will have to provide a file with the (measured) discharge and the corresponding target value for wse or discharge. In addition, the tag 'root_value_qseries_varname' has to be linked to the monitored variable which measures the discharge.
    4. 'discharge_time_table' is used if all other options do not work and you really know what you are doing ;) Shortly explained, this is a discharge_series with an additional time aspect. This is used for lake regulations where the discharge_series depend on the season of the year or day/night, etc.
    root_value - The root value is the constant target value which shall be established.
    root_value_series_file - Name of file where the discharge and/or time series are stored
    root_value_qseries_varname - This references to the name of another monitored variable which influences the target to be reached. Has to be provided for discharge_series and discharge_time_table.
    position - Identifier for the location, where you want to monitor a discharge or a wse. The identifier consists of two dot-separated strings. The first string refers to the region name, the second to the location of measurement as following: In 1D, this is the string given by the name tag in a cros section definition. In 2D, it refers to the name of a STRINGDEF for a monitored discharge or to the element number for a monitored wse in a particular element.
    delay - The time delay for feeding the monitored value into the controller.
    time_average_sec - Defines the interval from which the time-average of the monitored value is calculated. This can be used as a low-pass filter to reduce numerical or physical oscillations.

    Example

    see full PID example at CONTROLLER block and HID example 
    at the MANIPULATED_VARIABLE block.
    MANIPULATED_VARIABLE
    MANIPULATED_VARIABLE compulsory repeatable
    Super Blocks: BASEMENT > DOMAIN > CONTROLLER
    Description: This block defines a manipulated variable for a HID- or PID-controller.

    Variable type comp. condition units default values
    name string yes - - - Chars [a-zA-Z0-9_-] are allowed
    position string yes - - - -
    start_value real yes - - - -
    max_change_rate real no - - - x > 0
    range whitespace separated list of 2 reals no - [m rel.] - -
    time_range whitespace separated list of 2 reals no - [s] - -
    steady_value real no - - - -

    Block Usage

    Defining a manipulated variable is straight forward and independent of the controller type (HID or PID). At the moment, boundary conditions like an inflow, weir or gate can be subject to be manipulated..
    Read the help for the individual tags for more information.

    Description of Variables

    name - Unique name of the manipulated variable. This is used by monitored variables to relate their coefficients for a PID controller.
    position - Identifier for the boundary condition, which will be manipulated. The identifier consists of two dot-separated strings. The first string refers to the region name, the second to the boundary condition as following: In 1D, this is the string given by the name tag in a BOUNDARY definition. In 2D, it refers to the string_name in a BOUNDARY definition, or to the stringname1 in an INNER_BOUNDARY definition.
    start_value - The initial value of the manipulated variable at start-time of the simulation.
    max_change_rate - The maximum change rate of the manipulated value in units per second, This is an important parameter for PID controllers. If no value is set here, a PID-controller for a weir could start to oscillate because the controller may change the weir crest from 0 to 100 within no time.
    range - The possible value range for the manipulated variable, e.g. lowest and maximal possible level of a weir crest.
    time_range - The manipulated variable will only be controlled within this range of time. Outside of this range, the manipulated boundary condition will use the value specified as the steady_value.
    steady_value - The value of the manipulated variable for when the time is outside of the specified time range.

    Example

    // HID Example: Change the inflow discharge during runtime
CONTROLLER {
   name = dynamic_inflow
   type = HID
   // manipulate the inflow discharge 
   MANIPULATED_VARIABLE {
      name = inflow_manipulator
      position = regionname.stringname_of_inflow_boundary_condition
      start_value = 0.0
      range = (0 200)
   }
   // this variable monitors the inflow discharge
   // and generates a visual plot during runtime
   MONITORED_VARIABLE {
      name = inflow_measurement
      position = regionname.stringname_of_inflow_boundary_condition
      type = Q
   }
}