SHYFEM

Finite Element Model for Coastal Seas

User Manual

The SHYFEM Group

Georg Umgiesser
Oceanography, ISMAR-CNR
Arsenale Tesa 104, Castello 2737/F
30122 Venezia, Italy

[email protected]

Version 6.1.74

May 5, 2014
Contents

Disclaimer iii

1 Overview 1
1.1 What is it . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Installing SHYFEM 2
2.1 Downloading and unpacking . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.2 Needed software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2.3 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.4 Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.5 Compatibility problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.6 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

3 Preprocessing: The numerical grid 8

3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.2 Converting to GRD format . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.3 Boundary line: smoothing and reducing . . . . . . . . . . . . . . . . . . . 9
3.4 Other information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.5 Creating the basin file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3.5.1 The pre-processing routine vp . . . . . . . . . . . . . . . . . . . . 12
3.5.2 Optimization of the bandwidth . . . . . . . . . . . . . . . . . . . . 13
3.5.3 Internal and external node numbering . . . . . . . . . . . . . . . . 14

4 Running SHYFEM 15
4.1 How to run: the Parameter Input File (STR) . . . . . . . . . . . . . . . . . 15
4.1.1 The General Structure of the Parameter Input File . . . . . . . . . . 15
4.2 Basic usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.2.1 Minimal simulation . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2.2 Boundary conditions . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.3 Advanced usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.3.1 Variable time step . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.3.2 3D computations . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.3.3 Baroclinic terms . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.3.4 Turbulence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

A Hydrodynamic equations and resolution techniques 23

A.1 Equations and Boundary Conditions . . . . . . . . . . . . . . . . . . . . . 23
A.2 The Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
A.2.1 Discretization in Time - The Semi-Implicit Method . . . . . . . . . 24
A.2.2 Discretization in Space - The Finite Element Method . . . . . . . . 25
A.2.3 Mass Conservation . . . . . . . . . . . . . . . . . . . . . . . . . . 28
A.2.4 Inter-tidal Flats . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

i
B File formats 29
B.1 GRD file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

C Parameter list 31
C.1 Parameter list for the SHYFEM model . . . . . . . . . . . . . . . . . . . . 31
C.1.1 Section $title . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
C.1.2 Section $para . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
C.1.3 Section $name . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
C.1.4 Section $bound . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
C.1.5 Section $wind . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
C.1.6 Section $extra . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
C.1.7 Section $flux . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
C.2 Parameter list for the post processing routines . . . . . . . . . . . . . . . . 43
C.2.1 Section $title . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
C.2.2 Section $para . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
C.2.3 Section $color . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
C.2.4 Section $arrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
C.2.5 Section $legend . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
C.2.6 Section $legvar . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
C.2.7 Section $name . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Bibliography 50

ii
Disclaimer

Copyright (c) 1992-2012 by Georg Umgiesser

Permission to use, copy, modify, and distribute this software and its docu-
mentation for any purpose and without fee is hereby granted, provided that the
above copyright notice appear in all copies and that both that copyright notice
and this permission notice appear in supporting documentation.
This file is provided AS IS with no warranties of any kind. The author shall
have no liability with respect to the infringement of copyrights, trade secrets
or any patents by this file or any part thereof. In no event will the author be
liable for any lost revenue or profits or other special, indirect and consequential
damages.
Comments and additions should be sent to the author:

Georg Umgiesser
Oceanography, ISMAR-CNR
Arsenale Tesa 104, Castello 2737/F
30122 Venezia
Italy

Tel. : ++39-041-2407943
Fax : ++39-041-2407940
E-Mail : [email protected]

iii
Chapter 1

Overview

1.1 What is it
The finite element program SHYFEM is a program package that can be used to resolve the hy-
drodynamic equations in lagoons, coastal seas, estuaries and lakes. The program uses finite
elements for the resolution of the hydrodynamic equations. These finite elements, together
with an effective semi-implicit time resolution algorithm, makes this program especially
suitable for application to a complicated geometry and bathymetry.
This version of the program SHYFEM resolves the depth integrated shallow water equations.
It is therefore recommended for the application of very shallow basins or well mixed estu-
aries. Storm surge phenomena can be investigated also. This two-dimensional version of
the program is not suited for the application to baroclinic driven flows or large scale flows
where the the Coriolis acceleration is important.
Finite elements are superior to finite differences when dealing with complex bathymetric
situations and geometries. Finite differences are limited to a regular outlay of their grids.
This will be a problem if only parts of a basin need high resolution. The finite element
method has an advantage in this case allowing more flexibility with its subdivision of the
system in triangles varying in form and size.
This model is especially adapted to run in very shallow basins. It is possible to simulate
shallow water flats, i.e., tidal marshes that in a tidal cycle may be covered with water during
high tide and then fall dry during ebb tide. This phenomenon is handled by the model in a
mass conserving way.
Finite element methods have been introduced into hydrodynamics since 1973 and have
been extensively applied to shallow water equations by numerous authors [3, 9, 5, 4, 6].
The model presented here [10, 11] uses the mathematical formulation of the semi-implicit
algorithm that decouples the solution of the water levels and velocity components from
each other leading to smaller systems to solve. Models of this type have been presented
from 1971 on by many authors [7, 2, 1].

1
Chapter 2

Installing SHYFEM

2.1 Downloading and unpacking

The source code of the model is provided in a file named shyfem-6 1 74.tar.gz or simi-
lar, depending on the version of the code. In this case the version is 6 1 74. The file can be
downloaded from the SHYFEM web-site1 , or by contacting directly its authors.
Once you have downloaded the model distribution, move the file to the directory in which
you want to install the model and unpack the distribution. In the following we will assume
that the file is in your home directory and your home directory is called /home/model.
However, any other directory works as well. To unpack the distribution in your home
directory, move there and run the command:

cd /home/model
tar -xzvf shyfem-6 1 74.tar.gz

At this point a new folder named /home/model/shyfem-6 1 74 has been created. This
directory is the root of the SHYFEM model. All other commands given in this chapter
assume that you are in this directory. Therefore, before reading on, please move into this
directory:

cd /home/model/shyfem-6 1 74

2.2 Needed software

The source code is composed mainly of Fortran 77 files, but files written in C, Fortran 90,
Perl and Shell scripts are also present.
In order to use the model you have to compile it in a Linux Operating System. Several
software products must be present in order to be able to compile the model. Please refer to
the documentation of your Linux distribution for installing these programs.

• The package make is required for compilation.

• The perl interpreter, the bash shell and the gcc C compiler are necessary for com-
piling.
• A Fortran 77 and 90 compiler. Supported compilers are the Gnu g77 and g90 com-
pilers, the new Gnu compiler gfortran, the Intel Fortran compiler ifort or the
Portland group pgf90 Fortran compiler.
1 http://www.ismar.cnr.it/shyfem/

2
Please note that you might already have everything available in your Linux distribution,
with the exception maybe of the Fortran compiler.
To find out what software is installed on your computer and what you still have to install
you can run the following command:

make check_software

If you get something like bash: make: command not found, then you do not have make
installed. Please first install the make command and then run the command again.
The output of the command will show you what software you will still have to install. The
software is divided into different sections. The first section is needed software, which you
will not be able to do without. The next section is recommended software, which you really
should install, but for compilation and running you will not necessarily need it. The last
section is software which is optional, but which makes life easier.
You can always run make check_software again to check if the software had been suc-
cessfully installed. When you are satisfied with the output you can go to the next section.
Please note that you have to carry out the steps in this section only the first time you install
the model. If you install a new version of SHYFEM software you can skip these steps.

2.3 Installation
Before compiling it is advisable to install some files for a simpler usage of the model. As
long as you only want to tun a simulation, this step is not strictly necessary. But if you
will run some scripts of the distribution, these scripts will not work properly if you do not
install the model.
In order to install the model, you should run

make install

This command will do the following:

• It hardcodes the installation directory in all scripts of the model so only programs of
the installed version will be executed.
• It inserts a symbolic link syhfem from the home directory to the root of the SHYFEM
installation.
• It inserts a small snippet of code into the initialization files .bashrc .bash profile
.profile that are in your home directory. This will adjust your path to point to the
SHYFEM directory and gives you access to some administrative commands.

After this command you will find the original files that have been changed in your home
directory saved with a trailing number (e.g., .profile.35624 or similar). If you encounter
problems, just substitute back these files.
In order that your new settings will take effect you will have to log out and log in again. Al-
ternatively, you will have to execute one of the files .bashrc .bash profile .profile
that have actually changed. If .bashrc has been changed, then run . ˜/.bashrc.
If you do not want to run the installation routine, you should at least manually insert a
symbolic link to the root of the SHYFEM model. Otherwise some of the commands and
shell scripts will not work properly. This can be done with the command

cd
ln -s /home/model/shyfem-6 1 74 shyfem

3
from your home directory. If there is already such a link existing you will first have to
delete it (rm shyfem).
You should also think about the possibility to add the fembin path to your default paths to
have the main utility commands always available. To do this open your .bashrc file in the
home directory and add the following lines at the end of the file:

SHYFEMDIR=$HOME/fem
PATH=$PATH:$SHYFEMDIR/fembin
export SHYFEMDIR PATH

However, the same effect can be achieved more easily by using the abovementioned com-
mand make install.
If you ever want to uninstall the model, you can do it with the command make uninstall.
This will delete the symbolic link, cancel the hard links in the model scripts and restore the
systemfiles .bashrc .bash profile .profile to their original content.
Please note that you will still have to delete manually the model directory. This can be
done with the command rm -rf /home/model/shyfem-6 1 74). In this way, however,
changes to the code you have made will be lost.

2.4 Compilation
In order to compile the model you will first have to adjust some settings in the Rules.make
file. Assuming that you are already in the SHYFEM root directory (in our case it would
be /home/model/shyfem-6 1 74), open the file Rules.make with a text editor. In this file
the following options can be set:

• Parameters. In this section you have to set the maximum number of nodes (NKNDIM)
and elements (NELDIM) used by your grids. You might also have to set also the maxi-
mum number of elements attached to a node (NGRDIM) and the maximum bandwidth
(MBWDIM) of the z-level matrix. You can find these numbers when you create the
basin file with vpgrd. Finally you have to specify the maximum number of vertical
levels (NLVDIM). It is advisable to set this value close to the desired number of ver-
tical levels, since it affects the model speed performance. So, if you want to run the
model in 2D mode, please set NLVDIM to 1. For all other possible parameter settings
please have a look at param.h. However, you should never directly change this file.
Always make changes to the parameters in the Rules.make file.
• Compiler. Set the compiler you want to use. Please see also the section on needed
software and the one on compatibility problems to learn more about this choice.
• Parallel compilation. Some parts of the code are parallelized with OpenMP
statements. Here you can set if you want to use it or not. All supported compilers
(except g77) accept OpenMP statements.
• Solver for matrix solution. There are three different solvers implemented.
The GAUSS solver is the most robust and best tested solver, but it is quite slow. The
PARDISO solver needs an external library available at the Intel web-site2 , that can be
freely downloaded for non-commercial use. The Pardiso solver is parallelized, but
it seems to be a little slower than the SPARSKIT solver. The SPARSKIT solver is the
recommended solver, since it seems to be the fastest one. However, if you are ever
in doubt about your results you might want to revert back to the GAUSS solver and
check the results.
2 http://software.intel.com/en-us/articles/code-downloads/

4
 • NetCDF library. If you want output files in NetCDF format you need the NetCDF
library.
• GOTM library. The GOTM turbulence model is already included in the code. How-
ever, a newer and better tested version is available as an external module. In order to
use it please set this variable to true. This is the recommended choice. You will need
a Fortran 90 compiler to enable this choice.
• Ecological module. This option allows for the inclusion of an ecological mod-
ule into the code. Choices are between EUTRO, ERSEM and AQUABC. Please refer to
information given somewhere else on how to run these programs.

• Compiler options. Here several sections are present, one for each supported com-
piler. Normally it should not be necessary to change anything beyond this point.

Once you have set all these options you can start compilation with

make clean
make fem

This should compile everything. In case of a compilation error you will find some messages
during compilation and also at the bottom of the output, where a check is run to see, if the
main routines have been compiled.
Please remember that you will always have to run the commands above when you change
settings in the Rules.make file. If you only change something in the code, or if you only
change dimension parameters, it might be enough to run only make fem, which only com-
piles the necessary files. However, if you are in doubt, it is always a good idea to run
make clean or make cleanall before compiling, in order to start from a clean state.

2.5 Compatibility problems

The SHYFEM program is designed to work with most of the compilers that are available.
Normally there should be no problems with compatibility. However you have to keep in
mind some points that are listed below.
The supported compilers for SHYFEM are

• g77 This the old GNU compiler. It is Fortran 77 only. It is also a little outdated and
is not supported anymore by the major distributions. If you do not need software that
relies on Fortran 90 it is still possible to use it. However, GOTM and some ecological
modules are relying on Fortran 90 and cannot be used with the g77 compiler.
• gfortran This is the actual GNU compiler. It also supports Fortran 90. This is the
compiler that you will find in recent distributions.
• ifort This is the INTEL compiler. You will have to download and install it on your
own. It is very efficient and normally faster than the GNU compiler.
• pgf90 This is the Portland group compiler. It is a commercial compiler. It creates
very efficient code.

