BUNDESANSTALT FUR WASSERBAU¨ · BUNDESANSTALT FUR WASSERBAU¨ Karlsruhe•Hamburg•Ilmenau Technical Report Mathematical Model UnTRIM User Interface Description – Version June

BUNDESANSTALT FUR WASSERBAUKarlsruhe • Hamburg • Ilmenau

Technical Report

Mathematical Model UnTRIM

User Interface Description

– Version June 2004 (1.0) –

BUNDESANSTALT FUR WASSERBAUKarlsruhe • Hamburg • Ilmenau

Technical Report

Mathematical Model UnTRIM

User Interface Description

– Version June 2004 (1.0) –

Contributors: Vincenzo Casulli (Trento University, Italy)Gunther Lang (BAW, Germany)

Version-Date: June 2004

Version-no.: 1.0

Trento � Hamburg — August 2004

The Federal Waterways Engineering and Research Institute � Wedeler Landstr. 157 � D-22559 Hamburg � ([+49] (0)40 81908 - 0

mailto:[email protected]

mailto:[email protected]

The Federal Waterways Engineering and Research Institute (BAW)Mathematical Model UnTRIMUser Interface Description – Version June 2004 (1.0)

Summary

This document is the user interface description for the mathematical model UnTRIM. Thisdocument can be regarded as an appendix to Mathematical Model UnTRIM – Validation Docu-ment, which is available as a separate report.

Organization of this document

Chapter B contains a short overview for all user interface routines (see Section B.4 onpage 66) together with a detailed description of all Set-routines (see Section B.1 on page 1)as well as Get-functions (please refer to Section B.2 on page 24).

Chapter C summarizes the available Set-routines and Get-functions in tabular form. Thismay help the experienced user of UnTRIM to quickly access the correct routine or function,and informations about how to use them.

Chapter D contains short examples of the three standard input data files ("untrim.inp","untrim.grd" and "untrim.srs") which are read by the core of the computationalmodel.

Electronic user interface description document

This document is also available in electronic form in Portable Document Format (PDF). Theelectronic version may be read using ACROBAT READER software which is available formany computer platforms.

Acknowledgements

Ralph T. Cheng is responsible for the development of a version of the UnTRIM at the U. S.Geological Survey (USGS). Continuing discussions and exchanging of modeling ideas withregards to user interface description of UnTRIM with Ralph T. Cheng are acknowledged.

During the first International UnTRIM Users Workshop in Verona, June 7 – 9, 2004, it wasdecided to update this document, to conform to the actual version of the software (June2004). Positive and stimulating feedback from the users to continue working on this type ofdocument is herewidth gratefully acknowledged too.

Page i

http://www.baw.de/vip/abteilungen/wbk/Methoden/hnm/untrim/hnm_untrim-de.html


http://www.baw.de/vip/abteilungen/wbk/Methoden/hnm/untrim/PDF/vd-untrim-2004.pdf






Contents

B User interface 1B.1 Set routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

B.1.1 Interface set atmospheric pressure . . . . . . . . . . . . . . . . . 3B.1.2 Interface set bottom alpha . . . . . . . . . . . . . . . . . . . . . . . . 3B.1.3 Interface set bottom beta . . . . . . . . . . . . . . . . . . . . . . . . 4B.1.4 Interface set bottom concentration . . . . . . . . . . . . . . . . . 4B.1.5 Interface set bottom friction . . . . . . . . . . . . . . . . . . . . . 5B.1.6 Interface set concentration . . . . . . . . . . . . . . . . . . . . . . 6B.1.7 Interface set concentration bc . . . . . . . . . . . . . . . . . . . . 7B.1.8 Interface set density . . . . . . . . . . . . . . . . . . . . . . . . . . . 8B.1.9 Interface set elevation . . . . . . . . . . . . . . . . . . . . . . . . . . 8B.1.10 Interface set elevation bc . . . . . . . . . . . . . . . . . . . . . . . . 9B.1.11 Interface set flux limiter . . . . . . . . . . . . . . . . . . . . . . . . 9B.1.12 Interface set grid file . . . . . . . . . . . . . . . . . . . . . . . . . . 10B.1.13 Interface set horizontal velocity . . . . . . . . . . . . . . . . . . 10B.1.14 Interface set inflow bc . . . . . . . . . . . . . . . . . . . . . . . . . . 11B.1.15 Interface set inflow cc . . . . . . . . . . . . . . . . . . . . . . . . . . 12B.1.16 Interface set input file . . . . . . . . . . . . . . . . . . . . . . . . . 12B.1.17 Interface set point sources discharge . . . . . . . . . . . . . . . 12B.1.18 Interface set point sources concentration . . . . . . . . . . . . 13B.1.19 Interface set pressure . . . . . . . . . . . . . . . . . . . . . . . . . . 14B.1.20 Interface set pressure bc . . . . . . . . . . . . . . . . . . . . . . . . 14B.1.21 Interface set sediment . . . . . . . . . . . . . . . . . . . . . . . . . . 15B.1.22 Interface set settling velocity . . . . . . . . . . . . . . . . . . . . 15B.1.23 Interface set source file . . . . . . . . . . . . . . . . . . . . . . . . 16B.1.24 Interface set surface alpha . . . . . . . . . . . . . . . . . . . . . . . 16B.1.25 Interface set surface beta . . . . . . . . . . . . . . . . . . . . . . . . 17B.1.26 Interface set surface concentration . . . . . . . . . . . . . . . . 18B.1.27 Interface set turbulent h diffusivity . . . . . . . . . . . . . . . 18B.1.28 Interface set turbulent h viscosity . . . . . . . . . . . . . . . . . 19B.1.29 Interface set turbulent v diffusivity . . . . . . . . . . . . . . . 20B.1.30 Interface set turbulent v viscosity . . . . . . . . . . . . . . . . . 21B.1.31 Interface set velocity . . . . . . . . . . . . . . . . . . . . . . . . . . 21B.1.32 Interface set wind friction . . . . . . . . . . . . . . . . . . . . . . . 22B.1.33 Interface set wind velocity . . . . . . . . . . . . . . . . . . . . . . . 22

B.2 Get-functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24B.2.1 Interface get adjacent polygon . . . . . . . . . . . . . . . . . . . . 27B.2.2 Interface get atmospheric pressure . . . . . . . . . . . . . . . . . 28B.2.3 Interface get bottom alpha . . . . . . . . . . . . . . . . . . . . . . . . 28B.2.4 Interface get bottom beta . . . . . . . . . . . . . . . . . . . . . . . . 29B.2.5 Interface get bottom concentration . . . . . . . . . . . . . . . . . 29

Page ii


B.2.6 Interface get bottom face . . . . . . . . . . . . . . . . . . . . . . . . 30B.2.7 Interface get bottom flux . . . . . . . . . . . . . . . . . . . . . . . . 30B.2.8 Interface get bottom friction . . . . . . . . . . . . . . . . . . . . . 30B.2.9 Interface get bottom prism . . . . . . . . . . . . . . . . . . . . . . . . 31B.2.10 Interface get bottom stress . . . . . . . . . . . . . . . . . . . . . . . 31B.2.11 Interface get chezy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31B.2.12 Interface get concentration . . . . . . . . . . . . . . . . . . . . . . 32B.2.13 Interface get density . . . . . . . . . . . . . . . . . . . . . . . . . . . 32B.2.14 Interface get depth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33B.2.15 Interface get depth at edge . . . . . . . . . . . . . . . . . . . . . . . 33B.2.16 Interface get dt min . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34B.2.17 Interface get dx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34B.2.18 Interface get dx min . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34B.2.19 Interface get dy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34B.2.20 Interface get dz min . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35B.2.21 Interface get edge begin . . . . . . . . . . . . . . . . . . . . . . . . . 35B.2.22 Interface get edge center . . . . . . . . . . . . . . . . . . . . . . . . 35B.2.23 Interface get edge end . . . . . . . . . . . . . . . . . . . . . . . . . . . 36B.2.24 Interface get elevation . . . . . . . . . . . . . . . . . . . . . . . . . . 36B.2.25 Interface get elevation tolerance . . . . . . . . . . . . . . . . . . 37B.2.26 Interface get face height . . . . . . . . . . . . . . . . . . . . . . . . 37B.2.27 Interface get flux limiter . . . . . . . . . . . . . . . . . . . . . . . . 37B.2.28 Interface get gravity . . . . . . . . . . . . . . . . . . . . . . . . . . . 38B.2.29 Interface get hland . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38B.2.30 Interface get horizontal diffusivity . . . . . . . . . . . . . . . . 38B.2.31 Interface get horizontal velocity . . . . . . . . . . . . . . . . . . 38B.2.32 Interface get horizontal velocity x . . . . . . . . . . . . . . . . . 39B.2.33 Interface get horizontal velocity y . . . . . . . . . . . . . . . . . 40B.2.34 Interface get horizontal viscosity . . . . . . . . . . . . . . . . . 40B.2.35 Interface get iterations . . . . . . . . . . . . . . . . . . . . . . . . . 41B.2.36 Interface get layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41B.2.37 Interface get layer interface . . . . . . . . . . . . . . . . . . . . . 42B.2.38 Interface get left polygon . . . . . . . . . . . . . . . . . . . . . . . . 42B.2.39 Interface get location . . . . . . . . . . . . . . . . . . . . . . . . . . 42B.2.40 Interface get mass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43B.2.41 Interface get maximum iteration . . . . . . . . . . . . . . . . . . . . 43B.2.42 Interface get nof boundary polygons . . . . . . . . . . . . . . . . . 43B.2.43 Interface get nof edges . . . . . . . . . . . . . . . . . . . . . . . . . . 44B.2.44 Interface get nof faces . . . . . . . . . . . . . . . . . . . . . . . . . . 44B.2.45 Interface get nof inflow edges . . . . . . . . . . . . . . . . . . . . . 44B.2.46 Interface get nof internal edges . . . . . . . . . . . . . . . . . . . 45B.2.47 Interface get nof layers . . . . . . . . . . . . . . . . . . . . . . . . . 45

Page iii


B.2.48 Interface get nof point sources . . . . . . . . . . . . . . . . . . . . 45B.2.49 Interface get nof polygons . . . . . . . . . . . . . . . . . . . . . . . . 45B.2.50 Interface get nof prisms . . . . . . . . . . . . . . . . . . . . . . . . . 46B.2.51 Interface get nof species . . . . . . . . . . . . . . . . . . . . . . . . 46B.2.52 Interface get nof vertices . . . . . . . . . . . . . . . . . . . . . . . . 46B.2.53 Interface get nof wet edges . . . . . . . . . . . . . . . . . . . . . . . 47B.2.54 Interface get nof wet faces . . . . . . . . . . . . . . . . . . . . . . . 47B.2.55 Interface get nof wet polygons . . . . . . . . . . . . . . . . . . . . . 47B.2.56 Interface get nof wet prisms . . . . . . . . . . . . . . . . . . . . . . 48B.2.57 Interface get polygon . . . . . . . . . . . . . . . . . . . . . . . . . . . 48B.2.58 Interface get polygon area . . . . . . . . . . . . . . . . . . . . . . . . 48B.2.59 Interface get polygon center . . . . . . . . . . . . . . . . . . . . . . 49B.2.60 Interface get polygon edge . . . . . . . . . . . . . . . . . . . . . . . . 49B.2.61 Interface get polygon vertex . . . . . . . . . . . . . . . . . . . . . . 49B.2.62 Interface get pressure . . . . . . . . . . . . . . . . . . . . . . . . . . 50B.2.63 Interface get pressure tolerance . . . . . . . . . . . . . . . . . . . 50B.2.64 Interface get prism height . . . . . . . . . . . . . . . . . . . . . . . . 51B.2.65 Interface get radiation time . . . . . . . . . . . . . . . . . . . . . . 51B.2.66 Interface get right polygon . . . . . . . . . . . . . . . . . . . . . . . 51B.2.67 Interface get settling velocity . . . . . . . . . . . . . . . . . . . . 52B.2.68 Interface get source concentration . . . . . . . . . . . . . . . . . 53B.2.69 Interface get source discharge . . . . . . . . . . . . . . . . . . . . 53B.2.70 Interface get source layer . . . . . . . . . . . . . . . . . . . . . . . . 53B.2.71 Interface get source polygon . . . . . . . . . . . . . . . . . . . . . . 54B.2.72 Interface get surface alpha . . . . . . . . . . . . . . . . . . . . . . . 54B.2.73 Interface get surface beta . . . . . . . . . . . . . . . . . . . . . . . . 55B.2.74 Interface get surface concentration . . . . . . . . . . . . . . . . 55B.2.75 Interface get surface flux . . . . . . . . . . . . . . . . . . . . . . . . 55B.2.76 Interface get theta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56B.2.77 Interface get time step . . . . . . . . . . . . . . . . . . . . . . . . . . 56B.2.78 Interface get top face . . . . . . . . . . . . . . . . . . . . . . . . . . . 56B.2.79 Interface get top prism . . . . . . . . . . . . . . . . . . . . . . . . . . 57B.2.80 Interface get turbulent h diffusivity . . . . . . . . . . . . . . . 57B.2.81 Interface get turbulent v diffusivity . . . . . . . . . . . . . . . 57B.2.82 Interface get turbulent v viscosity . . . . . . . . . . . . . . . . . 58B.2.83 Interface get velocity . . . . . . . . . . . . . . . . . . . . . . . . . . 58B.2.84 Interface get vertex coordinates . . . . . . . . . . . . . . . . . . . 59B.2.85 Interface get vertical diffusivity . . . . . . . . . . . . . . . . . 59B.2.86 Interface get vertical velocity . . . . . . . . . . . . . . . . . . . . 59B.2.87 Interface get vertical viscosity . . . . . . . . . . . . . . . . . . . 60B.2.88 Interface get volume . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60B.2.89 Interface get wind friction . . . . . . . . . . . . . . . . . . . . . . . 61

Page iv


B.2.90 Interface get wind stress . . . . . . . . . . . . . . . . . . . . . . . . 61B.2.91 Interface get wind velocity . . . . . . . . . . . . . . . . . . . . . . . 62B.2.92 Interface get wind velocity x . . . . . . . . . . . . . . . . . . . . . 62B.2.93 Interface get wind velocity y . . . . . . . . . . . . . . . . . . . . . 62B.2.94 Interface get x vertex coordinate . . . . . . . . . . . . . . . . . . 63B.2.95 Interface get y vertex coordinate . . . . . . . . . . . . . . . . . . 63B.2.96 Interface sediment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63B.2.97 Interface with hydrodynamic pressure . . . . . . . . . . . . . . . . 64B.2.98 Interface with scalar transport . . . . . . . . . . . . . . . . . . . . 64

B.3 Check routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65B.3.1 Subroutine check continuity . . . . . . . . . . . . . . . . . . . . . . 65B.3.2 Subroutine check grid . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

B.4 User interface routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66B.4.1 Subroutine user set input files . . . . . . . . . . . . . . . . . . . 66B.4.2 Subroutine user set initial conditions . . . . . . . . . . . . . . 66B.4.3 Subroutine user set forcing terms . . . . . . . . . . . . . . . . . . 67B.4.4 Subroutine user get results . . . . . . . . . . . . . . . . . . . . . . 74

C Tables for set-routines and get-functions 76

D Example input data files 90D.1 Grid file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

D.1.1 Grid sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90D.1.2 Short description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90D.1.3 Example file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

D.2 Input data file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93D.2.1 Short description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93D.2.2 Example file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

D.3 Source and sink data file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95D.3.1 Short description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95D.3.2 Example file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Page v


List of Figures

Page vi


List of Tables

1 Nomenclature of set- and get- arguments . . . . . . . . . . . . . . . . . . . . . 772 Set-routines (set atmospheric pressure – set input file) . . . . . . . . . . . . . 783 Set-routines (set inflow bc – set wind velocity) . . . . . . . . . . . . . . . . . . 794 Get-functions (get adjacent polygon – get bottom stress) . . . . . . . . . . . . 805 Get-functions (get concentration – get dzmin) . . . . . . . . . . . . . . . . . . . 816 Get-functions (get edge begin – get horizontal diffusivity) . . . . . . . . . . . 827 Get-functions (get horizontal velocity – get mass) . . . . . . . . . . . . . . . . 838 Get-functions (get maximum iteration – get nof prisms) . . . . . . . . . . . . 849 Get-functions (get nof species – get polygon edge) . . . . . . . . . . . . . . . . 8510 Get-functions (get polygon vertex – get surface flux) . . . . . . . . . . . . . . 8611 Get-functions (get source polygon – get turbulent h diffusivity) . . . . . . . . 8712 Get-functions (get turbulent h viscosity – get wind friction) . . . . . . . . . . 8813 Get-functions (get wind stress – with scalar transport) . . . . . . . . . . . . . 89

Page vii


B User interface

B.1 Set routines

Set-routines are going to be used if (internal) default values for variables and parameters arenot appropriate for the scenario under investigation. In the following, all set-routines aregrouped according to their functionality:

� file names for standard input files

– steering data file

� set input file

– grid file

� set grid file

– sources and sinks file

� set source file

� steering data

– transport algorithm for scalar species

� set flux limiter

– scalar species

� set sediment

� initial data and (state) variables

– hydrodynamics

� set density

� set elevation

� set horizontal velocity

� set pressure

� set turbulent h viscosity

� set turbulent v viscosity

� set velocity

– scalar species

� set concentration

� set settling velocity

� set turbulent h diffusivity

� set turbulent v diffusivity

� data at lateral open boundaries with prescribed water level

– hydrodynamics

B. User interface Page 1


� set elevation bc

� set pressure bc

– scalar species

� set concentration bc

� data at lateral open boundaries with prescribed flow

– hydrodynamics

� set inflow bc

– scalar species

� set inflow cc

� boundary data at the free surface

– atmospheric data near the free surface

� set atmospheric pressure

� set wind friction

� set wind velocity

– data related to scalar species

� set surface alpha

� set surface beta

� set surface concentration

� boundary data at the bottom surface

– data related to bottom friction

� set bottom friction

– data related to scalar species

� set bottom alpha

� set bottom beta

� set bottom concentration

� sources and sinks

– hydrodynamics

� set point sources discharge

– scalar species

� set point sources concentration

All set routines available to the user are subsequently described and listed in alphabeticalorder.



B.1.1 Interface set atmospheric pressure

physical unit: m2/s2

default value: 0.0 (if interface is not used)

Assign normalized atmospheric pressure pa at polygon centers:

1. CALL set atmospheric pressure(s): a constant normalized atmospheric pres-sure s[real] is assigned to all polygons Np;

2. CALL set atmospheric pressure(i,s): the normalized atmospheric pressure isset for the i-th polygon (1 � i � Np) to a constant value s[real];

3. CALL set atmospheric pressure(a(:)): a spatially varying normalized atmo-spheric pressure a(Np)[real] is assigned to all polygons Np.

To determine Np use get nof polygons(). To obtain the normalized atmospheric pressurepa, the (real physical) atmospheric pressure has to be divided by ρ0.

B.1.2 Interface set bottom alpha

physical unit: m/s


Assign bottom flux parameter αB at polygon centers:

1. CALL set bottom alpha(s): a constant s[real] is assigned to the bottom fluxparameter αB for all scalar species Nc and all polygons Np;

2. CALL set bottom alpha(m,s): a constant s[real] is assigned to the bottom fluxparameter αB for the m-th scalar specie (1 � m � Nc) and all polygons Np;

3. CALL set bottom alpha(m,i,s): a constant s[real] is assigned to the bottomflux parameter αB for the m-th scalar specie (1�m�Nc) in the i-th polygon (1� i�Np);

4. CALL set bottom alpha(m,a(:)): spatially varying data a(Np)[real] are as-signed to the bottom flux parameter αB for the m-th scalar specie (1 � m � Nc) at all Np

polygons;

5. CALL set bottom alpha(b(:,:)): spatially varying data b(Np�Nc)[real], dif-ferent for each of the Nc scalar species, are assigned to the bottom flux parameter α B forall Nc species and all Np polygons.



αB � 0�0 must be fulfilled. Np can be determined by means of get nof polygons(),whereas Nc can be obtained from get nof species(). In dependence on the situa-tion at the bottom boundary the settings for α B , βB (set bottom beta) as well as CB

(set bottom concentration) must be chosen in a coordinated way.As an example please refer to paragraph Flux of scalar species through the bottom boundary

in the validation document.

B.1.3 Interface set bottom beta

physical unit: m/s


Assign bottom flux parameter βB at polygon centers:

1. CALL set bottom beta(s): a constant s[real] is assigned to the bottom flux pa-rameter βB for all scalar species Nc and all polygons Np;

2. CALL set bottom beta(m,s): a constant s[real] is assigned to the bottom fluxparameter βB for the m-th scalar specie (1 � m � Nc) and all polygons Np;

3. CALL set bottom beta(m,i,s): a constant s[real] is assigned to the bottomflux parameter βB for the m-th scalar specie (1�m�Nc) in the i-th polygon (1� i�Np);

4. CALL set bottom beta(m,a(:)): spatially varying data a(Np)[real] are as-signed to the bottom flux parameter βB for the m-th scalar specie (1 � m � Nc) at allNp polygons;

5. CALL set bottom beta(b(:,:)): spatially varying data b(Np�Nc)[real], differ-ent for each of the Nc scalar species, are assigned to the bottom flux parameter βB forall Nc species and all Np polygons.

βB � 0�0 must be fulfilled. Np can be determined by means of get nof polygons(),whereas Nc can be obtained from get nof species(). In dependence on the situa-tion at the bottom boundary the settings for βB , αB (set bottom alpha) as well as CB

(set bottom concentration) must be chosen in a coordinated way.As an example please refer to paragraph Flux of scalar species through the bottom boundary

in the validation document.

B.1.4 Interface set bottom concentration

physical unit: identical to physical unit of specie used






Assign bottom concentration CB at polygon centers:

1. CALL set bottom concentration(s): a constant s[real] is assigned to the bot-tom concentration CB for all scalar species Nc and all polygons Np;

2. CALL set bottom concentration(m,s): a constant s[real] is assigned to thebottom concentration CB for the m-th scalar specie (1 �m � Nc) and all polygons Np;

3. CALL set bottom concentration(m,i,s): a constant s[real] is assigned tothe bottom concentration CB for the m-th scalar specie (1 � m � Nc) in the i-th polygon(1 � i � Np);

4. CALL set bottom concentration(m,a(:)): spatially varying data a(Np)[real]

are assigned to the bottom concentration CB for the m-th scalar specie (1 � m � Nc) atall Np polygons;

5. CALL set bottom concentration(b(:,:)): spatially varying data b(Np�Nc)

[real], different for each of the Nc scalar species, are assigned to the bottom con-centration CB for all Nc species and all Np polygons.

Np can be determined by means of get nof polygons(), whereas Nc can be obtained fromget nof species(). In dependence on the situation at the bottom boundary the settingsfor CB , αB (set bottom alpha) as well as βB (set bottom beta) must be chosen in a co-ordinated way.

As an example please refer to paragraph Flux of scalar species through the bottom boundaryin the validation document.

B.1.5 Interface set bottom friction

physical unit: —

default value: g�C2z (if interface is not used), with Cz taken from the user’s input file

"untrim.inp"

Assign bottom friction coefficient rB at sides/edges:

1. CALL set bottom friction(s): a constant bottom friction s[real] is assignedto all sides Ns;

2. CALL set bottom friction(j,s): bottom friction is set for the j-th side (1 � j �Ns) to a constant value s[real];

3. CALL set bottom friction(a(:)): a spatially varying bottom friction a(Ns)

[real] is assigned to all sides Ns.




rB � 0�0 must be fulfilled. Ns can be determined by means of get nof edges(). In de-pendence on the computation of rB , different types of bottom friction laws can be applied.In general H in the aforementioned formulas should be replaced by ∆z j�kb� j�. In a two-dimensional depth-averaged simulation this is equivalent to the water depth, whereas inthe three-dimensional case this corresponds to the height of the lowermost face. kb� j� isobtained from get bottom face(j).

As an example please refer to paragraph Bottom friction in the validation document.

B.1.6 Interface set concentration



Assign concentration C for scalar species at prism centers:

1. CALL set concentration(s): a constant s[real] is assigned to the specie con-centration C for all scalar species Nc and all prisms I3 ;

2. CALL set concentration(m,s): a constant s[real] is assigned to the specieconcentration C for the m-th scalar specie (1 � m � Nc) and all prisms I3 ;

3. CALL set concentration(m,i,s): a constant s[real] is assigned to the specieconcentration C for the m-th scalar specie (1 � m � Nc) and all prisms belonging to thecomputational column above the i-th polygon (1 � i � Np);

4. CALL set concentration(m,i,k,s): a constant s[real] is assigned to thespecie concentration C for the m-th scalar specie (1 � m � Nc) in the k-th layer (kb�i� �k � kt�i�) above the i-th polygon (1 � i � Np);

5. CALL set concentration(m,a(:)): spatially varying data a(I3)[real] are as-signed to the specie concentration C for the m-th scalar specie (1 � m � Nc) at all I3

prisms;

6. CALL set concentration(m,i,a(:)): depth varying data a(Nz)[real] are as-signed to the specie concentration C for the m-th scalar specie (1 � m � Nc) and allprisms belonging to the computational column above the i-th polygon (1 � i � Np);

7. CALL set concentration(b(:,:)): spatially varying data b(I3�Nc)[real], dif-ferent for each of the Nc scalar species, are assigned to the concentration C for all Nc

species and all I3 prisms.

The total number of prisms I3 is given by get nof prisms(). Np can be determined bymeans of get nof polygons(), whereas Nc can be obtained from get nof species().




The number of vertical layers Nz can be retrieved using get nof layers(), while the bot-tom layer index kb�i� is given by get bottom prism(i) and kt�i� can be obtained fromget top prism(i).

B.1.7 Interface set concentration bc



Assign concentration C for scalar species at prism centers along open boundaries with pre-scribed water level:

1. CALL set concentration bc(s): a constant s[real] is assigned to the specieconcentration at lateral open boundaries for all scalar species Nc and all prisms I�

3above

open boundary polygons;

2. CALL set concentration bc(m,s): a constant s[real] is assigned to the specieconcentration at lateral open boundaries for the m-th scalar specie (1 � m � Nc) and allprisms I�

3above open boundary polygons;

3. CALL set concentration bc(m,i,s): a constant s[real] is assigned to thespecie concentration at lateral open boundaries for the m-th scalar specie (1 � m � Nc)and all prisms belonging to the computational column above the i-th (1 � i� N�

p) openboundary polygon;

4. CALL set concentration bc(m,i,k,s): a constant s[real] is assigned to thespecie concentration at lateral open boundaries for the m-th scalar specie (1 � m � Nc)in the k-th layer (kb�i�� k � kt�i�) above open boundary polygon i (1 � i � N�

p);

5. CALL set concentration bc(m,a(:)): spatially varying data a(I�3)[real] are

assigned to the specie concentration at lateral open boundaries for the m-th scalarspecie (1 � m � Nc) at all I�

3prisms above open boundary polygons;

6. CALL set concentration bc(m,i,a(:)): depth varying data a(Nz)[real] areassigned to the specie concentration at lateral open boundaries for the m-th scalarspecie (1 � m � Nc) and all prisms belonging to the computational column above thei-th open boundary polygon (1 � i � N�

p);

7. CALL set concentration bc(b(:,:)): spatially varying data b(I�3�Nc)[real],

different for each of the Nc scalar species, are assigned to the concentration at lateralopen boundaries for all Nc species and all I�

3prisms above open boundary polygons.

The total number of open boundary prisms is given by I�3� ∑

N�

p

i�1 �get nof prisms�i��1�.N�

p can be determined from get nof boundary polygons(), whereas Nc can be ob-tained from get nof species(). The number of vertical layers Nz can be retrieved using



get nof layers(), while the bottom layer index kb�i� is given by get bottom prism(i)

and kt�i� can be obtained from get top prism(i).

B.1.8 Interface set density

physical unit: —


Assign normalized water density ρ�ρ0 at prism centers:

1. CALL set density(s): a constant s[real] is assigned to the normalized waterdensity ρ�ρ0 for all prisms I3 ;

2. CALL set density(i,s): a constant s[real] is assigned to the normalized wa-ter density ρ�ρ0 for all prisms belonging to the computational column above the i-thpolygon (1 � i � Np);

3. CALL set density(i,k,s): a constant s[real] is assigned to the normalized wa-ter density ρ�ρ0 in the k-th layer (kb�i�� k � kt�i�) above the i-th polygon (1 � i � Np);

4. CALL set density(i,a(:)): depth varying data a(Nz)[real] are assigned tothe normalized water density ρ�ρ0 for all prisms belonging to the computational col-umn above the i-th polygon (1 � i � Np);

5. CALL set density(a(:)): spatially varying data a(I3)[real] are assigned to thenormalized water density ρ�ρ0 for all prisms I3 .

ρ � 0 must be fulfilled. The total number of prisms I3 is given by get nof prisms(),whereas Np can be determined by means of get nof polygons(). The number of ver-tical layers Nz can be retrieved using get nof layers(), while the bottom layer index kb�i�is given by get bottom prism(i) and kt�i� can be obtained from get top prism(i).

B.1.9 Interface set elevation

physical unit: m [reference level]


Assign water surface elevation η at polygon centers; positive values indicate that the watersurface is located above the reference level (e. g. mean sea level), whereas for negative valuesthe water surface lies below the reference level:

1. CALL set elevation(s): a constant s[real] is assigned to the water surface ele-vation η for all polygons Np;



2. CALL set elevation(i,s): a constant s[real] is assigned to the water surfaceelevation η at the i-th polygon (1 � i � Np);

3. CALL set elevation(a(:)): spatially varying data a(Np)[real] are assigned tothe water surface elevation η for each of the Np polygons.

Np is given by get nof polygons().

B.1.10 Interface set elevation bc



Assign water surface elevation η at polygon centers along open boundaries with prescribedwater level:

1. CALL set elevation bc(s): a constant s[real] is assigned to the water surfaceelevation η for all open boundary polygons N�

p;

2. CALL set elevation(i,s): a constant s[real] is assigned to the water surfaceelevation η at the i-th open boundary polygon (1 � i � N �

p);

3. CALL set elevation(a(:)): spatially varying data a(N�

p)[real] are assigned tothe water surface elevation η for each of the N�

p open boundary polygons.

N�

p is given by get nof boundary polygons().

B.1.11 Interface set flux limiter

physical unit: text string, no unit

default value: "0 (upwind)"

Select method to be used for advection of scalar species:

1. CALL set flux limiter(ch): a constant ch[character,len=80] is assigned tothe internal steering variable of the program; the following options are available at themoment:

(a) "Minmod";

(b) "van Leer";

(c) "Superbee".

Default is "0(upwind)", which corresponds to the classical method used in previousUnTRIM–versions.




B.1.12 Interface set grid file


default value: "untrim.grd" (if interface is not used)

Assign path and name of the grid file:

1. CALL set grid file(ch): a constant name ch[character] is assigned to thegrid file name.

B.1.13 Interface set horizontal velocity

physical unit: m/s


Assign the normal velocity component u at faces from user specified horizontal x-y-velocitycomponents:

1. CALL set horizontal velocity(uu,vv): a constant horizontal velocity withgiven x-y-components uu,vv[real] is assigned to the normal velocity componentu for all computational faces J3 ;

2. CALL set horizontal velocity(j,uu,vv): a constant horizontal velocity withgiven x-y-components uu,vv[real] is assigned to the normal velocity component ufor all computational faces lying above the j-th side (1 � j � Ns);

3. CALL set horizontal velocity(j,k,uu,vv): a constant horizontal velocitywith given x-y-components uu,vv[real] is assigned to the normal velocity com-ponent u for the computational face located in the k-th layer (kb� j� � k � kt� j�) abovethe j-th side (1 � j � Ns);

4. CALL set horizontal velocity(j,uu(:),vv): a depth-varying horizontal ve-locity with given variable x- and constant y-component uu(Nz),vv[real] is as-signed to the normal velocity component u for the computational faces lying abovethe j-th side (1 � j � Ns);

5. CALL set horizontal velocity(j,uu,vv(:)): a depth-varying horizontal ve-locity with given variable y- and constant x-component uu,vv(Nz)[real] is as-signed to the normal velocity component u for the computational faces lying abovethe j-th side (1 � j � Ns);

6. CALL set horizontal velocity(j,uu(:),vv(:)): a depth-varying horizon-tal velocity with given x-y-components uu(Nz),vv(Nz)[real] is assigned to thenormal velocity component u for the computational faces lying above the j-th side(1 � j � Ns);



7. CALL set horizontal velocity(uu(:),vv): a spatially varying horizontal ve-locity in x-direction and constant in y-direction with uu(J3),vv[real] is assigned tothe normal velocity component u at all the J3 computational faces;

8. CALL set horizontal velocity(uu,vv(:)): a spatially varying horizontal ve-locity in y-direction and constant in x-direction with uu,vv(J3)[real] is assigned tothe normal velocity component u at all the J3 computational faces;

9. CALL set horizontal velocity(uu(:),vv(:)): a spatially varying horizontalvelocity with given x-y-components uu(J3),vv(J3)[real] is assigned to the normalvelocity component u at all the J3 computational faces.

The total number of faces J3 is determined by means of get nof faces(), whereas Ns

is obtained from get nof egdes(). The number of vertical layers Nz can be retrievedusing get nof layers(), while the bottom layer index above edges kb� j� is given byget bottom face(j) and kt� j� can be obtained from get top face(j).

B.1.14 Interface set inflow bc

physical unit: m3/s


Assign discharge of water along open boundaries with prescribed flow (a positive value corre-sponds to inflow, a negative value is correlated with outflow):

1. CALL set inflow bc(s): a constant integral discharge s[real] is equally dis-tributed to all Nsf boundary edges with prescribed flow boundary condition;

2. CALL set inflow bc(j,s): a constant integral discharge s[real] is equally dis-tributed to all faces above edge j (Nsi �1� j�Nsf ) where the prescribed flow boundarycondition shall be applied;

3. CALL set inflow bc(j,k,s): a constant s[real] is assigned to the flow withinthe k-th layer (kb� j� � k � kt� j�) at open boundary edge j (Nsi � 1 � j � Nsf ) where theprescribed flow boundary condition shall be applied.

Nsi is given by get nof internal edges() and Nsf by Nsi�get nof inflow edges(),while the bottom layer index above edges kb� j� is given by get bottom face(j) and kt� j�can be obtained from get top face(j).



B.1.15 Interface set inflow cc



Assign prescribed concentration for species along open boundaries with prescribed flow:

1. CALL set inflow cc(s): a constant s[real] is assigned to the specie concentra-tion for all open boundary edges with prescribed flow boundary condition for all scalarspecies Nc;

2. CALL set inflow cc(m,s): a constant s[real] is assigned to the specie concen-tration for all open boundary edges with prescribed flow boundary condition for them-th scalar specie (1 � m � Nc);

3. CALL set inflow cc(m,j,s): a constant s[real] is assigned to the specie con-centration at the j-th edge (Nsi �1 � j � Nsf ) with prescribed flow boundary conditionfor the m-th scalar specie (1 � m � Nc);

4. CALL set inflow cc(m,j,k,s): a constant s[real] is assigned to the m-th specieconcentration (1 � m � Nc) at the j-th edge (Nsi � 1 � j � Nsf ) with prescribed flowboundary condition in the k-th layer (kb� j�� k � kt� j�).

Nsi is given by get nof internal edges() and Nsf by Nsi�get nof inflow edges(),while the bottom layer index above edges kb� j� is given by get bottom face(j)

and kt� j� can be obtained from get top face(j), whereas Nc can be retrieved usingget nof species().

B.1.16 Interface set input file


default value: "untrim.inp" (if interface is not used)

Assign path and name of the input file:

1. CALL set input file(ch): a constant name ch[character] is assigned to theinput file name.

B.1.17 Interface set point sources discharge

physical unit: m3/s




Assign point source discharge at prism centers (a positive value corresponds to inflow, anegative value is correlated with outflow):

1. CALL set point sources discharge(s): a constant source/sink discharges[real] is assigned to all source/sink locations Nd;

2. CALL set point sources discharge(n,s): the source/sink discharges[real]is assigned to the n-th source/sink location (1 � n � Nd);

3. CALL set point sources discharge(a(:)): a spatially varying discharge a(Nd)

[real] is assigned to all the Nd source/sink locations.

Nd is given by get nof point sources().

B.1.18 Interface set point sources concentration



Assign point source concentration C at prism centers:

1. CALL set point sources concentration(s): a constant s[real] is assignedto the source/sink concentration for all scalar species Nc and every source/sink loca-tion Nd;

2. CALL set point sources concentration(m,s): a constant s[real] is as-signed to the source/sink concentration for the m-th scalar specie (1 � m � Nc) andall source/sink locations Nd;

3. CALL set point sources concentration(n,m,s): a constant s[real] is as-signed to the source/sink concentration for the m-th scalar specie (1 � m � Nc) at then-th source/sink location (1 � n � Nd);

4. CALL set point sources concentration(m,a(:)): spatially varying data a(Nd)

[real] are assigned for the m-th specie (1 � m� Nc) to the Nd source/sink locations;

5. CALL set point sources concentration(b(:,:)): spatially varying datab(Nd,Nc)[real] are assigned for all species Nc and all source/sink locations Nd.

C � 0�0 must be fulfilled. Nd is given by get nof point sources() whereas Nc can beretrieved using get nof species(). During outflow, application of these routines has noeffect on computed results.



B.1.19 Interface set pressure



Assign non-hydrostatic normalized pressure component q at prism centers:

1. CALL set pressure(s): a constant s[real] is assigned to the normalized pres-sure component q for all computational prisms I3 ;

2. CALL set pressure(i,s): a constant s[real] is assigned to the normalized pres-sure component q for all prisms belonging to the computational column above polygoni (1 � i � Np);

3. CALL set pressure(i,k,s): a constant s[real] is assigned to the normalizedpressure component q for the k-th layer prism (kb�i� � k � kt�i�) above polygon i (1 �i � Np);

4. CALL set pressure(i,a(:)): depth varying data a(Nz)[real] are assigned tothe normalized pressure q for all prisms above polygon i (1 � i � Np);

5. CALL set pressure(a(:)): spatially varying data a(I3)[real] are assigned tothe normalized pressure q for all I3 computational prisms.

The total number of prisms I3 is given by get nof prisms(), whereas Np can be deter-mined from get nof polygons(). The number of vertical layers Nz can be retrieved usingget nof layers(), while the bottom layer index kb�i� is given by get bottom prism(i)

and kt�i� can be obtained from get top prism(i). To obtain the normalized pressure p,the (real physical) pressure has to be divided by ρ0.

B.1.20 Interface set pressure bc



Assign non-hydrostatic normalized pressure component q at prism centers along openboundaries with prescribed water level:

1. CALL set pressure bc(s): a constant s[real] is assigned to the normalizedpressure component q for all computational prisms I�

3along the open boundary;

2. CALL set pressure bc(i,s): a constant s[real] is assigned to the normalizedpressure component q for all prisms belonging to the computational column aboveopen boundary polygon i (1 � i � N�

p);



3. CALL set pressure bc(i,k,s): a constant s[real] is assigned to the normal-ized pressure component q for the k-th layer prism (kb�i�� k� kt�i�) above open bound-ary polygon i (1 � i � N�

p);

4. CALL set pressure bc(i,a(:)): depth varying data a(Nz)[real] are assignedto the normalized pressure q for all prisms above open boundary polygon i (1� i�N �

p);

5. CALL set pressure bc(a(:)): spatially varying data a(I�3)[real] are assigned

to the normalized pressure q for all I�3

computational prisms along the open boundary.

The total number of open boundary prisms is given by I�3� ∑

N�

p

i�1 �get nof prisms�i��1�. N�

p

can be determined from get nof boundary polygons(). The number of vertical layersNz can be retrieved using get nof layers(), while the bottom layer index kb�i� is given byget bottom prism(i) and kt�i� can be obtained from get top prism(i). To obtain thenormalized pressure p, the (real physical) pressure has to be divided by ρ0.

B.1.21 Interface set sediment

physical unit: —


Assign a factor to each of the scalar species which indicates active settling (� 0�0) or passivenon-settling (� 0�0) behaviour:

1. CALL set sediment(s): a constant factor s[real] is assigned to all species Nc;

2. CALL set sediment(a(:)): a species-dependent constant factor a(Nc)[real] isassigned to all species Nc;

3. CALL set sediment(m,s): a constant factor s[real] is assigned to the m-th scalarspecie (1 � m � Nc).

Nc is given by get nof species(). This interface allows the user to deal with severalsediment fractions differing in settling velocity by a constant factor.

B.1.22 Interface set settling velocity

physical unit: m/s


Assign a spatially varying settling velocity ws at the top of prisms for all actively settlingspecies:



1. CALL set settling velocity(s): a constant s[real] is assigned to the settlingvelocity ws for all computational prisms I3 ;

2. CALL set settling velocity(i,s): a constant s[real] is assigned to the set-tling velocity ws for all computational prisms located above polygon i (1 � i � Np);

3. CALL set settling velocity(i,k,s): a constant s[real] is assigned to thesettling velocity ws for the computational prism located in layer k (kb�i� � k � kt�i�)above polygon i (1 � i � Np);

4. CALL set settling velocity(i,a(:)): depth varying data a(Nz)[real] areassigned to the settling velocity ws for all prisms above polygon i (1 � i � Np);

5. CALL set settling velocity(a(:)): spatially varying data a(I3)[real] areassigned to the settling velocity ws for all prisms I3 .

The total settling velocity used in the computational run is determined by the values setusing this interface and multiplied with specie-dependent factor (CALL set sediment).ws � 0�0 must be fulfilled. The total number of prisms I3 is given by get nof prisms(),whereas Np can be determined by means of get nof polygons(). The number of verticallayers Nz can be retrieved using get nof layers(), while the bottom layer index kb�i� isgiven by get bottom prism(i) and kt�i� can be obtained from get top prism(i).

B.1.23 Interface set source file


default value: "untrim.srs" (if interface is not used)

Assign path and name of the sources and sinks file:

1. CALL set source file(ch): a constant name ch[character] is assigned to thesources and sinks file name.

B.1.24 Interface set surface alpha

physical unit: m/s


Assign surface flux parameter αT at polygon centers:

1. CALL set surface alpha(s): a constant s[real] is assigned to the surface fluxparameter αT for all scalar species Nc and all polygons Np;



2. CALL set surface alpha(m,s): a constant s[real] is assigned to the surfaceflux parameter αT for the m-th scalar specie (1 � m� Nc) and all polygons Np;

3. CALL set surface alpha(m,i,s): a constant s[real] is assigned to the surfaceflux parameter αT for the m-th scalar specie (1�m�Nc) in the i-th polygon (1� i�Np);

4. CALL set surface alpha(m,a(:)): spatially varying data a(Np)[real] are as-signed to the surface flux parameter αT for the m-th scalar specie (1 � m � Nc) at all Np

polygons;

5. CALL set surface alpha(b(:,:)): spatially varying data b(Np�Nc)[real], dif-ferent for each of the Nc scalar species, are assigned to the surface flux parameter α T

for all Nc species and all Np polygons.

αT � 0�0 must be fulfilled. Np can be determined by means of get nof polygons(),whereas Nc can be obtained from get nof species(). In dependence on the situationat the water surface boundary the settings for α T , βT (set surface beta) as well as CT

(set surface concentration) must be chosen in a coordinated way.As an example please refer to paragraph Flux of scalar species through the free-surface bound-

ary in the validation document.

B.1.25 Interface set surface beta

physical unit: m/s


Assign surface flux parameter βT at polygon centers:

1. CALL set surface beta(s): a constant s[real] is assigned to the surface fluxparameter βT for all scalar species Nc and polygons Np;

2. CALL set surface beta(m,s): a constant s[real] is assigned to the surface fluxparameter βT for the m-th scalar specie (1 �m � Nc) and all polygons Np;

3. CALL set surface beta(m,i,s): a constant s[real] is assigned to the surfaceflux parameter βT for the m-th scalar specie (1�m�Nc) in the i-th polygon (1� i�Np);

4. CALL set surface beta(m,a(:)): spatially varying data a(Np)[real] are as-signed to the surface flux parameter βT for the m-th scalar specie (1 � m � Nc) at all Np

polygons;

5. CALL set surface beta(b(:,:)): spatially varying data b(Np�Nc)[real], dif-ferent for each of the Nc scalar species, are assigned to the surface flux parameter βT forall Nc species and all Np polygons.




βT � 0�0 must be fulfilled. Np can be determined by means of get nof polygons(),whereas Nc can be obtained from get nof species(). In dependence on the situationat the water surface boundary the settings for βT , αT (set surface alpha) as well as CT

(set surface concentration) must be chosen in a coordinated way.As an example please refer to paragraph Flux of scalar species through the free-surface bound-

ary in the validation document.

B.1.26 Interface set surface concentration



Assign surface concentration CT at polygon centers:

1. CALL set surface concentration(s): a constant s[real] is assigned to thesurface concentration CT for all scalar species Nc and all polygons Np;

2. CALL set surface concentration(m,s): a constant s[real] is assigned to thesurface concentration CT for the m-th scalar specie (1 � m � Nc) and all polygons Np;

3. CALL set surface concentration(m,i,s): a constant s[real] is assigned tothe surface concentration CT for the m-th scalar specie (1 � m � Nc) in the i-th polygon(1 � i � Np);

4. CALL set surface concentration(m,a(:)): spatially varying data a(Np) [real]

are assigned to the surface concentration CT for the m-th scalar specie (1 � m � Nc) atall Np polygons;

5. CALL set surface concentration(b(:,:)): spatially varying data b(Np�Nc)

[real], different for each of the Nc scalar species, are assigned to the surface con-centration CT for all Nc species and all Np polygons.

Np can be determined by means of get nof polygons(), whereas Nc can be obtained fromget nof species(). In dependence on the situation at the water surface boundary the set-tings for CT , αT (set surface alpha) as well as βT (set surface beta) must be chosenin a coordinated way.

As an example please refer to paragraph Flux of scalar species through the free-surface bound-ary in the validation document.

B.1.27 Interface set turbulent h diffusivity

physical unit: m2/s






Assign horizontal turbulent diffusivity Kh at face centers:

1. CALL set turbulent h diffusivity(s): a constant s[real] is assigned to thehorizontal turbulent diffusivity Kh for all computational faces J3 ;

2. CALL set turbulent h diffusivity(j,s): a constant s[real] is assigned tothe horizontal turbulent diffusivity Kh for all computational faces above the j-th side(1 � j � Ns);

3. CALL set turbulent h diffusivity(j,k,s): a constant s[real] is assignedto the horizontal turbulent diffusivity Kh for the computational face within the k-thlayer (kb� j�� k � kt� j�) above the j-th side (1 � j � Ns);

4. CALL set turbulent h diffusivity(j,a(:)): depth varying data a(Nz) [real]

are assigned to the horizontal turbulent diffusivity Kh for all computational faces aboveside j (1 � j � Ns);

5. CALL set turbulent h diffusivity(a(:)): spatially varying data a(J3)[real]

are assigned to the horizontal turbulent diffusivity Kh for each of the J3 computationalfaces.

Kh � 0�0 must be fulfilled. The total number of faces J3 is determined by means ofget nof faces(), whereas Ns is obtained from get nof egdes(). The number of ver-tical layers Nz can be retrieved using get nof layers(), while the bottom layer in-dex above edges kb� j� is given by get bottom face(j) and kt� j� can be obtained fromget top face(j).

B.1.28 Interface set turbulent h viscosity

physical unit: m2/s


Assign horizontal turbulent viscosity νh at face centers:

1. CALL set turbulent h viscosity(s): a constant s[real] is assigned to thehorizontal turbulent viscosity νh for all computational faces J3 ;

2. CALL set turbulent h viscosity(j,s): a constant s[real] is assigned to thehorizontal turbulent viscosity νh for all computational faces located above the j-th edge(1 � j � Ns);

3. CALL set turbulent h viscosity(j,k,s): a constant s[real] is assigned tothe horizontal turbulent viscosity νh for computational face within the k-th layer(kb� j�� k � kt� j�) above the j-th edge (1 � j � Ns);



4. CALL set turbulent h viscosity(j,a(:)): depth varying data a(Nz)[real]

are assigned to the horizontal turbulent viscosity νh for all computational faces aboveedge j (1 � j � Np);

5. CALL set turbulent h viscosity(a(:)): spatially varying data a(J3)[real]

are assigned to the horizontal turbulent viscosity νh for each of the J3 computationalfaces.

νh � 0�0 must be fulfilled. The total number of faces J3 is determined by means ofget nof faces(), whereas Ns is obtained from get nof egdes(). The number of ver-tical layers Nz can be retrieved using get nof layers(), while the bottom layer in-dex above edges kb� j� is given by get bottom face(j) and kt� j� can be obtained fromget top face(j).

B.1.29 Interface set turbulent v diffusivity

physical unit: m2/s


Assign vertical turbulent diffusivity Kv at top of prisms:

1. CALL set turbulent v diffusivity(s): a constant s[real] is assigned to thevertical turbulent diffusivity Kv for all computational prisms I3 ;

2. CALL set turbulent v diffusivity(i,s): a constant s[real] is assigned tothe vertical turbulent diffusivity Kv for all computational prisms above the i-th polygon(1 � i � Np);

3. CALL set turbulent v diffusivity(i,k,s): a constant s[real] is assignedto the vertical turbulent diffusivity Kv for computational prism within the k-th layer(kb�i�� k � kt�i�) above the i-th polygon (1 � i � Np);

4. CALL set turbulent v diffusivity(i,a(:)): depth varying data a(Nz) [real]

are assigned to the vertical turbulent diffusivity Kv for all computational prisms abovepolygon i (1 � i � Np);

5. CALL set turbulent v diffusivity(a(:)): spatially varying data a(I3)[real]

are assigned to the vertical turbulent diffusivity Kv for each of the I3 computationalprisms.

Kv � 0�0 must be fulfilled. The total number of prisms I3 is given by get nof prisms(),whereas Np can be determined from get nof polygons(). The number of vertical layersNz can be retrieved using get nof layers(), while the bottom layer index kb�i� is given byget bottom prism(i) and kt�i� can be obtained from get top prism(i).



B.1.30 Interface set turbulent v viscosity

physical unit: m2/s


Assign vertical turbulent viscosity νv at the top of prisms:

1. CALL set turbulent v viscosity(s): a constant s[real] is assigned to thevertical turbulent viscosity νv for all computational prisms I3 ;

2. CALL set turbulent v viscosity(i,s): a constant s[real] is assigned to thevertical turbulent viscosity νv for all computational prisms located above the i-th poly-gon (1 � i � Np);

3. CALL set turbulent v viscosity(i,k,s): a constant s[real] is assigned tothe vertical turbulent viscosity νv for computational prism within the k-th layer (kb�i��k � kt�i�) above the i-th polygon (1 � i � Np);

4. CALL set turbulent v viscosity(i,a(:)): depth varying data a(Nz)[real]

are assigned to the vertical turbulent viscosity νv for all computational prisms abovepolygon i (1 � i � Np);

5. CALL set turbulent v viscosity(a(:)): spatially varying data a(I3)[real]

are assigned to the vertical turbulent viscosity νv for each of the I3 computationalprisms.

νv � 0�0 must be fulfilled. The total number of prisms I3 is given by get nof prisms(),whereas Np can be determined from get nof polygons(). The number of vertical layersNz can be retrieved using get nof layers(), while the bottom layer index kb�i� is given byget bottom prism(i) and kt�i� can be obtained from get top prism(i).

B.1.31 Interface set velocity

physical unit: m/s


Assign horizontal normal velocity component u at faces:

1. CALL set velocity(s): a constant s[real] is assigned to the normal velocitycomponent u for all computational faces J3 ;

2. CALL set velocity(j,s): a constant s[real] is assigned to the normal velocitycomponent u for all computational faces above the j-th side (1 � j � Ns);



3. CALL set velocity(j,k,s): a constant s[real] is assigned to the normal veloc-ity component u for the computational face lying in the k-th layer (kb� j� � k � kt� j�)above the j-th side (1 � j � Ns);

4. CALL set velocity(j,a(:)): depth varying data a(Nz)[real] are assigned tothe normal velocity component u for the computational faces lying above the j-th side(1 � j � Ns);

5. CALL set velocity(a(:)): spatially varying data a(J3)[real] are assigned tothe normal velocity component u at all the J3 computational faces.

The total number of faces J3 is determined by means of get nof faces(), whereas Ns

is obtained from get nof egdes(). The number of vertical layers Nz can be retrievedusing get nof layers(), while the bottom layer index above edges kb� j� is given byget bottom face(j) and kt� j� can be obtained from get top face(j).

B.1.32 Interface set wind friction

physical unit: —


Assign wind friction coefficient rT at sides/edges:

1. CALL set wind friction(s): a constant wind friction s[real] is assigned to allsides Ns;

2. CALL set wind friction(j,s): wind friction is set for the j-th side (1 � j � Ns) toa constant value s[real];

3. CALL set wind friction(a(:)): a spatially varying wind friction a(Ns)[real]

is assigned to all sides Ns.

rT � 0�0 must be fulfilled. Ns is obtained from get nof egdes(). In dependence on thecomputation of rT , different types of wind friction laws can be applied.

As an example please refer to paragraph Wind friction in the validation document.

B.1.33 Interface set wind velocity

physical unit: m/s


Assign components of the wind velocity (ua,va) at sides/edges:




1. CALL set wind velocity(wx,wy): constant x- and y-components wx,wy[real]are assigned to the wind velocity (ua,va) for all sides Ns;

2. CALL set wind velocity(j,wx,wy): x- and y-components wx,wy[real] are as-signed to the wind velocity (ua,va) at the j-th side (1 � j � Ns);

3. CALL set wind velocity(wx(:),wy): spatially varying x- and constant y-componentwx(Ns),wy[real] are assigned to the wind velocity (ua,va) for all sides Ns;

4. CALL set wind velocity(wx,wy(:)): spatially varying y- and constant x-componentwx,wy(Ns)[real] are assigned to the wind velocity (ua,va) for all sides Ns;

5. CALL set wind velocity(wx(:),wy(:)): spatially varying x- and y-componentswx(Ns),wy(Ns)[real] are assigned to the wind velocity (ua,va) for all sides Ns.

Ns is obtained from get nof egdes(). It is normally assumed, that the wind velocity isknown 10 m above the free water surface.



B.2 Get-functions

The get-functions are grouped according to their functionality:

� unstructured orthogonal grid data (horizontal structure)

– static size

� get nof boundary polygons

� get nof inflow edges

� get nof internal edges

� get nof edges

� get nof polygons

� get nof vertices

– dynamic size

� get nof wet edges

� get nof wet polygons

– static variables

� get dx min

� get hland

� get location

– static structure

� get adjacent polygon

� get edge begin

� get edge end

� get left polygon

� get right polygon

� get polygon

� get polygon edge

� get polygon vertex

– static geometry

� get dx

� get dy

� get edge center

� get polygon area

� get polygon center

� get vertex coordinates

� get x vertex coordinate

� get y vertex coordinate

– dynamic geometry



� get depth

� get depth at edge

� computational grid

– static size

� get nof faces

� get nof layers

� get nof prisms

– dynamic size

� get nof wet faces

� get nof wet prisms


� get dz min

– static structure

� get layer

– dynamic structure

� get bottom face

� get bottom prism

� get top face

� get top prism

– static geometry

� get layer interface

– dynamic geometry

� get face height

� get prism height

� get volume

� computational steering data


� get flux limiter

� get nof point sources

� get nof species

– logical data

� sediment

� with hydrodynamic pressure

� with scalar transport



– time stepping information

� get time step

– iterative solvers

� get elevation tolerance

� get pressure tolerance

� get iterations

� get maximum iteration

� computational results

– hydrodynamics

� get bottom stress

� get bottom flux

� get elevation

� get horizontal velocity

� get horizontal velocity x

� get horizontal velocity y

� get pressure

� get surface flux

� get velocity

� get vertical velocity

� get wind stress

– species

� get concentration

� get mass

� computational parameters and coefficients

– scalars

� get dt min

� get gravity

� get chezy

� get turbulent h diffusivity

� get turbulent h viscosity

� get radiation time

� get theta

� get turbulent v diffusivity

� get turbulent v viscosity

– equation of state data



� get density

– turbulence related data

� get turbulent h diffusivity

� get turbulent h viscosity

� get turbulent v diffusivity

� get turbulent v viscosity

– data related to sources and sinks

� get source concentration

� get source discharge

� get source layer

� get source polygon

– hydrodynamic boundary data

� get bottom friction

� get wind friction

� get wind velocity

� get wind velocity x

� get wind velocity y

� get atmospheric pressure

– species boundary data

� get bottom alpha

� get bottom beta

� get bottom concentration

� get surface alpha

� get surface beta

� get surface concentration

– sediment data

� get settling velocity

All get routines available to the user are subsequently described and listed in alphabeticalorder.

B.2.1 Interface get adjacent polygon

physical unit: —

Evaluate indices of adjacent polygons:

1. get adjacent polygon(i,l): returns scalar s[int] with index of adjacent poly-gon for the l-th (1 � l � Si) side of polygon i (1 � i � Np);



2. get adjacent polygon(i): array a(Si)[int] of adjacent polygons for the i-thpolygon (1 � i � Np) is returned, where a(l) is the adjacent polygon index for thel-th side;

3. get adjacent polygon(): array b(Np,4)[int] of adjacent polygons for all Np

polygons is returned, where b(i,l) represents the index of the polygon which is ad-jacent to the l-th (1 � l � Si) side of polygon i.

The index of an adjacent polygon is less than or equal to zero if there is no adjacent polygonavailable. The latter is the case if the side of a polygon is a boundary edge. The number ofsides Si for polygon i can be determined by means of get nof edges(i), whereas the totalnumber of polygons Np can be retrieved from get nof polygons().

B.2.2 Interface get atmospheric pressure


Retrieve normalized atmospheric pressure pa at polygon centers:

1. get atmospheric pressure(i): returns scalar s[real] with pa at polygon i (1 �i � Np);

2. get atmospheric pressure(): array a(Np)[real] is returned with pa at all Np

polygons;

3. get atmospheric pressure(x,y): returns scalar s[real] with pa at positionx,y [real].

To determine Np use get nof polygons(). Please notice that to obtain the (real physical)atmospheric pressure the normalized atmospheric pressure pa has to be multiplied by ρ0.

B.2.3 Interface get bottom alpha

physical unit: m/s

Retrieve bottom flux parameter αB at polygon centers:

1. get bottom alpha(m,i): returns scalar s[real] with αB for the m-th specie (1 �m � Nc) at the i-th polygon (1 � i � Np);

2. get bottom alpha(m): array a(Np)[real] is returned with αB for the m-th specie(1 � m � Nc) at all Np polygons, where a(i) contains αB for the i-th polygon;

3. get bottom alpha(): array b(Np�Nc)[real] is returned, where b(i,m) containsαB for specie m at polygon i;



4. get bottom alpha(m,x,y): returns scalar s[real]with αB for the m-th specie (1�m � Nc) at position x,y[real].

Nc can be retrieved using get nof species(), Np is obtained from get nof polygons().

B.2.4 Interface get bottom beta

physical unit: m/s

Retrieve bottom flux parameter βB at polygon centers:

1. get bottom beta(m,i): returns scalar s[real] with βB for the m-th specie (1 �m � Nc) at the i-th polygon (1 � i � Np);

2. get bottom beta(m): array a(Np)[real] is returned with βB for the m-th specie(1 � m � Nc) at all Np polygons, where a(i) contains βB for the i-th polygon;

3. get bottom beta(): array b(Np�Nc)[real] is returned, where b(i,m) containsβB for specie m at polygon i;

4. get bottom beta(m,x,y): returns scalar s[real] with βB for the m-th specie (1 �m � Nc) at position x,y[real].


B.2.5 Interface get bottom concentration


Retrieve bottom concentration CB at polygon centers:

1. get bottom concentration(m,i): returns scalar s[real] with CB for the m-thspecie (1 � m � Nc) at the i-th polygon (1 � i � Np);

2. get bottom concentration(m): array a(Np)[real] is returned with CB for them-th specie (1�m�Nc) at all Np polygons, where a(i) contains CB for the i-th polygon;

3. get bottom concentration(): array b(Np�Nc)[real] is returned, where b(i,m)contains CB for specie m at polygon i;

4. get bottom concentration(m,x,y): returns scalar s[real]with CB for the m-thspecie (1 � m � Nc) at position x,y[real].




B.2.6 Interface get bottom face

physical unit: —

Evaluate layer index k (1 � k � Nz) for the lowermost (bottom) face above the side of a poly-gon:

1. get bottom face(j): returns scalar s[int] with bottom face layer index k for sidej (1 � j � Ns);

2. get bottom face(): array a(Ns)[int] is returned with bottom face layer indicesfor all Ns sides, where a(j) represents the bottom layer index for the j-th side of thegrid.

The total number of sides (edges) Ns can be determined calling get nof edges().

B.2.7 Interface get bottom flux

physical unit: ”physical unit of specie used”�m3

Retrieve computed bottom flux qB at polygon centers:

1. get bottom flux(m,i): returns scalar s[real] with qB for the m-th specie (1 �m � Nc) at the i-th polygon (1 � i � Np);

2. get bottom flux(m): scalar s[real] is returned with integral bottom flux qB forthe m-th specie (1 � m � Nc);

3. get bottom flux(): array a(Nc)[real] is returned, where a(m) is the integralbottom flux qB for specie m.

Nc can be retrieved using get nof species(), Np is given by get nof polygons().Notice: Flux data returned by this function are not precisely equal to the simulated flux,

due to the sub-stepping algorithm used in the solver for the transport equation.

B.2.8 Interface get bottom friction

physical unit: —

Retrieve bottom friction coefficient rB at sides/edges:

1. CALL get bottom friction(j): returns scalar s[real] with rB at the j-th side(1 � j � Ns);

2. CALL get bottom friction(): array a(Ns)[real] is returned with rB at all Ns

sides where a(j) contains rB for the j-th side.

Ns can be determined by means of get nof edges().



B.2.9 Interface get bottom prism

physical unit: —

Evaluate layer index k (1 � k � Nz) for the lowermost (bottom) prism above a polygon:

1. get bottom prism(i): returns scalar s[int] with bottom prism layer index k forpolygon i (1 � i � Np);

2. get bottom prism(): array a(Np)[int] is returned with bottom prism layer in-dices for all Np polygons, where a(i) represents the bottom layer index for the i-thpolygon;

3. get bottom prism(x,y): returns scalar s[int] with bottom prism layer index kfor position x,y[real] (if the position is out of the model area, k � 0 will be returnedinstead).

The total number of polygons Np can be determined by means of get nof polygons().

B.2.10 Interface get bottom stress


Retrieve (normalized) normal component of bottom shear stress at sides/edges:

1. get bottom stress(j): return scalar s[real] for the j-th side (edge) (1 � j � Ns);

2. get bottom stress(): array a(Ns)[real] is returned with normal component ofbottom stress at all Ns sides (edges), where a(j) is the respective value for the j-thside.

Ns can be obtained from get nof edges(). To obtain the (real physical) normal componentof the bottom shear stress τB , the retrieved normalized one has to be multiplied by ρ0.

B.2.11 Interface get chezy

physical unit: m1/2/s

Retrieve constant Chezy friction factor (prescribed in steering data file untrim.inp):

1. get chezy(): scalar s[real] is returned with actual value used for the Chezy coef-ficient.

Normally the bottom friction coefficient is varying in space and time. Use get bottom friction

under these circumstances.



B.2.12 Interface get concentration


Retrieve specie concentration C at prism centers:

1. get concentration(m,i,k): returns scalar s[real] with C for the m-th specie(1 � m � Nc) at polygon i (1 � i � Np) within layer k (kb�i�� k � kt�i�);

2. get concentration(m,i): array a(Nz)[real] is returned with C for specie m (1�m�Nc) at all prisms above polygon i (1 � i�Np), where a(k) corresponds to C withinthe k-th layer (kb�i�� k � kt�i�);

3. get concentration(m): array a(I3)[real] is returned with C for the m-th specie(1 � m � Nc) at all I3 computational prisms;

4. get concentration(): array b(I3�Nc)[real] is returned with C for all species Nc

at all computational prisms I3 .

5. get concentration(m,x,y,z): returns scalar s[real] with C for the m-th specie(1 � m � Nc) at position x,y,z[real];

6. get concentration(m,x,y): array a(Nz)[real] is returned with C for the m-thspecie (1 � m � Nc) for all computational prisms above position x,y[real].

Nc is retrieved from get nof species(), Np from get nof polygons() and Nz fromget nof layers(). I3 can be determined using get nof prisms(). The bottom layerindex kb�i� for polygon i can be determined using get bottom prism(i) and kt�i� fromget top prism(i).

B.2.13 Interface get density

physical unit: —

Retrieve normalized water density ρ�ρ0 at prism centers:

1. get density(i,k): returns scalar s[real] with ρ�ρ0 at the i-th polygon (1 � i �Np) within layer k (kb�i�� k � kt�i�);

2. get density(i): array a(Nz) is returned with ρ�ρ0 for all computational prismsabove polygon i (1� i�Np), where a(k) corresponds to the normalized density withinlayer k (kb�i�� k � kt�i�);

3. get density(): array a(I3) is returned with ρ�ρ0 for all computational prisms I3 ;

4. get density(x,y,z): returns scalar s[real]with ρ�ρ0 at position x,y,z[real];



5. get density(x,y): array a(Nz) is returned with ρ�ρ0 for all computational prismsabove position x,y.

The total number of prisms I3 is given by get nof prisms(), whereas Np can be de-termined by means of get nof polygons(). The number of vertical layers Nz canbe retrieved using get nof layers(), while the bottom layer index kb�i� is given byget bottom prism(i) and kt�i� can be obtained from get top prism(i).

B.2.14 Interface get depth

physical unit: m

Extract depth at polygons:

1. get depth(i): returns scalar s[real] with depth at polygon i (1 � i � Np);

2. get depth(): array a(Np)[real] is returned with depth data for all Np polygons,a(i) is equivalent to the depth at the i-th polygon;

3. get depth(x,y): returns scalar s[real]with (polygon) depth at positionx,y[real](if the position is out of the model area, hL will be returned).

The total number of polygons Np can be determined by means of get nof polygons().The depth for permanently dry land hL can be obtained from get hland().

B.2.15 Interface get depth at edge

physical unit: m

Determine bathymetric depth h at sides/edges:

1. get depth at edge(j): returns scalar s[real] with the bathymetric depth h j forthe j-th side (1 � j � Ns);

2. get depth at edge(): array a(Ns)[real] is returned with bathymetric depth forall Ns sides, where a(j) represents the bathymetric depth for the j-th side.




B.2.16 Interface get dt min

physical unit: s

Extract minimum allowed time substep size ∆τ:

1. get dt min(): return scalar s[real] with ∆τ, the minimum allowed substep sizefor advective scalar transport.

B.2.17 Interface get dx

physical unit: m

Retrieve distance between adjacent polygon centers δ:

1. get dx(j): returns scalar s[real] with distance between the polygon centers adja-cent to the j-th side (1 � j � Ns);

2. get dx(): array a(Ns)[real] is returned with δ for all Ns sides, where a(j) corre-sponds to the center distance between polygons adjacent to the j-th side.

The total number of sides (edges) Ns can be determined calling get nof edges(). Thecondition δ � δmin always holds true. The minimum allowed distance between polygoncenters δmin can be obtained from get dx min().

B.2.18 Interface get dx min

physical unit: m

Return minimum allowed distance δmin between adjacent polygon centers:

1. get dx min(): returns scalar s[real] with minimum allowed distance δmin be-tween adjacent polygon centers.

The distance δ between polygon centers adjacent to sides is limited by δmin for reasons ofnumerical stability. δmin must be prescribed by the user in the input data file.

B.2.19 Interface get dy

physical unit: m

Extract side length λ:

1. get dy(j): returns scalar s[real] with the length of the j-th side (1 � j � Ns);



2. get dy(): array a(Ns)[real] is returned with λ for all Ns sides, where a(j) corre-sponds to the length of the j-th side.


B.2.20 Interface get dz min

physical unit: m

Return minimum allowed water depth Hmin:

1. get dz min(): returns scalar s[real] with minimum allowed water depth Hmin atcomputational points.

A computational point is considered to be wet (or active) if H � Hmin holds true. Otherwisethe computational point is treated as dry (or passive). Due to reasons of numerical stabilitythe minimum allowed water depth must be always larger than zero. Hmin is prescribed bythe user in the input data file.

B.2.21 Interface get edge begin

physical unit: —

Return index for the first vertex of a side (edge):

1. get edge begin(j): returns scalar s[int] with the first vertex index for the j-thside (1 � j � Ns);

2. get edge begin(): array a(Ns)[int] is returned with all indices of the first vertexfor all Ns sides, where a(j) corresponds to the index of the first vertex for the j-th side.

The total number of sides (edges) Ns can be determined calling get nof edges().get nof vertices() returns the total number of vertices Nv instead.

B.2.22 Interface get edge center

physical unit: m [origin]

Retrieve edge (side) center coordinates x j�y j:

1. get edge center(j): array a(2)[real] is returned with the center coordinatesfor the j-th edge (1 � j � Ns), where a(1) corresponds to x j and a(2) to y j;



2. get edge center(): array b(Ns,2)[real] is returned with the center coordinatesfor all Ns sides, wherein b(j,1) and b(j,2) are the center coordinates x j�y j for thej-th edge.

The total number of sides (edges) Ns can be determined calling get nof edges(). The edgecenter is located in the middle of an edge.

B.2.23 Interface get edge end

physical unit: —

Return index for the second vertex of a side (edge):

1. get edge end(j): returns scalar s[int] with the second vertex index for the j-thside (1 � j � Ns);

2. get edge end(): array a(Ns)[int] is returned with all indices of the second vertexfor all Ns sides, where a(j) corresponds to the index of the second vertex for the j-thside.

The total number of sides (edges) Ns can be determined calling get nof edges().get nof vertices() returns the total number of vertices Nv instead.

B.2.24 Interface get elevation


Retrieve water surface elevation η at polygon centers:

1. get elevation(i): returns scalar s[real] with water surface elevation η i at thei-th polygon (1 � i � Np);

2. get elevation(): array a(Np)[real] is returned with η for all polygons Np,where a(i) corresponds the water surface elevation at polygon i;

3. get elevation(x,y): returns scalar s[real] with water surface elevation η atx,y[real] for positions inside the modelling domain, or hL otherwise.

Np can be obtained from get nof polygons(). hL can be retrieved using get hland().



B.2.25 Interface get elevation tolerance

physical unit: —

Retrieve tolerance εη for free-surface iterative solver:

1. get elevation tolerance(): returns scalar s[real] with actual εη used in theprogram.

εη is specified by the user in the input data file "untrim.inp".

B.2.26 Interface get face height

physical unit: m

Extract height ∆z for faces above sides/edges:

1. get face height(j,k): returns scalar s[real]with the actual height ∆z j�k for j-thside (1 � j � Ns) and k-th layer (kb� j�� k � kt� j�);

2. get face height(j): array a(Nz)[real] is returned, wherein a(k) correspondsto the actual face height of the k-th layer for side j;

3. get face height(): array b(J3)[real] with the actual height for all faces J3 isretrieved.

∆z j�k is zero if the respective face is either a solid wall (boundary) or a dry (or passive)computational point. The total number of sides (edges) Ns can be determined callingget nof edges(), whereas the number of level surfaces (layers) Nz can be obtained fromget nof layers(). J3 can be obtained from get nof faces(), while the bottom layerindex kb� j� is given by get bottom face(j) and the respective surface layer index resultsfrom get top face(j).

B.2.27 Interface get flux limiter


Retrieve name of flux limiter used to compute advection for scalar species:

1. CALL get flux limiter( ): returns scalar ch[character,len=80] with thename of the flux limiter actually used:

(a) "0(upwind)";

(b) "Minmod";

(c) "van Leer";

(d) "Superbee".



B.2.28 Interface get gravity

physical unit: m/s2

Extract gravitational acceleration g:

1. get gravity(): returns scalar s[real] with actual value for g used in the simula-tion.

g is internally computed from the modelling domains (mean) geographic latitude Φ.

B.2.29 Interface get hland


Retrieve depth for permanently dry land hL :

1. get hland(): returns scalar s[real] with the value for the bathymetric depthwhich is used to characterize permanently dry land hL .

Locations with bathymetric depth h � hL are considered to become eventually wet (or active).All others are considered to be permanently dry land.

B.2.30 Interface get horizontal diffusivity

physical unit: m2/s

Retrieve scalar constant for horizontal diffusivity:

1. get horizontal diffusivity(): returns scalar s[real] with scalar constanthorizontal diffusivity.

This value is set by the user in the input file "untrim.inp" and is treated as a constant forall computational points.

Notice: The total horizontal diffusivity applied during computation is the sum of thisvalue plus its spatially varying contribution set using CALL set turbulent h diffusivity.

B.2.31 Interface get horizontal velocity

physical unit: m/s

Retrieve horizontally interpolated velocity components u (x-direction) and v (y-direction):



1. get horizontal velocity(x,y,z): returns array a(2)[real] with horizontalvelocity components at position x,y,z[real], where a(1) and a(2) correspond tou and v respectively;

2. get horizontal velocity(x,y): returns array b(Nz,2)[real] with u and v forall layers above position x,y[real], where b(k,:) corresponds to the velocity com-ponents within the k-th layer (kb�i�� k � kt�i�);

3. get horizontal velocity(x,y,z,i): returns array a(2)[real] with u and vat position x,y,z[real], which is assumed to be located in a computational prismabove the i-th polygon (1 � i � Np);

4. get horizontal velocity(x,y,i,k): returns array a(2)[real] with u and vat position x,y[real], which is assumed to lie inside polygon i (1 � i � Np) withinlayer k (kb�i�� k � kt�i�);

5. get horizontal velocity(x,y,i): returns array b(Nz,2)[real] with u and vfor all layers above position x,y[real], which is assumed to lie inside polygon i(1 � i � Np), where b(k,:) corresponds to the velocity components within the k-thlayer (kb�i�� k � kt�i�).

Np can be determined from get nof polygons(), kb�i� from get bottom prism(i) andkt�i� from get top prism(i). Nz is given by get nof layers(). Please notice that u and vare interpolated in horizontal direction from the projected horizontal velocities extrapolatedto the vertices. In z-direction no interpolation scheme is applied.

B.2.32 Interface get horizontal velocity x

physical unit: m/s

Retrieve horizontally interpolated velocity u (x-direction):

1. get horizontal velocity x(x,y,z): scalar s[real] is returned with horizon-tal velocity component u at position x,y,z[real];

2. get horizontal velocity x(x,y): returns array a(Nz)[real]with u for all lay-ers above position x,y[real], where a(k) corresponds to the u-component withinthe k-th layer (kb�i�� k � kt�i�);

3. get horizontal velocity x(x,y,z,i): scalar s[real] is returned with u at po-sition x,y,z[real], which is assumed to be located in a computational prism abovethe i-th polygon (1 � i � Np);

4. get horizontal velocity x(x,y,i,k): scalar s[real] is returned with u at po-sition x,y[real], which is assumed to lie inside polygon i (1 � i � Np) within layer k(kb�i�� k � kt�i�);



5. get horizontal velocity x(x,y,i): returns array a(Nz)[real] with u for alllayers above position x,y[real], which is assumed to lie inside polygon i (1 � i �Np), where a(k) corresponds to the u-component within the k-th layer (kb�i�� k� kt�i�).

Np can be determined from get nof polygons(), kb�i� from get bottom prism(i) andkt�i� from get top prism(i). Nz is given by get nof layers(). Please notice that u isinterpolated in horizontal direction from the projected horizontal velocities extrapolated tothe vertices. In z-direction no interpolation scheme is applied.

B.2.33 Interface get horizontal velocity y

physical unit: m/s

Retrieve horizontally interpolated velocity v (y-direction):

1. get horizontal velocity y(x,y,z): scalar s[real] is returned with horizon-tal velocity component v at position x,y,z[real];

2. get horizontal velocity y(x,y): returns array a(Nz)[real]with v for all lay-ers above position x,y[real], where a(k) corresponds to the v-component withinthe k-th layer (kb�i�� k � kt�i�);

3. get horizontal velocity y(x,y,z,i): scalar s[real] is returned with v at po-sition x,y,z[real], which is assumed to be located in a computational prism abovethe i-th polygon (1 � i � Np);

4. get horizontal velocity y(x,y,i,k): scalar s[real] is returned with v at po-sition x,y[real], which is assumed to lie inside polygon i (1 � i � Np) within layer k(kb�i�� k � kt�i�);

5. get horizontal velocity y(x,y,i): returns array a(Nz)[real] with v for alllayers above position x,y[real], which is assumed to lie inside polygon i (1 � i �Np), where a(k) corresponds to the v-component within the k-th layer (kb�i�� k� kt�i�).

Np can be determined from get nof polygons(), kb�i� from get bottom prism(i) andkt�i� from get top prism(i). Nz is given by get nof layers(). Please notice that v isinterpolated in horizontal direction from the projected horizontal velocities extrapolated tothe vertices. In z-direction no interpolation scheme is applied.

B.2.34 Interface get horizontal viscosity

physical unit: m2/s

Retrieve scalar constant for horizontal viscosity:



1. get horizontal viscosity(): returns scalar s[real] with scalar constant hori-zontal viscosity.


Notice: The total horizontal viscosity applied during computation is the sum of this valueplus its spatially varying contribution set using CALL set turbulent h viscosity.

B.2.35 Interface get iterations

physical unit: —

Retrieve actual number of iterations done by the iterative solvers:

1. get iterations(): returns array a(1|2)[real] with the actual number of itera-tions used in the program:

(a) a(1) contains the number of iterations used to compute the free surface;

(b) a(2) contains the number of iterations used to compute the hydrodynamic pres-sure.

In situations when the pressure is assumed to by hydrostatic an array of length 1 isreturned, whereas its length is 2 in non-hydrostatic situations!

Which approximation for the pressure is used in the computation can be inquired by meansof with hydrodynamic pressure.

B.2.36 Interface get layer

physical unit: —

Return layer index k for a given depth z:

1. get layer(z): for a given depth z[real] a scalar s[int] is returned, which rep-resents the actual layer index k (1 � k �Nz) for a given depth z; if k � 0 is returned z liesbelow the lowermost (deepest) layer.

The number of level surfaces (layers) Nz can be obtained from get nof layers().



B.2.37 Interface get layer interface


Retrieve z-coordinate of level surface:

1. get layer interface(k): returns scalar s[real] with z-coordinate zk� 12

for thek-th level surface (1 � k � Nz);

2. get layer interface(): array a(0:Nz)[real] is returned, wherein a(0) corre-sponds to the maximum bathymetric depth and a(k) is the z-coordinate zk� 1

2for the

k-th level surface, i. e. a�Nz� is equivalent to hL .

The number of level surfaces (layers) Nz can be obtained from get nof layers().

B.2.38 Interface get left polygon

physical unit: —

Return polygon index i for the left polygon adjacent to a given side (edge):

1. get left polygon(j): returns scalar s[int]with index i for the left neighbouringpolygon adjacent to the j-th side (1 � j � Ns);

2. get left polygon(): array a(Ns)[int] with indices for left neighbouring poly-gons for all Ns sides is returned, wherein a(j) is the polygon index for the left neigh-bour of the j-th side.

If i � 0 is returned no neighbouring polygon exists to the left, which may be the casefor e. g. sides along boundaries. The total number of sides (edges) Ns is obtained fromget nof edges().

B.2.39 Interface get location


Extract location name for the modelling domain:

1. get location(): returns c*80[char] with the name of the modelling domain.

The name of the modelling domain is specified by the user in the grid input file.



B.2.40 Interface get mass


Determine specie (salt, heat, sediment, etc.) mass present:

1. get mass(m,i,k): returns scalar s[real] with specie mass present for the m-thspecie (1 � m � Nc) at the i-polygon (1 � i � Np) within layer k (kb�i�� k � kt�i�);

2. get mass(m,i): returns scalar s[real] with accumulated specie mass for the m-thspecie (1�m�Nc) available in the computational column above polygon i (1� i�Np);

3. get mass(m): returns scalar s[real] with accumulated specie mass for the m-thspecie (1 � m � Nc) within the overall computational domain;

4. get mass(): array a(Nc)[real] is returned with accumulated specie masses forall Nc species within the overall computational domain, where a(m) represents theaccumulated mass for the m-th specie.

Nc can be retrieved using get nof species() and Np from get nof polygons(). kb�i�results from get bottom prism(i) and kt�i� from get top prism(i).

B.2.41 Interface get maximum iteration

physical unit: —

Retrieve maximum number of iterations nε for iterative solvers:

1. get maximum iteration(): returns scalar s[int] with nε used in the program.

This value is set by the user in the input file "untrim.inp"

B.2.42 Interface get nof boundary polygons

physical unit: —

Retrieve the number of polygons N �

p located along the open boundary of the modelling do-main with prescribed water level.

1. get nof boundary polygons(): returns scalar s[int] with actual number ofboundary polygons N�

p.

This value is prescribed by the user in the grid input file untrim.grd¨.



B.2.43 Interface get nof edges

physical unit: —

Retrieve number of sides (edges):

1. get nof edges(i): returns scalar s[int] with the actual number of sides Si forpolygon i (1 � i � Np);

2. get nof edges(): array a(Np)[int] with actual number of sides for all polygonsNp is returned, where a(i) contains the number of sides for the i-th polygon.

The total number of polygons Np can be retrieved calling get nof polygons().

B.2.44 Interface get nof faces

physical unit: —

Extract number of computational faces:

1. get nof faces(j): returns scalar s[int] with number of faces Jj above the j-thside (1 � j � Ns);

2. get nof faces(): a scalar s[int] with the total number of faces J3 above all Ns

sides is returned.

The total number of sides (edges) Ns is obtained from get nof edges().

B.2.45 Interface get nof inflow edges

physical unit: —

Extract number of inflow edges along the open boundary of the model domain with pre-scribed flow.

1. get nof internal edges(): returns scalar s[int] with number of edges nsf withprescribed flow.

This value is (indirectly) set by the user in the grid file "untrim.grd". Please notice thatNsf � Nsi �nsf holds.



B.2.46 Interface get nof internal edges

physical unit: —

Extract number of internal edges (internal edges are sides shared by two polygons):

1. get nof internal edges(): returns scalar s[int] with number of internal edgesNsi .

This value is set by the user in the grid file "untrim.grd".

B.2.47 Interface get nof layers

physical unit: —

Retrieve the number of level surfaces Nz:

1. get nof layers(): returns scalar s[int] with the number of level surfaces Nz.

This value is prescribed by the user in the input file "untrim.inp".

B.2.48 Interface get nof point sources

physical unit: —

Retrieve the number of point sources Nd:

1. get nof point sources(): returns scalar s[int] with the number of pointsources Nd.

This value is prescribed by the user in the input file "untrim.srs".

B.2.49 Interface get nof polygons

physical unit: —

Retrieve the number of polygons Np:

1. get nof polygons(): returns scalar s[int] with the number of polygons Np.

This value is prescribed by the user in the grid file "untrim.grd".



B.2.50 Interface get nof prisms

physical unit: —

Extract the number of computational prisms:

1. get nof prisms(i): returns scalar s[int] with number of prisms Ii above the i-thpolygon (1 � i � Np);

2. get nof prisms(): a scalar s[int] with the total number of computational prismsI3 above all Np polygons is returned;

3. get nof prisms(x,y): returns scalar s[int] with the number of computationalprisms Ii above position x,y[real] (if the position is out of the model area, Ii � 0will be returned instead).


B.2.51 Interface get nof species

physical unit: —

Retrieve number of species Nc:

1. get nof species(): a scalar s[int] with the actual number of species Nc is re-turned.


B.2.52 Interface get nof vertices

physical unit: —

Retrieve number of vertices:

1. get nof vertices(i): returns scalar s[int]with number of vertices Si for the i-thpolygon (1 � i � Np);

2. get nof vertices(): returns scalar s[int]with the overall number of vertices Nv.

This value is set by the user in the grid file "untrim.grd".The total number of polygons Np can be retrieved calling get nof polygons().



B.2.53 Interface get nof wet edges

physical unit: —

Determine the actual number of wet sides/edges:

1. get nof wet edges(i): returns scalar s[int] with number of wet sides (edges)for the i-th polygon (1 � i � Np);

2. get nof wet edges(): returns scalar s[int]with the overall number of wet edges.

The total number of polygons Np can be retrieved calling get nof polygons(). An edge jis considered wet if Hj � Hmin holds true.

B.2.54 Interface get nof wet faces

physical unit: —

Determine the actual number of wet faces:

1. get nof wet faces(j): returns scalar s[int]with number of wet faces for the j-thside (1 � j � Ns);

2. get nof wet faces(): returns scalar s[int] with the overall number of wet faces.

The total number of sides (edges) Ns is obtained from get nof edges(). A face (edge) j atlayer k is considered wet if ∆z j�k � Hmin holds true.

B.2.55 Interface get nof wet polygons

physical unit: —

Determine the actual number of wet polygons:

1. get nof wet polygons(): returns scalar s[int] with the overall number of wetpolygons.

An polygon i is considered wet if Hi � Hmin holds true.



B.2.56 Interface get nof wet prisms

physical unit: —

Determine the actual number of wet prisms:

1. get nof wet prisms(i): returns scalar s[int] with number of wet prisms abovepolygon i (1 � i � Np);

2. get nof wet prisms(): returns scalar s[int] with the overall number of wetprisms;

3. get nof wet prisms(x,y): returns scalar s[int] with the number of wet prismsabove position x,y[real] (if the position is out of the model area, zero will be re-turned instead).

The total number of polygons Np can be retrieved calling get nof polygons(). A prismis considered being wet if ∆zi�k �Hmin holds true.

B.2.57 Interface get polygon

physical unit: —

Determine polygon index i from given position x�y:

1. get polygon(x,y): returns scalar s[int] with index i of polygon whereinx,y[real] is located (if the position is out of the model area, i � 0 will be returnedinstead).

B.2.58 Interface get polygon area

physical unit: m2

Determine polygon area P:

1. get polygon area(i): returns scalar s[real] with area Pi for the i-th polygon(1 � i � Np);

2. get polygon area(): array a(Np)[real] with actual areas for all polygons Np isreturned, where a(i) is equivalent to Pi, the area of the i-th polygon.




B.2.59 Interface get polygon center


Retrieve center coordinates xi�yi for polygons:

1. get polygon center(i): array a(2)[real] is returned with the center coordi-nates for the i-th polygon (1 � i � Np), where a(1) corresponds to xi and a(2) to yi;

2. get polygon center(): array b(Np,2)[real] is returned with the center coordi-nates for all Np polygons, wherein b(i,1) and b(i,2) are the center coordinates xi�yi

for the i-th polygon;

3. get polygon center(x,y): returns array a(2)[real] with the center coordi-nates of the polygon wherein x,y[real] is located.


B.2.60 Interface get polygon edge

physical unit: —

Evaluate indices for sides (edges) of polygons:

1. get polygon edge(i,l): returns scalar s[int]with index j for the l-th (1� l � Si)side of polygon i (1 � i � Np);

2. get polygon edge(i): array a(Si)[int] of side indices j�i� :� is returned for thethe i-th polygon, where a(l) is the side index j for the l-th side of the i-th polygon;

3. get polygon edge(): array b(Np,4)[int] of side indices for all Np polygons is re-turned, where b(i,l) represents the side index for the l-th (1� l � Si) side of polygoni.

The number of sides Si for polygon i can be determined by means of get nof edges(i),whereas the total number of polygons Np can be retrieved from get nof polygons().

B.2.61 Interface get polygon vertex

physical unit: —

Evaluate indices for vertices (nodes) of polygons:

1. get polygon vertex(i,l): returns scalar s[int]with index n for the l-th (1� l �Si) node of polygon i (1 � i � Np);



2. get polygon vertex(i): array a(4)[int] of vertex indices is returned for the thei-th polygon, where a(l) is the vertex index n for the l-th node of the i-th polygon;

The total number of polygons Np can be retrieved from get nof polygons() whereas theactual number of edges (�vertices) Si for polygon i is obtained by means of get nof edges(i).

B.2.62 Interface get pressure


Retrieve normalized non-hydrostatic pressure component q at prism centers:

1. get pressure(i,k): returns scalar s[real] with q at polygon i (1 � i� Np) withinlayer k (kb�i�� k � kt�i�);

2. get pressure(i): array a(Nz)[real] is returned with q at all prisms above poly-gon i (1 � i � Np), where a(k) corresponds to q within the k-th layer (kb�i�� k � kt�i�);

3. get pressure(): array a(I3)[real] is returned with q at all I3 computationalprisms;

4. get pressure(x,y,z): returns scalar s[real] with q at position x,y,z[real];

5. get pressure(x,y): array a(Nz)[real] is returned with q for all computationalprisms above position x,y[real].

Np can be retrieved from get nof polygons() and Nz from get nof layers(). I3 can bedetermined using get nof prisms(). For the i-th polygon the bottom and top layer in-dices kb�i� and kt�i� can be obtained from get bottom prism(i) and get top prism(i)

respectively. Multiplication of q with ρ0 gives the (real physical) non-hydrostatic pressurecomponent.

B.2.63 Interface get pressure tolerance

physical unit: —

Retrieve tolerance εq for non-hydrostatic pressure iterative solver:

1. get pressure tolerance(): returns scalar s[real] with actual εq used in theprogram.




B.2.64 Interface get prism height

physical unit: m

Retrieve prism height ∆zi�k:

1. get prism height(i,k): returns scalar s[real] with the actual height ∆zi�k atpolygon i (1 � i � Np) for layer k (kb�i�� k � kt�i�);

2. get prism height(i): array a(Nz)[real] is returned, wherein a(k) correspondsto the actual prism height for the k-th layer of polygon i (1 � i � Np);

3. get prism height(): array b(I3)[real] with the actual height for all prisms I3 isretrieved;

4. get prism height(x,y,z): returns scalar s[real] with the actual height ∆zi�k forposition x,y,z[real] (if position is not located within the computational volume∆zi�k � 0�0 is returned);

5. get prism height(x,y): array a(Nz)[real] is returned for the column of com-putational prisms above position x,y[real].

The total number of polygons Np can be retrieved calling get nof polygons(), whereasthe number of level surfaces (layers) Nz is available from get nof layers(). kb�i� re-sults from get bottom prism(i) and kt�i� from get top prism(i). The total numberof prisms I3 can be determined using get nof prisms().

B.2.65 Interface get radiation time

physical unit: 1/s

Retrieve radiation time tr:

1. get radiation time(): returns scalar s[real]with actual tr used in the program.

This value is prescribed by the user in the input file "untrim.inp"

B.2.66 Interface get right polygon

physical unit: —

Return polygon index i for the right polygon adjacent to a given side (edge):

1. get right polygon(j): returns scalar s[int]with index i for the right neighbour-ing polygon adjacent to the j-th side (1 � j � Ns);



2. get right polygon(): array a(Ns)[int] with indices for right neighbouringpolygons for all Ns sides is returned, wherein a(j) is the polygon index of the rightneighbour of the j-th side.

If i � 0 is returned no neighbouring polygon exists to the right, which may be the casefor e. g. sides along boundaries. The total number of sides (edges) Ns is obtained fromget nof edges().

B.2.67 Interface get settling velocity

physical unit: m/s

Retrieve settling velocity ws either at top of prisms or interpolated in z-direction, for specieswhich are labelled as sediment:

1. get settling velocity(i,k): returns scalar s[real] with ws at polygon i (1 �i � Np) for layer k (kb�i�� k � kt�i�);

2. get settling velocity(i): array a(0:Nz)[real] is returned with ws for thecomputational column above polygon i (1� i�Np), where a(k) is the settling velocityfor the k-th layer (kb�i�� k � kt�i�);

3. get settling velocity(): array a(I3)[real] is returned with ws for all compu-tational prisms;

4. get settling velocity(x,y,z): returns scalar s[real] with vertically interpo-lated ws at position x,y,z[real];

5. get settling velocity(z,i): returns scalar s[real] with vertically interpo-lated ws at position z[real] above polygon i (kb�i�� k � kt�i�);

6. get settling velocity(x,y): array a(0:Nz)[real] is returned with ws for thecomputational column above position x,y[real], where a(k) is the settling velocityfor the k-th layer (kb�i�� k � kt�i�);

7. get settling velocity(x,y,k): returns scalar s[real] with ws for the k-thlayer (kb�i�� k � kt�i�) at position x,y[real].

I3 can be retrieved using get nof prisms(), whereas Nz is given by get nof layers().The bottom and top layer indices kb�i� and kt�i� can be determined for the i-th polygon bymeans of get bottom prism(i) and get top prism(i). Please notice that ws � 0�0 cor-responds to downward settling of particles. If a z-coordinate is prescribed in the functioncall, ws is computed by means of a linear interpolation in vertical direction. Horizontally nointerpolation scheme is applied.



Notice: The total settling velocity, as applied during computation, may differ for activelysettling species by a constant factor from the values returned, if factors �� 1 were used inCALL set sediment.

B.2.68 Interface get source concentration


Retrieve source concentration C at prism centers:

1. get source concentration(n,m): returns scalar s[real] with actual C for then-th source (1 � n � Nd) and the m-th specie (1 � m � Nc);

2. get source concentration(m): array a(Nd)[real] is returned with actual C forthe m-th specie (1 � m � Nc) at all Nd sources, where a(n) is the respective specieconcentration at the n-th source;

3. get source concentration(): array b(Nd,Nc)[real] is returned with actual Cfor all Nc species and all Nd sources, where b(n,m) is the concentration for the m-thspecie at the n-th source.

Nd can be obtained from get nof point sources() and Nc from get nof species().

B.2.69 Interface get source discharge

physical unit: m3/s

Extract discharge for sources and sinks:

1. get source discharge(n): returns scalar s[real] with actual discharge of then-th source (1 � n � Nd);

2. get source discharge(): array a(Nd)[real] with actual discharge for all Nd

sources is returned, where a(n) is the discharge of the n-th source.

Nd can be obtained from get nof point sources().

B.2.70 Interface get source layer

physical unit: —

Retrieve layer index k (1 � k � Nz) of sources/sinks:



1. get source layer(n): returns scalar s[int] with layer index k within which then-th source (1 � n � Nd) is located in;

2. get source layer(): array a(Nd)[int] with layer indices for all Nd sources isreturned, where a(n) is the layer index of the n-th source.


B.2.71 Interface get source polygon

physical unit: —

Retrieve polygon index i (1 � i � Np) of sources/sinks:

1. get source polygon(n): returns scalar s[int]with polygon index i within whichthe n-th source (1 � n � Nd) is located in;

2. get source polygon(): array a(Nd)[int] with polygon indices for all Nd sourcesis returned, where a(n) is the polygon index of the n-th source.


B.2.72 Interface get surface alpha

physical unit: m/s

Retrieve surface flux parameter αT at polygon centers:

1. get surface alpha(m,i): returns scalar s[real] with αT for the m-th specie (1 �m � Nc) at the i-th polygon (1 � i � Np);

2. get surface alpha(m): array a(Np)[real] is returned with αT for the m-th specie(1 � m � Nc) at all Np polygons, where a(i) contains αT for the i-th polygon;

3. get surface alpha(): array b(Np�Nc)[real] is returned, where b(i,m) containsαT for specie m at polygon i;

4. get surface alpha(m,x,y): returns scalar s[real] with αT for the m-th specie(1 � m � Nc) at position x,y[real].

Nc can be retrieved using get nof species(), Np is given by get nof polygons().



B.2.73 Interface get surface beta

physical unit: m/s

Retrieve surface flux parameter βT at polygon centers:

1. get surface beta(m,i): returns scalar s[real] with βT for the m-th specie (1 �m � Nc) at the i-th polygon (1 � i � Np);

2. get surface beta(m): array a(Np)[real] is returned with βT for the m-th specie(1 � m � Nc) at all Np polygons, where a(i) contains βT for the i-th polygon;

3. get surface beta(): array b(Np�Nc)[real] is returned, where b(i,m) containsβT for specie m at polygon i;

4. get surface beta(m,x,y): returns scalar s[real]with βT for the m-th specie (1�m � Nc) at position x,y[real].

Nc can be retrieved using get nof species(), Np from get nof polygons().

B.2.74 Interface get surface concentration


Retrieve surface concentration CT at polygon centers:

1. get surface concentration(m,i): returns scalar s[real] with CT for the m-thspecie (1 � m � Nc) at the i-th polygon (1 � i � Np);

2. get surface concentration(m): array a(Np)[real] is returned with CT for them-th specie (1�m�Nc) at all Np polygons, where a(i) contains CT for the i-th polygon;

3. get surface concentration(): array b(Np�Nc)[real] is returned, whereb(i,m)contains CT for specie m at polygon i;

4. get surface concentration(m,x,y): returns scalar s[real] with CT for the m-th specie (1 � m � Nc) at position x,y[real].

Nc can be retrieved using get nof species(), Np is given by get nof polygons().

B.2.75 Interface get surface flux


Retrieve computed free surface flux qT at polygon centers:



1. get surface flux(m,i): returns scalar s[real] with qT for the m-th specie (1 �m � Nc) at the i-th polygon (1 � i � Np);

2. get surface flux(m): scalar s[real] is returned with integral free surface flux qT

for the m-th specie (1 �m � Nc);

3. get surface flux(): array a(Nc)[real] is returned, where a(m) is the integralfree surface flux qT for specie m.

Nc can be retrieved using get nof species(), Np is given by get nof polygons().Notice: Flux data returned by this function are not precisely equal to the simulated flux,

due to the sub-stepping algorithm used in the solver for the transport equation.

B.2.76 Interface get theta

physical unit: —

Retrieve impliciteness factor θ:

1. get theta(): returns scalar s[real] with actual θ used in the program.

θ is prescribed by the user in the input data file "untrim.inp".

B.2.77 Interface get time step

physical unit: s

Extract time step ∆t (in seconds):

1. get time step(): returns scalar s[real] with actual ∆t used in the program.

∆t is prescribed by the user in the input data file "untrim.inp".

B.2.78 Interface get top face

physical unit: —

Evaluate layer index k (1� k �Nz) for the topmost (surface) face above the side of a polygon:

1. get top face(j): returns scalar s[int] with surface face layer index k for side j(1 � j � Ns);

2. get top face(): array a(Ns)[int] is returned with surface face layer indices forall Ns sides, where a(j) represents the surface layer index for the j-th side of the grid.

A surface layer index k � 0 will be returned if no (active) computational face is available (dryside). The total number of sides (edges) Ns can be determined calling get nof edges().



B.2.79 Interface get top prism

physical unit: —

Evaluate layer index k (1 � k � Nz) for the topmost (surface) prism above a polygon:

1. get top prism(i): returns scalar s[int]with surface prism layer index k for poly-gon i (1 � i � Np);

2. get top prism(): array a(Np)[int] is returned with surface prism layer indicesfor all Np polygons, where a(i) represents the surface layer index for the i-th polygon;

3. get top prism(x,y): returns scalar s[int] with surface prism layer index k forposition x,y[real] (if the position is out of the model area, k � 0 will be returnedinstead).

A surface layer index k � 0 will be returned if no (active) computational prism is avail-able (dry polygon). The total number of polygons Np can be determined by means ofget nof polygons().

B.2.80 Interface get turbulent h diffusivity

physical unit: m2/s

Retrieve horizontal turbulent diffusivity Kh at faces:

1. get turbulent h diffusivity(j,k): returns scalar s[real] with Kh at the j-thside (1 � j � Ns) within layer k (kb� j�� k � kt� j�);

2. get turbulent h diffusivity(j): array a(Nz)[real] is returned with Kh forall computational faces above side j (1 � j � Ns), where a(k) is the correspondingvalue for the k-th layer (kb� j�� k � kt� j�);

3. get turbulent h diffusivity(): array a(J3)[real] is returned with Kh for allcomputational faces.

J3 is retrieved from get nof faces(). Ns can be obtained from get nof edges() and Nz

from get nof layers(). Bottom face layer index kb� j� is given by get bottom face(j)

and kt� j� can be retrieved from get top face(j).

B.2.81 Interface get turbulent v diffusivity

physical unit: m2/s

Retrieve vertical turbulent diffusivity Kv at top of prisms:



1. get turbulent v diffusivity(i,k): returns scalar s[real] with Kv at the i-thpolygon (1 � i � Np) for layer k (kb�i�� k � kt�i�);

2. get turbulent v diffusivity(i): array a(Nz)[real] is returned with Kv forall computational prisms above polygon i (1 � i � Np), where a(k) is the correspond-ing value for the k-th layer (kb�i�� k � kt�i�);

3. get turbulent v diffusivity(): array a(I3)[real] is returned with Kv for allcomputational prisms.

I3 is retrieved from get nof prisms(). Np can be obtained from get nof polygons()

and Nz from get nof layers(). The bottom prism layer index kb�i� is given byget bottom prism(i) and kt�i� results from get top prism(i).

B.2.82 Interface get turbulent v viscosity

physical unit: m2/s

Retrieve vertical turbulent viscosity νv at top of prisms:

1. get turbulent v viscosity(i,k): returns scalar s[real] with νv at the i-thpolygon (1 � i � Np) for layer k (kb�i�� k � kt�i�);

2. get turbulent v viscosity(i): array a(Nz)[real] is returned with νv for allcomputational prisms above polygon i (1 � i � Np), where a(k) is the correspondingvalue for the k-th layer (kb�i�� k � kt�i�);

3. get turbulent v viscosity(): array a(I3)[real] is returned with νv for allcomputational prisms.

I3 is retrieved from get nof prisms(). Np can be obtained from get nof polygons()

and Nz from get nof layers(). The bottom prism layer index kb�i� is given byget bottom prism(i) and kt�i� results from get top prism(i).

B.2.83 Interface get velocity

physical unit: m/s

Retrieve horizontal normal velocity u at computational faces:

1. get velocity(j,k): returns scalar s[real] with u at the j-th side (edge) (1 � j �Ns) within layer k (kb� j�� k � kt� j�);

2. get velocity(j): array a(Nz)[real] is returned with u for all computationalfaces above side j (1 � j � Ns), where a(k) contains u for the k-th layer (kb� j� � k �kt� j�);



3. get velocity(): array a(J3)[real] is returned with u at all J3 faces.

Ns can be retrieved using get nof edges() and Nz is obtained from get nof layers().The bottom face layer index kb� j� can be determined using get bottom face(j) whereaskt� j� is given by get top face(j). J3 is retrieved from get nof faces().

B.2.84 Interface get vertex coordinates


Retrieve coordinates (x�y) for vertices:

1. get vertex coordinates(i): array a(2)[real] is returned with coordinates ofthe i-th vertex (1� i�Nv), where a(1) and a(2) are the respective x- and y-coordinatesof the i-th vertex;

2. get vertex coordinates(): array b(Nv,2)[real] ist returned with the coordi-nates for all Nv vertices, wherein b(i,1) and b(i,2) are the respective x- and y-coordinates of the i-th vertex.

The overall number of vertices Nv can be obtained from get nof vertices().

B.2.85 Interface get vertical diffusivity

physical unit: m2/s

Retrieve scalar constant for vertical diffusivity:

1. get vertical diffusivity(): returns scalar s[real] with scalar constant verti-cal diffusivity.


Notice: The total vertical diffusivity applied during computation is the sum of this valueplus its spatially varying contribution set using CALL set turbulent v diffusivity.

B.2.86 Interface get vertical velocity

physical unit: m/s

Retrieve vertical velocity component w either at top of prisms or interpolated in z-direction:

1. get vertical velocity(i,k): returns scalar s[real] with w at the i-th polygon(1 � i � Np) for layer k (kb�i�� k � kt�i�);



2. get vertical velocity(i): array a(0:Nz)[real] is returned with w for all com-putational faces above polygon i (1 � i � Np), where a(k) contains w for the k-th layer(kb�i�� k � kt�i�);

3. get vertical velocity(): array a(I3)[real] is returned with w for all I3 com-putational prisms;

4. get vertical velocity(x,y,z): returns scalar s[real] with w vertically inter-polated to position x,y,z[real];

5. get vertical velocity(x,y,k): returns scalar s[real] with w at positionx,y[real] for layer k (kb�i�� k � kt�i�);

6. get vertical velocity(z,i): returns scalar s[real] with w vertically interpo-lated to position z[real] above polygon i (1 � i � Np);

7. get vertical velocity(x,y): array a(0:Nz)[real] is returned with w for allcomputational faces above position x,y[real], where a(k) contains w for the k-thlayer (kb�i�� k � kt�i�).

I3 is given by get nof prisms(). Np can be determined from get nof polygons(). kb�i�results from get bottom prism(i) and kt�i� from get top prism(i). Nz is given byget nof layers(). If a z-coordinate is prescribed in the function call, w is computed bymeans of linear interpolation in vertical direction. Horizontally no interpolation scheme isapplied.

B.2.87 Interface get vertical viscosity

physical unit: m2/s

Retrieve scalar constant for vertical viscosity:

1. get vertical viscosity(): returns scalar s[real] with scalar constant verticalviscosity.


Notice: The total vertical viscosity applied during computation is the sum of this valueplus its spatially varying contribution set using CALL set turbulent v viscosity.

B.2.88 Interface get volume

physical unit: m3

Computes the volume for computational prisms:



1. get volume(i,k): returns scalar s[real] corresponding to the fluid volume insidethe computational prism above polygon i (1 � i � Np) within layer k (kb�i�� k � kt�i�);

2. get volume(i): returns scalar s[real] with the fluid volume above polygon i (1 �i � Np);

3. get volume(): returns scalar s[real] with the overall fluid volume.

The total number of polygons Np can be retrieved from get nof polygons. kb�i� can beobtained from get bottom prism(i) and kt�i� from get top prism(i).

B.2.89 Interface get wind friction

physical unit: —

Retrieve wind friction coefficient rT at sides/edges:

1. CALL get wind friction(j): returns scalar s[real] with rT at the j-th side (1 �j � Ns);

2. CALL get wind friction(): array a(Ns)[real] is returned with rT at all Ns sides,where a(j) contains rT for the j-th side.

Ns can be determined by means of get nof edges().

B.2.90 Interface get wind stress


Retrieve the normalized normal component of wind shear stress at sides/edges:

1. get wind stress(j): return scalar s[real] for the j-th side (1 � j � Ns);

2. get wind stress(): array a(Ns)[real] is returned for all all Ns sides, where a(j)is the respective value for the j-th side.

Ns can be obtained from get nof edges(). The (real physical) normal component of theactual wind stress τT is obtained by multiplication with ρ0.



B.2.91 Interface get wind velocity

physical unit: m/s

Retrieve components of the wind velocity (ua,va) at sides/edges:

1. get wind velocity(j): array a(2)[real] is returned for the j-th side (1� j�Ns),where a(1) and a(2) correspond to the x- and y-components of the wind velocity(ua,va);

2. get wind velocity(): array b(Ns,2)[real] is returned with wind velocity at allNs sides, where b(j,:) gives the respective value for the j-th side.

Ns is obtained from get nof egdes().

B.2.92 Interface get wind velocity x

physical unit: m/s

Retrieve x-component ua of the wind velocity at sides/edges:

1. get wind velocity x(j): returns scalar s[real] with the x-component ua for thej-th side (1 � j � Ns);

2. get wind velocity x(): array a(Ns)[real] is returned with x-component ua atall Ns sides.


B.2.93 Interface get wind velocity y

physical unit: m/s

Retrieve y-component va of the wind velocity at sides/edges:

1. get wind velocity y(j): returns scalar s[real] with the y-component va for thej-th side (1 � j � Ns);

2. get wind velocity y(): array a(Ns)[real] is returned with y-component va atall Ns sides.




B.2.94 Interface get x vertex coordinate


Retrieve x-coordinate for vertices:

1. get x vertex coordinate(i): scalar s[real] is returned with the x-coordinatefor the i-th vertex (1 � i � Nv);

2. get x vertex coordinate(): array a(Nv)[real] ist returned with the x-coordina-tes for all Nv vertices.


B.2.95 Interface get y vertex coordinate


Retrieve y-coordinate for vertices:

1. get y vertex coordinate(i): scalar s[real] is returned with the y-coordinatefor the i-th vertex (1 � i � Nv);

2. get y vertex coordinate(): array a(Nv)[real] ist returned with the y-coordina-tes for all Nv vertices.


B.2.96 Interface sediment

physical unit: logical, no unit

Check if a specie is a sediment with a settling velocity ws:

1. sediment(m): returns scalar s[log] which is true if the m-th specie (1 �m � Nc) is asediment with settling velocity ws or false otherwise.

Nc can be determined from get nof species().Notice: Currently factors set using CALL set sediment cannot be retrieved by an ap-

propriate Get-function.



B.2.97 Interface with hydrodynamic pressure


Check if the hydrodynamic pressure solver has been turned on in the ongoing simulation:

1. with hydrodynamic pressure(): returns scalar s[log] which is true if the ongo-ing simulation is performed with the assumption that the pressure is non-hydrostaticor false otherwise (hydrostatic assumption).

The result of this function is dependent on user’s input data in file "untrim.inp".

B.2.98 Interface with scalar transport


Check if scalar transport has been turned on in the ongoing simulation:

1. with scalar transport(): returns scalar s[log]which is true if the ongoing sim-ulation is performed with transport of scalar species or false otherwise.

The result of this function is dependent on user’s input data in file "untrim.inp".



B.3 Check routines

� check routines

– grid structure and grid quality

� check grid

– continuity

� check continuity

All check routines available to the user are subsequently described and listed in alphabeticalorder.

B.3.1 Subroutine check continuity

This subroutine has no parameters. The routine can be called during each time step. Thefollowing checks are performed:

1. determine maximum error for computed water levels;

2. determine maximum volume error within a polygon;

3. determine total volume error for the computational domain.

This routine is very helpful to check accuracy of the numerical solution. Results may be usedto optimize some of the solver parameters in file "untrim.inp".

B.3.2 Subroutine check grid

This subroutine has no parameters. The routine may be called once after the grid has beenread by the computational core of the program. The follwing checks are carried through:

1. determine smallest/largest area for all polygons;

2. determine smallest/largest length for all sides (edges);

3. determine smallest/largest distance between adjacent polygon centers for all edges;

4. compute statistics for all distances between adjacent polygon centers;

5. determine the number of centers which are not contained in their polygon;

6. compute maximum violation of orthogonality condition;

7. determine the number of edges with incorrect orientation (edges with negative distancebetween adjacent polygon centers);

8. stop execution if there are negative polygon areas;

9. stop execution in case of invalid sources and/or sinks locations.



B.4 User interface routines

In the following sections for each of the typical operations within the user interface routinesthe most important get- and set-functions are listed. These listings are in general not compre-hensive, and the user may find that additional functions out of the vast amount of availablefunctions (see section B.1 on page 1 and section B.2 on page 24) might be useful in case.

B.4.1 Subroutine user set input files

This routine is called once during the initialization phase by the computational core of thesoftware. The user has the possibility to set user-specific paths and names for the threedifferent input files. The following routines and/or functions may be useful in this respect:

� path and name for the steering file (default is "untrim.inp")

– set input file

� path and name for the grid file (default is "untrim.grd")

– set grid file

� path and name for the sources and sinks file (default is "untrim.srs")

– set source file

Notice: if one or several of the before mentioned set-routines are not used the respective filenames will be initialized to their default names .

B.4.2 Subroutine user set initial conditions

This routine is called once during the initialization phase by the computational core of thesoftware. The user has the possibility to set the inital conditions as required. The followingroutines and/or functions may be useful in this context:

� auxiliary functions

– get bottom face

– get bottom prism

– get nof faces

– get nof layers

– get nof polygons

– get nof prisms

– get nof species

– get top face

– get top prism



� inquiry functions

– with hydrodynamic pressure

– with scalar transport

� hydrodynamic initial data

– CALL set elevation

– CALL set horizontal velocity

– CALL set velocity

– CALL set pressure

� species initial data

– CALL set concentration

– CALL set sediment

� check routines for the grid

– CALL check grid

Notice: if one or several of the before mentioned set-routines are not used, the respectivedata will be initialized to zero.

B.4.3 Subroutine user set forcing terms

This routine is called once during each time step performed by the computational core of thesoftware. The user has the possibility to set the boundary data as required. On the followingpages, the most useful routines and/or functions are listed in several sections.

open boundary data Boundary data at open model boundaries are normally set bythe user to non-default values. Ideally the data should be available for time level tn�1. Thefollowing routines and/or functions may be of use for this purpose:


– get bottom face


– get nof layers

– get nof boundary polygons

– get nof inflow edges

– get time step

– get top face

– get top prism






– get face height

– get prism height

– get edge center

– get polygon center

� hydrodynamic open boundary data (with prescribed water level)

– CALL set elevation bc

– CALL set pressure bc

� hydrodynamic inflow boundary data (with prescribed flow)

– CALL set inflow bc

� species open boundary data (with prescribed water level)

– CALL set concentration bc

� species inflow boundary data (with prescribed flow)

– CALL set inflow cc

Notice: if one or several of the before mentioned set-routines are never used the respectiveboundary data will be initialized with their default values (normally zero). Some of thefunctions are acting on different parts (polygons with prescribed water level and edges withprescribed flow) of the open boundary.

sources and sinks If the transport of species is modelled the respective concentra-tion for sources and sinks should be set. The following routines and/or functions may beuseful in this respect:


– get nof layers

– get nof point sources

– get nof species

– get time step


– get concentration

– get source concentration



– get source discharge

– get source layer

– get source polygon


� strength of sources and sinks

– CALL set point sources discharge

� concentration for sources and sinks

– CALL set point sources concentration

Notice: if some of the before mentioned set-routines are never used, the respective sourcesand sinks data will remain with their default values (normally zero).

bottom friction boundary data Normally the user has to prescribe a frictioncoefficient at the bottom surface. In dependence on the parametrization used, this may beeither a constant or spatially varying, e. g. in dependence on time-dependent water depth.The following routines and/or functions may be useful in this respect:


– get nof edges


– get time


– get depth at edge

– get edge center

– get elevation

� bottom friction coefficient

– CALL set bottom friction

Notice: if the before mentioned set-routine is never used the bottom friction coefficient isassumed to be equal to g

C2z, with Cz prescribed in file "untrim.inp".

atmospheric boundary data The user is enabled to set wind speed and atmo-spheric pressure at the free surface. Normally wind speed as measured or computed 10 mabove the free surface is used. In reality the wind friction coefficient is varying in space andtime. The following routines and/or functions may be useful:




– get nof edges


– get time step


– get edge center


� wind friction coefficient

– CALL set wind friction

� wind speed

– CALL set wind velocity

� atmospheric pressure

– CALL set atmospheric pressure

Notice: if some of the aforementioned set-routines are never used respective atmosphericdata will be initialized to default values (zero).

density (equation of state) If there are species present, density is normally nolonger a constant. The user is enabled to compute and set the density according to his or herrequirements in dependence on the actual species concentrations. The following routinesand/or functions may be useful in this respect:



– get nof layers

– get nof prisms

– get nof species

– get time step

– get top prism




� density

– CALL set density

Notice: if the before mentioned set-routine is never used, normalized density is assumed tobe 1.0 (ρ � ρ0).



turbulent viscosities and diffusivities The user is enabled to assign mean-ingful values to the vertical and horizontal turbulent viscosities (νv, νh) and diffusivities (Kv,Kh). They normally strongly depend on space and time. The following routines and/orfunctions may be useful in this respect:


– get bottom face


– get nof layers


– get nof prisms

– get nof species

– get top face

– get top prism


– get density

– get edge center

– get face height

– get gravity

– get horizontal velocity

– get horizontal velocity x

– get horizontal velocity y




� turbulent viscosity

– CALL set turbulent h viscosity

– CALL set turbulent v viscosity

� turbulent diffusivity (if scalar transport of tracers is taken into account)

– CALL set turbulent h diffusivity

– CALL set turbulent v diffusivity

Notice: the before mentioned functions enable the user to set the spatially- and time-varyingcomponent of the total viscosities and diffusivities as used in the program; the total valuesdo also take into account the constant contribution from the steering data file untrim.inp;if the above-mentioned set-routines are not used, total diffusivities and viscosities are equiv-alent to the values from "untrim.inp".



fluxes of tracers through the surface and the bottom The user isenabled to set the boundary data at the free surface as well as at the bottom individually foreach of the species, if required. The following routines and/or functions may be useful:




– get nof species

– get time step

– get top prism




– sediment

– get settling velocity


� species bottom flux data

– CALL set bottom alpha

– CALL set bottom beta

– CALL set bottom concentration

� species surface flux data

– CALL set surface alpha

– CALL set surface beta

– CALL set surface concentration

Notice: if one or several of the before mentioned set-routines are never used the respectiveflux data will be initialized to zero. This means that a zero-flux condition will be applied atthe free surface, and for the bottom.

settling velocity of active tracers The user is enabled to assign meaningfulvalues to the settling velocity ws for suspended sediments, which e. g. may depend on tur-bulence intensity. Settling velocity may vary in space and time. Settling velocities betweendifferent tracers may differ by a constant factor. The following routines and/or functionsmay be useful in this respect:





– get nof layers


– get nof prisms

– get nof species

– get top prism



– get gravity

– get turbulent v viscosity

– get turbulent v diffusivity

– sediment

� settling velocity

– CALL set sediment

– CALL set settling velocity

The settling velocity (set by means of CALL set settling velocity) will be mulipliedfor each tracer with a constant factor prescribed through CALL set sediment.

Notice: if the aforementioned set-routine CALL set sediment was never used for aspecific specie, its settling velocity will remain zero.

checks and balances There are a few functions available which allow to retrievevaluable informations concerning numerical accuracy as well as performance of the compu-tational core of the program:

� check iterations done by the iterative solvers

– get iterations

� water volume

– get volume

� tracer mass

– get mass

� fluxes of tracer at the free surface and at the bottom

– get surface flux

– get bottom flux



� continuity of water volume

– CALL check continuity

� drying and wetting

– get nof wet edges

– get nof wet faces

– get nof wet polygons

– get nof wet prisms

B.4.4 Subroutine user get results

This routine is called once for each time step. The user is offered the possibility to outputany results he/she is interested in. The following routines and/or functions may be usefulin this respect:


– get nof faces

– get nof layers

– get nof point sources


– get nof prisms

– get nof species

– get time step




� computational results

– get bottom stress


– get elevation

– get horizontal velocity

– get horizontal velocity x

– get horizontal velocity y

– get mass

– get pressure



– get velocity

– get vertical velocity

– get wind stress

� parameters and coefficients

– get bottom alpha

– get bottom beta

– get bottom concentration

– get bottom friction

– get density

– get horizontal diffusivity

– get horizontal viscosity

– get settling velocity

– get surface alpha

– get surface beta

– get surface concentration

– get turbulent h diffusivity

– get turbulent h viscosity

– get turbulent v diffusivity

– get turbulent v viscosity

– get vertical diffusivity

– get vertical viscosity

– get wind friction

� boundary data

– get atmospheric pressure

– get bottom flux

– get surface flux

– get wind velocity

– get wind velocity x

– get wind velocity y



C Tables for set-routines and get-functions

In the following subsections all interfaces for set-routines as well as get-functions are pre-sented in tabular form. For each interface the available set of arguments is given. The tablesshould help the experienced user to quickly select any routine together with the requiredarguments. For the arguments used througout Table 2 on page 78 to Table 13 on page 89 thenomenclature shown in Table 1 on the next page applies.

C. Tables for set-routines and get-functions Page 76


argument description

i polygon indexj edge (side) indexk layer indexl side/vertex index within polygonm specie indexn source/sink location indexn12(:) integer array of size 1 (hydrostatic) or 2 (non-hydrostatic)s,t scalar variablesac(:) data ac(Nz) for all layers Nz

ac0(:) data ac0(0 : Nz) for all layer interfaces Nz

af(:),bf(:) data af(J3),bf(J3) for all faces J3

ai(:) data ai(Np) for all polygons Np

ail(:,:) data ail(Np�4) for all polygons Np and all sidesai b(:) data ai b(N�

p) for all boundary polygons N�

p

aim(:,:) data aim(Np�Nc) for all polygons Np and all species Nc

aj(:),bj(:) data aj(Ns),bj(Ns) for all edges (sides) Ns

al(:) data al(Si) for all sides Si of a polygonam(:) data am(Nc) for all species Nc

an(:) data an(Nd) for all source/sink locations Nd

anm(:,:) data anm(Nd�Nc) for all source/sink locations Nd and all species Nc

ap(:) data ap(I3) for all prisms I3

ap b(:) data ap b(I�3) for all boundary prisms I�

3

apm(:,:) data apm(I3�Nc) for all prisms I3 and all species Nc

apm b(:,:) data apm b(I�3�Nc) for all boundary prisms I�

3and all species Nc

av(:) data av(Nv) for all vertices Nv

c(:) coordinates c(2) for a single pointci(:,:) coordinates ci(Np�2) for all polygonscj(:,:) coordinates cj(Ns�2) for all edgescv(:,:) coordinates cv(Nv�2) for all verticesst character string st(LEN=80)v(:) vector data v(2) for a single pointvj(:,:) vector data v(Ns�2) for all edgesvc(:,:) vector data v(Nz�2) for all layers Nz

x,y,z coordinates

Table 1: Nomenclature for set-routines and get-functions.

C. Tables for set-routines and get-functions Page 77

The

FederalW

aterways

Engineering

andR

esearchInstitute

(BA

W)

Mathem

aticalMod

elUnT

RIM

User

InterfaceD

escription–

Version

June2004

(1.0)

interface name allowed sets of arguments

set atmospheric pressure (s|i,s|ai(:))

set bottom alpha (s|m,s|m,i,s|m,ai(:)|aim(:,:))

set bottom beta (s|m,s|m,i,s|m,ai(:)|aim(:,:))

set bottom concentration (s|m,s|m,i,s|m,ai(:)|aim(:,:))

set surface alpha (s|m,s|m,i,s|m,ai(:)|aim(:,:))

set surface beta (s|m,s|m,i,s|m,ai(:)|aim(:,:))

set surface concentration (s|m,s|m,i,s|m,ai(:)|aim(:,:))

set bottom friction (s|j,s|aj(:))

set concentration (s|m,s|m,i,s|m,i,k,s|m,ap(:)|m,i,ac(:)|apm(:,:))

set concentration bc (s|m,s|m,i,s|m,i,k,s|m,ap b(:)|m,i,ac(:)|apm b(:,:))

set density (s|i,s|i,k,s|i,ac(:)|ap(:))

set elevation (s|i,s|ai(:))

set elevation bc (s|i,s|ai b(:))

set flux limiter (st)

set grid file (st)

set horizontal velocity (s,t|j,s,t|j,k,s,t|j,ac(:),t|j,s,bc(:)|j,ac(:),bc(:)| . . .. . .af(:),s|s,bf(:)|af(:),bf(:))

set input file (st)

Table 2: Available interfaces for set-routines together with allowed arguments (set atmospheric pressure – set input file). For details about thenomenclature please refer to Table 1 on the page before.

C.Tables

forset-routines

andget-functions

Page78

The

FederalW

aterways

Engineering

andR

esearchInstitute

(BA

W)

Mathem

aticalMod

elUnT

RIM

User

InterfaceD

escription–

Version

June2004

(1.0)

interface name allowed sets of arguments

set inflow bc (s|j,s|j,k,s)

set inflow cc (s|m,s|m,j,s|m,j,k,s)

set point sources discharge (s|n,s|an(:))

set point sources concentration (s|n,s|n,m,s|m,an(:)|anm(:,:))

set pressure (s|i,s|i,k,s|i,ac(:)|ap(:))

set pressure bc (s|i,s|i,k,s|i,ac(:)|ap b(:))

set sediment (s|am(:)|m,s)

set settling velocity (s|i,s|i,k,s|i,ac(:)|ap(:))

set source file (st)

set turbulent h diffusivity (s|j,s|j,k,s|j,ac(:)|af(:))

set turbulent h viscosity (s|j,s|j,k,s|j,ac(:)|af(:))

set turbulent v diffusivity (s|i,s|i,k,s|i,ac(:)|ap(:))

set turbulent v viscosity (s|i,s|i,k,s|i,ac(:)|ap(:))

set velocity (s|j,s|j,k,s|j,ac(:)|af(:))

set wind friction (s|j,s|aj(:))

set wind velocity (s,t|j,s,t|aj(:),t|s,bj(:)|aj(:),bj(:))

Table 3: Available interfaces for set-routines together with allowed arguments (set inflow bc – set wind velocity). For details about the nomen-clature please refer to Table 1 on page 77.

C.Tables

forset-routines

andget-functions

Page79

The

FederalW

aterways

Engineering

andR

esearchInstitute

(BA

W)

Mathem

aticalMod

elUnT

RIM

User

InterfaceD

escription–

Version

June2004

(1.0)

interface name allowed sets of arguments and results

get adjacent polygon arg (i,l) (i) ()

resINT i al(:) ail(:,:)

get atmospheric pressure arg (i) () (x,y)

resREAL s ai(:) s

get bottom alpha arg (m,i) (m) () m,x,y

resREAL s ai(:) aim(:,:) s

get bottom beta arg (m,i) (m) () m,x,y


get bottom concentration arg (m,i) (m) () m,x,y


get bottom face arg (j) ()

resINT s aj(:)

get bottom flux arg (m,i) m ()

resREAL s am(:)

get bottom friction arg (j) ()

resREAL s aj(:)

get bottom prism arg (i) () x,y

resINT s ai(:) s

get bottom stress arg (j) ()

resREAL s aj(:)

Table 4: Available interfaces for get-functions together with allowed arguments (arg) and returned results (res) (get adjacent polygon –get bottom stress). For details about the nomenclature please refer to Table 1 on page 77.

C.Tables

forset-routines

andget-functions

Page80

The

FederalW

aterways

Engineering

andR

esearchInstitute

(BA

W)

Mathem

aticalMod

elUnT

RIM

User

InterfaceD

escription–

Version

June2004

(1.0)


get concentration arg (m,i,k) (m,i) (m) () (m,x,y,z) (m,x,y)

resREAL s ac(:) ap(:) apm(:,:) s ac(:)

get chezy arg ()

resREAL s

get density arg (i,k) (i) () (x,y,z) (x,y)

resREAL s ac(:) ap(:) s ac(:)

get depth arg (i) () (x,y)

resREAL s ai(:) s

get depth at edge arg (j) ()

resREAL s aj(:)

get dt min arg ()

resREAL s

get dx arg ()

resREAL s

get dx min arg ()

resREAL s

get dy arg (j) ()

resREAL s aj(:)

get dz min arg ()

resREAL s

Table 5: Available interfaces for get-functions together with allowed arguments (arg) and returned results (res) (get concentration – get dzmin).For details about the nomenclature please refer to Table 1 on page 77.

C.Tables

forset-routines

andget-functions

Page81

The

FederalW

aterways

Engineering

andR

esearchInstitute

(BA

W)

Mathem

aticalMod

elUnT

RIM

User

InterfaceD

escription–

Version

June2004

(1.0)


get edge begin arg (j) ()

resINT s aj(:)

get edge center arg (j) ()

resREAL c(:) cj(:,:)

get edge end arg (j) ()

resINT s aj(:)

get elevation arg (i) () (x,y)

resREAL s ai(:) s

get elevation tolerance arg ()

resREAL s

get face height arg (j,k) (j) ()

resREAL s ac(:) af(:)

get flux limiter arg ()

resCHAR st

get gravity arg ()

resREAL s

get hland arg ()

resREAL s

get horizontal diffusivity arg ()

resREAL s

Table 6: Available interfaces for get-functions together with allowed arguments (arg) and returned results (res) (get edge begin –get horizontal diffusivity). For details about the nomenclature please refer to Table 1 on page 77.

C.Tables

forset-routines

andget-functions

Page82

The

FederalW

aterways

Engineering

andR

esearchInstitute

(BA

W)

Mathem

aticalMod

elUnT

RIM

User

InterfaceD

escription–

Version

June2004

(1.0)


get horizontal velocity arg (x,y,z) (x,y) (x,y,z,i) (x,y,i,k) (x,y,i)

resREAL v(:) vc(:,:) v(:) v(:) vc(:,:)

get horizontal velocity x arg (x,y,z) (x,y) (x,y,z,i) (x,y,i,k) (x,y,i)

resREAL s ac(:) s s ac(:)

get horizontal velocity y arg (x,y,z) (x,y) (x,y,z,i) (x,y,i,k) (x,y,i)

resREAL s ac(:) s s ac(:)

get horizontal viscosity arg ()

resREAL s

get layer arg (z)

resINT k

get iterations arg ()

resINT n12(:)

get layer interface arg (k) ()

resREAL s ac0(:)

get left polygon arg (j) ()

resINT s ai(:)

get location arg ()

resCHAR st

get mass arg (m,i,k) (m,i) (m) ()

resREAL s s s am(:)

Table 7: Available interfaces for get-functions together with allowed arguments (arg) and returned results (res) (get horizontal velocity –get mass). For details about the nomenclature please refer to Table 1 on page 77.

C.Tables

forset-routines

andget-functions

Page83

The

FederalW

aterways

Engineering

andR

esearchInstitute

(BA

W)

Mathem

aticalMod

elUnT

RIM

User

InterfaceD

escription–

Version

June2004

(1.0)


get maximum iteration arg ()

resINT s

get nof boundary polygons arg ()

resINT s

get nof edges arg (i) ()

resINT s ai(:)

get nof faces arg (j) ()

resINT s s

get nof inflow edges arg ()

resINT s

get nof internal edges arg ()

resINT s

get nof layers arg ()

resINT s

get nof point sources arg ()

resINT s

get nof polygons arg ()

resINT s

get nof prisms arg (i) () (x,y)

resINT s s s

Table 8: Available interfaces for get-functions together with allowed arguments (arg) and returned results (res) (get maximum iteration –get nof prisms). For details about the nomenclature please refer to Table 1 on page 77.

C.Tables

forset-routines

andget-functions

Page84

The

FederalW

aterways

Engineering

andR

esearchInstitute

(BA

W)

Mathem

aticalMod

elUnT

RIM

User

InterfaceD

escription–

Version

June2004

(1.0)


get nof species arg ()

resINT s

get nof vertices arg (i) ()

resINT s s

get nof wet edges arg (i) ()

resINT s s

get nof wet faces arg (j) ()

resINT s s

get nof wet polygons arg ()

resINT s

get nof wet prisms arg (i) () (x,y)

resINT s s s

get polygon arg (x,y)

resINT s

get polygon area arg (i) ()

resREAL s ai(:)

get polygon center arg (i) () (x,y)

resREAL c(:) ci(:,:) c

get polygon edge arg (i,l) (i) ()

resINT s al(:) ail(:,:)

Table 9: Available interfaces for get-functions together with allowed arguments (arg) and returned results (res) (get nof species –get polygon edge). For details about the nomenclature please refer to Table 1 on page 77.

C.Tables

forset-routines

andget-functions

Page85

The

FederalW

aterways

Engineering

andR

esearchInstitute

(BA

W)

Mathem

aticalMod

elUnT

RIM

User

InterfaceD

escription–

Version

June2004

(1.0)


get polygon vertex arg (i,l) (i) ()

resINT s al(:) ail(:,:)

get pressure arg (i,k) (i) () (x,y,z) (x,y)


get pressure tolerance arg ()

resREAL s

get prism height arg (i,k) (i) () (x,y,z) (x,y)


get radiation time arg ()

resREAL s

get right polygon arg (j) ()

resINT s aj(:)

get source concentration arg (n,m) (m) ()

resREAL s an(:) anm(:)

get source discharge arg (n) ()

resREAL s an(:)

get source layer arg (n) ()

resINT s an(:)

get surface flux arg (m,i) m ()

resREAL s am(:)

Table 10: Available interfaces for get-functions together with allowed arguments (arg) and returned results (res) (get polygon vertex –get surface flux). For details about the nomenclature please refer to Table 1 on page 77.

C.Tables

forset-routines

andget-functions

Page86

The

FederalW

aterways

Engineering

andR

esearchInstitute

(BA

W)

Mathem

aticalMod

elUnT

RIM

User

InterfaceD

escription–

Version

June2004

(1.0)


get source polygon arg (n) ()

resINT s an(:)

get surface alpha arg (m,i) (m) () (m,x,y)


get surface beta arg (m,i) (m) () (m,x,y)


get surface concentration arg (m,i) (m) () (m,x,y)


get settling velocity arg (i,k) (i) () (x,y,z) (z,i) (x,y) (x,y,k)

resREAL s ac0(:) ap(:) s s ac0(:) s

get theta arg ()

resREAL s

get time step arg ()

resREAL s

get top face arg (j) ()

resINT s aj(:)

get top prism arg (i) () (x,y)

resINT s ai(:) s

get turbulent h diffusivity arg (j,k) (j) ()


Table 11: Available interfaces for get-functions together with allowed arguments (arg) and returned results (res) (get source polygon –get turbulent h diffusivity). For details about the nomenclature please refer to Table 1 on page 77.

C.Tables

forset-routines

andget-functions

Page87

The

FederalW

aterways

Engineering

andR

esearchInstitute

(BA

W)

Mathem

aticalMod

elUnT

RIM

User

InterfaceD

escription–

Version

June2004

(1.0)


get turbulent h viscosity arg (j,k) (j) ()


get turbulent v diffusivity arg (i,k) (i) ()

resREAL s ac(:) ap(:)

get turbulent v viscosity arg (i,k) (i) ()

resREAL s ac(:) ap(:)

get velocity arg (j,k) (j) ()


get vertex coordinates arg (i) ()

resREAL c(:) cv(:,:)

get vertical diffusivity arg ()

resREAL s

get vertical velocity arg (i,k) (i) () (x,y,z) (x,y,k) (z,i) (x,y)

resREAL s ac(:) ap(:) s s s ac(:)

get vertical viscosity arg ()

resREAL s

get volume arg (i,k) (i) ()

resREAL s s s

get wind friction arg (j) ()

resREAL s aj(:)

Table 12: Available interfaces for get-functions together with allowed arguments (arg) and returned results (res) (get turbulent v diffusivity –get wind friction). For details about the nomenclature please refer to Table 1 on page 77.

C.Tables

forset-routines

andget-functions

Page88

The

FederalW

aterways

Engineering

andR

esearchInstitute

(BA

W)

Mathem

aticalMod

elUnT

RIM

User

InterfaceD

escription–

Version

June2004

(1.0)


get wind stress arg (j) ()

resREAL s aj(:)

get wind velocity arg (j) ()

resREAL v(:) vj(:,:)

get wind velocity x arg (j) ()

resREAL s aj(:)

get wind velocity y arg (j) ()

resREAL s aj(:)

get x vertex coordinate arg (l) ()

resREAL s av(:)

get y vertex coordinate arg (l) ()

resREAL s av(:)

sediment arg (m)

resLOG s

with hydrodynamic pressure arg ()

resLOG s

with scalar transport arg ()

resLOG s

Table 13: Available interfaces for get-functions together with allowed arguments (arg) and returned results (res) (get wind stress –with scalar transport). For details about the nomenclature please refer to Table 1 on page 77.

C.Tables

forset-routines

andget-functions

Page89


D Example input data files

D.1 Grid file

D.1.1 Grid sorting

Polygons as well as edges/sides of a grid stored in file "untrim.grd" must be sorted inan appropriate way. This is required for reasons of efficiency and correctness. The followingorderings must be fulfilled (tasks for the grid generator):

� vertices:

1. for each polygon the vertices must be given in counter-clockwise orientation (pro-gram will stop if this is not the case);

2. no sorting is required for the global vertex numbers.

� polygons:

1. for reasons of efficiency and accuracy a red-black-ordering of the polygons is rec-ommended:

(a) the red polygons must become the first �1�Npr � ones out of the Np polygons;

(b) the black polygons must be numbered �Npr �1�Np�;

Notice: If no red-black-ordering is used, Npr � Np must hold true.

2. if there are N�

p polygons along the open boundary where the water level shall beprescribed, they must be assigned the lowermost numbers

�1�N�

p

�.

� sides/edges:

1. for reasons of efficiency all internal sides (sharing two polygons) must be assignedthe lowermost numbers �1�Nsi �;

2. all (closed or open) boundary edges must be moved to the tail �Nsi �1�Ns�;

3. if some open boundary edges are sides with prescribed flow (Dirichlet boundarycondition), these edges must be brought to the head of the tail

�Nsi �1�Nsf

�.

Notice: If a Dirichlet boundary condition is not used at all, Nsf � Nsi must hold true.

D.1.2 Short description

The grid file is sub-divided into the following sections:

1. Fortran NAMELIST-data section LISTGRD:

(a) ne: number of polygons Np;

(b) ns: number of sides Ns;

(c) nv: number of vertices Nv;

D. Example input data files Page 90


(d) nbc: number of boundary polygons N�

p;

(e) nr: number of red polygons Npr (red-black-sorting);

(f) nsi: number of internal sides Nsi ;

(g) nsf: number of last side with prescribed flow Nsf ;

(h) angle: (mean) geographic latitude Φ;

(i) hland: depth for permanently dry land hL ;

(j) location: text string to describe the model domain.

Please notice that hL must be chosen in such a way that for the water level maxη i ��hL

always holds true.

2. list of cartesian coordinates xl �yl (l � 1�Nv) for all vertices of the grid; each line of inputcontains the following data for a vertex:

(a) x: x-coordinate;

(b) y: y-coordinate.

3. list of data related to the Np polygons in the grid; each input line contains the followingdata for one polygon:

(a) ks: number of sides/vertices Si (3 � Si � 4) of the polygon;

(b) xc: x-coordinate for the center of the polygon;

(c) yc: y-coordinate for the center of the polygon;

(d) list of pairs (nen,is) for each vertex/side (l � 1�Si) of the polygon:

i. nen: index for the l-th vertex;

ii. is: index for the l-th side/edge.

Please notice that vertices as well as sides must be prescribed consecutively incounter-clockwise orientation for each polygon.

4. list of data related to the Ns edges/sides in the grid; each input line contains the fol-lowing data for one side/edge:

(a) hu: depth h;

(b) jb: index for the first vertex;

(c) jb: index for the second vertex;

(d) je(2): indices for the left (i� j�1�) as well as the right (i� j�2�) polygon adjacent tothe actual edge; zero must be prescribed if the respective neighbour polygon isnot present (e. g. along boundaries).



D.1.3 Example fileThe following lines show an (abbreviated) example for the grid data file "untrim.grd".The line-numbers l?? indicated are not part of the grid input file.

l01 &LISTGRD

l02 NE = 5154

l03 NS = 8166l04 NV = 3013

l05 NBC = 6l06 NR = 1621

l07 NSI = 6572l08 NSF = 6578

l09 ANGLE = 0

l10 HLAND = -10000l11 LOCATION = "channel turn with rectangular cross section"

l12 /l13 4500.0 440.0

l14 4500.0 460.0

l15 4500.0 480.0l16 ... cont.

l17 3 4495.0 450.0 2 4 2549 2 1 3l18 3 4495.0 470.0 2 5 3 7 2549 4

l19 3 4495.0 490.0 4 10 1460 8 3 9

l20 ... cont.l21 -10001.0 1 870 0 5143

l22 10.0 1 2549 5143 1l23 -10001.0 1 2 1 0

l24 10.0 2 2549 1 2

l25 -10001.0 2 3 2 0l26 10.0 3 1304 5144 5145

l27 10.0 3 2549 2 5144l28 10.0 3 1460 5145 3

l29 -10001.0 3 4 3 0l30 10.0 4 1460 3 4

l31 ... cont.

A few comments on the short example shown above:

l01 – l11: contents of the namelist LISTGRD; the ANGLE was set to be 0, which also meansthat no Coriolis effects will be taken into account in the simulation.

l05 – l05: there are six polygons with prescribed water level;

l07 – l08: there are six sides with prescribed flow;

l12 – l12: terminator ”/”for the namelist section.

l13 – l13: x- and y-coordinate of the first vertex.

l14 – l16: coordinates for the remaining vertices.



l17 – l17: polygon-oriented data for the first polygon (triangle);

l18 – l20: polygon-oriented data for the remaining polygons.

l21 – l21: edge-oriented data for the first edge; the depth of the first edge (�10001.0) issmaller than HLAND, which means that this edge represents permanently dry land (e. g.true for solid walls at the boundaries); on the other hand the left neighbour polygon isnot available for this edge, whereas the right polygon index corresponds to 5143.

l22 – l31: edge-oriented data for the remaining edges.

D.2 Input data file


The input data file is sub-divided into the following sections:

1. Fortran NAMELIST-data section LISTINP: noli = 0 slip = 1.0

(a) nk: number of level surfaces Nz (Nz � 1); if one layer is chosen the depth averagedvelocities will be computed; if more than one layer is chosen the velocity will becomputed for several layers (vertical velocity profile);

(b) nq: steering parameter (0�use hydrostatic pressure approximation, 1�hydrodynamicpressure);

(c) nsp: number of dissolved species (e. g. salinity, temperature, suspended sedi-ment);

(d) epsi: tolerance εη for the free-surface iterative solver (10�8 � εη � 0�1);

(e) qpsi: tolerance εq for the non-hydrostatic pressure iterative solver (10�8 � εη �

0�1);

(f) maxiter: maximum number of iterations nε for the iterative solvers;

(g) theta: impliciteness factor θ (0�5 � θ� 1�0); recommended value θ� 0�6;

(h) delt: numerical time step ∆t;

(i) dxmin: minimum allowed distance δmin (δmin � 0�0) between polygon centers;

(j) dzmin: minimum allowed water depth Hmin (Hmin � 0�0);

(k) dtmin: to solve for tracer transport, the time step ∆t is automatically broken intoa smaller or larger number of substeps ∆τ i; if Ms is the current number of substeps,the substepping procedure will continue as long as ∆t�∑Ms

1 ∆τi � dtmin holds;

(l) hvis: horizontal molecular viscosity νhm (νh

m � 0�0);

(m) vvis: vertical molecular viscosity νvm (νv

m � 0�0);

(n) hdif: horizontal molecular diffusivity Khm (Kh

m � 0�0);

(o) vdif: vertical molecular diffusivity Kvm (Kv

m � 0�0);



(p) trx: inverse of the relaxation time at open boundaries;

(q) cz: Chezy bottom friction coeffizcient Cz (Cz � 0�0);

(r) noli: switch non-linear advective terms on (noli� 1) or off (noli� 0);

(s) slip: slip parameter for velocity boundary condition at solid vertical walls, e.g.:

i. free slip: 1.0;

ii. partial slip: 0.0;

iii. no slip: -1.0.

2. if more than one layer nk was chosen, nk-1 level surfaces must be prescribed from topto bottom.

Notice: The use of parameter epsi can be optimized by checking the influence on resultsfrom CALL check continuity.

D.2.2 Example fileThe following lines show an example for the input data file untrim.inp. The line-numbersl?? indicated are not part of the input data file.

l01 &LISTINP

l02 NK = 10

l03 NQ = 1l04 NSP = 1

l05 EPSI = 1.00E-04l06 QPSI = 1.00E-04

l07 MAXITER = 1000

l08 THETA = 0.6l09 DELT = 0.25

l10 DXMIN = 5.00000E-02l11 DZMIN = 5.00000E-03

l12 DTMIN = 1.00000E-04l13 HVIS = 0.0

l14 VVIS = 0.0

l15 HDIF = 0.0l16 VDIF = 0.0

l17 TRX = 1000000000.0l18 CZ = 50.0

l19 NOLI=1

l20 SLIP=1.0l21 /

l22 -2.00000l23 -1.00000

l24 0.00000

l25 1.00000l26 2.00000

l27 4.00000



l28 6.00000l29 8.00000

l30 10.00000


l02 – l02: ten vertical layers are prescribed in this case, which means that the vertical flowprofile can be resolved.

l03 – l03: the pressure will be computed during the simulation because the pressure is as-sumed to be non-hydrostatic.

l04 – l04: one dissolved specie (e. g. temperature) is taken into account.

l05 – l06: tolerances for the iterative solvers.

l07 – l07: maximum number of iterations for the iterative solvers.

l08 – l08: an impliciteness factor of 0.6 guarantees numerical stability.

l09 – l09: small time steps are necessary if the time scales of the physical processes are alsosmall.

l10 – l10: minimum horizontal distance between polygon centers.

l11 – l11: minimum allowed water depth.

l12 – l12: minimum substep size.

l13 – l16: molecular viscosities are set to zero in this situation (inviscid case).

l17 – l17: the inverse of the relaxation time is set to a high number at open boundaries; as aconsequence of this outgoing waves may be reflected (back) at open boundaries.

l18 – l18: default bottom friction coefficient.

l19 – l19: non-linear advective terms are switched on;

l20 – l20: free slip condition for velocities at lateral boundaries;

l21 – l21: terminator ”/”for the namelist section.

l22 – l30: level surfaces between vertical layers.

D.3 Source and sink data file


The input file for sources and sinks is sub-divided into the following sections:

1. number of sources and sinks Nd



(a) ncs: number of sources and sinks Nd (Nd � 0).

2. list of data related to the Nd sources and sinks; each line contains the following data forone source/sink:

(a) ics: polygon index i for the horizontal location of the source/sink;

(b) kcs: layer index k for the vertical position of the source/sink;

If this type of file is absent or empty no sources/sinks will be assumend (Nd � 0).

D.3.2 Example fileThe following lines show an example for the source/sink data file untrim.srs. The line-numbers l?? indicated are not part of the source/sink data file.

l01 3

l02 1254 2l03 1254 3

l04 3140 3


l01 – l01: three sources/sinks are prescribed;

l02 – l03: the first two sources/sinks are located in the same polygon but at different depth(within layers two and three);

l04 – l04: the third source/sink is located in a different polygon (within layer three).


Documents

BUNDESANSTALT FUR WASSERBAU¨ · BUNDESANSTALT FUR WASSERBAU¨ Karlsruhe•Hamburg•Ilmenau Technical Report Mathematical Model UnTRIM User Interface Description – Version June