Whatever compiler you choose to use, you have to set your choice in the Rules.make
file. Even if not desirable, different compilers can give you slightly different results in the
computations. This is due to the different optimizations enabled and maybe a different
treatment of accuracy and round off. Other compatibility issues are the following.

5
 • With g77 and ifort it is possible to open the same file in read only mode more
than once. This is useful, e.g., if you have two open boundaries, but you want to
prescribe the same value on these two boundaries. With gfortran or pgf90 you
cannot do this. A file, even in read only mode, can be opened only once. In the
above example you therefore have to copy the input file to a new name (duplicate it)
and then prescribe the two different files as boundary conditions.
• With gfortran it is very difficult to decide if a file is formatted or unformatted.
Some modules allow the use of either formatted or unformatted input files, where
the check on the file type is made via software. In case of gfortran this may not
work reliably. The only solution to this problem is to specify the file type directly in
the code.
• Objects generated during compilation and libraries used in linking are normally not
compatible between compilers. What this means is that, when you switch compiler,
you will have to recompile everything with make cleanall; make fem. Otherwise
you will encounter errors during the linkage process.
• Unformatted files are normally not portable between different compilers. You nor-
mally cannot use a basin file created with programs compiled with one compiler
together with a program compiled with another compiler. The same is true for unfor-
matted data files (initial conditions, wind and meteo forcing, etc.).
If you have problems reading a basin file, try basinf. If this is not working chances
are high that you have the problem described above. In case of unformatted data files
the diagnosis is not so easy. In any case, you can solve the problem recompiling all
programs with the commands make cleantotal; make fem and then re-creating
all unformatted files with the newly compiled programs. In case of the basin file,
you will have to run the pre-processor on the grid again.
If you have obtained unformatted data files from others, then there is really no easy
solution to this problem. Exchanging unformatted files between different computers
and compilers is never a good idea.
• A similar problem exists if you switch files between different architectures (32 bit
and 64 bits), even if created with the same compiler. These files are normally not
portable.
• Nan values (Not a Number) are treated differently between different compilers. Nan
values are created if a not well defined operation is executed (divide by 0 or square
root of a negative number). All compilers above (except pgf90) treat Nans to be not
comparable to any number. This means that a logical expression a.eq.a is always
false if a is a Nan. However the pgf90 compiler treats Nans to be comparable to
any other number. So, an expression like a.ne.a will evaluate to true. SHYFEM
includes code to handle these problems gracefully, but incompatibilities might still
show up.
• In parallel execution you might get a segmentation fault during execution. This
is normally due to limited stack size. You can change the behavior by increasing
the stack size (ulimit -s unlimited) on the console before running the program.
Compilers may behave differently. Please see also the section on parallel execution
in the file Rules.make.

2.6 Summary
In summary, the following steps have to be carried out before you will be able to run the
model:

6
 • Get the distribution and unpack it in a place of your choice.
• Move to the root of the distribution (e.g., cd /home/model/shyfem-6 1 74).
• Check if all software is available (make check_software). This step has to be done
only the first time you install SHYFEM on a computer.

• Install the model (make install). This has to be done every time you get and install
a new version of the model.
• Adjust options in Rules.make. This has to be done every time you change options
(compiler, parallel execution, etc.). After this you have to run also make cleanall.

• Adjust dimension parameters in Rules.make. This has to be done the first time and
every time you change application (basin, etc.) to adapt the dimensions to the new
problem. You might also run make cleanall after this step, but it is not required.
• Compile the programs with make fem and have a look at the error messages.

Moreover, below a summary of administrative commands is given that are available in

SHYFEM.

make version shows version of distribution

make clean deletes objects and executables from a previous
compilation
make cleanall same as make clean but also deletes compiled li-
braries
make fem compiles SHYFEM
make doc makes this manual (femdoc/shyfem.pdf)
make check_software checks the availability of installed software
make check_compilation checks if all programs have been compiled
make changed finds files that are changed with respect to the
original distribution
make changed_zip zips files that are changed with respect to the orig-
inal distribution to the file changed_zip.zip
make install installs SHYFEM
make uninstall uninstalls SHYFEM

Finally, if you have installed the model with make install, the following utility com-
mands are available

shyfemdir shows information about actual SHYFEM settings

shyfemdir fem_dir sets fem_dir to be the new default SHYFEM version
shyfeminstall shows information about original SHYFEM installation
shyfemcd moves into root of actual SHYFEM directory

7
Chapter 3

Preprocessing: The numerical

grid

3.1 Overview
Before you can start using the model you have to create a numerical grid. Ths step is more
difficult for models that work on unstructured grids (like finite element models) than for
finite difference models, where often it is enough to have a regular gridded bathymetry to
start running simulations.
This chapter describes the steps that you have to take in order to be able to create a numer-
ical grid for SHYFEM. If you are in the happy position to already have a numerical finite
element grid, then you can jump ahead to the section on how to transform to/from other
grid formats. You might still have to interpolate a bathymetry onto the numerical grid, so
you will have to refer to the section on interpolating bathymetry. In any case, at the end
you will have to create a (unformatted) basin file, so that SHYFEM is able to read in the
information.
The steps that have to be carried out to create a numerical grid are

1. obtain raw digital data of the coastline and the bathymetry

2. convert the digital data into a format GRD that is read by the provided routines

3. prepare the coastline

4. create the numerical grid with an automatic grid generator
5. regularize the grid
6. interpolate bathymetry onto the created grid

7. create the basin file (the finite element version of the grid file)

As mentioned above, some of the steps can be skipped if you already have a finite element
grid. If you already have a grid with bathymetry information you can jump to point 7.
However, you will have to convert your grid into the GRD format used by SHYFEM. The
GRD format is documented in the appendix. For some of the most common unstructured
grid formats routines are available to convert between these formats and the GRD format. In
any case, the GRD format is quite easy to parse and write, so you might be able to write a
transformation routine yourself.
In the following a description is given what you have to do if you start from scratch. Please
refer to the section on other programs to create a grid for conversion routines.

8
3.2 Converting to GRD format
Data files with boundary line and bathymetry should be given. These files have to be
transformed into GRD files, that can be read and manipolated with the programs mesh and
grid. Examples of how to do so can be found in coast.pl and ldb.pl for the coastline and
bathy.pl for the bathymetry points.

coast.pl mpcoast.dat > coast.grd

bathy.pl mpbathy.dat > depth.grd

Please note that the coordinates for the GRD files should be always in meters. Therefore,
if you have your coordinates in other units, you have to adjust the conversion routines in
order to create the new coordinates in meters.
Please note that UTM coordinates are in meters, so UTM coordinates are fine. However,
since UTM coordinates are normally huge numbers, there might be an accuracy problem
when you try to create the grid. If this happens, you should first shift your UTM coordinates
so that the origin of your new coordinate system coincides with the central point of your
grid. This translation can be done using the program grd_transl.pl.
Other transformation routines are:

• dxf2grd.pl Transforms a grid from DXF (Autocad) to GRD format. This is still ex-
perimental.
• kml2grd.pl Transforms a grid from the Google Earth format KML to GRD format.
• xyz2grd.pl Transforms a simple list of nodes to GRD format. Every line contains 3
values (x, y, z) or two values (x, y), when the information on depth is missing.

Please note that for SHYFEM depth values have to be positive. If your files have depth
values as negative numbers, you will have to invert them. You can use the command

grd_modify.pl -depth_invert grd-file

to achieve this task.

3.3 Boundary line: smoothing and reducing

With the routine grid the coastline can be viewed. However, normally the line needs some
post-processing. It might either have resolution which is too high, island might show up as
open lines etc..
It is important that there is one closed boundary line that defines the whole domain of the
computation. If you have an open coastline, please close the line with the routine grid at
the places where you want your open boundary to be.
Once this domain boundary line has been defined, care has to be taken that the lines inside
this domain, which denote islands, are closed.
Finally the resolution of the boundary lines (coast and islands) have to be adjusted. If the
cosatline is left as it is you might have a much too high resolution along the boundaries.
This is due to the fact that the meshing algorithm does not discard any points given to it.
This means that all boundary nodes are used for the meshing. Therefore, if you have a
very high resolution boundary line, you will get many elements along the boundary amd
reletively little elements (depending on the number of internal points) in the inside of the
basin.
Smoothing and reduction of the boundary lines can be done with the routine reduce. The
command is

reduce -s sigma -r reduct coast.grd

9
Here sigma specifies the langth scall for the smoothing operator and reduct is the length
scale below which points may be deleted. Both values have to be given in the same units of
the coordinates of the file coast.grd, so normally meters. The smoothed file can be found
in smooth.grd and the subsequently reduced file in reduct.grd.
If there are some points in the boundary line that should not be smoothed they can be given
a depth value of -1. This is a flag that indicates that the position of these points will not be
touched.

3.4 Other information

Construct a background grid
===========================

If you want a grid with a uniform solution all over, then

you are already in a position to run the meshing algorithm.
You just say: "mesh -I2000 coast-new.grd" and then
the constructed mesh will be in final.grd. The number 2000
means that you want aprox. 2000 internal points in the domain.
You may adjust this number to your needs.

However, you will normally want to have different resolution

in the domain (high at the inlets of lagoons, at interesting
sites like harbours etc..). Then you have to construct a
background grid that gives an indication to the meshing
algorithm what kind of resolution is need in what area.

You open the coastline with grid and construct elements

that cover the parts or all of the domain. The areas where
no background grid exists will use the (constant) resolution of the
domain computed by the routine mesh using the total number of
internal nodes (2000 in this example).

Where a background grid exists the model uses the depth values at the
element vertices (nodes) to compute a new value for this resolution.
The depth value acts like a factor that multiplies the constant
overall resolution to obtain a local resolution. So, for example,
constructing a background grid and setting all depth values to 1
would not change the resolution at all from a situation without
background grid. A factor higher than 1 increases the resolution
and one smaller than 1 decreses it. Therefore, in areas where
resolution should be higher than average you can set it to
2 or higher, and in other areas, where you want lower resolution,
you can set it to 0.5 or lower. All nodes of the background grid
need to have a depth (resolution) value. Inside each background
element the resolution is interpolated between the three nodes
(vertices).

In order to distinguish the background grid from the elements

that are constructed by the meshing routine, they must become
a unique element type. You can set it to a value that is not
used for other elements (99 is a good choice). All elements
of the background grid must have this element type.

10
Please extract the background grid from the grid file you just
have constructed by running exgrd: "exgrd -LS coast-new.grd".
The file "new.grd" contains only the background grid. Rename it to
something more useful (mv new.grd bck1.grd). You are then
ready to start the meshing algorithm.

manually construct background grid using coast-new.grd

delete coastline (leave only background elements in file)
exgrd -LS coast-new.grd
set depth at nodes for resolution
set type in elements to 99
rename to bck1.grd
mv new.grd bck1.grd

Meshing of the basin

====================

The meshing algorithm is called mesh. Please see "mesh -h" for
help of the command line options. The most important are:

-I2000 use aprox. 2000 internal nodes for the domain

-g99 element type of background grid is 99

With this parameters the call to mesh would be

"mesh -I2000 -g99 coast-new bck1".
The created mesh can be found in final.grd.

Please note that you can specify more than one file for the coast line,
so you could keep the domain line and the island lines in seperate files.
You can also have different background grid for different areas in
different files. So a call like this is also possible:
"mesh -I2000 -g99 coast island1 island2 bck1 bck2 bck3".

After the meshing please have a look at the result (final.grd).

If you need more overall resolution, increase the number of internal
points (here 2000). If you need more resolution in the background grid,
open the background file and increase the factor (depth) value where needed.
You might also need other areas with a background grid. Once you
are satisfied with the result please save it to a more meaningful name.

mesh -I2000 -g99 coast-new bck1

mv final.grd mesh1.grd

Adjust elements for regularity

==============================

After the creation of the mesh, the grid is still not good enough
for usage in a finite element model. This is due to the fact that
the grid is too irregular. Therefore a program has to be applied
that regularizes the grid.

The program is called regularize. It must be given the input grid file

11
(irregular) and creates a new one with much more regular characteristics.
The program has to be called as:
"regularize mesh1.grd mesh2.grd".
In this case the new regular grid is in mesh2.grd.

Interpolate bathymetry
======================

To interpolate bathymetry, a grd file with single points containig

depth values has to be available. This file, together with the basin
onto which the bathymetry has to be interpolated, has to be specified
for the program basbathy. The simplest call is:

basbathy mesh2 bathy

where bathy.grd is the grd file with the bathymetry values and
mesh2 is the basin for which to interpolate the bathymetry.
Different types of interpolation can be used. Please run
"basbathy -h" for more options.

The new grd file will be in "new.grd".

basbathy mesh2 bathy

mv new.grd mesh3.grd

Create basin for FEM model (bandwidth optimization)

===================================================

Before proceeding to the simulations we must first create a

representation of the basin suitable for the finite element model.

In order to create the finite element reppresentation of the

grid, please run "vpgrd mesh3". This creates a file mesh3.bas.
This is a binary file suitable for being read by the finite
element model.

vpgrd mesh3

3.5 Creating the basin file

The pre-processing routine vp is used to generate an optimized version of the file that de-
scribes the basin where the main program is to be run. In the following a short introduction
in using this program is given.

3.5.1 The pre-processing routine vp

The main routine hp reads the basin file generated by the pre-processing routine vp and uses
it as the description of the domain where the hydrodynamic equations have to be solved.
The program vp is started by typing vp on the command line. From this point on the
program is interactive, asking you about the basin file name and other options. Please

12
follow the online instructions.
The routine vp reads a file of type GRD. This type of file can be generated and manipulated
by the program grid which is not described here. In short, the file GRD consists of nodes
and elements that describe the geometrical layout of the basin. Moreover, the elements
have a type and a depth.
The depth is needed by the main program hp to run the model. The type of the element is
used by hp to determine the friction parameter on the bottom, since this parameter may be
assigned differently, depending on the various situations of the bottom roughness.
This file GRD is read by vp and transformed into an unformatted file BAS. It is this file that
is then read by the main routine hp. Therefore, if the name of the basin is lagoon, then the
file GRD is called lagoon.grd and the output of the pre-processing routine vp is called
lagoon.bas.
The program vp normally uses the depths assigned to the elements in the file GRD to
determine the depth of the finite elements to use in the program hp. In the case that these
depth values are not complete, and that all nodes have depths assigned in the GRD file, the
nodal values of the depths are used and interpolated onto the elements. However, if also
these nodal depth values are incomplete or are missing altogether, the program terminates
with an error.

3.5.2 Optimization of the bandwidth

The main task of routine vp is the optimization of the internal numbering of the nodes and
elements. Re-numbering the elements is just a mere convenience. When assembling the
system matrix the contribution of one element after the other has to be added to the system
matrix. If the elements are numbered in terms of lowest node numbers, then the access
of the nodal pointers is more regular in computer memory and paging is more likely to be
inhibited.
However, re-numbering the nodes is absolutely necessary. The system matrix to be solved
is of band-matrix type. I.e., non-zero entries are all concentrated along the main diagonal
in a more or less narrow band. The larger this band is, the larger the amount of cpu time
spent to solve the system. The time to solve a band matrix is of order n · m2 , where n is the
size of the matrix and m is the bandwidth. Note that m is normally much smaller than n.
If the nodes are left with the original numbering, it is very likely that the bandwidth is
very high, unless the nodes in the file GRD are by chance already optimized. Since the
bandwidth m is entering the above formula quadratically, the amount of time spent solving
the matrix will be prohibitive. E.g., halving the bandwidth will speed up computations by
a factor of 4.
The bandwidth is equal to the maximum difference of node numbers in one element. It is
therefore important to re-number the nodes in order to minimize this number. However,
there exist only heuristic algorithms for the minimization of this number.
The two main algorithms used in the routine vp are the Cuthill McGee algorithm and the
algorithm of Rosen. The first one, starting from one node, tries to number all neighbors in
a greedy way, optimizing only this step. From the points numbered in this step, the next
neighbors are numbered.
This procedure is tried from more than one node, possibly from all boundary nodes. The
numbering resulting from this algorithm is normally very good and needs only slight en-
hancements to be optimum.
Once all nodes are numbered, the Rosen algorithm tries to exchange these node numbers,
where the highest difference can be found. This normally gives only a slight improvement
of the bandwidth. It has been seen, however, that, if the node numbers coming out from the
Cuthill McGee algorithm are reversed, before feeding them into the Rosen algorithm, the
results tend to be slightly better. This step is also performed by the program.
All these steps are performed by the program without intervention by the operator, if the
automatic optimization of bandwidth is chosen in the program vp. The choices are to not

13
perform the bandwidth optimization at all (GRD file has already optimized node number-
ing), perform it automatically or perform it manually. It is suggested to always perform
automatic optimization of the bandwidth. This choice will lead to a nearly optimum num-
bering of the nodes and will be by all means good results.
If, however, you decide to do a manual optimization, please follow the online instructions
in the program.

3.5.3 Internal and external node numbering

As explained above, the elements and nodes of the basin are re-numbered in order to opti-
mize the bandwidth of the system matrix and so the execution speed of the program.
However, this re-numbering of the node and elements is transparent to the user. The pro-
gram keeps pointers from the original numbering (external numbers) to the optimized num-
bering (internal numbers). The user has to deal only with external numbers, even if the
program uses internally the other number system.
Moreover, the internal numbers are generated consecutively. Therefore, if there are a total
of 4000 nodes in the system, the internal nodes run from 1 to 4000. The external node
numbers, on the other side, can be anything the user likes. They just must be unique. This
allows for insertion and deletion of nodes without having to re-number over and over again
the basin.
The nodes that have to be specified in the input parameter file use again external numbers.
In this way, changing the structure of the basin does not at all change the node and element
numbers in the input parameter file. Except in the case, where modifications actually touch
nodes and elements that are specified in the parameter file.

14
Chapter 4

Running SHYFEM

In the following an overview is given on running the model SHYFEM. The model needs a
parameter input file that is read on standard input. Moreover, it needs some external files
that are specified in this parameter input file. The model produces several external files
with the results of the simulation. Again, the name of this files can be influenced by the
parameter input file

4.1 How to run: the Parameter Input File (STR)

The model reads one input file that determines the behavior of the simulation. All possible
parameters can and must be set in this file. If other data files are to be read, here is the place
where to specify them.
The model reads this parameter file from standard input. Thus, if the model binary is called
hp and the parameter file param.str, then the following line starts the simulation
ht < param.str
and runs the model.

4.1.1 The General Structure of the Parameter Input File

The input parameter file is the file that guides program performance. It contains all nec-
essary information for the main routine to execute the model. Nearly all parameters that
can be given have a default value which is used when the parameter is not listed in the file.
Only some time parameters are compulsory and must be present in the file.
The format of the file looks very like a namelist format, but is not dependent on the compiler
used. Values of parameters are given in the form : name = value or name = ’text’. If
name is an array the following format is used :
name = value1 , value2, ... valueN
The list can continue on the following lines. Blanks before and after the equal sign are
ignored. More then one parameter can be present on one line. As separator blank, tab and
comma can be used.
Parameters, arrays and data must be given in between certain sections. A section starts
with the character $ followed by a keyword and ends with $end. The $keyword and $end
must not contain any blank characters and must be the first non blank characters in the line.
Other characters following the keyword on the same line separated by a valid separator are
ignored.
Several sections of data may be present in the input parameter file. Further ahead all sec-
tions are presented and the possible parameters that can be specified are explained. The

15
$title
benchmark test for test lagoon
bench
venlag
$end

$para
itanf = 0 itend = 86400 idt = 300
ireib = 5 czdef = 2.5E-3
dragco = 2.5E-3
$end

$bound1
kbound = 73 74 76
boundn = ’levels1.dat’
$end

$bound2
kbound = 150 157 97 101
boundn = ’levels1.dat’
$end

$name
wind=’win18sep.win’
$end

next are tide gauges used in calibration

$extra ------- tide gauges for calibration ---------

13,133,99,259,328,772,419,1141,1195,1070,1064,942,468,1154
73,74,76,353,350,349,1374,1154,1160,1161,408,409,786,795
$end

Figure 4.1: Example of a parameter input file (STR file)

sequence in which the sections appear is of no importance. However, the first section must
always be section \$title, the section that determines the name of simulation and the
basin file to use and gives a one line description of the simulation.
Lines outside of the sections are ignored. This gives the possibility to comment the param-
eter input file.
Figure 4.1 shows an example of a typical input parameter file and the use of the sections
and definition of parameters.

4.2 Basic usage

This section explains typical usage of the model. It will show how the model can be run
doing basic 2D hydrodynamic simulations, simulate a passive tracer, compute T/S, use
the Coriolis force and apply wind forcing. More advanced usages of the model, like 3D
simulations and the use of the turbulence module will be presented later. This section is
conceived as a simple HOWTO document. For the exact meaning and usage of the single
parameters, please see the section on input parameters.
To run a simulation, two things are needed. The first is the description of the basin and the

16
$title
benchmark test for test lagoon
bench
venlag
$end

$para
itanf = 0 itend = 86400 idt = 300
$end

Figure 4.2: Example of a basic parameter input file (STR file)

numerical grid, which must be prepared beforehand and then must be compiled in a form
that the model can use. How this is been done has already been described in the chapter
dealing with preprocessing.
The second thing that is needed is a description of the simulation and the forcings that have
to be applied. This is done through a parameter input file. Here we call it STR file, because
historically these files always ended with an extension of .str. However, any extension
can be used.

4.2.1 Minimal simulation

A basic version of an STR file can be found in 4.2. In fact, it is so basic, it really does not
do anything. Here only the compulsory parameters have been inserted. These are:

• An introductory section $title where on three lines the following information is

given:

1. A description of the run. This can be any text that fits on one line.
2. The name of the simulation. This name is used for all files that the simulation
produces. These files differ from each other only by their extension.
3. The name of the basin. This is the basin file without the extension .bas.

• A section $para that contains all necessary parameters for the simulation to be run.
The only compulsory parameters are the ones that specify the start of the simulation
itanf, its end itend and its time step idt.

In order to be more helpful, some more information must be added to the STR file. As an
example let’s have a look on 4.1. Here we have added two parameters that deal with the
type of friction to be used. ireib specifies the bottom friction formulation, here through
a simple quadratic bulk formula. (For the exact meaning of the parameters, please refer to
the appendix where all parameters are listed.) The parameter czdef specifies the value to
use for the bottom drag coefficient.

4.2.2 Boundary conditions

In order to have a more meaningfull simulation, we need to specify boundary conditions.
In this section we will deal with the open boundary conditions, e.g., the conditions at the
place where the basin comunicates with other water bodies. For lagoons it would be the
inlets.
For every boundary condition one section $bound must be specified. Since you can have
more than one open boundary you must specify also the number of your boundary, e.g.,

17
$bound1, $bound2 etc. Inside every section you can then specify the various parameters
that characterize your boundary.
Basically there two types of open boundary conditions. Either the water level or the dis-
charges (fluxes) can be specified. The parameter that decides the type of boundary is ibtyp.
A value of one indicates water levels, instead a value of 2 or 3 indicates fluxes. If you
specify discharges entering at the border of the domain, ibtyp = 2 should be specified.
Otherwise, if there are internal sources in the basin then ibtyp = 3 must be used. If you do
not define this parameter, a value of 1 will be used and water levels will be specified.
The only compulsary parameter in this section is the list of boundary nodes. You do this
with the parameter kbound. In the case of ibtype 1 or 2 at least two nodes must be
specified, in order to give an extension of the boundary. The numeration of the boundary
nodes must be consecutive and with the basin on its left side when going along the boundary
nodes. In the case of ibtyp = 3 even a single point can be given.
The boundary values you want to give are normally specified through a a file with a time
series. You give the name of the file that contains the time series with the parameter boundn.
An example with two boundaries can again be found in Fig. 4.1. Here water levels are
prescribed and the values for the water levels are read from a file levels1.dat.
If the values on the boundary you want to impose can be described through a simple sinus
function, you can also give the bounadry values specifying the parameters for the sinus
function. An example of a water level boundary with a tide of ±70cm and a period of 12
hours (semi-diurnal) is given in Fig. 4.3. Note thet zref gives the average water level of
the boundary. If you specify ampli=0 you get a constant boundary value of zref.

$bound1
ibtyp = 1 kbound = 23 25 28
ampli = 0.70 period = 43200 phase = 10800 zref = 0.
$end

Figure 4.3: Example of a boundary with regular sinusoidal water levels. The pahse of
10800 (3 hours) makes sure that the simulation starts at slack tide when the basin is com-
pletely full.

4.3 Advanced usage

4.3.1 Variable time step
Generally SHYFEM is run with a fixed time step given by the parameter idt. This choice is
acceptable when the model runs in unconditionally stable conditions (ie. linear simulation,
no horizontal viscosity).
The introduction of the advective terms (ilin=0) or horizontal viscosity (ahpar greater 0)
can introduce instabilities. To be sure that the model runs in stable conditions, it must be
assured that the Courant Number is smaller than 1. Please note that only in the case of
advection we should call this number the Courant number. However, we will continue to
use the term Courant number for all stability related issues.
In the case of advection the Courant number is defined as
v∆t
Cou = (4.1)
∆x
where v is the current speed, ∆t the time step and ∆x the element size. For finite elements,
due to the triangular grid, this expression is slightly more complicated. As can be seen,
lowering the time step will bring the Courant number below the limit of 1.

18
To keep the Courant Number under the limit it is necessary to adapt the time step at every
computation. The variable timestep is computed introducing in the STR file in the $para
section the parameters itsplt, coumax and idtsyn.
coumax gives the limit of the Courant number. This is normally 1, but since no exact stabil-
ity limit can be derived for the non-linear advective terms, another value can be specified.
If instabilities arise, a slightly lower value than 1 (0.9) can be tried.
itsplt decides about the time step splitting. If this value is 0, the time step will be kept
constant at its initial value. A value of 1 devides the initial time step into (possibly) equal
parts, but makes sure that at the end of the micro time steps one complete macro time step
has been executed. The last mode itsplt = 2 does not care about the macro time step,
but always uses the biggest time step possible. In this case it is not assured that after some
micro time steps a macro time step will be recovered. Please note that the initial macro
time step idt will never be exceeded.
Finally, the parameter idtsyn is only used in case of itsplt = 2. This parameter makes
sure that after a time of idtsyn the time step will be syncronized to this time. Therefore,
setting idtsyn = 3600 means that there will be a time stamp every hour, even if the model
has to take one very small time step in order to reach that time.
An example of how to set the variable time stepping scheme is shown in Fig. 4.4. Here
the Courant number is lowered to 0.9 and the variable time step is syncronized every 3600
seconds (1 hour).
$para
coumax = 0.9 itsplt = 2 idtsyn = 3600
$end

Figure 4.4: Example of variable time step settings. The time step is syncronized at every
hour, and the Courant number is lowered to 0.9.

4.3.2 3D computations
The basic way to run the model is in 2D, computing for each element of the grid one value
for the whole water column. All the variables are computed in the center of the layer,
halfway down the total depth. Deeper basins or highly variable bathymetry can require
for the correct reproduction of the velocities, temperature and salinity the need for 3D
computation.
The 3D computation is performed on the basis of z layers. In this representation each layer
horizontally has constant depth over the whole basin, but vertically the layer thickness
may vary between different layers. However, the first layer (surface layer) is of varying
thickness because of the water level variation, and the last layer of an element might be
only partially present due to the bathymetry.
Layers are counted from the the surface layer (layer 1) down to the maximum layer, de-
pending again on the local depth. Therefore, elements (and nodes) normally have a different
total number of layers from one to each other. This is opposed to sigma layers where the
number of total layers is constant all over the basin, but the thickness of each layer varies
between different elements.
In order to use layers for 3D computations a new section $layers has to be introduced
into the STR file, where the sequence of depth values of the bottom of the layers has to
be declared. Please, make sure that in the file Rules.make, the number of allowed levels
nlvdim is greater or equal than the ones actually used in the STR file. Layer depths must be
declared in increasing order. An example of a $layer section is given in figure 4.5. Please
note that the maximum depth of the basin in the example must not exceed 20 m.
A specific treatment for the bottom layer has to be carried out. In fact, if the model runs on
basins with variable bathymetry, for each element there will be a different total number of

19
$layers
2 4 6 8 10 13 16 20
$end

Figure 4.5: Example of section $layers. The maximum depth of the basin is 20 meters.
The first 5 layers have constant thickness of 2 m, while the last three vary between 3 and 4
m.

layers. The bathymetric value normally does not coincide with one of the layer depths, and
therefore the last layer must be treated seperately.
To declare how to treat the last layer two parameters have to be inserted in the $para
section. The first is hlvmin, the minimum depth, expressed as a percentage with respect to
the full layer depth, ranging between 0 and 1, This is the fraction that the last layer must
have in order to be maintained as a seperate layer. The second parameter is ilytyp and
it defines the kind of adjustment done on the last layer. If it is set to 0 no adjustment is
done, if it is set to 1 the depth of the last layer is adjusted to the one declared in the STR
file (full layer change). If it is 2 the adjustment to the previous layer is done only if the
fraction of the last layer is smaller than hlvmin (change of depth). If it is 3 (default) the
bathymetric depth is kept and added to the last but one layer. Therefore with a value of 0 or
3 the total depth will never be changed, whereas with the other levels the total depth might
be adjusted.
As an example, take the layer definition of Fig. 4.5. Let hlvmin be set to 0.5, and let an
element have a depth of 6.5 m. The total number of layers is 4, where the first 3 have each a
thickness of 2 m and the last layer of this element (layer 4) is 0.5 m. However, the nominal
thickness of layer 4 is 2 m and therefore its relative thickness is 0.25 which is smaller than
hlvmin. With ilytyp=0 no adjustment will be done and the total number of layers in this
element will be 4 and the last layer will have a thickness of 0.5 m. With ilytyp=1 the
total number of layers will be changed to 3 (all of them with 2 m thickness) and the total
depth will be adjusted to 6 m. The same will happen with ilytyp=2, because the relative
thickness in layer 4 is smaller than hlvmin. Finally, with ilytyp=3 the total number of
layers will be changed to 3 but the remaining depth of 0.5 m will be added to layer 3 that
will become 2.5 m.
In the case the element has a depth of 7.5 m, the relative thickness is now 0.75 and greater
than hlvmin. In this case, with ilytyp=0, 2 and 3 no adjustment will be done and the total
number of layers in this element will be 4 and the last layer will have a thickness of 1.5
m. With ilytyp=1 the total number of layers will be kept as 4 but the total depth will be
adjusted to 8 m. This will make all layers equal to 2 m thickness.
The introduction of layers requires also to define the values of vertical eddy viscosity and
eddy diffusivity. In any case a value of these two parameters has to be set if the 3D run is
performed. This could be done by setting a constant value of the parameters vistur (ver-
tical viscosity) and diftur (vertical diffusivity). In this case possible values are between
1·10−2 and 1·10−5 , depending on the stability of the water column. Higher values (1·10−2 )
indicate higher stability and a stronger barotropic behavior.
The other possibility is to compute the vertical eddy coeficients through a turbulence clo-
sure scheme. This usage will be described in the scetion on turbulence.

4.3.3 Baroclinic terms

The baroclinic pressure gradient term permits to compute the variation of velocity due to
the horizontal gradients of temperature and/or salinity. These gradients act on the horizontal
variation of density.
If the variations of temperature and salinity and the baroclinic pressure gradient term has
to be computed, the parameter ibarcl (in section $para) must be set different from 0.

20
Setting ibarcl to a value different from 0 will simulate the transport and diffusion of
temperature and salinity in the basin. A value of 1 will compute the full baroclinic pressure
terms. A value of 2 will do diagnostic simulations. This means that baroclinic pressure
terms are still included in the hydrodynamic equations, but temperature and salinity will not
be computed but will be read from a file. Finally for ibarcl=3 temperature and salinity will
be computed but no baroclinic pressure term will be used. In this case the hydrodynamic
equations and the equations for temperature and salinity are decoupled and there is no feed
back from the density field to the currents.
In any case, if temperature and salinity are computed, first they must be initialized either
with constant values or with variable 3D matrices. In the first case the reference values
have to be imposed in temref and salref. An example of this type of simulation is given
in Fig. 4.6.
If the temperature and salinity are given as 3D matrices files, they must be provided in
the $name section, giving the file names in tempin and saltin. In case of diagnostic
simulations the matrices of temperature and salinity have to be provided in the files named
tempd and saltd and data must be available for the whole period of simulation.

$para
ibarcl = 1 temref = 18. salref = 35.
$end

Figure 4.6: Example of baroclinic simulation. The initial values for temperature and salin-
ity are set to 18 C and 35.

4.3.4 Turbulence
In the Reynolds equations turbulent eddy diffusivities and viscosities are introduced into
the equations that must be parameterized and given some value. Moreover SHYFEM as-
sumes the hydrostatic approximation. Therefore, there is the need to parameterize the
non-hydrostatic effects. These are considered sub-scale processes which are mainly of
convective nature.
Vertical eddy viscosities and diffusivities have to be defined if there is the intent to model
the turbulence effects. These vertical eddy viscosities and diffusivities can be set to constant
values, defining vistur and diftur in the $para section. There is also the opportunity to
compute, at each timestep, variable values of them, using the turbulence closure module.
The parameter that has to be set in order too choose the turbulence scheme is iturb in the
$para section.. If iturb=0 the vertical eddy viscosity and eddy diffusivity are set constant
(default 0) and must be defined in vistur and diftur.
If iturb=1 the turbulence closure scheme applied is the k − ε model. If iturb=2 the
GOTM turbulence closure module is used. In this case the file gotmturb.nml must be
provided that sets all necessary parameters. This file must be declared in the section $name
for the item gotmpa.
A default gotmturb.nml file is provided and it allows the computation of the vertical eddy
viscosity and eddy diffusivity by means of the GOTM k − ε model. More information on
the GOTM turbulence closure module can be found in the GOTM Manual 1 .
If the turbulence module should be used, a value of iturb=2 is recommended. An example
of the settings for the turbulence closure scheme is given in Fig. 4.7.

1 http://www.gotm.net/index.php?go=documentation

21
$para
iturb = 2
$end
$name
gotmpa = ’gotmturb.nml’
$end

Figure 4.7: Example of turbulence settings. The GOTM module for the turbulence closure
is used. The parameters are contained in file gotmturb.nml.

22
Appendix A

Hydrodynamic equations and

resolution techniques

A.1 Equations and Boundary Conditions

The equations used in the model are the well known vertically integrated shallow water
equations in their formulation with water levels and transports.

∂U ∂ζ
+ gH + RU + X = 0 (A.1)
∂t ∂x
∂V ∂ζ
+ gH + RV +Y = 0 (A.2)
∂t ∂y
∂ζ ∂U ∂V
+ + =0 (A.3)
∂t ∂x ∂y
where ζ is the water level, u, v the velocities in x and y direction, U,V the vertical integrated
velocities (total or barotropic transports)
Z ζ Z ζ
U= u dz V= v dz
−h −h

g the gravitational acceleration, H = h + ζ the total water depth, h the undisturbed water
depth, t the time and R the friction coefficient. The terms X,Y contain all other terms that
may be added to the equations like the wind stress or the nonlinear terms and that need not
be treated implicitly in the time discretization. following treatment.
The friction coefficient has been expressed as
√
g u2 + v2
R= (A.4)
C2 H
with C the Chezy coefficient. The Chezy term is itself not retained constant but varies with
the water depth as
C = ks H 1/6 (A.5)
where ks is the Strickler coefficient.
In this version of the model the Coriolis term, the turbulent friction term and the nonlinear
advective terms have not been implemented.
At open boundaries the water levels are prescribed. At closed boundaries the normal ve-
locity component is set to zero whereas the tangential velocity is a free parameter. This
corresponds to a full slip condition.

23
A.2 The Model
The model uses the semi-implicit time discretization to accomplish the time integration.
In the space the finite element method has been used, not in its standard formulation, but
using staggered finite elements. In the following a description of the method is given.

A.2.1 Discretization in Time - The Semi-Implicit Method

Looking for an efficient time integration method a semi-implicit scheme has been chosen.
The semi-implicit scheme combines the advantages of the explicit and the implicit scheme.
It is unconditionally stable for any time step ∆t chosen and allows the two momentum
equations to be solved explicitly without solving a linear system.
The only equation that has to be solved implicitly is the continuity equation. Compared
to a fully implicit solution of the shallow water equations the dimensions of the matrix are
reduced to one third. Since the solution of a linear system is roughly proportional to the
cube of the dimension of the system the saving in computing time is approximately a factor
of 30.
It has to be pointed out that it is important not to be limited with the time step by the CFL
criterion for the speed of the external gravity waves
∆x
∆t < √
gH

where ∆x is the minimum distance between the nodes in an element. With the discretization
described below in most parts of the lagoon we have ∆x ≈ 500m and H ≈ 1m, so ∆t ≈ 200
sec. But the limitation of the time step is determined by the worst case. For example, for
∆x = 100 m and H = 40 m the time step criterion would be ∆t < 5 sec, a prohibitive small
value.
The equations (1)-(3) are discretized as follows

ζn+1 − ζn 1 ∂(U n+1 +U n ) 1 ∂(V n+1 +V n )

+2 +2 =0 (A.6)
∆t ∂x ∂y

U n+1 −U n ∂(ζn+1 + ζn )
+ gH 12 + RU n+1 + X = 0 (A.7)
∆t ∂x
V n+1 −V n ∂(ζn+1 + ζn )
+ gH 12 + RV n+1 +Y = 0 (A.8)
∆t ∂y
With this time discretization the friction term has been formulated fully implicit, X,Y fully
explicit and all the other terms have been centered in time. The reason for the implicit
treatment of the friction term is to avoid a sign inversion in the term when the friction
parameter gets too high. An example of this behavior is given in Backhaus [1].
If the two momentum equations are solved for the unknowns U n+1 and V n+1 we have
n+1 + ζn )
 
n+1 1 n 1 ∂(ζ
U = U − ∆tgH 2 − ∆tX (A.9)
1 + ∆tR ∂x
n+1 + ζn )
 
n+1 1 n 1 ∂(ζ
V = V − ∆tgH 2 − ∆tY (A.10)
1 + ∆tR ∂y
If ζn+1 were known, the solution for U n+1 and V n+1 could directly be given. To find ζn+1
we insert (A.9) and (A.10) in (A.6). After some transformations (A.6) reads
 
n+1 2 g ∂ ∂ζn+1 ∂ ∂ζn+1
ζ − (∆t/2) (H ) + (H )
1 + ∆tR ∂x ∂x ∂y ∂y

24
  
g ∂ ∂ζn ∂ ∂ζn
= ζn + (∆t/2)2 (H ) + (H ) (A.11)
1 + ∆tR ∂x ∂x ∂y ∂y
  n n

2 + ∆tR ∂U ∂V
− (∆t/2) +
1 + ∆tR ∂x ∂y
2  
∆t ∂X ∂Y
+ +
2(1 + ∆tR) ∂x ∂y

The terms on the left hand side contain the unknown ζn+1 , the right hand contains only
known values of the old time level. If the spatial derivatives are now expressed by the finite
element method a linear system with the unknown ζn+1 is obtained and can be solved by
standard methods. Once the solution for ζn+1 is obtained it can be substituted into (A.9)
and (A.10) and these two equations can be solved explicitly. In this way all unknowns of
the new time step have been found.
Note that the variable H also contains the water level through H = h + ζ. In order to avoid
the equations to become nonlinear ζ is evaluated at the old time level so H = h + ζn and H
is a known quantity.

A.2.2 Discretization in Space - The Finite Element Method

While the time discretization has been explained above, the discretization in space has still
to be carried out. This is done using staggered finite elements. With the semi-implicit
method described above it is shown below that using linear triangular elements for all
unknowns will not be mass conserving. Furthermore the resulting model will have propa-
gation properties that introduce high numeric damping in the solution of the equations.
For these reasons a quite new approach has been adopted here. The water levels and the
velocities (transports) are described by using form functions of different order, being the
standard linear form functions for the water levels but stepwise constant form functions
for the transports. This will result in a grid that resembles more a staggered grid in finite
difference discretizations.

Formalism
Let u be an approximate solution of a linear differential equation L. We expand u with the
help of basis functions φm as

u = φm um m = 1, K (A.12)

where um is the coefficient of the function φm and K is the order of the approximation. In
case of linear finite elements it will just be the number of nodes of the grid used to discretize
the domain.
To find the values um we try to minimize the residual that arises when u is introduced into L
multiplying the equation L by some weighting functions Ψn and integrating over the whole
domain leading to
Z Z Z
ψn L(u) dΩ = ψn L(φm um ) dΩ = um ψn L(φm ) dΩ (A.13)
Ω Ω Ω

If the integral is identified with the elements of a matrix anm we can write (A.13) also as a
linear system
anm um = 0 n = 1, K m = 1, K (A.14)
Once the basis and weighting functions have been specified the system may be set up and
(A.14) may be solved for the unknowns um .

25
 f f
a a
H L aa H L aa

AC HH  L aa
C HH  L aa

 CA Hf L
C Hft L
f

  C@
PP  E QQ L f
PP C j 

Q L
PCt PCf
tP QLt
Q
φi

PE @
 i C E P@ Pf @
QL
 
C P Pf i
t  
@
 CE
J  @ C
J  @
f
 CE
J
S  @ f C
J  @
f t S f
t Jt 
XX X 
A XXCE

J  A XXXC

A
A

S S  A
A
S 
A
A

S S  A
A
S 
A
XXXA
n S  XXXA

A
S 
A
t
X St A

X S
ψn

Figure A.1: a) form functions in domain b) domain of influence of node i

Staggered Finite Elements

For decades finite elements have been used in fluid mechanics in a standardized manner.
The form functions φm were chosen as continuous piecewise linear functions allowing a
subdivision of the whole area of interest into small triangular elements specifying the coef-
ficients um at the vertices (called nodes) of the triangles. The functions φm are 1 at node m
and 0 at all other nodes and thus different from 0 only in the triangles containing the node
m. An example is given in the upper left part of Fig. 1a where the form function for node i
is shown. The full circle indicates the node where the function φi take the value 1 and the
hollow circles where they are 0.
The contributions anm to the system matrix are therefore different from 0 only in elements
containing node m and the evaluation of the matrix elements can be performed on an ele-
ment basis where all coefficients and unknowns are linear functions of x and y.
This approach is straightforward but not very satisfying with the semi-implicit time step-
ping scheme for reasons explained below. Therefore an other way has been followed in
the present formulation. The fluid domain is still divided in triangles and the water levels
are still defined at the nodes of the grid and represented by piecewise linear interpolating
functions in the internal of each element, i.e.
ζ = ζm φm m = 1, K
However, the transports are now expanded, over each triangle, with piecewise constant (non
continuous) form functions ψn over the whole domain. We therefore write
U = Un ψn n = 1, J
where n is now running over all triangles and J is the total number of triangles. An example
of ψn is given in the lower right part of Fig. 1a. Note that the form function is constant 1
over the whole element, but outside the element identically 0. Thus it is discontinuous at
the element borders.
Since we may identify the center of gravity of the triangle with the point where the trans-
ports Un are defined (contrary to the water levels ζm which are defined on the vertices of
the triangles), the resulting grid may be seen as a staggered grid where the unknowns are
defined on different locations. This kind of grid is usually used with the finite difference
method. With the form functions used here the grid of the finite element model resembles
very much an Arakawa B-grid that defines the water levels on the center and the velocities
on the four vertices of a square.
Staggered finite elements have been first introduced into fluid mechanics by Schoenstadt
[8]. He showed that the un-staggered finite element formulation of the shallow water equa-
tions has very poor geostrophic adjustment properties. Williams [12, 13] proposed a similar

26
algorithm, the one actually used in this paper, introducing constant form functions for the
velocities. He showed the excellent propagation and geostrophic adjustment properties of
this scheme.

The Practical Realization

The integration of the partial differential equation is now performed by using the subdivi-
sion of the domain in elements (triangles). The water levels ζ are expanded in piecewise
linear functions φm , m = 1, K and the transports are expanded in piecewise constant func-
tions ψn , n = 1, J where K and J are the total number of nodes and elements respectively.
As weighting functions we use ψn for the momentum equations and φm for the continuity
equation. In this way there will be K equations for the unknowns ζ (one for each node) and
J equations for the transports (one for each element).
In all cases the consistent mass matrix has been substituted with the their lumped equiva-
lent. This was mainly done to avoid solving a linear system in the case of the momentum
equations. But it was of use also in the solution of the continuity equation because the
amount of mass relative to one node does not depend on the surrounding nodes. This was
important especially for the flood and dry mechanism in order to conserve mass.

Finite Element Equations

If equations (A.9,A.10,A.11) are multiplied with their weighting functions and integrated
over an element we can write down the finite element equations. But the solution of the
water levels does actually not use the continuity equation in the form (A.11), but a slightly
different formulation. Starting from equation (A.6), multiplied by the weighting function
ΦM and integrated over one element yields
∂(U n+1 +U n ) ∂(V n+1 +V n )
Z Z  
ΦN (ζ n+1 n ∆t
− ζ ) dΩ + ( 2 ) ΦN + ΦN dΩ = 0
Ω Ω ∂x ∂y
If we integrate by parts the last two integrals we obtain
Z Z  
∂ΦN n+1 ∂ΦN n+1
ΦN (ζn+1 − ζn ) dΩ − ( ∆t2 ) (U +U n ) + (V +V n ) dΩ = 0
Ω Ω ∂x ∂y
plus two line integrals, not shown, over the boundary of each element that specify the
normal flux over the three element sides. In the interior of the domain, once all contribu-
tions of all elements have been summed, these terms cancel at every node, leaving only
the contribution of the line integral on the boundary of the domain. There, however, the
boundary condition to impose is exactly no normal flux over material boundaries. Thus,
the contribution of these line integrals is zero.
If now the expressions for U n+1 ,V n+1 are introduced, we obtain a system with again only
the water levels as unknowns
∂ΦN ∂ζn+1 ∂ΦN ∂ζn+1
Z Z
2
ΦN ζn+1 dΩ + (∆t/2) αg H( + ) dΩ
Ω Ω ∂x ∂x ∂y ∂y
∂ΦN ∂ζn ∂ΦN ∂ζn
Z Z
= ΦN ζn dΩ + (∆t/2)2 αg H( + ) dΩ
Ω Ω ∂x ∂x ∂y ∂y
Z
∂ΦN n ∂ΦN n
+ (∆t/2)(1 + α) ( U + V ) dΩ (A.15)
Ω ∂x ∂y
Z
∂ΦN ∂ΦN
− (∆t 2 /2)α ( X+ Y ) dΩ
Ω ∂x ∂y
Here we have introduced the symbol α as a shortcut for
1
α=
1 + ∆tR

27
The variables and unknowns may now be expanded with their basis functions and the com-
plete system may be set up.

A.2.3 Mass Conservation

It should be pointed out that only through the use of this staggered grid the semi-implicit
time discretization may be implemented in a feasible manner. If the Galerkin method is
applied in a naive way to the resulting equation (A.11) (introducing the linear form func-
tions for transports and water levels and setting up the system matrix), the model is not
mass conserving. This may be seen in the following way (see Fig. 1b for reference). In the
computation of the water level at node i, only ζ and transport values belonging to triangles
that contain node i enter the computation (full circles in Fig. 1b). But when, in a second
step, the barotropic transports of node j are computed, water levels of nodes that lie further
apart from the original node i are used (hollow circles in Fig. 1b). These water levels have
not been included in the computation of ζi , the water level at node i. So the computed trans-
ports are actually different from the transports inserted formally in the continuity equation.
The continuity equation is therefore not satisfied.
These contributions of nodes lying further apart could in principle be accounted for. In this
case not only the triangles Ωi around node i but also all the triangles that have nodes in
common with the triangles Ωi would give contributions to node i, namely all nodes and
elements shown in Fig. 1b. The result would be an increase of the bandwidth of the matrix
for the ζ computation disadvantageous in terms of memory and time requirements.
Using instead the approach of the staggered finite elements, actually only the water levels
of elements around node i are needed for the computation of the transports in the triangles
Ωi . In this case the model satisfies the continuity equation and is perfectly mass conserving.

A.2.4 Inter-tidal Flats

Part of a basin may consist of areas that are flooded during high tides and emerge as islands
at ebb tide. These inter-tidal flats are quite difficult to handle numerically because the
elements that represent these areas are neither islands nor water elements. The boundary
line defining their contours is wandering during the evolution of time and a mathematical
model must reproduce this features.
For reasons of computer time savings a simplified algorithm has been chosen to represent
the inter-tidal flats. When the water level in at least one of the three nodes of an element
falls below a minimum value (5 cm) the element is considered an island and is taken out
of the system. It will be reintroduced only when in all three nodes the water level is again
higher then the minimum value. Because in dry nodes no water level is computed anymore,
an estimate of the water level has to be given with some sort of extrapolation mechanism
using the water nodes nearby.
This algorithm has the advantage that it is very easy to implement and very fast. The
dynamical features close to the inter-tidal flats are of course not well reproduced but the
behavior of the method for the rest of the lagoon gave satisfactory results.
In any case, since the method stores the water levels of the last time step, before the ele-
ment is switched off, introducing the element in a later moment with the same water levels
conserves the mass balance. This method showed a much better performance than the one
where the new elements were introduced with the water levels taken from the extrapolation
of the surrounding nodes.

28
Appendix B

File formats

B.1 GRD file

format of input file for grid utility

=============================================================

legend :

n item number (node, element, line)

t type
d depth
x,y coordinates
ntot number of following nodes
n1,n2 node numbers

=============================================================

format of lines in input file :

comment:

0 [anything]

node:

1 n t x y [d]

element:

2 n t ntot n1 n2 n3 ... [d]

line:

3 n t ntot n1 n2 ... [d]

=============================================================

comment :

29
lines may be split at any point, except befor optional argument
d must not be on seperate line
if line is split, the continuation line(s) must start with a blank
blank lines can be inserted as needed
if d is not specified -999. will be used (flag)
use t=0 if you do not know what to use
n must be unique for every item type
item numbers need not be consecutive
the sequence of items is not important, nodes can be mixed with elements/lines
the minimum number of nodes for element items is 3
the minimum number of nodes for line items is 2
element items should have all nodes unique
line items with the same first and last node are considered closed

=============================================================

example 1 :

0 example of one line

1 11 0 10. 10.
1 12 0 20. 20.

3 7 0 2 11 12

#----------------

example 2 :

0 example of one element with continuation line

1 11 0 10. 10.
1 12 0 20. 20.
1 15 0 10. 20.

2 7 0 3
11 12 15

=============================================================

30
Appendix C

Parameter list

C.1 Parameter list for the SHYFEM model

C.1.1 Section $title
This section must be always the first section in the parameter input file. It contains only
three lines. An example is given in figure C.1.

$title
free one line description of simulation
name_of_simulation
name_of_basin
$end

Figure C.1: Example of section $title

The first line of this section is a free one line description of the simulation that is to be
carried out. The next line contains the name of the simulation. All created files will use
this name in the main part of the file name with different extensions. Therefore the hydro-
dynamic output file (extension out) will be named name_of_simulation.out. The last
line gives the name of the basin file to be used. This is the pre-processed file of the basin
with extension bas. In our example the basin file name_of_basin.bas is used.
The directory where this files are read from or written to depends on the settings in section
$name. Using the default the program will read from and write to the current directory.

C.1.2 Section $para

This section defines the general behavior of the simulation, gives various constants of pa-
rameters and determines what output files are written. In the following the meaning of all
possible parameters is given.
Note that the only compulsory parameters in this section are the ones that chose the duration
of the simulation and the integration time step. All other parameters are optional.

Compulsory time parameters This parameters are compulsory parameters that define
the period of the simulation. They must be present in all cases.
itanf Start of simulation. (Default 0)

itend End of simulation.

31
idt Time step of integration.

Output parameters The following parameters deal with the output frequency and start
time to external files. The content of the various output files should be looked up in the
appropriate section.
The default for the time step of output of the files is 0 which means that no output file is
written. If the time step of the output files is equal to the time step of the simulation then at
every time step the output file is written. The default start time of the output is 0.
idtout Time step and start time for writing to file OUT, the file containing the
itmout general hydrodynamic results.

idtext Time step and start time for writing to file EXT, the file containing hy-
itmext drodynamic data of extra points. The extra points for which the data is
written to this file are given in section extra of the parameter file.

idtrst Time step and start time for writing the restart file (extension RST). No
itmrst restart file is written with idtrst equal to 0. A negative value is also
possible for the time step. In this case the used time step is -idtrst,
but the file is overwritten every time. It therefore contains always only
the last written restart record. (Default 0)

itrst Time to use for the restart. If a restart is performed, then the file name
containing the restart data has to be specified in restrt and the time
record corresponding to itrst is used in this file. A value of -1 is
also possible. In this case the last record in the restart file is used for
the restart and the simulation starts from this time. Be aware that this
option changes the parameter itanf to the time of the last record found
in restrt.
ityrst Type of restart. If 0 and the restart file is not found the program will
exit with an error. Otherwise the program will simply continue with a
cold start. If ityrst is 1 and the given time record is not found in the
file it will exit with error. If it is 2 it will initialize all values from the
first time record after itrst. Therefore, the value of 2 will guarantee
that the program will not abort and continue running, but it might be not
doing what you want. (Default 0)

idtres Time step and start time for writing to file RES, the file containing resid-
itmres ual hydrodynamic data.

idtrms Time step and start time for writing to file RMS, the file containing
itmrms hydrodynamic data of root mean square velocities.

idtflx Time step and start time for writing to file FLX, the file containing dis-
itmflx charge data through defined sections. The transects for which the dis-
charges are computed are given in section flux of the parameter file.

idtvol Time step and start time for writing to file VOL, the file containing
itmvol volume information of areas defined by transects. The transects that
are used to compute the volumes are given in section volume of the
parameter file.

netcdf This parameter chooses output in NetCDF format if netcdf is 1, else

the format is unformatted fortran files. (Default 0)

32
General time and date parameters A time and date can be assigned to the simulation.
These values refer to the time 0 of the FEM model. The format for the date is YYYYM-
MDD and for the time HHMMSS. You can also give a time zone if your time is not referring
to GMT but to another time zone such as MET.
date The real date corresponding to time 0. (Default 0) time The real time corresponding
to time 0. (Default 0) tz The time zone you are in. This is 0 for GMT, 1 for MET and 2 for
MEST (MET summer time). (Default 0)

Model parameters The next parameters define the inclusion or exclusion of certain terms
of the primitive equations.
ilin Linearization of the momentum equations. If ilin is different from 0
the advective terms are not included in the computation. (Default 1)

itlin This parameter decides how the advective (non-linear) terms are com-
puted. The value of 0 (default) uses the usual finite element discretiza-
tion over a single element. The value of 1 choses a semi-lagrangian
approach that is theoretically stable also for Courant numbers higher
than 1. It is however recommended that the time step is limited using
itsplt and coumax described below. (Default 0)

iclin Linearization of the continuity equation. If iclin is different from 0 the

depth term in the continuity equation is taken to be constant. (Default
0)
The next parameters allow for a variable time step in the hydrodynamic computations. This
is especially important for the non-linear model (ilin=0) because in this case the criterion
for stability cannot be determined a priori and in any case the time integration will not be
unconditionally stable.
The variable time steps allows for longer basic time steps (here called macro time steps)
which have to be set in idt. It then computes the optimal time step (here micro time step)
in order to not exceed the given Courant number. However, the value for the macro time
step will never be exceeded.
itsplt Type of variable time step computation. If this value is 0, the time
step will kept constant at its initial value. A value of 1 devides the
initial time step into (possibly) equal parts, but makes sure that at the
end of the micro time steps one complete macro time step has been
executed. The last mode itsplt = 2 does not care about the macro
time step, but always uses the biggest time step possible. In this case it
is not assured that after some micro time steps a macro time step will
be recovered. Please note that the initial macro time step will never be
exceeded. (Default 0)

coumax Normally the time step is computed in order to not exceed the Courant
number of 1. However, in some cases the non-linear terms are sta-
ble even for a value higher than 1 or there is a need to achieve a
lower Courant number. Setting coumax to the desired Courant number
achieves exactly this effect. (Default 1)

idtsyn In case of itsplt = 2 this parameter makes sure that after a time of
idtsyn the time step will be syncronized to this time. Therefore, setting
idtsyn = 3600 means that there will be a time stamp every hour, even
if the model has to take one very small time step in order to reach that
time. This parameter is useful only for itsplt = 2 and its default value
of 0 does not make any syncronization.

33
idtmin This variable defines the smallest time step possible when time step
splitting is enabled. Normally the smallest time step is 1 second. But
when dealing with a lot of wet and drying in areas then sometimes it
is useful to take out elements that limit the time step too much. In the
case that idtmin is set to a value greater than 1 the program will switch
off temporarily elements that are responsible for such a small time step.
(Default 0)
These parameters define the weighting of time level in the semi-implicit algorithm. With
these parameters the damping of gravity or Rossby waves can be controlled. Only modify
them if you know what you are doing.
azpar Weighting of the new time level of the transport terms in the continuity
equation. (Default 0.5)

ampar Weighting of the new time level of the pressure term in the momentum
equations. (Default 0.5)

afpar Weighting of the new time level of the Coriolis term in the momentum
equations. (Default 0.5)

avpar Weighting of the new time level of the non-linear advective terms in the
momentum equations. (Default 0.0)
The next parameters define the weighting of time level for the vertical stress and advection
terms. They guarantee the stability of the vertical system. For this reason they are normally
set to 1 which corresponds to a fully implicit discretization. Only modify them if you know
what you are doing.
atpar Weighting of the new time level of the vertical viscosity in the momen-
tum equation. (Default 1.0)

adpar Weighting of the new time level of the vertical diffusion in the scalar
equations. (Default 1.0)

aapar Weighting of the new time level of the vertical advection in the scalar
equations. (Default 1.0)

Coriolis parameters The next parameters define the parameters to be used with the Cori-
olis terms.
icor If this parameter is 0, the Coriolis terms are not included in the com-
putation. A value of 1 uses a beta-plane approximation with a variable
Coriolis parameter f , whereas a value of 2 uses an f-plane approxi-
mation where the Coriolis parameter f is kept constant over the whole
domain. (Default 0)

dlat Average latitude of the basin. This is used to compute the Coriolis pa-
rameter f . If not given the latitude in the basin file is used. If given
the value of dlat in the input parameter file effectively substitues the
value given in the basin file. This parameter is not used if spherical
coordinates are used (isphe=1). (Default 0)

34
isphe If 0 a cartesian coordinate system is used, if 1 the coordinates are in the
spherical system (lat/lon). Please note that in case of spherical coordi-
nates the Coriolis term is always included in the computation, even with
icor = 0. If you really do not want to use the Coriolis term, then please
set icor = -1. The default is -1, which means that the type of coordinate
system will be determined automatically.

Depth parameters The next parameters deal with handling depth values of the basin.
href Reference depth. If the depth values of the basin and the water levels
are referred to mean sea level, href should be 0 (default value). Else
this value is subtracted from the given depth values. For example, if
href = 0.20 then a depth value in the basin of 1 meter will be reduced
to 80 centimeters.
hzmin Minimum total water depth that will remain in a node if the element
becomes dry. (Default 0.01 m)

hzoff Total water depth at which an element will be taken out of the compu-
tation because it becomes dry. (Default 0.05 m)

hzon Total water depth at which a dry element will be re-inserted into the
computation. (Default 0.10 m)

hmin Minimum water depth (most shallow) for the whole basin. All depth
values of the basin will be adjusted so that no water depth is shallower
than hmin. (Default is no adjustment)

hmax Maximum water depth (deepest) for the whole basin. All depth values
of the basin will be adjusted so that no water depth is deeper than hmax.
(Default is no adjustment)

Bottom friction The friction term in the momentum equations can be written as Ru and
Rv where R is the variable friction coefficient and u, v are the velocities in x, y direction
respectively. The form of R can be specified in various ways. The value of ireib is
choosing between the formulations. In the parameter input file a value λ is specified that is
used in the formulas below.
ireib Type of friction used (default 0):
0 No friction used
1 R = λ is constant

2 λ is the Strickler coefficient. In this formulation R is written as

R = Cg2 |u|
H with C = ks H
1/6 and λ = k is the Strickler coefficient.
s
In the above formula g is the gravitational acceleration, |u| the
modulus of the current velocity and H the total water depth.
3 λ is the Chezy coefficient. In this formulation R is written as R =
g |u|
C2 H
and λ = C is the Chezy coefficient.
4 R = λ/H with H the total water depth

5 R = λ |u|
H

35
czdef The default value for the friction parameter λ. Depending on the value
of ireib the coefficient λ is describing linear friction, constant drag
coefficient or a Chezy or Strickler form of friction (default 0).

iczv Normally R is evaluated at every time step (iczv = 1). If for some
reason this behavior is not desirable, iczv = 0 evaluates the value of
R only before the first time step, keeping it constant for the rest of the
simulation. (default 1)
The value of λ may be specified for the whole basin through the value of czdef. For more
control over the friction parameter it can be also specified in section area where the friction
parameter depending on the type of the element may be varied. Please see the paragraph
on section area for more information.

Physical parameters The next parameters describe physical values that can be adjusted
if needed.
rowass Average density of sea water. (Default 1025 kg m−3 )

roluft Average density of air. (Default 1.225 kg m−3 )

grav Gravitational acceleration. (Default 9.81 m s−2 )

Wind parameters The next two parameters deal with the wind stress to be prescribed at
the surface of the basin.
The wind data can either be specified in an external file (ASCII or binary) or directly in the
parameter file in section wind. The ASCII file or the wind section contain three columns,
the first giving the time in seconds, and the others the components of the wind speed. Please
see below how the last two columns are interpreted depending on the value of iwtype. For
the format of the binary file please see the relative section. If both a wind file and section
wind are given, data from the file is used.
The wind stress is normally computed with the following formula

τx = ρa cD |u|ux τy = ρa cD |u|uy (C.1)

where ρa , ρ0 is the density of air and water respectively, u the modulus of wind speed and
ux , uy the components of wind speed in x, y direction. In this formulation cD is a dimen-
sionless drag coefficient that varies between 1.5 ·10−3 and 3.2 ·10−3 . The wind speed is
normally the wind speed measured at a height of 10 m.
iwtype The type of wind data given (default 1):
0 No wind data is processed
1 The components of the wind is given in [m/s]
2 The stress (τx , τy ) is directly specified

3 The wind is given in speed [m/s] and direction [degrees]. A direction

of 0o specifies a wind from the north, 90o a wind from the east
etc.
4 As in 3 but the speed is given in knots

itdrag Formula to compute the drag coefficient. A value of 0 uses the constant
value given in dragco. With 1 the Smith and Banke formula is used.

36
dragco Drag coefficient used in the above formula. The default value is 0 so it
must be specified. Please note also that in case of iwtype = 2 this value
is of no interest, since the stress is specified directly.

wsmax Maximum wind speed allowed in [m/s]. This is in order to avoid errors
if the wind data is given in a different format from the one spwecified
by iwtype. (Default 50)

Parameters for 3d The next parameters deal with the layer structure in 3D.
dzreg Normally the bottom of the various layers are given in section $levels.
If only a regular vertical grid is desired then the parameter dzreg can be
used. It specifies the spacing of the vertical layers in meters. (Default is
0, which means that the layers are specified explicitly in $levels.
The last layer (bottom layer) is treated in a special way. Depending on the parameter
ilytyp there are various cases to be considered. A value of 0 leaves the last layer as it is,
even if the thickness is very small. A value of 1 will always eliminate the last layer, if it has
not full layer thickness. A value of 2 will do the same, but only if the last layer is smaller
than hlvmin (in units of fraction). Finally, a value of 3 will add the last layer to the layer
above, if its layer thickness is smaller than hlvmin.
ilytyp Treatment of last (bottom) layer. 0 means no adjustment, 1 deletes the
last layer, if it is not a full layer, 2 only deletes it if the layer thickness is
less than hlvmin, and 3 adds the layer thickness to the layer above if it
is smaller than hlvmin. Therefore, 1 and 2 might change the total depth
and layer structure, while 3 only might change the layer structure. The
value of 1 will always give you full layers at the bottom.

hlvmin Minimum layer thickness for last (bottom) layer used when ilytyp is
2 or 3. The unit is fractions of the nominal layer thickness. Therefore,
a value of 0.5 indicates that the last layer should be at least half of the
full layer.
The next parameters deal with vertical diffusivity and viscosity.
diftur Vertical turbulent diffusion parameter for the tracer. (Default 0)

difmol Vertical molecular diffusion parameter for the tracer. (Default 1.0e-06)

vistur Vertical turbulent viscosity parameter for the momentum. (Default 0)

vismol Vertical molecular viscosity parameter for the momentum. (Default

1.0e-06)

dhpar Horizontal diffusion parameter (general). (Default 0)

The next parameters deal with the control of the scalar transport and diffusion equation.
You have possibility to prescribe the tvd scheme desired and to limit the Courant number.
itvd Type of the horizontal advection scheme used for the transport and dif-
fusion equation. Normally an upwind scheme is used (0), but setting
the parameter itvd to a value greater than 0 choses a TVD scheme. A
value of 1 will use a TVD scheme based on the average gradient, and
a value of 2 will use the gradient of the upwind node (recommended).
This feature is still experimental, so use with care. (Default 0)

37
itvdv Type of the vertical advection scheme used for the transport and dif-
fusion equation. Normally an upwind scheme is used (0), but setting
the parameter itvd to 1 choses a TVD scheme. This feature is still
experimental, so use with care. (Default 0)

rstol Normally the internal time step for scalar advection is automatically
adjusted to produce a Courant number of 1 (marginal stability). You
can set rstol to a smaller value if you think there are stability problems.
(Default 1)

Temperature and salinity The next parameters deal with the transport and diffusion of
temperature and salinity. Please note that in order to compute T/S the parameter ibarcl
must be different from 0. In this case T/S advection is computed, but may be selectively
turned off setting one of the two parameters itemp or isalt explicitly to 0.
itemp Flag if the computation on the temperature is done. A value different
from 0 computes the transport and diffusion of the temperature. (De-
fault 1)

isalt Flag if the computation on the salinity is done. A value different from
0 computes the transport and diffusion of the salinity. (Default 1)
The next parameters set the initial conditions for temperature and salinity. Both the average
value and and a stratification can be specified.
temref Reference (initial) temperature of the water in centigrade. (Default 0)

salref Reference (initial) salinity of the water in psu (practical salinity units)
or ppt. (Default 0)

tstrat Initial temperature stratification in units of [C/km]. A positive value

indicates a stable stratification. (Default 0)

sstrat Initial salinity stratification in units of [psu/km]. A positive value indi-

cates a stable stratification. (Default 0)
The next parameters deal with horizontal diffusion of temperature and salinity. These pa-
rameters overwrite the general parameter for horizontal diffusion dhpar.
thpar Horizontal diffusion parameter for temperature. (Default 0)

shpar Horizontal diffusion parameter for salinity. (Default 0)

Concentrations The next parameters deal with the transport and diffusion of a conserva-
tive substance. The substance is dissolved in the water and acts like a tracer.
iconz Flag if the computation on the tracer is done. A value different from 0
computes the transport and diffusion of the substance. If greater than 1
iconz concentrations are simulated. (Default 0)

conref Reference (initial) concentration of the tracer in any unit. (Default 0)

contau If different from 0 simulates decay of concentration. In this case contau

is the decay rate (e-folding time) in days. (Default 0)

chpar Horizontal diffusion parameter for the tracer. This value overwrites the
general parameter for horizontal diffusion dhpar. (Default 0)

38
Output for scalars The next parameters define the output frequency of the computed
scalars (temperature, salinity, generic concentration) to file.
idtcon Time step and start time for writing to file CON (concentration) and
itmcon NOS (temperature and salinity).

C.1.3 Section $name

In this sections names of directories or input files can be given. All directories default to
the current directory, whereas all file names are empty, i.e., no input files are given.

Directory specification This parameters define directories for various input and output
files.
basdir Directory where basin file BAS resides. (Default .)

datdir Directory where output files are written. (Default .)

tmpdir Directory for temporary files. (Default .)

defdir Default directory for other files. (Default .)

File names The following strings enable the specification of files that account for initial
conditions or forcing.
zinit File with initial water level distribution.

wind File with wind data. The file may be either formatted or unformatted.
For the format of the unformatted file please see the section where the
WIN file is discussed. The format of formatted ASCII file is in standard
time-series format, with the first column containing the time in seconds
and the next two columns containing the wind data. The meaning of the
two values depend on the value of the parameter iwtype in the para
section.
rain File with rain data. This file is a standard time series with the time
in seconds and the rain values in mm/day. The values may include
also evaporation. Therefore, also negative values (for evaporation) are
permitted.

qflux File with heat flux data. This file must be in a special format to account
for the various parameters that are needed by the heat flux module to
run. Please refer to the information on the file qflux.

restrt Name of the file if a restart is to be performed. The file has to be pro-
duced by a previous run with the parameter idtrst different from 0.
The data record to be used in the file for the restart must be given by
time itrst.
gotmpa Name of file containing the parameters for the GOTM turbulence model
(iturb = 1).

saltin Name of file containing initial conditions for salinity

tempin Name of file containing initial conditions for temperature

39
conzin Name of file containing initial conditions for concentration

C.1.4 Section $bound

These parameters determine the open boundary nodes and the type of the boundary: level
or flux boundary. At the first the water levels are imposed, on the second the fluxes are
prescribed.
There may be multiple sections bound in one parameter input file, describing all open
boundary conditions necessary. Every section must therefore be supplied with a boundary
number. The numbering of the open boundaries must be increasing. The number of the
boundary must be specified directly after the keyword bound, such as bound1 or bound 1.
kbound Array containing the node numbers that are part of the open boundary.
The node numbers must form one contiguous line with the domain (ele-
ments) to the left. This corresponds to an anti-clockwise sense. At least
two nodes must be given.

ibtyp Type of open boundary.

0 No boundary values specified
1 Level boundary. At this open boundary the water level is imposed and
the prescribed values are interpreted as water levels in meters. If
no value for ibtyp is specified this is the default.
2 Flux boundary. Here the discharge in m3 s−1 has to be prescribed.
3 Internal flux boundary. As with ibtyp = 2 a discharge has to be
imposed, but the node where discharge is imposed can be an in-
ternal node and need not be on the outer boundary of the do-
main. For every node in kbound the volume rate specified will
be added to the existing water volume. This behavior is differ-
ent from the ibtyp = 2 where the whole boundary received the
discharge specified.
4 Momentum input. The node or nodes may be internal. This feature
can be used to describe local acceleration of the water column.
The unit is force / density [m4 s−2 ]. In other words it is the rate
of volume [m3 s−1 ] times the velocity [m/s] to which the water is
accelerated.

iqual If the boundary conditions for this open boundary are equal to the ones
of boundary i, then setting iqual = i copies all the values of boundary
i to the actual boundary. Note that the value of iqual must be smaller
than the number of the actual boundary, i.e., boundary i must have been
defined before.
The next parameters give a possibility to specify the file name of the various input files
that are to be read by the model. Values for the boundary condition can be given at any
time step. The model interpolates in between given time steps if needed. The grade of
interpolation can be given by intpol.
All files are in ASCII and share a common format. The file must contain two columns, the
first giving the time of simulation in seconds that refers to the value given in the second
column. The value in the second column must be in the unit of the variable that is given.
The time values must be in increasing order. There must be values for the whole simulation,
i.e., the time value of the first line must be smaller or equal than the start of the simulation,

40
and the time value of the last line must be greater or equal than the end of the simulation.
boundn File name that contains values for the boundary condition. The value
of the variable given in the second column must be in the unit deter-
mined by ibtyp, i.e., in meters for a level boundary, in m3 s−1 for a flux
boundary and in m4 s−2 for a momentum input.

zfact Factor with which the values from boundn are multiplied to form the
final value of the boundary condition. E.g., this value can be used to
set up a quick sensitivity run by multiplying all discharges by a factor
without generating a new file. (Default 1)

levmin A point discharge normally distributes its discharge over the whole wa-
levmax ter column. If it is important that in a 3D simulation the water mass dis-
charge is concentrated only in some levels, the parameters levmin and
levmax can be used. They indicate the lowest and deepest level over
which the discharge is distributed. Default values are 0, which indicate
that the discharge is distributed over the whole water column. Setting
only levmax distributes from the surface to this level, and setting only
levmin distributes from the bottom to this level.
conzn File name that contains values for the respective boundary condition,
tempn i.e., for concentration, temperature and salinity. The format is the same
saltn as for file boundn. The unit of the values given in the second column
must the ones of the variable, i.e., arbitrary unit for concentration, centi-
grade for temperature and psu (per mille) for salinity.
The next variables specify the name of the boundary value file for different modules. Please
refer to the documentation of the single modules for the units of the variables.
bio2dn File name that contains values for the ecological module (EUTRO-
WASP).

sed2dn File name that contains values for the sediment transport module

mud2dn File name that contains values for the fluid mud module

lam2dn File name that contains values for the fluid mud module (boundary con-
dition for the structural parameter, to be implemented)

dmf2dn File name that contains values for the fluid mud module (boundary con-
ditions for the advection of flocsizes, to be implemented)

tox3dn File name that contains values for the toxicological module.

intpol Order of interpolation for the boundary values read through files. Use
for 1 for stepwise (no) interpolation, 2 for linear and 4 for cubic in-
terpolation. The default is linear interpolation, except for water level
boundaries (ibtyp=1) where cubic interpolation is used.
The next parameters can be used to impose a sinusoidal water level (tide) or flux at the open
boundary. These values are used if no boundary file boundn has been given. The values
must be in the unit of the intended variable determined by ibtyp.
ampli Amplitude of the sinus function imposed. (Default 0)

period Period of the sinus function. (Default 43200, 12 hours)

41
phase Phase shift of the sinus function imposed. A positive value of one quar-
ter of the period reproduces a cosine function. (Default 0)

zref Reference level of the sinus function imposed. If only zref is specified
(ampli = 0) a constant value of zref is imposed on the open boundary.
With the next parameters a constant value can be imposed for the variables of concentration,
temperature and salinity. In this case no file with boundary values has to be supplied. The
default for all values is 0, i.e., if no file with boundary values is supplied and no constant is
set the value of 0 is imposed on the open boundary. A special value of -999 is also allwoed.
In this case the value imposed is the ambient value of the parameter close to the boundary.
conz Constant boundary values for concentration, temperature and salinity
temp respectively. If these values are set no boundary file has to be supplied.
salt (Default 0)
The next two values are used for constant momentum input. This feature can be used to
describe local acceleration of the water column. The values give the input of momentum
in x and y direction. The unit is force / density (m4 s−2 ). In other words it is the rate of
volume (m3 s−1 ) times the velocity (m/s) to which the water is accelerated.
These values are used if boundary condition ibtyp = 4 has been chosen and no boundary
input file has been given. If the momentum input is varying then it may be specified with
the file boundn. In this case the file boundn must contain three columns, the first for the
time, and the other two for the momentum input in x, y direction.
umom Constant values for momentum input. (Default 0)
vmom

C.1.5 Section $wind

In this section the wind data can be given directly without the creation of an external file.
Note, however, that a wind file specified in the name section takes precedence over this
section. E.g., if both a section wind and a wind file in name is given, the wind data from
the file is used.
The format of the wind data in this section is the same as the format in the ASCII wind file,
i.e., three columns, with the first specifying the time in seconds and the other two columns
giving the wind data. The interpretation of the wind data depends on the value of iwtype.
For more information please see the description of iwtype in section para.

C.1.6 Section $extra

In this section the node numbers of so called “extra” points are given. These are points
where water level and velocities are written to create a time series that can be elaborated
later. The output for these “extra” points consumes little memory and can be therefore
written with a much higher frequency (typically the same as the integration time step) than
the complete hydrodynamic output. The output is written to file EXT.
The node numbers are specified in a free format on one ore more lines. An example can be
seen in figure 4.1. No keywords are expected in this section.

C.1.7 Section $flux

In this section transects are specified through which the discharge of water is computed by
the program and written to file FLX. The transects are defined by their nodes through which
they run. All nodes in one transect must be adjacent, i.e., they must form a continuous line
in the FEM network.

42
The nodes of the transects are specified in free format. Between two transects one or more
0’s must be inserted. An example is given in figure C.2.

$flux
1001 1002 1004 0
35 37 46 0 0 56 57 58 0
407
301
435 0 89 87
$end

Figure C.2: Example of section $flux

The example shows the definition of 5 transects. As can be seen, the nodes of the transects
can be given on one line alone (first transect), two transects on one line (transect 2 and 3),
spread over more lines (transect 4) and a last transect.

C.2 Parameter list for the post processing routines

The format of the parameter input file is the same as the one for the main routine. Please
see this section for more information on the format of the parameter input file.
Some sections of the parameter input file are identical to the sections used in the main
routine. For easier reference we will repeat the possible parameters of these section here.

C.2.1 Section $title

This section must be always the first section in the parameter input file. It contains only
three lines. An example has been given already in figure C.1.
The only difference with respect to the $para section of the main routine is the first line.
Here any description of the output can be used. It is just a way to label the parameter file.
The other two line with the name of simulation and the basin are used to open the files
needed for plotting.

C.2.2 Section $para

These parameters set generic values for the plot.
Some of the parameters set coordinates in the plot. For example, the values x0, y0 and
x1, y1 indicate the actual plotting area, which can be bigger or smaller than the extension
of the numerical grid.
Normally, values have to be in meters (the same as the coordinates in the numerical grid).
However, also relative coordinates can be used. If all values given are in the range between
-1 and +2, then these values are interpreted as relative coordinates. Therefore, x coordinates
of 0 indicate the left border, and 1 the right border. The upper left quarter of the domain
can be chosen with (x0, y0) = (0,0.5) and (x1, y1) = (0.5,1).
x0 Lower left corner of the plotting area. (Default is whole area)
y0

x1 Upper right corner of the plotting area. (Default is whole area)

y1
The next values give the position, where the legend (scale bar and true north) is plotted.
x0leg Lower left corner of the area where the legend is plotted.
y0leg

43
x1leg Upper right corner of the area. where the legend (north and scale) is
y1leg plotted.

dxygrd Grid size if the results are interpolated on a regular grid. A value of
0 does not use a regular grid but the original finite element grid for
plotting. (Default 0)

typls Typical length scale to be used when scaling velocity or transport ar-
rows. If dxygrd is given this length is used and typls is not used. If
not given it is computed from the basin parameters. (Default 0)

typlsf Additional factor to be used with typls to determine the length of the
maximum or reference vector. This is the easiest way to scale the ve-
locitiy arrows with an overall factor. (Default 1)

velref Reference value to be used when scaling arrows. If given, a vector with
this value will have a length of typls*typlsf on the map, or, in case
dxygrd is given, dxygrd*typlsf. If not set the maximum value of the
velocity/transport will be used as velref. (Default 0)

velmin Minimum value for which an arrow will be plotted. With this value you
can eliminate small arrows in low dynamic areas. (Default 0)

isphe If 0 a cartesian coordinate system is used, If 1 the coordinates are in

the spherical system (lat/lon). Among other, this indicates that the x-
coordinates will be multiplied by a factor that accounts for the visual
deformation using lat/lon coordinates. The default is -1, which means
that the type of coordinate system will be determined automatically.
(Default -1)

reggrd If different from 0 it plots a regular grid over the plot for geographical
reference. The value of reggrd gives the spacing of the regular grid
lines. The units must be according to the units used for the coordinates.
With value of -1 the regular grid is determined automatically. (Default
-1)

regdst This value gives the number of intervals that are used to sub-divide the
grid given by reggrd with a black and white scale around the plot. If 0
it tries to determine automatically the sub-intervals (2 or 4). A value of
-1 does not plot the subgrid scale. (Default 0)

reggry If plotting the regular overlay grid this gives the grey value used for the
grid. 0 is black, and 1 is white. A value of 1 does not plot the overlay
grid, but still writes the labels. (Default 0.5)

bndlin Name of file that gives the boundary line that is not part of the finite
element domain. The file must be in BND format. You can use the
program grd2bnd.pl to create the file from a GRD file. (Default is no
file)

ioverl Create overlay of velocity vectors on scalar value. With the value of
0 no overlay is created, 1 creates an overlay with the velocity speed.
The value of 2 overlays vertical velocities 3 water levels and 4 overlays
bathymetry.(Default 0)

44
inorm Normally the horizontal velocities are plotted in scale. The value of
inorm can change this behavior. A value of 1 normalizes velocity vec-
tors (all vectors are the same length), whereas 2 scales from a given
minimum velocity velmin. Finally, the value of 3 uses a logarithmic
scale. (Default 0)

C.2.3 Section $color

The next parameters deal with the definition of the colors to be used in the plot. A color
bar is plotted too.
icolor Flag that determines the type of color table to be used. 0 stands for gray
scale, 1 for HSB color table. Other possible values are 2 (from white to
blue), 3 (from white to red), 4 (from blue over white to red). Values 5
and 6 indicate non-linear HSB color tables. (Default 0)

isoval Array that defines the values for the isolines and colors that are to be
plotted. Values given must be in the unit of the variable that will be
plotted, i.e., meters for water levels etc.

color Array that gives the color indices for the plotting color to be used.
Ranges are from 0 to 1. The type of the color depends on the vari-
able icolor. For the gray scale table 0 represents black and 1 white.
Values in between correspond to tones of gray. For the HSB color table
going from 0 to 1 gives the color of the rainbow. There must be one
more value in color than in isoval. The first color in color refers
to values less than isoval(1), the second color in color to values be-
tween isoval(1) and isoval(2). The last color in color refers to
values greater than the last value in isoval.

x0col Lower left corner of the area where the color bar is plotted.
y0col

x1col Upper right corner of the area where the color bar is plotted.
y1col

faccol Factor for the values that are written to the color bar legend. This en-
ables you, e.g., to give water level results in mm (faccol = 1000).
(Default 1)

ndccol Decimals after the decimal point for the values written to the color bar
legend. Use the value -1 to not write the decimal point. A value of 0
automatically computes the number of decimals needed. (Default 0)

legcol Text for the description of the color bar. This text is written above the
color bar.
It is not necessary to give all values for isolines and colors above. A faster way is to give
only the minimum and maximum values and fix the number of isovalues to be used.
niso Total number of isolines to use. (Default is nisodf)

nisodf Default number of isolines to use. (Default 5)

colmin Minimum and maximum color index used. Defaults are 0.1 and 0.9
colmax respectively. The value of colmax can be smaller than colmin which
inverts the color index used.

45
valmin Minimum and maximum value for isovalues to be used. There is no
valmax default.
dval Difference of values between isolines. If this value is greater then 0
the values for isolines and the total number of isolines are computed
automatically using also valmin and valmax. (Default 0)
Since there is a great choice of combinations between the parameters, we give here the
following rules how the values for colors and isolines are determined.
If colors are given in array color, they are used, else colmin and colmax or their respective
defaults are used to determine the color bar. If isoval is given it is used, else valmin and
valmax are used. If valmin and valmax are not given they are computed every time for
each plot and the minimum and maximum value in the basin are used. In any case, if
isoval is specified the total number of isovalues is known and niso is ignored. However,
if isoval is not given then first dval is used to decide how many isovalues to plot, and if
dval is 0 then the niso and finally nisodf is used.
Other parameters that can be changed are the following.
nisomx Maximum for niso allowed. This is especially useful when the value
for niso is determined automatically. It avoids you to plot 1000 isolines
due to wrong settings of dval. However, if you want to use 50 isovalues
then just set niso and nisomx to 50. (Default 20)

nctick Number of values to be written in color bar. If niso is high the labels
on the color bar become unreadable. Therefore you can use nctick to
write only some of the values to the color bar. For example, if valmin
is 0 and valmax is 5 and you use many isolines, then setting nctick
to 6 would give you labels at values 0,1,2,3,4,5. If nctick is 0 then all
lables are written. (Default 0)

isolin Normally the isolines are not drawn on the plot, just the colors are used
to show the value in the different parts of the plot. A value different
from 0 plots also the isolines. In this case isolin gives the number of
isolines to be plotted. A good choice is to make this equal to nctick,
so that the isolines correspond to the values written on the colorbar. For
compatibility, a value of 1 plots all isolines. (Default 0)

isoinp Normally inside elements the values are interpolated. Sometimes it is

usefull to just plot the value of the node without interpolation inside the
element. This can be accomplished by setting isoinp=0. (Default 1)

bgray Gray value used for the finite element grid when plotting the bathyme-
try. (Default 0.8)

bsgray Gray value used to plot the finite element grid over a scalar or velocity
plot. This is basically useful for debugging reasons. The default is to
not plot the grid (Default -1.0)

C.2.4 Section $arrow

The next parameters deal with the reference arrow that is plotted in a legend. The arrow
regards the plots where the velocity or the transport is plotted.
x0arr Lower left corner of the area where the reference arrow is plotted.
y0arr

46
x1arr Upper right corner of the area where the reference arrow is plotted.
y1arr

facvel Factor for the value that is written to the arrow legend for the velocity.
This enables you, e.g., to give velocities in mm/s (facvel = 1000).
(Default 1)

ndcvel Decimals after the decimal point for the values written to the arrow
legend. Use the value -1 to not write the decimal point. (Default 2)

legvel Text for the description of the arrow legend. This text is written above
the arrow.
arrvel Length of arrow in legend (in velocity units). If not given the arrow
length will be computed automatically. (Default 0)

sclvel Additional factor to be used for the arrow in the legend. When the
arrow length will be computed automatically, this parameter gives the
possibility to change the length of the reference vector. This is an easy
way to scale the velocitiy arrow with an overall factor. Not used if
arrvel is given. (Default 1)

C.2.5 Section $legend

In this section annotations in the plots can be given. The section consists of a series of lines
that must contain the following information:
The first value is a keyword that specifies what has to be plotted. Possible values are text,
line, vect, rect, circ and also wid and col. These correspond to different types of
information that is inserted into the plot such as text, line, vector, rectangle or circle (filled
or just outline). Moreover, the color and line width of the pen can be controlled by with
wid and col.
In case of text the starting position (lower left corner) is given, then the point size of the
font and the text that is inserted. line needs the starting and end point of the line. The
same with vect, but in this case also the relative tip size must be given as a final parameter.
rect needs the coordinates of the lower left corner and upper right corner of the rectangle.
It also needs the color used for the filling of the rectangle (0-1) or the flag -1 which only
draws the outline of the rectangle without filling it. circ needs the center point and the
radius and a fill color (see rectangle). Finally wid needs the relative width of the line and
col the stroke color used when plotting lines.
A small example of an annotation that explains the above parameters would be:

$legend
text 30500 11800 15 ’Chioggia’ #text, 15pt
line 30500 11800 35000 15000 #line
vect 30500 11800 35000 15000 0.1 #arrow, tipsize 0.1
rect 30500 11800 35000 15000 0.1 #rectangle, fill color 0.1
rect 30500 11800 35000 15000 -1 #rectangle (outline, no fill)
circ 30500 11800 5000 -1 #circle (outline, no fill)
wid 5 #set line width to 5
col 0.5 #set color to 0.5
$end

There is also an old way to specify the legend that does not use keywords. However, this
way is deprecated and unsupported and is therefore not described anymore in this manual.

47
C.2.6 Section $legvar
In this section variable fields like the date and wind vectors may be inserted into the plot.
A time and date can be assigned to the simulation results. These values refer to the time 0
of the FEM model. The format for the date is YYYYMMDD and for the time HHMMSS.
You can also give a time zone if your time is not referring to GMT but to another time zone
such as MET. Please note that you have to give this information only if the simulation does
not contain it already. Normally, this information is already assigned during the simulation
runs.
date The real date corresponding to time 0. (Default 0)

time The real time corresponding to time 0. (Default 0)

tz The time zone you are in. This is 0 for GMT, 1 for MET and 2 for
MEST (MET summer time). (Default 0)

tzshow The time zone you want to show your results. If your time zone is GMT
(0) and you want to show the results referred to MET (+1) set this to +1.
Please note that you have to set this variable only if you want to show
results in a different time zone than the one given in tz. (Default 0)
The information of date and time may be written to the plot. This is done with the following
parameters.
xdate Starting point for the date text (lower left corner).
ydate

sdate Point size of the text. (Default 18)

idate Output mode. If 0 no date is written to the plot, else the date and time
is written. (Default 0)
Wind data can be used to insert a wind vector into the figure. This is useful because in the
case of variable wind the direction and speed of the wind that was blowing in the moment
of the plot is shown.
Since only one wind vector can be plotted, the wind data must consist of one value for each
time. The same ASCII file that is used in the STR file can be used.
xwind Starting point where the wind arrow is plotted.
ywind

iwtype Type of wind data. The same as the one in the STR file. If this parameter
is 0 then no wind vector is plotted. (Default 0)

lwwind Line width of the wind vector. (Default 0.1)

scwind Scaling parameter of the wind vector. This depends on the size of your
plot. If your wind is 10 m/s and you want the vector to strech over a
distance of 5 km on the plot then you have to choose the value of 500
(10*500=5000) for scwind. (Default 1)

wfile Name of the file containing the wind data. This may be the same file
than the one used in the STR file to run the program.
The wind vector is also given a text legend with the speed of the wind written out. The next
parameters decide where and how this information is put.
xtwind Starting point for the legend text (lower left corner).
ytwind

48
stwind Point size of the text. (Default 18)

wtext Text used for the legend (Default ’Wind speed’)

wunit Unit for the wind speed (Default ’m/s’)

C.2.7 Section $name

Directory specification This parameters define directories for various input and output
files.
basdir Directory where basin file BAS resides. (Default .)

datdir Directory where output files are written. (Default .)

tmpdir Directory for temporary files. (Default .)

defdir Default directory for other files. (Default .)

49
Bibliography

[1] Jan O. Backhaus. A semi-implicit scheme for the shallow water equations for aplica-
tion to shelf sea modelling. Continental Shelf Research, 2(4):243–254, 1983.
[2] Kurt C. Duwe and Regina R. Hewer. Ein semi-implizites gezeitenmodell für wattge-
biete. Deutsche Hydrographische Zeitschrift, 35(6):223–238, 1982.
[3] G. Grotkop. Finite element analysis of long-period water waves. Computer Methods
in Applied Mechanics and Engineering, 2(2):147–157, 1973.
[4] B. Herrling. Computation of shallow water waves with hybrid finite elements. Ad-
vances in Water Resources, 1:313–320, 1978.
[5] Bruno Herrling. Ein finite-element-modell zur berechnung von Tideströmungen in
ästuarien mit Wattflächen. Die Küste, 31:102–113, 1977.
[6] K.-P. Holz and G. Nitsche. Tidal wave analysis for estuaries with intertidal flats.
Advances in Water Resources, 5:142–148, 1982.
[7] Michael Kwizak and André J. Robert. A semi-implicit scheme for grid point atmo-
spheric models of the primitive equations. Monthly Weather Review, 99(1):32–36,
1971.
[8] A. Schoenstadt. A transfer function analysis of numerical schemes used to simulate
geostrophic adjustment. Monthly Weather Review, 108:1248, 1980.
[9] C. Taylor and J. Davis. Tidal and long wave propagation—a finite element approach.
Computers & Fluids, 3:125–148, 1975.
[10] Georg Umgiesser. A model for the Venice Lagoon. Master’s thesis, University of
Hamburg, 1986.
[11] Georg Umgiesser and Andrea Bergamasco. A staggered grid finite element model of
the Venice Lagoon. In J. Periaux K. Morgan, E. Ofiate and O.C. Zienkiewicz, editors,
Finite Elements in Fluids. Pineridge Press, 1993.
[12] R. T. Williams. On the formulation of finite-element prediction models. Monthly
Weather Review, 109:463, 1981.
[13] R. T. Williams and O. C. Zienkiewicz. Improved finite element forms for the shallow-
water wave equations. International Journal for Numerical Methods in Fluids, 1:81,
1981.

50