SWASH

USER MANUAL

SWASH version 2.00AB

SWASH USER MANUAL

by

The SWASH team

mail address :

Delft University of Technology

Faculty of Civil Engineering and Geosciences
Environmental Fluid Mechanics Section
P.O. Box 5048
2600 GA Delft
The Netherlands

website

http://swash.sourceforge.net

Copyright (c) 2010-2014 Delft University of Technology.

Permission is granted to copy, distribute and/or modify this document under the terms of
the GNU Free Documentation License, Version 1.2 or any later version published by the
Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no BackCover Texts. A copy of the license is available at http://www.gnu.org/licenses/fdl.html#TOC1.

iv

Contents
1 About this manual

2 General description and instructions for use

2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Background, features and applications . . . . . . . . .
2.2.1 Objective and context . . . . . . . . . . . . . .
2.2.2 A birds-eye view of SWASH . . . . . . . . . . .
2.2.3 Model features and validity of SWASH . . . . .
2.2.4 Relation to Boussinesq-type wave models . . . .
2.2.5 Relation to circulation and coastal flow models .
2.3 Internal scenarios, shortcomings and coding bugs . . .
2.4 Units and coordinate systems . . . . . . . . . . . . . .
2.5 Choice of grids and time windows . . . . . . . . . . . .
2.5.1 Introduction . . . . . . . . . . . . . . . . . . . .
2.5.2 Computational grid and time window . . . . . .
2.5.3 Input grid(s) and time window(s) . . . . . . . .
2.5.4 Input grid(s) for transport of constituents . . .
2.5.5 Output grids . . . . . . . . . . . . . . . . . . .
2.6 Boundary conditions . . . . . . . . . . . . . . . . . . .
2.7 Time and date notation . . . . . . . . . . . . . . . . .
2.8 Troubleshooting . . . . . . . . . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

3
3
3
3
4
6
8
8
9
9
10
10
11
12
13
14
15
16
16

3 Input and output files

3.1 General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Input / output facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3 Print file and error messages . . . . . . . . . . . . . . . . . . . . . . . . . .

19
19
19
20

4 Description of commands
4.1 List of available commands . . . . . .
4.2 Sequence of commands . . . . . . . .
4.3 Command syntax and input / output
4.4 Start-up . . . . . . . . . . . . . . . .
PROJECT . . . . . . . . . . .

21
21
23
24
24
24

. . . . . . .
. . . . . . .
limitations .
. . . . . . .
. . . . . . .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

vi

4.5

4.6

SET . . . . . . . . . . . . . . . .
MODE . . . . . . . . . . . . . . .
COORDINATES . . . . . . . . .
Model description . . . . . . . . . . . . .
4.5.1 Computational grid . . . . . . . .
CGRID . . . . . . . . . . . . . .
READGRID COORDINATES . .
VERTICAL . . . . . . . . . . . .
4.5.2 Input grids and data . . . . . . .
INPGRID . . . . . . . . . . . . .
READINP . . . . . . . . . . . . .
INPTRANS . . . . . . . . . . . .
READTRANS . . . . . . . . . .
4.5.3 Initial and boundary conditions .
INITIAL . . . . . . . . . . . . . .
BOUND SHAPE . . . . . . . . .
BOUNDCOND . . . . . . . . . .
SPONGE LAYER . . . . . . . .
POROSITY . . . . . . . . . . . .
4.5.4 Physics . . . . . . . . . . . . . . .
WIND . . . . . . . . . . . . . . .
FRICTION . . . . . . . . . . . .
VISCOSITY . . . . . . . . . . . .
VEGETATION . . . . . . . . . .
TRANSPORT . . . . . . . . . . .
BREAKING . . . . . . . . . . . .
4.5.5 Numerics . . . . . . . . . . . . .
NONHYDROSTATIC . . . . . .
DISCRETIZATION . . . . . . .
TIME INTEGRATION . . . . . .
Output . . . . . . . . . . . . . . . . . . .
4.6.1 Output locations . . . . . . . . .
FRAME . . . . . . . . . . . . . .
GROUP . . . . . . . . . . . . . .
CURVE . . . . . . . . . . . . . .
RAY . . . . . . . . . . . . . . . .
ISOLINE . . . . . . . . . . . . .
POINTS . . . . . . . . . . . . . .
4.6.2 Write or plot computed quantities
QUANTITY . . . . . . . . . . . .
OUTPUT . . . . . . . . . . . . .
BLOCK . . . . . . . . . . . . . .
TABLE . . . . . . . . . . . . . .

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

24
27
27
28
28
28
29
30
31
31
36
40
41
42
42
42
43
49
50
50
50
53
54
55
56
59
60
60
62
65
67
68
68
69
70
70
71
72
72
72
74
75
83

vii
4.6.3
4.7

Write or plot intermediate results

TEST . . . . . . . . . . . . . . .
Lock-up . . . . . . . . . . . . . . . . . .
COMPUTE . . . . . . . . . . . .
STOP . . . . . . . . . . . . . . .

.
.
.
.
.

5 Setting up your own command file

5.1 Computational grid . . . . . . . . . . . . .
5.2 Input grids . . . . . . . . . . . . . . . . . .
5.3 Initial and boundary conditions . . . . . .
5.4 Numerical parameters . . . . . . . . . . .
5.4.1 Duration of simulation . . . . . . .
5.4.2 Time step . . . . . . . . . . . . . .
5.4.3 Vertical pressure gradient . . . . .
5.4.4 Momentum conservation . . . . . .
5.4.5 Discretization of advection terms in
5.4.6 Moving shorelines . . . . . . . . . .
5.5 Physical parameters . . . . . . . . . . . . .
5.5.1 Depth-induced wave breaking . . .
5.5.2 Subgrid turbulent mixing . . . . . .
5.5.3 Vertical turbulent mixing . . . . . .
5.5.4 Bottom friction . . . . . . . . . . .
5.6 Output quantities, locations and formats .
5.7 The importance of parallel computing . . .

.
.
.
.
.

.
.
.
.
.

. .
. .
. .
. .
. .
. .
. .
. .
the
. .
. .
. .
. .
. .
. .
. .
. .

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

.
.
.
.
.

. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
momentum equations
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .
. . . . . . . . . . . . .

.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.

84
84
85
85
86

.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.

87
87
91
93
96
96
96
97
98
98
100
101
101
102
103
103
103
103

A Definitions of variables

107

B Command syntax
B.1 Commands and command schemes . . . . .
B.2 Command . . . . . . . . . . . . . . . . . . .
B.2.1 Keywords . . . . . . . . . . . . . . .
Spelling of keywords . . . . . . . . .
Required and optional keywords . . .
Repetitions of keywords and/or other
B.2.2 Data . . . . . . . . . . . . . . . . . .
Character data and numerical data .
Spelling of data . . . . . . . . . . . .
Required data and optional data . .
B.3 Command file and comments . . . . . . . . .
B.4 End of line or continuation . . . . . . . . . .

111
111
111
111
112
112
113
113
113
113
115
115
116

C File swash.edt

. . .
. . .
. . .
. . .
. . .
data
. . .
. . .
. . .
. . .
. . .
. . .

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

.
.
.
.
.
.
.
.
.
.
.
.

117

viii
Bibliography

125

Index

126

Chapter 1
About this manual
The information about the SWASH package is distributed over two different documents.
This User Manual describes the complete input and usage of the SWASH package. The
Implementation Manual explains the installation procedure of SWASH on a single- or multiprocessor machine with distributed memory. Apart from these documents, programmers
who want to further develop SWASH can also consult the Programming rules as applied
for SWAN; see http://www.swan.tudelft.nl for further details.
In Chapter 2 general description of the model and some instructions concerning the usage
of SWASH, the treatment of grids, boundary conditions, etc. are given. It is advised to
read this chapter before consulting the rest of the manual. Chapter 3 gives some remarks
concerning the input and output files of SWASH. Chapter 4 describes the complete set of
commands of the program SWASH. In Chapter 5 some guidelines for setting up a command
file is outlined.
It is strongly advised that users who are not so experienced in the use of SWASH should
first read Chapters 2 and 3. Also, Chapter 5 is recommended.
This manual also contains some appendices. In Appendix A definitions of some parameters
are given. Appendix B outlines the syntax of the command file (or input file). A complete
set of all the commands use in SWASH can be found in Appendix C.

Chapter 1

Chapter 2
General description and instructions
for use
2.1

Introduction

The purpose of this chapter is to provide the user with relevant background information
on SWASH and to give some general advice in choosing the basic input for SWASH computations.
A general suggestion is: start simple. SWASH helps in this with default options. Moreover,
it is a good idea to read Chapter 5 first when setting up a command file for the first time.
Furthermore, suggestions are given that should help the user to choose among the many
options conditions and in which mode to run SWASH (1D or flume-like, 2D or basin-like,
depth-averaged or multi-layered, etc.). In addition, the way you need to specify the parameters and options resembles to that of SWAN. Hence, those users who are familiar with
SWAN should be able to use SWASH without much effort. It is recommended to carry out
some available test cases first to get acquaint with the program.

2.2
2.2.1

Background, features and applications

Objective and context

SWASH is a general-purpose numerical tool for simulating non-hydrostatic, free-surface,

rotational flows and transport phenomena in one, two or three dimensions. The governing
equations are the nonlinear shallow water equations including non-hydrostatic pressure and
some transport equations, and provide a general basis for simulating
wave transformation in both surf and swash zones due to nonlinear wave-wave interactions, interaction of waves with currents, interaction of waves with structures, wave
damping due to vegetation, and wave breaking as well as runup at the shoreline,
3

Chapter 2
complex changes to rapidly varied flows typically found in coastal flooding resulting
from e.g. dike breaks, tsunamis, and flood waves,
density driven flows in coastal seas, estuaries, lakes, and rivers, and
large-scale ocean circulation, tides and storm surges.

The model is referred to as a wave-flow model and is essentially applicable in the coastal
regions up to the shore. This has prompted the acronym SWASH for the associated code,
standing for Simulating WAves till SHore. The basic philosophy of the SWASH code is to
provide an efficient and robust model that allows a wide range of time and space scales
of surface waves and shallow water flows in complex environments to be applied. As a
result, SWASH allows for the entire modelling process to be carried out in any area of
interest. This includes small-scale coastal applications, like waves approaching a beach,
wave penetration in a harbour, flood waves in a river, oscillatory flow through canopies,
salt intrusion in an estuary, and large-scale ocean, shelf and coastal systems driven by
Coriolis and meteorological forces to simulate tidal waves and storm surge floods.
SWASH is close in spirit to SWAN (Simulating WAves Nearshore) with respect to the
pragmatism employed in the development of the code in the sense that comprises are
sometimes necessary for reasons of efficiency and robustness. On the one hand, it provides
numerical stability and robustness, and on the other hand it gives accurate results in a
reasonable turn-around time.

2.2.2

A birds-eye view of SWASH

The open source code of SWASH has been developed based on the work of Stelling and
Zijlema (2003), Stelling and Duinmeijer (2003), Zijlema and Stelling (2005, 2008) and Smit
et al. (2013). The main elements of the SWASH code are:
It is based on an explicit, second order finite difference method for staggered grids
whereby mass and momentum are strictly conserved at discrete level. As a consequence, this simple and efficient scheme is able to track the actual location of incipient
wave breaking. Also, momentum conservation enables the broken waves to propagate with a correct gradual change of form and to resemble steady bores in a final
stage. Yet, this approach is appropriate for hydraulic jumps, dam-break problems
and flooding situations as well.
In the case of flow contractions, the horizontal advective terms in momentum equations are approximated such that constant energy head is preserved along a streamline.
By considering the similarity between breaking waves and moving hydraulic jumps,
energy dissipation due to wave breaking is inherently accounted for. In addition,
nonlinear wave properties under breaking waves such as asymmetry and skewness
are preserved.

General description and instructions for use

For accuracy reason, the pressure is split-up into hydrostatic and non-hydrostatic
parts. Time stepping is done in combination with a projection method, where correction to the velocity field for the change in non-hydrostatic pressure is incorporated.
Moreover, space discretization precedes introduction of pressure correction, so that
no artificial pressure boundary conditions are required.
Because of the abovementioned pressure splitting, hydrostatic flow computation can
be done easily as well by simply switching off the non-hydrostatic pressure. As such,
SWASH is appropriate for the simulation of large-scale tides and storm surges.
With respect to time integration of the continuity and momentum equations, the
second order leapfrog scheme is adopted, as it does not alter the wave amplitude while
its numerical dispersion is favourable. This will prove beneficial to wave propagation.
Alternatively, time discretization may take place by explicit time stepping for horizontal advective and viscosity terms and semi-implicit time stepping using the method
for both surface level and pressure gradients as well as the free-surface condition. As
a consequence, unconditional stability is achieved with respect to the celerity of gravity waves. The enhanced stability of this time stepping allows larger time steps, by a
factor of five to ten, compared to the leapfrog scheme, and may thus be beneficial to
large-scale applications such as tidal flow, and wind and density driven circulation.
The physical domain can be discretized by subdivision of the continuum into cells
of arbitrary shape and size. A structured grid is employed, which means that each
interior cell is surrounded by the same number of cells. A distinction is made between
the definition of the grid in the horizontal and vertical direction. In the horizontal
planes, rectilinear or orthogonal curvilinear, boundary-fitted grid can be considered.
Either Cartesian coordinates on a plane or spherical coordinates on the globe can be
defined. In the vertical direction, the computational domain is divided into a fixed
number of layers in a such a way that both the bottom topography and the free
surface can be accurately represented. In this way, it permits more resolution near
the free surface as well as near the bed.
In order to resolve the frequency dispersion up to an acceptable level of accuracy,
a compact difference scheme for the approximation of vertical gradient of the nonhydrostatic pressure is applied in conjunction with a vertical layer mesh employing
equally distributed layers. This scheme receives good linear dispersion up to kd 8
and kd 16 with two and three equidistant layers, respectively, at 1% error in
phase velocity of primary waves (k and d are the wave number and still water depth,
respectively). The model improves its frequency dispersion by simply increasing the
number of vertical layers.
The three-dimensional simulation of flows exposing strong vertical variation amounts
to the accurate computation of vertical turbulent mixing of momentum and some constituents, such as salt, heat and suspended sediment, combined with an appropriate

Chapter 2
vertical terrain-following grid employing sufficient number of non-equidistant layers.
The vertical variation may be generated by wind forcing, bed stress, Coriolis force
or density stratification.
The combined effects of wave-wave and wave-current interaction in shallow water
are automatically included and do not need any additional modelling, such as calculating the radiation stresses explicitly and subsequently solving a wave-averaged
hydrodynamic model separately.
For a proper representation of the interface of water and land, a simple approach is
adopted that tracks the moving shoreline by ensuring non-negative water depths and
using the upwind water depths in the momentum flux approximations.

Like SWAN, the software package of SWASH includes user-friendly pre- and post-processing
and does not need any special libraries (e.g. PETSc, HYPRE). In addition, SWASH is
highly flexible, accessible and easily extendible concerning several functionalities of the
model. As such, SWASH can be used operationally and the software can be used freely
under the GNU GPL license (http://swash.sourceforge.net).

2.2.3

Model features and validity of SWASH

SWASH is a free-surface, terrain-following, multi-dimensional hydrodynamic simulation

model to describe unsteady, rotational flow and transport phenomena in coastal waters
as driven by e.g., waves, tides, buoyancy and wind forces. It solves the continuity and
momentum equations, and optionally the equations for conservative transport of salinity,
temperature and suspended load for noncohesive sediment (e.g. sand). In addition, the
vertical turbulent dispersion of momentum and diffusion of salt, heat and suspended sediment are calculated by means of the standard k turbulence model. The transport
equations are coupled with the momentum equations through the baroclinic forcing term,
whereas the equation of state is employed that relates density to salinity, temperature and
suspended sediment.
SWASH accounts for the following physical phenomena:
wave propagation, frequency dispersion, shoaling, refraction and diffraction,
nonlinear wave-wave interactions (including surf beat and triads),
wave breaking,
wave runup and rundown,
moving shoreline,
bottom friction,
partial reflection and transmission,

General description and instructions for use

wave interaction with structures,

wave-current interaction,
wave-induced currents,
vertical turbulent mixing,
subgrid turbulence,
wave damping induced by aquatic vegetation,
rapidly varied flows,
tidal waves,
bores and flood waves,
wind driven flows,
space varying wind and atmospheric pressure,
density driven flows,
transport of suspended load for noncohesive sediment,
turbidity flows, and
transport of tracer.
The model has been validated with a series of analytical, laboratory and field test cases.
Overall, the level of agreement between predictions and observations is quite favourable,
particularly in view of the fact that a wide range of wave conditions and topographies were
modelled.
SWASH is proved to reproduce the main features of surf zone dynamics, such as nonlinear
shoaling, wave breaking, wave runup and wave-driven currents. For instance, considering
a typical surf zone where the dominant processes of triad interaction and depth-induced
breaking can be isolated, it was found that the model yields a realistic representation of
the observed frequency spectra, including the overall spectral shape at frequencies above
the spectral peak, and the inclusion of subharmonics. This is followed by a transformation
toward a broadband spectral shape as the waves approach the shoreline. Such phenomena
appear to be rooted in the ability of the momentum-conservative scheme to mimic the
dynamics within travelling bores associated with wave breaking across the surf zone.

2.2.4

Chapter 2

Relation to Boussinesq-type wave models

SWASH is not a Boussinesq-type wave model. In fact, SWASH may either be run in depthaveraged mode or multi-layered mode in which the computational domain is divided into a
fixed number of vertical terrain-following layers. SWASH improves its frequency dispersion
by increasing this number of layers rather than increasing the order of derivatives of the
dependent variables like Boussinesq-type wave models. Yet, it contains at most second
order spatial derivatives, whereas the applied finite difference approximations are at most
second order accurate in both time and space.
In addition, SWASH does not have any numerical filter nor dedicated dissipation mechanism to eliminate short wave instabilities. Neither does SWASH include other ad-hoc
measures like the surface roller model for wave breaking, the slot technique for moving
shoreline, the source functions for internal wave generation, and the alteration of the governing equations for modelling wave-current interaction. As such, SWASH is very likely
to be competitive with the extended Boussinesq-type wave models in terms of robustness
and the computational resource required to provide reliable model outcomes in challenging
wave and flow conditions. Therefore, it can be seen as an attractive alternative to the
Boussinesq-type wave models.

2.2.5

Relation to circulation and coastal flow models

SWASH is a non-hydrostatic wave-flow model and is originally designed for wave transformation in coastal waters. However, with the extension of meteorological and baroclinic forcing and solute transport (since version 2.00), this model is capable of using for
large-scale flow and transport phenomena driven by tidal, wind and buoyancy forces. In
this respect, SWASH is very similar to other traditional hydrodynamic models, such as
WAQUA, Delft3D-FLOW, ADCIRC, ROMS, FVCOM, UNTRIM, SLIM and SUNTANS.
They mainly differ in numerics and geometric flexibility.
The need to accurately predict small-scale coastal flows and transport of contaminants
encountered in environmental issues is becoming more and more recognized. The aforementioned models, however, are orginally designed to simulate large-scale circulation. The
development of these models is often dictated by model limitations, numerical techniques
and computer capabilities. For instance, the hydrostatic pressure assumption prohibits
the models to appropriately simulate surface waves, internal waves, and small-scale flows
around hydraulic structures.
In principle, SWASH has no limitations and can capture flow phenomena with spatial
scales from centimeters to kilometers and temporal scales from seconds to hours. Yet, this
model can be employed to resolve the dynamics of wave transformation, buoyancy flow
and turbulent exchange of momentum, salinity, heat and suspended sediment in shallow
seas, coastal waters, surf zone, estuaries, reefs, rivers and lakes.

General description and instructions for use

2.3

Internal scenarios, shortcomings and coding bugs

Sometimes the user input to SWASH is such that the model produces unreliable or unstable
results. This may be the case, for instance, if the bathymetry is not well resolved or the
boundary conditions are wrong (not well-posed). In addition, SWASH may invoke some
internal scenarios instead of terminating the computations. The reasons for this model
policy is that
SWASH needs to be robust, and
the problem may be only very local, or
the problem needs to be fully computed before it can be diagnosed.
Examples are:
The minimum depth for checking drying and flooding may be adapted as soon as the
water level is below the bottom.
A dynamically adjusted time step controlled by the Courant number in a user prescribed range is implemented. This time step control for a particular SWASH run is
provided in the PRINT file.
Based on a stability criterion due to the explicit treatment of the horizontal eddy
viscosity term in the momentum equations, a maximum of the eddy viscosity is
determined at each time step. The user will be informed about this measure by
means of a warning in the PRINT file when the number of instable points is more
than 1% of the total number of grid points.
Some other problems which the SWASH user may encounter are due to more fundamental shortcomings, e.g., turbulence modelling, and unintentional coding bugs.
Because of the issues described above, the results may look realistic, but they may (locally)
not be accurate. Any change in these scenarios or shortcomings, in particular newly discovered coding bugs and their fixes, are published on the SWASH website and implemented
in new releases of SWASH.

2.4

Units and coordinate systems

SWASH expects all quantities that are given by the user to be expressed in S.I. units: m,
kg, s and composites of these with accepted compounds, such as Newton (N) and Pascal
(Pa). Consequently, the water level and water depth are in m, flow velocity in m/s, etc.
For wind, (incident) wave and flow direction both the Cartesian and a nautical convention
can be used (see below). Directions and spherical coordinates are in degrees (0 ) and not
in radians.

10

Chapter 2

SWASH operates either in a Cartesian coordinate system or in a spherical coordinate

system, i.e. in a flat plane or on a spherical Earth. In the Cartesian system, all geographic
locations and orientations in SWASH, e.g. for the bottom grid or for output points, are
defined in one common Cartesian coordinate system with origin (0,0) by definition. This
geographic origin may be chosen totally arbitrarily by the user. In the spherical system,
all geographic locations and orientations in SWASH, e.g. for the bottom grid or for output
points, are defined in geographic longitude and latitude. Both coordinate systems are
designated in this manual as the problem coordinate system.
In the input and output of SWASH the direction of wind, (incident) wave and current are
defined according to either
the Cartesian convention, i.e. the direction to where the vector points, measured
counterclockwise from the positive xaxis of this system (in degrees) or
a nautical convention (there are more such conventions), i.e. the direction where the
wind or the waves come from, measured clockwise from geographic North.
All other directions, such as orientation of grids, are according to the Cartesian convention!
For regular grids, i.e. uniform and rectangular, Figure 4.1 (in Section 4.5) shows how the
locations of the various grids are determined with respect to the problem coordinates. All
grid points of curvilinear grids are relative to the problem coordinate system.

2.5
2.5.1

Choice of grids and time windows

Introduction

Both spatial grids and time windows need to be defined.

The spatial grids that need to be defined by the user are (if required):
a computational spatial grid on which SWASH performs the computations,
one (or more) spatial input grid(s) for the bottom, (initial) current field, (initial)
water level, bottom friction, wind, atmospheric pressure, porosity regions, grain sizes
of armour rocks, heights of breakwaters and quays and vegetation density (each input
grid may differ from the others),
one (or more) spatial input grid(s) for transport of constituents to define initial and
stationary boundary conditions for constituents, and
one (or more) spatial output grid(s) on which the user requires output of SWASH.
Wind, bottom friction, grain sizes, heights of porous structures and vegetation density do
not require a grid if they are uniform over the area of interest.

General description and instructions for use

11

For one-dimensional situations, i.e. /y 0, SWASH can be run in 1D mode.

If a uniform, rectangular computational grid is chosen in SWASH, then all input and output
grids must be uniform and rectangular too, but they may all be different from each other.
If an orthogonal curvilinear computational grid is chosen in SWASH, then each input grid
should be either uniform, rectangular or identical to the used curvilinear computational
grid.
Also, SWASH may operate with different time windows with different time steps (each
may have a different start and end time and time step):
one computational time window in which SWASH performs the computations,
one (or more) input time window(s) in which wind and pressure field (if present) are
given by the user (each input window may differ form the others) and
one (or more) output time window(s) in which the user requires output of SWASH.
During the computation SWASH obtains bottom, current, water level, wind, pressure,
bottom friction, porosity, grain size, structure height and vegetation density information
by tri-linear interpolation from the given input grid(s) and time window(s). The output is
in turn obtained in SWASH by bi-linear interpolation in space from the computational grid;
there is no interpolation in time, the output time is shifted to the nearest computational
time level. Interpolation errors can be reduced by taking the grids and windows as much
as equal to one another as possible (preferably identical). It is recommended to choose
output times such that they coincide with computational time levels.

2.5.2

Computational grid and time window

The computational grid must be defined by the user. The orientation (direction) can
be chosen arbitrarily.
If the computational grid extends outside the input grid, the reader is referred to Section 2.5.3 to find the assumptions of SWASH on depth, current, water level, wind, bottom
friction, porosity, grain size, structure height and vegetation density in the non-overlapping
area.
The spatial resolution of the computational grid should be sufficient to resolve relevant details of the wave field. Usually a good choice is to take the resolution of the computational
grid approximately equal to that of the bottom or current grid.
SWASH may not use the entire user-provided computational grid if the user defines exception values on the bottom grid (see command INPGRID BOTTOM) or on the curvilinear
computational grid (see command CGRID). A computational grid point is either
wet, i.e. the grid point is included in the computation since it represents water or

12

Chapter 2
dry, i.e. the grid point is excluded from the simulation since it represents land which
may vary as moving shoreline or
exceptional, i.e. the grid point is permanently excluded from the computations since
it is so defined by the user. This provides a means to make a line of dams or screens
through the computational domain, separating the flow on both sides. This line
of thin dams may represent a small obstacle with subgrid dimensions that possibly
influence the local flow (e.g. breakwater, jetty, or small harbour).

It must be noted that for parallel runs using MPI the user must indicate an exception value
when reading the bottom levels (by means of command INPGRID BOTTOM EXCEPTION), if
appropriate, in order to obtain good load balancing.
The computational time window must be defined by the user. The computational
window in time must start at a time that is early enough that the initial state of SWASH has
propagated through the computational area before reliable output of SWASH is expected.
Before this time the output may not be reliable since usually the initial state is not known.
The computational time step must be given by the user. Since, SWASH is based on explicit
schemes, it is limited by a Courant stability criterion (which couples time and space steps).
Moreover, the accuracy of the results of SWASH are obviously affected by the time step.
Generally, the time step in SWASH should be small enough to resolve the time variations
of computed wave field itself. Usually, it is enough to consider the time variations of the
wave boundary conditions.

2.5.3

Input grid(s) and time window(s)

The bathymetry, current, water level, bottom friction (if spatially variable), wind (if spatially variable), atmospheric pressure, porosity regions, grain sizes, heights of porous structures (if spatially variable) and vegetation density (if spatially variable) need to be provided
to SWASH on so-called input grids. It is best to make an input grid so large that it completely covers the computational grid.
When the atmospheric pressure is included, it must be combined with space varying wind.
They may be read from a meteorological file. Space varying wind and pressure is of particular importance for the simulation of storm surges.
In the region outside the input grid SWASH assumes that the bottom level, the water level,
bottom friction, atmospheric pressure, stone diameter and vegetation density are identical
to those at the nearest boundary of the input grid (lateral shift of that boundary). In the
regions not covered by this lateral shift (i.e. in the outside quadrants of the corners of the
input grid), a constant field equal to the value at the nearest corner point of the input
grid is taken. For the current and wind velocity, SWASH takes 0 m/s for points outside
the input grid, while for porosity and structure height, SWASH takes 1 and 99999 (i.e.
emerged), respectively, for points outside the input grid.

General description and instructions for use

13

One should choose the spatial resolution for the input grids such that relevant spatial details in the bathymetry, current, bottom friction, wind and pressure are properly resolved.
Special care is required in cases with sharp and shallow ridges (sand bars, shoals, breakwaters) in the sea bottom and extremely steep bottom slopes. Very inaccurate bathymetry
can result in very inaccurate wave transformation or flooding and drying. In such cases
the ridges are vitally important to obtain good SWASH results. This requires not only
that these ridges should be well represented on the input grid but also after interpolation
on the computational grid. This can be achieved by choosing the grid lines of the input
grid along the ridges (even if this may require some slight shifting of the ridges) and
choosing the computational grid to be identical to the input grid (otherwise the ridge may
be lost in the interpolation from the bottom input grid to the computational grid). An
alternative is to smooth the bottom gradients. But this should be done in a way that the
quality and feature of the bathymetric data is more or less the same.
In SWASH, wind, pressure and bottom friction may be time varying. In that case they
need to be provided to SWASH in so-called input time windows (they need not be identical with the computational, output or other input windows). It is best to make an input
window larger than the computational time window. SWASH assumes zero values at times
before the earliest begin time of the input parameters (which may be the begin time of any
input parameter such as wind). SWASH assumes constant values (the last values) at times
after the end time of each input parameter. The input windows should start early enough
so that the initial state of SWASH has propagated through the computational area before
reliable output of SWASH is expected.
Finally, one should use a time step that is small enough that time variations in the wind,
pressure and bottom friction are well resolved.

2.5.4

Input grid(s) for transport of constituents

With SWASH some transport phenomena of constituents can be simulated that result
from tidal, wind and wave forcing in stratified flows. The considered constituents are
salinity, temperature and suspended sediment load. The presence of these constituents
will influence the density of water and consequently, they will induce flow through the
baroclinic pressure gradient. In this way, transport of constituents and water flow are
coupled. Examples are salt intrusion in an estuary, sediment transport in turbidity flows
and transport of dissolved matter in lakes and rivers.
Only the background temperature is considered in the model, and the heat exchange flux
at the air-water interface is not taken into account.
With respect to the sediment transport, the following assumptions are made.
Only transport of noncohesive sediment is modelled; cohesive sediment is not taken
into account.

14

Chapter 2
Only suspended load is modelled; bed load is not taken into account.
The three-dimensional sediment transport processes include advection, diffusion,
pickup and settling.
In the depth-averaged mode, however, there is no mass exchange of suspended sediment between the bed and the flow.
The pickup function approach is employed. This function models the amount of
sediment eroded from the bed into the fluid, i.e. upward sediment flux, and is related
to the bottom shear stress. The downward sediment flux depends on the settling
velocity only.
The intergranular interactions are excluded.

The inclusion of transport of constituent in SWASH must be done by means of an input

grid for each constituent. Such an input grid represents the ambient or background concentration of the corresponding constituent as an initial state, while it provides information
along the open boundaries of the computational domain. The use of this information to
impose a boundary condition for constituent depends on the flow direction. At inflow, the
concentration is prescribed using this information delivered by the input grid. At outflow,
the concentration is determined solely by the concentration in upstream part of the domain due to pure advection. It is assumed that the area of interest in which transport
phenomena occur is far away from the open boundaries. The ambient concentration at
open boundaries is therefore supposed to be steady state. However, for unsteady salt intrusion in a tidal inlet, the concentration is prescribed at inflow by means of a so-called
Thatcher-Harleman boundary condition. In this way, a smooth (sinusoidal) transition from
the outflow concentration to the inflow boundary condition can be described; see also command TRANSPORT.
It is advised to make an input grid so large that it completely covers the computational
grid. Otherwise, SWASH assumes that in the region outside the input grid, the constituent
equals to the value at the nearest boundary of the input grid (lateral shift of that boundary).
Finally, both the initial state and boundary conditions of any constituent may be vary in
the vertical direction. This needs to be provided to SWASH with an input grid for each
vertical layer.

2.5.5

Output grids

SWASH can provide output on uniform, rectilinear grids that are independent from the
input grids and from the computational grid. In the computation with an orthogonal
curvilinear computational grid, curvilinear output grids are available in SWASH. An output grid has to be specified by the user with an arbitrary resolution, but it is of course

General description and instructions for use

15

wise to choose a resolution that is fine enough to show relevant spatial details. It must be
pointed out that the information on an output grid is obtained from the computational
grid by bi-linear interpolation (output always at computational time level). This implies
that some inaccuracies are introduced by this interpolation. It also implies that bottom or
wind information on an output plot has been obtained by interpolating twice: once from
the input grid to the computational grid and once from the computational grid to the output grid. If the input, computational and output grids are identical, then no interpolation
errors occur.
In the regions where the output grid does not cover the computational grid, SWASH assumes output values equal to the corresponding exception value. For example, the default
exception value for the surface elevation is 9. The exception values of output quantities
can be changed by means of the QUANTITY command.
Output can be requested at regular intervals starting at a given time always at computational times.

2.6

Boundary conditions

The boundaries of the computational grid in SWASH are either land, beach or water.
SWASH provides the following specification of boundary conditions:
different wavemakers:
Regular waves by means of Fourier series or time series.
Irregular unidirectional waves by means of 1D spectrum. The spectrum may
be obtained from observations or by specifying a parametric shape (PiersonMoskowitz, Jonswap or TMA).
Irregular multidirectional waves by means of 2D spectrum. The spectrum may
be obtained from a SWAN run or by specifying a parametric shape (PiersonMoskowitz, Jonswap or TMA) while the directional spreading can be expressed
with the well-known cosine power or in terms of the directional standard deviation.
absorbing-generating boundary conditions,
velocity or discharge,
Riemann invariants,
full reflection at closed boundaries or solid walls,
Sommerfeld or radiation condition,
sponge layers, and

16

Chapter 2
periodic boundary conditions.

When imposing irregular waves at a boundary segment by means of a spectrum it is assumed that the variation of the depth along the boundary segment is slowly.
SWASH has the option to make a computation that is nested in SWAN. In such a run,
SWASH interpolates the locations, as specified in the SWAN run with POINTS or CURVE,
to the user-defined boundary, either side or segment (see command BOUNDCOND), of the
concerning SWASH run. The SWAN spectra are written to those locations using the
SWAN command SPECOUT. These wave spectra are employed as boundary conditions using the SPECSWAN command. It is assumed that the wave spectra are stationary. Also,
both SWASH and SWAN runs must used the same coordinate system, either Cartesian or
spherical.

2.7

Time and date notation

SWASH employs the following time notation: hhmmss.msc with hh, mm, ss and msc
denoting hours, minutes, seconds and milliseconds, respectively. Alternatively, SWASH
can run for dates
between the years 0 and 9999, if ISO-notation is used in the input (recommended)
or
between the years 1931 and 2030 if two-digit code for years is used (formats 2-6 in
every command that contains moments in time).

2.8

Troubleshooting

Sometimes SWASH produces an error message concerning an instability due to the fact
that the water level is below the bottom level and stops. It is general difficult to find the
cause of this problem. However, some suggestions about possible reasons and what to do
in such cases are given below.
Checking of the input should always be done at first. It is important that dimensions,
model parameters, numerical parameters and boundary conditions are given in a
correct manner. Also, consult Chapter 5, if necessary. In any case, check the PRINT
file.
If all input is correct and the model is supposed to converge then the common measure
is always to reduce the time step (see command COMPUTE). Especially in the case of
a transient or spin up a small time step may be necessary. Since this is the easiest
way to overcome problems, it is always a good practice to start with this measure.
Note that sometimes the maximum Courant number should be decrease as well (see
command TIMEI EXPL [cflhig]).

General description and instructions for use

17

Sometimes instabilities may be due to wiggles in the solution. A possible remedy

is to choose an upwind discretization or even the first order upwinding. Another
improvement might be due to choosing a flux limiter (e.g. minmod).
Sometimes the solution of the Poisson pressure equation can not be found as the
BiCGSTAB solver did not converged. This may happen, for instance, when a considerable number of layers ( 30) is involved. In such a case the choice for the
ILU preconditioner might be a good alternative (see command NONHYDrostatic ...
PRECond ILU).

18

Chapter 2

Chapter 3
Input and output files
3.1

General

SWASH is one single computer program. The names of the files provided by the user should
comply with the rules of file identification of the computer system on which SWASH is
run. In addition: SWASH does not permit file names longer than 36 characters. Moreover, the maximum length of the lines in the input files for SWASH is 120 positions.
The user should provide SWASH with a number of files (input files) with the following
information:
a file containing the instructions of the user to SWASH (the command file),
file(s) containing: grid, bottom, (initial) current and water level, friction, porosity,
and wind and pressure (if relevant) and
file(s) containing boundary conditions.

3.2

Input / output facilities

To assist in making the command file, an edit file is available to the user (see Appendix C).
In its original form this file consists only of comments; all lines begin with exclamation
mark. In the file, all commands as given in this User Manual (Chapter 4) are reproduced
as mnemonics for making the final command file. Hence, the user does not need to consult
the User Manual every time to check the correct spelling of keywords, order of data, etc.
The user is advised to first copy the edit file (the copy file should have a different name)
and then start typing commands between the comment lines of the edit file.
SWASH is fairly flexible with respect to output processing. Output is available for many
different quantities. However, the general rule is that output is produced by SWASH only
at the users request. The instructions of the user to control output are separated into
three categories:
19

20

Chapter 3
Definitions of the geographic location(s) of the output. The output locations may be
either on a grid, or along user specified lines (e.g., a given depth contour line) or at
individual output locations.
Times for which the output is requested.
Type of output quantities (water level, velocity or discharge, pressure, etc.).

3.3

Print file and error messages

SWASH always creates a print file. Usually the name of this file is identical to the name
of the command file of the computations with the extension (.SWS) replaced with (.PRT).
Otherwise, it depends on the batch file that is used by the user. Consult the Implementation
Manual for more information.
The print file contains an echo of the command file, an overview of the actual physical
and numerical parameters to be used in the simulation run, and possibly warning and
error messages. These messages are usually self-explanatory. The print file also contains
computational results if the user so requests (with command BLOCK or TABLE).
IN ANY CASE, ALWAYS CHECK THE PRINT FILE!

Chapter 4
Description of commands
4.1

List of available commands

The following commands are available to users of SWASH (to look for the commands
quickly, see table of contents and index).
Start-up commands
(a) Start-up commands:
PROJECT
SET
MODE
COORD

title of the problem to be computed

sets values of certain general parameters
requests a 1D-mode / 2D-mode of SWASH
to choose between Cartesian and spherical coordinates

Commands for model description

(b) Commands for computational grid:
CGRID
READGRID
VERT

defines dimensions of computational grid

reads an orthogonal curvilinear computational grid
defines vertical grid schematisation

(c) Commands for input fields:

INPGRID
READINP
INPTRAN
READTRA

defines dimensions of e.g. bottom, porosity and friction grids

reads input fields
defines dimensions of grids for transport of constituents
reads stationary input fields of transport constituents

21

22

Chapter 4

(d) Commands for initial and boundary conditions:

INITIAL
BOUND
SPONGE
POROS

specifies an initial flow field and turbulence quantities

specifies the boundary conditions
defines sponge layers
defines porosity layers

(e) Commands for physics:

WIND
FRIC
VISC
VEGET
TRANSP
BRE

specifies wind speed, direction and wind drag

specifies bottom friction
includes horizontal and/or vertical turbulent eddy viscosity
activates wave damping induced by aquatic vegetation
specifies some relevant parameters for transport of constituents
controls wave breaking

(f ) Commands for numerics:

NONHYD
DISCRET
TIMEINT

to choose approximation for nonhydrostatic pressure

to choose space discretization
to choose time integration

Output commands
(g) Commands for output locations:
FRAME
GROUP
CURVE
RAY
ISOLINE
POINTS

defines
defines
defines
defines
defines
defines

an output frame (a regular grid)

an output group (for regular and curvilinear grids)
an output curve
a set of straight output lines (rays)
a depth or bottom contour (for output along that contour)
a set of individual output points

(h) Commands to write or plot output quantities:

QUANTITY
OUTPUT
BLOCK
TABLE

defines properties of output quantities

influence format of block and/or table
requests a block output (geographic distribution)
requests a table output (set of locations)

Description of commands

23

(i) Commands to write or plot intermediate results:

requests an output of intermediate results for testing purposes

TEST

Lock-up commands
(j) Commands to lock-up the input file:
starts a computation
end of users input

COMPUTE
STOP

4.2

Sequence of commands

SWASH executes the above command blocks (a,...,j) in the above sequence except (f), (i)
and (j). The commands of the blocks (f) and (i) may appear anywhere before block (j),
except that TEST POINTS must come after READINP BOTTOM. The commands of block (j)
may appear anywhere in the command file (all commands after COMPUTE are ignored by
SWASH, except STOP). A sequence of commands of block (g) is permitted (all commands
will be executed without overriding). Also a sequence of commands of block (h) is permitted
(all commands will be executed without overriding).
Within the blocks the following sequence is to be used:
In
In
In
In
In
In
In
In
In
In

block
block
block
block
block
block
block
block
block
block

(a)
(b)
(c)
(d)
(e)
(f)
(g)
(h)
(i)
(j)

:
:
:
:
:
:
:
:
:
:

no prescribed sequence in block

READGRID after CGRID, and VERT after CGRID
READINP after INPGRID (repeat both in this sequence for each quantity)
no prescribed sequence in block
no prescribed sequence in block
no prescribed sequence in block
ISOLINE after RAY (ISOLINE and RAY can be repeated independently)
no prescribed sequence in block
no prescribed sequence in block
STOP after COMPUTE

It must be noted that a repetition of a command may override an earlier occurrence of

that command.
Many commands provide the user with the opportunity to choose an option (e.g. discretization scheme) or assign values to coefficients (e.g. bottom friction coefficient). If the
user does not use such option SWASH will use a default value.
Some commands cannot be used in 1D-mode (see individual command descriptions below).

24

Chapter 4

4.3

Command syntax and input / output limitations

The command syntax is given in Appendix B.

Limitations:
The maximum length of the input lines is 120 characters.
The maximum length of the file names is 36 characters.
The maximum number of file names is 99. This can be extended (edit the file
swashinit to change highest unit number of 99 to a higher number).

4.4

Start-up

PROJect name nr
title1
title2
title3
With this required command the user defines a number of strings to identify the SWASH
run (project name e.g., an engineering project) in the print and plot file.
name
nr

title1

title2
title3

is the name of the project, at most 16 characters long.

Default: blanks.
is the run identification (to be provided as a character string; e.g. the run
number) to distinguish this run among other runs for the same project; it is at
most 4 characters long. It is the only required information in this command.
is a string of at most 72 characters provided by the user to appear in the
output of the program for the users convenience.
Default: blanks.
same as title1.
same as title1.

SET [level] [nor] [depmin] [maxmes] [maxerr] [seed]

[grav] [rhowat] [temp] [salinity] [dynvis] [rhoair] [rhosed]

&
&

Description of commands
[cdcap] [prmean] [backvisc] [kappa]
|
CORIolis

NAUTical

25
&

<

> [printf] [prtest] [outlev]

| -> CARTesian |

With this optional command the user assigns values to various general parameters.
[level]
[nor]

[depmin]

[maxmes]

[maxerr]

[seed]

[grav]
[rhowat]

[temp]

still water level (in m).

Default: [level]=0.
direction of North with respect to the xaxis (measured counterclockwise);
default [nor]= 90o , i.e. xaxis of the problem coordinate system
points East.
When spherical coordinates are used (see command COORD) the value
of [nor] may not be modified.
threshold water depth (in m). Any grid point with water depth smaller than
[depmin] is taken out of the computation.
Default: [depmin] = 0.00005.
maximum number of error messages (not necessarily the number of errors!)
during the computation at which the computation is terminated. During the
computational process messages are written to the PRINT file.
Default: [maxmes] = 200.
during pre-processing SWASH checks input data. Depending on the severity
of the errors encountered during this pre-processing, SWASH does not start
computations. The user can influence the error level above which SWASH will
not start computations (at the level indicated the computations will continue).
The error level [maxerr] is coded as follows:
1 : warnings,
2 : errors (possibly automatically repaired or repairable by SWASH),
3 : severe errors.
Default: [maxerr] = 1.
is the seed of the random number generator used to select phase angles
for the different Fourier components. By selecting different seeds different
time series can be obtained from the same wave spectrum (see command
BOUNDCOND).
Default: [seed] = 12345678.
is the gravitational acceleration (in m/s2 ).
Default: [grav] = 9.81.
is the density of water (in kg/m3 ).
Default: [rhowat] = 1000.
Note: this is usually the reference density. The actual density depends on
the temperature and salinity of water.
is the (ambient) temperature of water (in o C).

26

[salinity]
[dynvis]
[rhoair]
[rhosed]
[cdcap]

[prmean]

[backvisc]

[kappa]
CORIOLIS
NAUTICAL

CARTESIAN

[printf]

[prtest]

[outlev]

Chapter 4
Default: [temp] = 14.
is the (ambient) salinity of water (in ppt).
Default: [salinity] = 31.
is the dynamical viscosity of water (in kg/ms).
Default: [dynvis] = 0.001.
is the density of air (in kg/m3 ).
Default: [rhoair] = 1.205.
is the density of sediment (in kg/m3 ).
Default: [rhosed] = 2650.
is the maximum value for the wind drag coefficient. A value of [cdcap] = 99999
means no cutting off the drag coefficient. A suggestion for this parameter is
[cdcap] = 2.5 103 .
Default: [cdcap] = 99999.
is the mean atmospheric pressure (in N/m2 ). This will be used to correct the
water level along the water level boundaries so that it is consistent with the
local atmospheric pressure. A value of [prmean] = 1 means no correction.
Default: [prmean] = 1.
is the background viscosity (in m2 /s). It may be convenient to specify this
ambient viscosity to account for all forms of unresolved vertical mixing.
The value must be small compared to the vertical viscosity calculated by the
standard k model. Experiences suggest a value of 104 to 103 m2 /s.
Default: [backvisc] = 0.
is the Von Karman constant.
Default: [kappa] = 0.4.
indicates that the Coriolis force will be included.
indicates that the Nautical convention for wind and current direction (SWASH
input and output) and for incident wave boundary condition will be used
instead of the default Cartesian convention. For definition, see Section 2.4
or Appendix A.
indicates that the Cartesian convention for wind and current direction (SWASH
input and output) and for incident wave boundary condition will be used.
For definition, see Section 2.4 or Appendix A.
unit reference number of the PRINT file. As default, [printf] is equal to 4. If
it is changed to 6 all print output will be written to the screen. This is useful
if print output is lost due to abnormal end of the program, while information
about the reason is expected to be in the PRINT file.
unit reference number of the test output file. As default, [prtest] is equal to 4.
If it is changed to 6 all test output will be written to the screen. This is
useful if test print output is lost due to abnormal end of the program, while
information about the reason is expected to be in the test output file.
defines the amount of output for iterative solvers.
It is coded as follows:
0 : no output,

27

Description of commands
1 : only fatal errors will be printed,
2 : gives output concerning the iteration process,
3 : additional information about the iteration is printed.
Default: [outlev] = 0.

|
MODE <

|
NONSTationary

|-> TWODimensional |
>

<

>
|

ONEDimensional |

With this optional command the user indicates that the run will be either one-dimensional
(1D-mode, flume) or two-dimensional (2D-mode, basin).
Note that the keyword NONSTATIONARY is obliged.
The default option is NONSTATIONARY TWODIMENSIONAL.

| -> CARTesian
COORDINATES <

| -> CCM
|

SPHErical

<
|

QC

Command to choose between Cartesian and spherical coordinates (see Section 2.4).
CARTESIAN
SPHERICAL

CCM

QC

all locations and distances are in m. Coordinates are given with respect
to x and yaxes chosen by the user in the various commands.
all coordinates of locations and geographical grid sizes are given in degrees;
x is longitude with x = 0 being the Greenwich meridian and x > 0 is East of
this meridian; y is latitude with y > 0 being the Northern hemisphere. Input
and output grids have to be oriented with their xaxis to the East; mesh sizes
are in degrees. All other distances are in meters.
defines the projection method in case of spherical coordinates. CCM means
central conformal Mercator. The horizontal and vertical scales are uniform
in terms of cm/degree over the area shown. In the centre of the scale is
identical to that of the conventional Mercator projection (but only at that
centre). The area in the projection centre is therefore exactly conformal.
the projection method is quasi-cartesian, i.e. the horizontal and vertical scales
are equal to one another in terms of cm/degree.

28

Chapter 4

Note that spherical coordinates can also be used for relatively small areas, say 10 or 20
km horizontal dimension. This may be useful if one obtains the boundary conditions by
nesting in an oceanic model which is naturally formulated in spherical coordinates.
Note that in case of spherical coordinates regular grids must always be oriented E-W, N-S,
i.e. [alpc]=0, [alpinp]=0, [alpfr]=0 (see commands CGRID, INPUT GRID and FRAME,
respectively).

4.5

Model description

4.5.1

Computational grid
| -> REGular [xpc] [ypc] [alpc] [xlenc] [ylenc] [mxc] [myc] |

CGRID <

>
|

CURVilinear [mxc] [myc]

(EXCeption

[xexc]

[yexc])

&

| -> X
REPeating

<
|

With this required command the user defines the geographic location, size, resolution and
orientation of the computational grid in the problem coordinate system (see Section 2.5.2)
in case of a uniform, rectilinear computational grid or an orthogonal curvilinear grid. The
origin of the regular grid and the direction of the positive xaxis of this grid can be chosen
arbitrary by the user.
this option indicates that the computational grid is to be taken as uniform and
rectangular.
CURVILINEAR this option indicates that the computational grid is to be taken as curvilinear.
The user must provide the coordinates of the grid points with command
READGRID COOR.
[xpc]
geographic location of the origin of the computational grid in the problem
coordinate system (xcoordinate, in m). See command COORD.
Default: [xpc] = 0.0 (Cartesian coordinates).
In case of spherical coordinates there is no default, the user must give a value.
[ypc]
geographic location of the origin of the computational grid in the problem
coordinate system (ycoordinate, in m). See command COORD.
Default: [ypc] = 0.0 (Cartesian coordinates).
In case of spherical coordinates there is no default, the user must give a value.
[alpc]
direction of the positive xaxis of the computational grid (in degrees, Cartesian
convention). In 1D-mode, [alpc] should be equal to the direction [alpinp]

REGULAR

29

Description of commands

[xlenc]
[ylenc]
[mxc]

[myc]

EXCEPTION

[xexc]

[yexc]

REPEATING

X
Y

(see command INPGRID).

Default: [alpc] = 0.0.
length of the computational grid in xdirection (in m). In case of spherical
coordinates [xlenc] is in degrees.
length of the computational grid in ydirection (in m). In 1D-mode, [ylenc]
should be 0. In case of spherical coordinates [ylenc] is in degrees.
number of meshes in computational grid in xdirection for a uniform, rectilinear
grid or direction for a curvilinear grid (this number is one less than the
number of grid points in this domain!).
number of meshes in computational grid in ydirection for a uniform, rectilinear
grid or direction for a curvilinear grid (this number is one less than the
number of grid points in this domain!). In 1D-mode, [myc] should be 0.
only available in the case of a curvilinear grid. If certain grid points are to be
ignored during the computation (e.g. land points that remain dry i.e. no
flooding; saving computer time and memory), then this can be indicated by
identifying these grid points in the file containing the grid point coordinates
(see command READGRID). For an alternative, see command INPGRID BOTTOM.
the value which the user uses to indicate that a grid point is to be ignored
in the computations (this value is provided by the user at the location of the
xcoordinate considered in the file of the xcoordinates, see command
READGRID COOR). Required if the option EXCEPTION is used.
Default: [xexc] = 0.0.
the value which the user uses to indicate that a grid point is to be ignored
in the computations (this value is provided by the user at the location of the
ycoordinate considered in the file of the ycoordinates, see command
READGRID COOR). Required if the option EXCEPTION is used.
Default: [yexc] = [xexc].
this option indicates that the grid is repeated in one specific direction.
It means that information leaving at one end of the domain enters at
the opposite end. So, the current or wave field is periodic in one direction
with the length of the domain in that direction.
NOT FOR 1D-MODE.
the computational grid is repeated in xdirection.
This is default.
the computational grid is repeated in ydirection.

For illustration of a regular grid with its dimensions, see Figure 4.1.
READgrid COORdinates [fac] fname [idla] [nhedf] [nhedvec] &
| -> FREe
|

|
|

30

Chapter 4

ypaxis

problem
coordinates

(mxc,myc)

ycaxis
xcaxis

computational grid

(0,myc)

(mxc,0)

ypc

alpc
(0,0)
problem
coordinates

xpc

xpaxis

Figure 4.1: Coordinates of the origin [xpc] and [ypc], the orientation [alpc] and the
grid point numbering of the computational grid with respect to the problem coordinates
system. Note that in case of spherical coordinates the xc and xpaxes both point East.
|
<

| form |
FORmat

|
|
|

<

|
>

| [idfm] |
UNFormatted

>
|
|
|

CANNOT BE USED IN 1D-MODE.

This command READGRID COOR must follow a command CGRID CURV. With this command
(required if the computational grid is orthogonal curvilinear; not allowed in case of a regular grid) the user controls the reading of the coordinates of the computational grid points.
These coordinates must be read from a file as a vector (xcoordinate, ycoordinate of
each single grid point). See command READINP for the description of the options in this
command READGRID. SWASH will check whether all angles in the grid are > 0 and < 180
degrees. If not, it will print an error message giving the coordinates of the grid points
involved. It is recommended to use grids with angles between 45 and 135 degrees.

| M
VERTical [kmax] < [thickness] <

>

Description of commands

31

| -> PERC
With this optional command the user indicates that the run will be in multi-layered mode
and controls the distribution of vertical layers.
[kmax]
[thickness]
M
PERC

number of vertical layers.

layer thickness (in meters or as percentage of water depth).
thickness is given in meters. This layer has a fixed thickness.
thickness is given as percentage. This layer has a variable thickness.
This is default.

Notes:
The layers are numbered from top (=1) to bottom (=[kmax]).
If no [thickness] is given, the layers are distributed equidistantly.
The sum of thicknesses defined as percentages must be 100.
At least one layer with variable thickness must be given.
The layers interfaces are equivalent to the well-known sigma planes, if all the layers
have a variable thickness.
For short wave simulations, it is advised to choose variable thicknesses only, preferably
equidistantly distributed.

4.5.2

Input grids and data

|
|
|
|
|
|
|
|
|
|
|
|

INPgrid

(<

BOTtom
WLEVel
| CURrent
<
| VX
| VY
FRiction
| WInd
<

|
|
|
|
|
|
|
|
|
|
|
|
>)

&

32

Chapter 4
|
|
|
|
|
|
|
|
|
|
|
|

| WX
| WY
PRessure
POROsity
PSIZe
HSTRUCture
NPLAnts

|
|
|
|
|
|
|
|
|
|
|
|

| -> REGular [xpinp] [ypinp] [alpinp] [mxinp] [myinp] [dxinp] [dyinp] |

<

> &
|

CURVilinear
(EXCeption

STAGgered

[excval])

| -> Sec
(NONSTATionary [tbeginp] [deltinp] <
MIn
|
HR
|
DAy

&
|
>

[tendinp])

|
|

OPTION CURVILINEAR NOT FOR 1D-MODE.

With this required command the user defines the geographic location, size and orientation
of an input grid and also the time characteristics of the variable if it is not stationary. If
this is the case (the variable is not stationary), the variable should be given in a sequence
of fields, one for each time step [deltinp]. The actual reading of values of bottom, wind,
pressure, etc. from file is controlled by the command READINP.
This command INPGRID must precede the following command READINP.
There can be different grids for bottom level (BOTTOM), current (CURRENT), bottom friction
coefficient (FRICTION), wind velocity (WIND), atmospheric pressure (PRESSURE), porosity
layers (POROSITY), stone diameters (PSIZE), heights (HSTRUCTURE) of porous structures
and vegetation density (NPLANTS).
If the current velocity components are available on different grids, then option VX, VY can
define these different grids for the x and ycomponent of the current, respectively (but
the grids must have identical orientation). Different grids for VX and VY may be useful if
the data are generated by a circulation model using a staggered grid. The same holds for

Description of commands

33

the wind velocity components, i.e. WX and WY.

In the case of a regular grid (option REGULAR in the INPGRID command) the current and
wind velocity vectors are defined with the x and ycomponent of the current or wind
vector with respect to the xaxis of the input grid. In case of an orthogonal curvilinear
grid (option CURVILINEAR in the INPGRID command) the current and wind velocity vectors
are defined with the x and ycomponent of the current or wind vector with respect to
the xaxis of the problem coordinate system.
Porosity layers can be placed inside the computational domain to simulate reflection and
transmission effects of porous structures such as rubble mound breakwaters and jetties.
Porosity is defined as the volumetric porosity of the structures and its value is in between
0 and 1. A porosity value of 0.45 is typically used for breakwaters. A small value (< 0.1)
should be interpreted as impermeable, like walls and dams. Also structure heights (relative to the bottom) can be specified so that both submerged and emerged breakwaters is
allowed.
If the user specifies an input grid for the atmospheric pressure, then an input grid for
wind must be included as well. Both space varying wind and pressure may be read from a
meteorological file.
For wind velocity, friction coefficient, grain size, height of porous structures and vegetation
density it is also possible to use a constant value over the computational field (see commands WIND, FRICTION, POROSITY and VEGETATION, respectively). No grid definition for
wind, friction, grain size, structure height or vegetation density is then required.
Note that in case of options BOTTOM, POROSITY, PSIZE, HSTRUCTURE and NPLANTS only
stationary input field is allowed.
If land points remain dry during the computation (no flooding!), then these points can
be ignored. In this way, simulation time and internal memory can be saved. This can be
done by indicating bottom level in these points as exception value. See command INPGRID
BOTTOM EXCEPTION. For parallel runs using MPI, an exception value for bottom levels
should be prescribed in order to have a good load-balancing!
Exception value for bottom levels can also be used to take into account dams, screens,
quays or jetties in the domain. In addition, they may represent small obstacles with subgrid dimensions that possibly influence the local flow pattern. In this way, the user can
defined a line of thin dams that separate the flow on both sides.
See Section 2.5.3 for more information on input grids.
BOTTOM
WLEV

defines the input grid of the bottom level. (For the definition of the bottom
level, see command READINP).
defines the input grid of the water level. (For the definition of the water
level, see command READINP).

34
CURRENT
VX
VY
FRICTION
WIND

WX
WY
PRESSURE
POROSITY

PSIZE
HSTRUCTURE
NPLANTS
REGULAR
[xpinp]

[ypinp]

[alpinp]

[mxinp]
[myinp]

Chapter 4
defines the input grid of the current field (same grid for x and ycomponents).
defines the input grid of the xcomponent of the current field (different grid
than ycomponent but same orientation).
defines the input grid of the ycomponent of the current field (different grid
than xcomponent but same orientation).
defines the input grid of the bottom friction coefficient (defined in command
FRICTION, not to be confused with this option FRICTION!).
defines the input grid of the wind velocity field (same grid for x and
ycomponent).
If neither of the commands WIND and READINP WIND is used it is assumed
that there is no wind.
defines the input grid of the xcomponent of the wind velocity field
(different grid than ycomponent but same orientation).
defines the input grid of the ycomponent of the wind velocity field
(different grid than xcomponent but same orientation).
defines the input grid of the atmospheric pressure. (For the definition of
the atmospheric pressure, see command READINP).
defines the input grid of the porosity distribution.
If neither of the commands POROSITY and READINP POROSITY is used it is
assumed that there is no porous structure.
defines the input grid of the grain sizes of porous structures.
defines the input grid of the heights of porous structures.
defines input grid of the horizontally varying vegetation density (defined
in command VEGETATION).
means that the input grid is uniform and rectangular.
geographic location (xcoordinate) of the origin of the input grid in
problem coordinates (in m) if Cartesian coordinates are used or in degrees if
spherical coordinates are use (see command COORD).
Default: [xpinp] = 0. In case of spherical coordinates there is no default, the
user must give a value.
geographic location (ycoordinate) of the origin of the input grid in
problem coordinates (in m) if Cartesian coordinates are used or in degrees if
spherical coordinates are use (see command COORD).
Default: [ypinp] = 0. In case of spherical coordinates there is no default, the
user must give a value.
direction of the positive xaxis of the input grid (in degrees, Cartesian convention).
See command COORD.
Default: [alpinp] = 0.
number of meshes in xdirection of the input grid (this number is one less
than the number of grid points in this direction!).
number of meshes in ydirection of the input grid (this number is one less
than the number of grid points in this direction!).
In 1D-mode, [myinp] should be 0.

Description of commands

35

mesh size in xdirection of the input grid,

in m in case of Cartesian coordinates or
in degrees if spherical coordinates are used, see command COORD.
[dyinp]
mesh size in ydirection of the input grid,
in m in case of Cartesian coordinates or
in degrees if spherical coordinates are used, see command COORD.
In 1D-mode, [dyinp] may have any value.
Default: [dyinp] = [dxinp].
CURVILINEAR means that the input grid is curvilinear; this option is available only if the
computational grid is curvilinear as well. The input grid is identical
to the computational grid.
NOT FOR 1D-MODE.
STAGGERED
means that the input grid of a grid-oriented (not Cartesian!) velocity
component u or v is staggered in y or xdirection, respectively.
The velocity components are given in their points of definition according
to the Arakawa C-grid staggering.
NOT FOR 1D-MODE.
EXCEPTION
certain points inside the given grid that are to be ignored during the
computation can be identified by means of an exception value as given in
the corresponding input file as controlled by the command READINP.
NOT FOR 1D-MODE.
[excval]
exception value; required if the option EXCEPTION is used.
Note: if [fac] 6= 1 (see command READINP), [excval] must be given as
[fac] times the exception value.
NONSTATION the variable is nonstationary (given in a time sequence of fields).
NOT FOR 1D-MODE.
[tbeginp]
begin time of the first field of the variable, the format is:
1 : ISO-notation
19870530.153000
2 : (as in HP compiler)
30May87 15:30:00
3 : (as in Lahey compiler) 05/30/87.15:30:00
4 :
15:30:00
5 :
87/05/30 15:30:00
6 : as in WAM
8705301530
7 :
153000.000
This format is installation dependent. See Implementation Manual or ask the
person who installed SWASH on your computer. Default is option 7.
[deltinp]
time interval between fields, the unit is indicated in the next option:
SEC
unit seconds
MIN
unit minutes
HR
unit hours
DAY
unit days
[tendinp]
end time of the last field of the variable, the format is:
1 : ISO-notation
19870530.153000
[dxinp]

36

Chapter 4
2 : (as in HP compiler)
30May87 15:30:00
3 : (as in Lahey compiler) 05/30/87.15:30:00
4 :
15:30:00
5 :
87/05/30 15:30:00
6 : as in WAM
8705301530
7 :
153000.000
This format is installation dependent. See Implementation Manual or ask the
person who installed SWASH on your computer. Default is option 7.

|
|
|
|
|
|
|
|
READinp

<

BOTtom
WLEVel
CURrent
FRiction

|
|
|
|
|
|
|
|

WInd
|
|
|
|
|
|
|
|
|
|

PRessure
POROsity
PSIZe
HSTRUCture
NPLAnts

>
|
|
|
|
|
|
|
|
|
|

[fac]

fname1

SERIes

<

>

[nhedf] ([nhedt]) ([nhedvec])

fname2

[idla]

&

| -> FREe
|
|
| form |
<
FORmat
<
>
|
| [idfm] |
|
|
UNFormatted

With this required command the user controls the reading of values of the indicated variables from file. This command READINP must follow a command INPGRID.

|
|
|
>
|
|
|

Description of commands

37

If the variables are in one file, then the READINP commands should be given in the same
sequence as the sequence in which the variables appear in the file.
BOTTOM

WLEV

CURRENT

FRICTION

WIND

PRESSURE
POROSITY

PSIZE

HSTRUCTURE

NPLANTS

with this option the user indicates that bottom levels (in m) are to be read from
file (bottom level positive downward relative to an arbitrary horizontal datum
level). The sign of the input can be changed with option [fac] = 1. (see below).
with this option the user indicates that water levels (in m) are to be read from
file (water level positive upward relative to the same datum level as used in
option BOTTOM). Sign of input can be changed with option [fac] = 1. If the
water level is constant in space and time, the user can use the command SET
to add this (still) water level to the still water depth.
rectilinear (curvilinear) input grid: with this option the user indicates that
the x and ycomponent ( and component) (in m/s) are to be read from
one and the same file (with one READINP command). With this option SWASH
reads first all xcomponents (components), and then all ycomponents
(components) (see below). The first component (x or component) is
always eastward oriented and the second one (y or component) is always
northward oriented. The components and are taken along the directions of
the grid lines of the curvilinear grid!
with this option the user indicates that friction coefficient is to be read from
file for Manning or Chezy formulas or Nikuradse roughness height. If the
coefficients are constant in space and time: see command FRICTION.
rectilinear (curvilinear) input grid: with this option the user indicates that
the x and ycomponent ( and component) (in m/s) are to be read from
one and the same file (with one READINP command). With this option SWASH
reads first all xcomponents (components), and then all ycomponent
(components) (see below). The components and are taken along the
directions of the grid lines of the curvilinear grid! If the wind is constant, see
command WIND.
with this option the user indicates that atmospheric pressures (in N/m2 ) are
to be read from file. Unit can be changed with option [fac] (see below).
with this option the user indicates that volumetric porosity is to be read from
file. Porosity values less than 1 indicates the location of porous structures. A
value of 1 represents water points. Regions with small porosity values (< 0.1)
should be treated as impermeable regions, i.e. land points.
with this option the user indicates that grain sizes (in m) of porous structures
are to be read from file. If the grain size is constant for all porous structures
then see command POROSITY for specification.
with this option the user indicates that heights (in m) of porous structures
(relative to the bed level) are to be read from file. If the height is constant
for all porous structures then see command POROSITY for specification.
with this option the user indicates that horizontally varying vegetation
density (per m2 ) is to be read from file. If the density is constant then

38

[fac]

fname1
SERIES

fname2

[idla]

Chapter 4
see command VEGETATION for specifcation.
SWASH multiplies all values that are read from file with [fac]. For instance
if the bottom levels are given in unit decimeter, one should make [fac]=0.1 to
obtain levels in m. To change sign of bottom level use a negative value of [fac].
Note that [fac] = 0 is not allowed!
Default: [fac]=1.
name of the file with the values of the variable.
with this option (only for MODE NONSTATIONARY) the user indicates that the
names of the files containing the nonstationary variable(s) are located in a
separate file with name fname2 (see below).
name of file that contains the names of the files where the variables
are given. These names are to be given in proper time sequence. SWASH reads
the next file when the previous file end has been encountered. In these files the
input should be given in the same format as in the above file fname1 (that
implies that a file should start with the start of an input time step).
prescribes the order in which the values of bottom levels and other fields
should be given in the file.
=1: SWASH reads the map from left to right starting in the upper-left-hand
corner of the map (it is assumed that the xaxis of the grid is pointing
to the right and the yaxis upwards). A new line in the map should
start on a new line in the file. The lay-out is as follows:
1,myc+1
1,myc
...
1,1

2,myc+1
2,myc
...
2,1

...
...
...
...

mxc+1, myc+1
mxc+1, myc
...
mxc+1, 1

=2: as [idla]=1 but a new line in the map need not start on a new line in
the file.
=3: SWASH reads the map from left to right starting in the lower-left-hand
corner of the map. A new line in the map should start on a new line in
the file. The lay-out is as follows:
1,1
1,2
...
1,myc+1

2,1
2,2
...
2,myc+1

...
...
...
...

mxc+1, 1
mxc+1, 2
...
mxc+1, myc+1

=4: as [idla]=3 but a new line in the map need not start on a new line
in the file.
=5: SWASH reads the map from top to bottom starting in the lower-left-hand
corner of the map. A new column in the map should start on a new line in
the file. The lay-out is as follows:

39

Description of commands

1,1
2,1
...
mxc+1,1

[nhedf]

[nhedt]

[nhedvec]

FREE

FORMAT

form
[idfm]

1,2
2,2
...
mxc+1,2

...
...
...
...

1, myc+1
2, myc+1
...
mxc+1, myc+1

=6: as [idla]=5 but a new column in the map need not start on a new line
in the file.
Default: [idla]=1.
is the number of header lines at the start of the file. The text in the header
lines is reproduced in the PRINT file created by SWASH (see Section 3.3). The
file may start with more header lines than [nhedf] because the start of the
file is often also the start of a time step and possibly also of a vector
variable (each having header lines, see below, [nhedt] and [nhedvec]).
Default: [nhedf]=0.
only if variable is time dependent: number of header lines in the file at the
start of each time level. A time step may start with more header lines than
[nhedt] because the variable may be a vector variable which has its own header
lines (see below [nhedvec]).
Default: [nhedt]=0.
for each vector variable: number of header lines in the file at the start of
each component (e.g., x or ycomponent).
Default: [nhedvec]=0.
With this option the user indicates that the values are to be read with free
format. Free format is a standard of the computer programming language
FORTRAN. The free format conventions in reading from a file are almost the
same as the conventions for the command syntax given elsewhere in this manual;
the most important differences are:
1. There are no continuation marks, reading continues until the required
number of data has been read, or until a slash (/) is encountered.
2. Input lines can be longer than 80 characters (depending on the operating
system of the computer).
3. Comment is not allowed.
With free format empty fields, repetition factors, and closure of a line by a slash,
can be used.
with this option the user indicates that fixed format (FORTRAN convention) is
to be used when reading the values from file. The format can be defined in one
of two ways, by giving the format number [idfm] or the format string form.
a userspecified format string according to Fortran convention, e.g.
(10X,12F5.0).
this format number is interpreted as follows:
=1: Format according to BODKAR convention (a standard of the Ministry
of Transport and Public Works in the Netherlands).

40

Chapter 4

Format string: (10X,12F5.0).

=5: Format (16F5.0), i.e. an input line consists of 16 fields of 5 places each.
=6: Format (12F6.0), i.e. an input line consists of 12 fields of 6 places each.
=8: Format (10F8.0), i.e. an input line consists of 10 fields of 8 places each.
UNFORMATTED is a form of reading without conversion (binary files). Not recommended for
ordinary use.
If the file does not contain a sufficient number of data (i.e. less than the number of grid
points of the input grid), SWASH will write an error message to the PRINT file, and if
[itest]>0 (see command TEST) it will reproduce the data in the PRINT file, using the
lay-out according to [idla]=1. This echo of the data to print file is also made if the
READINP command is embedded between two TEST commands in the command file as
follows:
TEST 120
READINP ....
TEST 0

INPtrans

| SALinity
|
< TEMPerature
|
| SEDiment

|
|
>

&

|
|

| -> REGular [xpinp] [ypinp] [alpinp] [mxinp] [myinp] [dxinp] [dyinp] |

<

> &
|

CURVilinear
(EXCeption

[excval])

(NONUNIForm

[kmax])

OPTION CURVILINEAR NOT FOR 1D-MODE.

With this command the user defines the geographic location, size and orientation of a
stationary input grid for the transport of constituent. This input grid thus supplies initial
and stationary boundary conditions for the considered constituent. The actual reading of
constituent values from file is controlled by the command READTRANS.
This command INPTRANS must precede the following command READTRANS.
There can be different grids for salinity (SALINITY), temperature or heat (TEMPERATURE)

&

41

Description of commands
and suspended sediment load (SEDIMENT).
See command INPGRID for the description of the options in this command INPTRANS.
See Section 2.5.4 for more information on (input) grids for transport of constituents.

the constituent is nonuniform in vertical.

the number of layers representing the number of input fields as given in
a sequence (see command READTRANS). This number must be equal to the
number of vertical layers in multi-layered mode (see command VERTICAL)
or 1 (i.e. uniform in vertical).
Default: [kmax] = 1.

NONUNIFORM
[kmax]

|
|
READtrans

<

SALinity

|
|

TEMPerature
|
|

SEDiment

| fname1
>

[fac]

|
|

>
| LAYers

[nhedf]

<

[idla]

&

fname2 |

| -> FREe
|
|
<
FORmat
|
|
|
UNFormatted

| form |
<
>
| [idfm] |

|
|
|
>
|
|
|

With this command the user controls the reading of initial and boundary values of transport constituents from file. This command READTRANS must follow a command INPTRANS.
The constituents that can be read are salinity (SALINITY) (in ppt, psu or kg/m3 ), temperature (TEMPERATURE) (in o C) and suspended sediment load (SEDIMENT) (in kg/m3 ).
See command READINP for the description of the options in this command READTRANS.
LAYERS

fname2

with this option (only for multi-layered mode) the user indicates that the
names of the files containing the nonuniform constituent are resided in a
separate file with name fname2 (see below).
name of file that contains the names of the files where the constituents
are given. These names are to be given in proper sequence, i.e. from top
(first layer) to bottom (last layer). SWASH reads the next file when the
previous file end has been encountered. In these files the input should be

42

Chapter 4
given in the same format as in the above file fname1.

4.5.3

INITial

Initial and boundary conditions

| -> CONstant [wlev] [vx] [vy] [tke] [epsilon]
|
<
ZERO
|
| STEAdy

This command can be used to specify the initial values for flow variables.
CONSTANT
[wlev]
[vx]
[vy]
[tke]
[epsilon]
ZERO
STEADY

the initial flow and turbulence quantities are set to a constant.

the water level.
the ucomponent of velocity.
the vcomponent of velocity.
the turbulent kinetic energy.
the dissipation rate of turbulent kinetic energy.
Both the initial water level and velocity components are set to zero.
If this option is specified, the initial velocities will be derived from
the water levels using the Chezy formula for steady flow. This can
shorten the spin-up time of the SWASH run and can be meaningful
in the case of quasi-steady flow condition (e.g. flow in a river).

|
|
BOUnd SHAPespec

<

PM

|
|

-> JONswap
|
|

DSPR

[gamma]

>
|
|

TMA
| -> POWer

<

| -> SIG |
<

>
|

RMS |

| -> PEAK

<

>
MEAN

>
DEGRees

This command BOUND SHAPESPEC defines the shape of the spectra (both in frequency and
direction) at the boundary of the computational grid in case of parametric spectral input
(see command BOUNDCOND).

&

43

Description of commands

Pierson-Moskowitz spectrum will be used.

JONSWAP spectrum will be used. This is default.
peak enhancement parameter of the JONSWAP spectrum.
Default: [gamma]=3.3.
A modified JONSWAP spectrum for finite depth will be used.
The significant wave height (for definition, see Appendix A) is used as
the characteristic wave height.
This is default.
The RMS wave height (for definition, see Appendix A) is used as
the characteristic wave height.
The peak period is used as the characteristic wave period.
This is default.
Tm01 (for definition, see Appendix A) is used as the characteristic wave period.
option for expressing the width of the directional distribution; the distribution
function itself is cosm ().
the directional width is expressed with the power m itself.
This option is default.
the directional width is expressed in terms of the directional standard deviation
of the cosm () distribution (for definition, see Appendix A).

PM
JONSWAP
[gamma]
TMA
SIG

RMS
PEAK
MEAN
DSPR
POWER
DEGREES

If this command is not used, the JONSWAP option will be used by SWASH with [gamma]=3.3
and POWER for the directional width.

|
|
|
|

| -> SIDE
|
|
|
|

North
NW
West
SW
< South
| SE
| East
| NE

|
|
|
|

| -> CCW

| CLOCKWise

> <
|
|
|

>

|
|
|
|
|

BOUndcond <

>
|
|
|
|

| -> XY
SEGMent

<

[x]

[y]

>

|
|
|

<

>
|

IJ

<

[i]

[j]

>

&

44

Chapter 4
BTYPe WLEV|VEL|DISCH|RIEMann|WEAKrefl|SOMMerfeld|OUTFlow

&

LAYer [k] | HYPerbolic | LOGarithmic

&

SMOOthing [period] SEC|MIN|HR|DAY

&

ADDBoundwave

&

| FOURier
| REGular
| CONstant < SPECTrum
|
| SERIes
|
| SPECFile

[azero] < [ampl] [omega] [phase] >

[h] [per] [dir]
[h] [per] [dir] [dd] [cycle] SEC|MIN|HR|DAY
fname [itmopt]
fname [cycle] SEC|MIN|HR|DAY

<

&
|
|
|
|
|
|
| VARiable <
|
|

FOURier
REGular
SPECTrum
SERIes
SPECFile
SPECSwan

< [len]
< [len]
< [len]
< [len]
< [len]
fname

[azero] < [ampl] [omega] [phase] > >

[h] [per] [dir] >
[h] [per] [dir] [dd] [cycle] S|MI|HR|DA >
fname [itmopt] >
fname [cycle] SEC|MIN|HR|DAY >
[cycle] SEC|MIN|HR|DAY

This command BOUNDCOND defines a boundary condition at the boundary. It consists of two
parts, the first part defines the boundary side or segment where the boundary condition
will be given, the second part defines the parameters.
There are two ways to define the part of the boundary at which the boundary condition is
imposed. The first (SIDE) is easiest if the boundary is one full side of the computational
grid, although it should not be used for curvilinear grids. The second (SEGMENT) can be
used if the boundary segment goes around the corner of the grid, or if the segment is only
part of one side of the grid.
This BOUNDCOND command can be given a number of times, i.e. to define boundary conditions on various sides or segments of the boundary. One BOUNDCOND command can be used
for only one side or one contiguous segment.
SIDE

NORTH, ...

the boundary is one full side of the computational grid (in 1D cases either
of the two ends of the 1D grid).
SHOULD NOT BE USED IN CASE OF CURVILINEAR GRIDS!
indicates on which side the boundary condition is applied. N means the
boundary is the north edge (if present) of the computational area, likewise
for W is west, S is south, E is east, NW is northwest, NE is northeast,
SW is southwest and SE is southeast. The side does not have to face exactly
the given direction (the nearest direction of the normal to the side is taken;

Description of commands

CCW,
CLOCKWISE
SEGMENT

XY

[x], [y]
IJ

[i], [j]

BTYPE
WLEV
VEL
DISCH
RIEMANN

WEAKREFL

45

this direction is determined as the normal to the sum of the vectors joining
the grid points on the boundary; there is an interruption in the boundary
(due to the occurrence of exception values) then this interruption is ignored
in the summation).
Note: in case of Cartesian coordinates, the direction of the problem coordinate
system must be defined by the user (see the SET ...[north] command), by
default the positive xaxis points East.
see description of [len] below; these option are only effective if the
option VARIABLE is used (see below).
is used if SIDE is not used, i.e. either the boundary segment goes
around a corner of the grid, or the segment is only part of one side of the
grid. The distance along the segment (see [len] below) is measured
from the first point of the segment (see XY or IJ).
the segment is defined by means of a series of points in terms of problem
coordinates; these points do not have to coincide with grid points. The
(straight) line connecting two points must be close to grid lines of the
computational grid (the maximum distance is one hundredth of the length of
the straight line).
This option is default.
problem coordinates of a point of the boundary segment (see command COORD).
the segment is defined by means of a series of computational grid points
given in terms of grid indices; not all grid points on the segment have to be
mentioned. If two points are on the same grid line, intermediate points are
assumed to be on the segment as well.
grid indices of a point of the segment. Values of [i] range from 1 to [mxc]+1
and values of [j] from 1 and [myc]+1 ([mxc] and [myc] as defined in the
command CGRID).
with this option the type of boundary condition is given.
water level is imposed.
Required further specification by means of Fourier series or time series.
velocity normal to the boundary is imposed.
Required further specification by means of Fourier series or time series.
discharge per unit width normal to the boundary is imposed.
Required further specification by means of Fourier series
or time series.
Riemann invariant is imposed. It is defined as u 2 gh with
u the velocity normal to the boundary and h the water depth.
The sign depends on the location of the boundary. The plus sign refers
to an inflow velocity at the western/left and southern/lower boundaries,
and the minus sign refers to inflow velocity at the eastern/right and
northern/upper boundary.
Required further specification by means of Fourier series or time series.
the boundary condition is weakly reflective.
Required further specification by means of Fourier series or time series

46

Chapter 4

of water level, or regular or irregular waves by means of a spectrum.

SOMMERFELD Sommerfeld radiation condition is imposed.
No further specification is needed.
OUTFLOW
water depth is aligned to bottom level (for supercritical flow only).
No further specification is needed.
LAYER
indicates a layer where the boundary condition is given.
[k]
layer index (1 [k] [kmax]).
HYPERBOLIC the vertical hyperbolic cosine profile for velocity at the boundary is assumed.
LOGARITHMIC the vertical logarithmic profile for velocity at the boundary is assumed.
SMOOTHING
with this option a ramp function is applied to start up the simulation smoothly.
[period]
the smoothing period of which the unit is indicated in the next option:
SEC
unit seconds
MIN
unit minutes
HR
unit hours
DAY
unit days
ADDBOUNDWAV with this option second order bound long wave is added to the first order,
irregular waves.
CONSTANT
with this option the boundary condition is constant along the side or segment.
FOURIER
the Fourier series is defined by means of the following parameters:
[azero]
the amplitude for zero frequency is given (in m).
[ampl]
the amplitudes for a number of components are given (in m).
[omega]
the angular frequencies for a number of components are given (in rad s1 ).
[phase]
the phase for a number of components are given (in degrees).
REGULAR
monochromatic, long-crested wave is defined with the following parameters:
[h]
the wave height (in m).
[per]
the wave period (in s).
[dir]
the wave direction (in degrees; Cartesian or Nautical convention, see
command SET).
Default: no specification of [dir] means incident direction is perpendicular
to the boundary (only in case of rectilinear grid).
SPECTRUM
the wave spectrum is defined by means of the following spectral parameters
(see command BOUND SHAPE for spectral shape):
[h]
the characteristic wave height (in m).
[h]
is the value of the significant wave height, if option SIG was chosen
in command BOUND SHAPE or
[h]
is the value of the RMS wave height, if option RMS was chosen
in command BOUND SHAPE.
[per]
the characteristic wave period (in s).
[per] is the value of the peak period, if option PEAK was chosen
in command BOUND SHAPE or
[per] is the value of the mean period Tm01 , if option MEAN was chosen
in command BOUND SHAPE.
[dir]
the peak wave direction (in degrees; Cartesian or Nautical convention, see

Description of commands

[dd]

[cycle]

SERIES

command SET).
Default: no specification of [dir] means incident direction is perpendicular
to the boundary (only in case of rectilinear grid).
coefficient of directional spreading; a cosm () distribution is assumed.
[dd] is interpreted as the directional standard deviation in degrees,
if the option DEGREES is chosen in the command BOUND SHAPE.
[dd] is interpreted as the power m, if the option POWER is chosen
in the command BOUND SHAPE.
Default: [dd] = 0., i.e. no directional spreading.
the cyclic period of the time series of surface elevation to be synthesized.
This may correspond to the time period over which surface elevation is
outputted after steady-state condition has been established. The
corresponding unit is indicated in the next option:
SEC
unit seconds
MIN
unit minutes
HR
unit hours
DAY
unit days
the time series is given in a file.
This file is for only one location; it has a number of lines which each contain
2 numbers, i.e.: time, quantity. The notation of time is indicated by [itmopt]
(see below). However, if time is represented as a real number in seconds, then
do not specify [itmopt]. The quantity depends on the type of boundary
condition (see command BTYPE).
Example of such a file containing surface elevation in meters ([itmopt] = 7):
000000.000
000001.000
000002.000
000003.000
000004.000
000005.000
000006.000
000007.000

fname
[itmopt]

47

0.0000000E+00
4.2307975E-08
1.6923190E-07
3.8077177E-07
6.7692758E-07
1.0576993E-06
1.5230870E-06
2.0730906E-06

name of the file containing the time series.

time coding option. The following format can be employed:
1 : ISO-notation
19870530.153000
2 : (as in HP compiler)
30May87 15:30:00
3 : (as in Lahey compiler) 05/30/87.15:30:00
4 :
15:30:00
5 :
87/05/30 15:30:00
6 : as in WAM
8705301530
7 :
153000.000

48

SPECFILE

Chapter 4
Default: no specification of [itmopt] means time is represented as
a real number in seconds.
the wave spectrum is given in a file. There are two types of files:

files containing 1D or non-directional wave spectrum

(usually from measurements), and

files containing 2D or directional wave spectrum

(possibly from a SWAN run).
A file containing the 1D wave spectrum is for only one location; it has
the string SPEC1D on the first line of the file and a number of lines which
each contain 2 numbers, i.e.: frequency in Hz, variance density in m2 /Hz.
Example of such a file:
SPEC1D
3.8602E-03
5.7903E-03
7.7204E-03
9.6505E-03
1.1581E-02
1.3511E-02
1.5441E-02
1.7371E-02

fname
[cycle]

VARIABLE

[len]

5.2168E-01
1.0230E+00
1.4567E+00
1.7232E+00
1.8832E+00
1.7570E+00
1.3429E+00
9.8666E-01

The structure of the files containing directional spectrum is described in

Appendix D of the SWAN User Manual. These files may only contain
stationary wave spectra, and can be used for one location only.
name of the file containing the wave spectrum.
the cyclic period of the time series of surface elevation to be synthesized.
This may correspond to the time period over which surface elevation is
outputted after steady-state condition has been established. The
corresponding unit is indicated in the next option:
SEC
unit seconds
MIN
unit minutes
HR
unit hours
DAY
unit days
with this option the boundary condition can vary along the side or segment.
The boundary condition is prescribed at a number of points of the side or
segment, these points are characterized by their distance from the begin
point of the side or segment.
is the distance from the first point of the side or segment to the point along
the side or segment for which the incident wave spectrum is prescribed.
Note: these points do no have to coincide with grid points of the computational
grid. [len] is the distance in m or degrees in the case of spherical
coordinates, not in grid steps. The values of [len] should be given

Description of commands

SPECSWAN

fname
[cycle]

49

in ascending order. The length along a SIDE is measured in clockwise or

counterclockwise direction, depending on the options CCW or CLOCKWISE (see
above). The option CCW is default. In case of a SEGMENT the length is
measured from the indicated begin point of the segment.
the wave spectra are given in a file and are obtained from a SWAN run. The
structure of this file is described in Appendix D of the SWAN User Manual.
This file must contain more than 1 stationary wave spectrum, either 1D or 2D.
The coordinates of the locations will be taken into account and SWASH will
interpolate the spectra to the given boundary side or segment. The coordinate
system of the SWAN run must be the same as the one used by the current
SWASH run. See also Section 2.6.
CANNOT BE USED IN 1D-MODE.
name of the file containing the wave spectra.
the cyclic period of the time series of surface elevation to be synthesized.
This may correspond to the time period over which surface elevation is
outputted after steady-state condition has been established. The
corresponding unit is indicated in the next option:
SEC
unit seconds
MIN
unit minutes
HR
unit hours
DAY
unit days

Note that by specifying regular or irregular waves at the boundary, the vertical hyperbolic
cosine velocity profile is assumed. Hence, no type of boundary condition should be specified, except BTYPE WEAKREFL if a weakly reflective boundary is assumed.

| North
|
| West

|
|
|

| South
|
| East

|
|
|

SPONgelayer <

>

[width]

This command can be used to specify the sponge layers around the computational domain.
Sponge layers are very effective in absorbing wave energy at open boundaries where waves
are supposed to leave the computational domain freely. So, they prevent reflections at
open boundaries. A sponge layer may have a width of 3 to 5 typical wave lengths.

50

Chapter 4

Note that by including a sponge layer of [width] meters, the computational domain needs
to be extended with [width] meters as well (see command CGRID).
NORTH
WEST
SOUTH
EAST
[width]

sponge layer is placed at the north edge of the domain.

sponge layer is placed at the west edge of the domain.
sponge layer is placed at the south edge of the domain.
sponge layer is placed at the east edge of the domain.
the width of sponge layer in meters.

POROsity [size] [height] [alpha0] [beta0]

This command indicates the use of porosity layers inside the computational domain to
simulate full/partial reflection and transmission through porous structures such as breakwaters, quays and jetties. See commands INPGRID POROSITY and READINP POROSITY in
order to define porosity layers. If neither of this command nor the command READINP
POROSITY is used, SWASH will not account for both reflection and transmission effects.
[size]

[height]

[alpha0]

[beta0]

4.5.4

characteristic grain size of porous structure(s) (in m).

Note that [size] is allowed to vary over the computational region; in that
case use the commands INPGRID PSIZE and READINP PSIZE to define and
read the grain sizes of different porous structures. The value of [size] in
this command is then not required (it will be ignored).
structure height (relative to the bottom in meters). Both submerged and
emerged porous structures can be defined in this way. An emerged structure
is the default.
Default: [height] = 99999.
Note that [height] is allowed to vary over the computational region; in that
case use the commands INPGRID HSTRUC and READINP HSTRUC to define and
read the structure heights of different structures. The value of [height] in
this command is then not required (it will be ignored).
particle-form constant for laminar friction loss.
Note: 780 [alpha0] 1500.
Default: [alpha0] = 1000.
particle-form constant for turbulent friction loss.
Note: 1.8 [beta0] 3.6.
Default: [beta0] = 2.8.

Physics

Description of commands

WIND

51

| -> CONstant [cd]

|
|
|
|
CHARNock [beta] [height]
|
|
|
|
LINear [a1] [a2] [b] [wlow] [whigh] |
|
|
[vel] [dir] <
WU
> REL [alpha]
|
|
|
GARRatt
|
|
|
|
SMIthbanke
|
|
|
|
FIT
|

With this optional command the user can specify wind speed, direction and wind drag.
Wind speed and direction are assumed constant. If this command is not used, SWASH
will not account for wind effect.
This command is usually meant for large-scale wind driven circulation, tides and storm
surges. Inclusion of wind effects may also be beneficial to buoyancy driven flows in coastal
seas, estuaries and lakes. However, this option should not be used for applications
concerning short wave propagation, such as wave transformation in coastal waters,
ports and harbours.
In SWASH seven different wind drag formulation are available, i.e., constant, linear on
wind speed, Charnock, Wu, Garratt, Smith and Banke and the second order polynomial
fit. The Charnock drag formulation is based on an implicit relationship between the wind
and the roughness, while the other formulations, those of Wu, Garratt and Smith and
Banke, express a linear relationship between the drag and the wind speed.
Recent observations indicate that these linear parameterizations overestimate the drag coefficient at high wind speeds (U10 > 20 m/s, say). Based on many authoritative studies it
appears that the drag coefficient increases almost linearly with wind speed up to approximately 20 m/s, then levels off and decreases again at about 35 m/s to rather low values
at 60 m/s wind speed. We fitted a 2nd order polynomial to the data obtained from these
studies, and this fit is given by
Cd = (0.55 + 2.97U 1.49U 2 ) 103
where U = U10 /Uref , and the reference wind speed Uref = 31.5 m/s is the speed at which
the drag attains its maximum value in this expression. These drag values are lower than
in the expression of Wu (1982) by 10% 30% for high wind speeds (15 U10 30 m/s)
and over 30% for hurricane wind speeds (U10 > 30 m/s).

52

Chapter 4

Usually, the wind stress depends on the drag and the wind speed at a height of 10 m,
U10 . However, it might be obvious that the influence of wind stress will reduce if the
water is flowing in the same direction and it will decrease when the water flow and wind
are in opposite directions. This may lead to a smaller wind setup on very shallow areas.
Hence, the wind stress may be dependent on the wind velocity relative to the water,
i.e. U10 u, instead of the wind velocity as such. Here, u is either the depth-averaged
flow velocity in the depth-averaged mode or the surface flow velocity in the multi-layered
mode. Experiments have shown that the eigenfrequencies damp out much faster when this
alternative is employed.
The considered wind is at 10 m above the surface. However, it might be better to consider
the wind at the surface in order to relate this wind to the flow velocity. A factor
(0 < 1) is introduced that take into account the difference between the wind velocity
at 10 m height and the wind velocity at the surface, Us = U10 . With the use of in this
formulation the influence of the flow velocity becomes even stronger. However, the exact
value of is yet unknown; further research on this parameter is needed. Therefore, this
parameter is optionally and should be used with care.
The default option is a constant wind drag coefficient, while the wind stress is related to
the wind velocity at 10 m height only.
[vel]
[dir]
CONSTANT
[cd]
CHARNOCK
[beta]
[height]
LINEAR

[a1]
[a2]
[b]
[wlow]
[whigh]
WU
GARRATT

wind velocity at 10 m height (in m/s).

wind direction at 10 m height (in degrees; Cartesian or Nautical
convention, see command SET).
this option indicates that a constant drag coefficient will be adopted.
dimensionless coefficient.
Default: [cd] = 0.002.
indicates that the Charnock drag formulation will be adopted.
dimensionless Charnock coefficient.
Default: [beta] = 0.032.
height (in m) above the free surface where the wind speed has been measured.
Default: [height] = 10.
indicates that the wind drag depends linearly on wind speed.
For this, both lower and upper bounds of the wind speed, [wlow], [whigh],
and two coefficients, [a1], [b], need to be specified as follows:
cd = 0.001 ( [a1] + [b] U10 ), with cd the drag coefficient and U10 the wind
speed in between [wlow] and [whigh].
coefficient in the above linear function.
not used.
coefficient in the above linear function.
lower bound of wind speed.
upper bound of wind speed.
indicates that the drag formulation of Wu will be adopted.
indicates that the drag formulation of Garratt will be adopted.

Description of commands

53

indicates that the drag formulation of Smith and Banke will be adopted.
drag coefficient is based on the 2nd order polynomial fit.
indicates that the wind stress depends on the wind velocity relative to the water.
parameter to relate the wind velocity at 10 m height to wind velocity at surface.
Note: 0 < [alpha] 1.
Default: [alpha] = 1.

SMITHBANKE
FIT
RELATIVE
[alpha]

The quantities [vel] and [dir] are required if this command is used except when the
command READINP WIND is specified.

|
|
|
|
FRICtion

<

CONstant [cf]
CHEZy [cf]
-> MANNing [cf]

|
|
|

| -> SMOOTH
LOGlaw <
|

ROUGHness [h]

With this optional command the user can activate bottom friction. If this command is not
used, SWASH will not account for bottom friction.
For typically depth-averaged calculations, three different bottom friction values are available, i.e., constant, Chezy and Manning values. Although they are associated with depthaveraged flow velocities, they may be applied in the multi-layered mode as well. However,
some inaccuracies may occur in the vertical structure of the velocity, in particular when the
depth-averaged velocity is zero. Alternatively, the logarithmic wall law may be applied. In
this case, a distinction is made between smooth and rough beds. For rough beds, the user
must apply a Nikuradse roughness height.
The aforementioned friction formulations are usually derived for quasi-steady flow condition (e.g. flow in a river). However, numerical experiments have indicated that the
Manning formula provides a good representation of wave dynamics in the surf zone, and
even better to that returned by other friction formulations.
The default option is: MANNING with a constant friction coefficient.
CONSTANT
[cf]

this option indicates that a dimensionless friction coefficient will be adopted.

dimensionless coefficient.

54

CHEZY
[cf]

MANNING
[cf]

LOGLAW
SMOOTH

ROUGHNESS

[h]

Chapter 4
Default: [cf] = 0.002.
Note that [cf] is allowed to vary over the computational region; in that
case use the commands INPGRID FRICTION and READINP FRICTION to
define and read the friction data. The command FRICTION is still required
to define the type of friction expression. The value of [cf] in this command
is then not required (it will be ignored).
indicates that the Chezy formula will be activated.
Chezy coefficient (in m1/2 /s).
Default: [cf] = 65.
Note that [cf] is allowed to vary over the computational region; in that
case use the commands INPGRID FRICTION and READINP FRICTION to
define and read the friction data. The command FRICTION is still required
to define the type of friction expression. The value of [cf] in this command
is then not required (it will be ignored).
indicates that the Manning formula will be activated.
Manning coefficient (in m1/3 s).
Default: [cf] = 0.019.
Note that [cf] is allowed to vary over the computational region; in that
case use the commands INPGRID FRICTION and READINP FRICTION to
define and read the friction data. The command FRICTION is still required
to define the type of friction expression. The value of [cf] in this command
is then not required (it will be ignored).
indicates that the logarithmic wall law will be activated.
indicates that the bottom is smooth, i.e. the roughness height is zero.
This option can be used in the depth-averaged mode (a logarithmic velocity
profile is then assumed). Note that this option must be combined with the
standard k model in the multi-layered mode (see command VISC).
This option is default.
indicates that the bottom is rough and is determined by the roughness height.
This option can be used in the depth-averaged mode (a logarithmic velocity
profile is then assumed). Note that this option must be combined with the
standard k model in the multi-layered mode (see command VISC).
Nikuradse roughness height (in m).
Note that [h] is allowed to vary over the computational region; in that case
use the commands INPGRID FRICTION and READINP FRICTION to define
and read the roughness heights. The command FRICTION is still required to
define the type of friction expression. The value of [h] in this command is
then not required (it will be ignored).

| -> CONstant [visc]

|

Description of commands
| -> Horizontal <
|
|
|
|

55

SMAGorinsky [cs]
MIXing [lm]

VISCosity <
|
|
|

Vertical

KEPS [cfk] [cfe]

With this optional command the user can activate turbulent mixing. If this command is
not used, SWASH will not account for turbulent mixing.
In SWASH both the horizontal and vertical eddy viscosities can be specified.
Three different horizontal eddy viscosity models are available, i.e., a constant viscosity,
the Smagorinsky model and the Prandtl mixing length hypothesis. Vertical mixing can be
modelled by using the standard k model.
The default option is a constant horizontal eddy viscosity.
HORIZONTAL
CONSTANT
[visc]
SMAGORIN
[cs]
MIXING
[lm]
VERTICAL
KEPS
[cfk]
[cfe]

VEGEtation

indicates that the horizontal mixing will be activated.

this option indicates that a constant horizontal eddy viscosity will be adopted.
constant viscosity value (in m2 /s).
indicates that the Smagorinsky model will be employed.
Smagorinsky constant.
Default: [cs] = 0.2.
indicates that the Prandtl mixing length hypothesis will be used.
mixing length (in meters).
indicates that the vertical mixing will be activated.
indicates that the standard k model will be used.
vegetative drag-related coefficient for turbulent kinetic energy.
Default: [cfk] = 0.07.
vegetative drag-related coefficient for dissipation rate.
Default: [cfe] = 0.16.

< [height] [diamtr] [nstems] [drag] >

With this optional command the user can activate wave damping induced by aquatic
vegetation. If this command is not used, SWASH will not account for vegetation effects.
The vegetation (rigid plants) can be divided over a number of vertical segments and so, the
possibility to vary the vegetation vertically is included. Each vertical segment represents

56

Chapter 4

some characteristics of the plants. These variables as indicated below can be repeated as
many vertical segments to be chosen.
[height]
[diamtr]
[nstems]

[drag]

the plant height per vertical segment (in m).

the diameter of each plant stand per vertical segment (in m).
the number of plant stands per square meter for each segment.
Note that [nstems] is allowed to vary over the computational region to
account for the zonation of vegetation. In that case use the commands
INPGRID NPLANTS and READINP NPLANTS to define and read the vegetation
density. The (vertically varying) value of [nstems] in this command will
be multiplied with this horizontally varying plant density.
Default: [nstems] = 1.
the drag coefficient per vertical segment.

| -> Sec
TRANSPort [diff] [retur] <
MIn
|
HR
|
DAy

| -> Yes
> [fall] [size] [snum] DENSity <

|
|

| No

With this optional command the user can specify some relevant parameters in case of
transport of constituent. These parameters are only relevant when transport of salinity,
temperature, or suspended sediment load is included.
Inclusion of transport of constituent is indicated by the commands INPTRANS SALINITY
and READTRANS SALINITY in case of salinity, or the commands INPTRANS TEMPERATURE and
READTRANS TEMPERATURE in case of temperature, or the commands INPTRANS SEDIMENT
and READTRANS SEDIMENT in case of suspended sediment load. Using these commands,
both the initial and stationary boundary conditions for constituent are thus specified. If
none of these commands is used, SWASH will not account for transport of any of these
constituents.
The first parameter that may be specified in this command is the horizontal eddy diffusivity. A uniform eddy diffusivity value may be chosen that can be used as a calibration
parameter to account for all forms of unresolved horizontal mixing. This parameter may be
chosen independently from the eddy viscosity (see command VISCOSITY HOR). The eddy
diffusivity depends on the flow and the grid size used in the simulation. A typical smallscale model with grid sizes of tens of meters or less, the eddy diffusivity typically ranges
from 1 to 10 m2 /s. For a large-scale (tidal) areas with grid sizes of at least hundreds of
meters, the parameter is typically in the range of 10 to 100 m2 /s. Alternatively, when not
specified, the eddy diffusivity is related to the eddy viscosity that is determined by either
the Smagorinsky model or the Prandtl mixing length model. Otherwise it is zero.

57

Description of commands

Note that in 3D simulations the vertical eddy diffusivity is automatically included and is
related to the vertical mixing (see command VISCOSITY VERT).

concentration at opening

The second parameter in this command is the return time for unsteady salt intrusion in
a tidal flow. A boundary condition at the seaward side is required. This is usually the
ambient or background concentration of salt sea water. However, at the transition between
sea and river, alternating conditions hold regarding inflow of salt sea water during flood
tide and outflow of fresh river water during ebb tide. Immediately after low water, the
salinity of the inflowing water will not be equal to the salinity of the sea water. It will take
some time before this happens at the boundary. This time lag is the return time for salinity
from its value at the outflow depending on conditions in the interior of model domain relative to its background value specified at the inflow, see Figure 4.2. This memory effect is

outflow

inflow

outflow

background concentration

return time
time (s)

Figure 4.2: Return time for unsteady salt intrusion.

characterised by the so-called Thatcher-Harleman condition that specifies an appropriate

time lag. The return time depends on the tidal flow conditions outside the estuary.
Fall velocity or sediment settling velocity can be used to simulate the behaviour of suspended sediment in water. Due to gravity sediment will sink to the bottom and generate
turbid currents. This parameter cannot be used in the depth-averaged mode. If the fall
velocity is not specified by the user, then the fall velocity will be calculated by SWASH
depending on the particle size (see below).
Median sediment diameter must be specified for three reasons. First, a pickup function is
employed to model the upward sediment flux in which the amount of noncohesive sediment
(sand) is eroded from the bed surface into the flow. The following pickup function is used

58

Chapter 4

(Van Rijn, 1984):

cr
t c
= 0.00033

c z
cr

!3/2

(s 1)0.6 g 0.6 d0.8

50
,
0.2

> cr

with c the (volumetric) sediment concentration, t the vertical eddy viscosity (see command
VISCOSITY VERT), c the Schmidt number for sediment, the Shields parameter related
to the bed shear stress, cr = 0.05 the critical Shields parameter, s = 2.65 the sediment
specific gravity (see command SET [rhosed]), d50 the median sediment diameter, and
the kinematic viscosity of water. Sediment deposition is determined by the downward flux
related to the settling velocity.
Second, it is assumed that the interaction between sediment and turbulent flow is mainly
governed by sediment-induced buoyancy effects. In this respect, the standard k model
and the logarithmic wall law near the bed surface must be applied. This wall law is used to
calculate the bed shear stress, which in turn serves as one of the parameters for the pickup
function. The roughness height depends on the particle size and is determined as 5.5 d50 .
Third, the fall velocity may depend on the sediment diameter, as follows:
ws =

v
u
u2
(s 1)gd50 t +

v
u

u
36 2
36 2
t

(s 1)gd350
(s 1)gd350

This formula will be employed when the fall velocity is not specified by the user.
Because of the assumption of the upward sediment flux being equal to the pickup rate,
the Schmidt number c for sediment becomes a free parameter. Experiences have shown
that sediment diffusivity is rather sensitive to this parameter. The sediment diffusivity is
usually larger than the eddy viscosity, and so c < 1.
The turbidity flow is usually considered as a mixture of water and sediment with a mixture
density, i.e. the effect of sediment on the density of (salt) water is included. However, in
some cases it may be desirable not to include this effect. In this case the density of
water remains unchanged, while the sediment transport is only influenced by the flow and
(turbulent) dispersion. Hence, sediment can be considered here as a passive tracer.
[diff]
[retur]

[fall]

constant horizontal eddy diffusivity (in m2 /s).

return time, the unit is indicated in the next option:
SEC
unit seconds
MIN
unit minutes
HR
unit hours
DAY
unit days
fall velocity (in mm/s).
Note that if [fall] is not given then it will be calculated
based on the sediment diameter.

Description of commands
[size]
[snum]
DENSITY
YES
NO

59

median sediment diameter (in m).

Schmidt number for sediment.
Default: [snum] = 0.7.
this option indicates whether to include the density effect
of suspended sediment in the fluid mixture or not.
indicates that the mixture density will be computed.
This is default.
indicates that the density of water will not be changed
by the presence of sediment in the water column.

BREaking [alpha] [beta]

With this optional command the user can control wave breaking in the case of relatively
coarse resolution in the vertical. If this command is not used, SWASH will not account for
this control. Note that SWASH will account for energy dissipation due to wave breaking
anyhow!
By considering the similarity between breaking waves and bores or moving hydraulic jumps,
energy dissipation due to wave breaking is inherently accounted for. However, when a
few vertical layers are to be employed, the amount of this energy dissipation may be
underestimated due to the inaccuracy with which the phase velocity at the front face of
the breaking wave is approximated. To initiate the wave breaking process correctly, steep
bore-like wave fronts need to be tracked and this can be controlled by the vertical speed
of the free surface. When this exceeds a fraction of the shallow water celerity, as follows,
q

> gh
t

the non-hydrostatic pressure in corresponding grid points is then neglected and remains
so at the front face of the breaker. The parameter > 0 represents the maximum local
surface steepness and determines the onset of the breaking process. A threshold value of
= 0.6 is advised. (This corresponds to a local front slope of 25o .) This single value is
not subject to calibration and seems to work well for all the test cases we have considered,
both regular and irregular waves.

To represent persistence of wave breaking (even if t < gh), we also label a grid point
for hydrostatic computation if a neighbouring grid point has been labelled for hydrostatic
computation and the local steepness is still high enough, i.e.,
q

> gh
t

with < . In all other grid points, the computations are non-hydrostatic.

60

Chapter 4

This approach combined with a proper momentum conservation leads to a correct amount
of energy dissipation on the front face of the breaking wave. Moreover, nonlinear wave
properties such as asymmetry and skewness are preserved as well.
Note that by taking a sufficient number of vertical layers (10 or so) the phase velocity at
the breaking front will be computed accurately enough and hence, this option should not
be activated.
[alpha]

[beta]

4.5.5

threshold parameter at which to initiate wave breaking.

Note: [alpha] > 0.
Default: [alpha] = 0.6.
threshold parameter at which to stop wave breaking.
Note: 0 < [beta] < [alpha].
Default: [beta] = 0.3.

Numerics

NONHYDrostatic

/
STAndard \
\ -> BOX
/

[theta]

SOLVer [rhsaccur] [initaccur] [maxiter] [relax]

PREConditioner

ILUD|ILU

With this optional command the user can include the non-hydrostatic pressure in the
shallow water equations. If this command is not used, SWASH will not account for nonhydrostatic pressure, i.e. pressure is assumed to be hydrostatic.
Hydrostatic pressure assumption can be made in case of propagation of long waves, such
as large-scale ocean circulations, tides and storm surges. This assumption does not hold
in case of propagation of short waves, unstable stratified flows, and other small-scale applications where vertical acceleration is dominant.
In SWASH two different schemes for the vertical pressure gradient are available, i.e., the
classical central differencing (option STANDARD) and the Keller-box scheme (option BOX).
The former approximation is particularly meant for applications where vertical structures
are important, e.g. stratified flows with density currents, undertow and flows over steep
and rapidly varying bottoms, while the latter will be mainly used for accurate short wave
propagation.
The time integration of the vertical pressure gradient is the so-called scheme (a mix of

&

&

Description of commands

61

explicit and implicit Euler schemes). With [theta] = 0.5 we have the well-known second
order accurate Crank-Nicolson scheme with the smallest truncation error, while [theta]
= 1 indicates the first order implicit Euler scheme. Note that only values of [theta] in
the range [0.5,1] are allowed for stability reasons.
By inclusion of the non-hydrostatic pressure, a solution of the Poisson pressure equation
is required. In SWASH this equation is solved by an iterative solution method and the
user may controls this by means of the keyword SOLVER. Two linear solvers are adopted:
Strongly Implicit Procedure (SIP) and BiCGSTAB preconditioned with an incomplete LU
factorization. The former one is particularly meant for the depth-averaged case, while the
latter one can only be applied for the multi-layered case. The incomplete LU factorization
is either ILU or ILUD. The latter is restricted to the main diagonal of the matrix, i.e.
the off-diagonals remain unchanged. The choice of the preconditioner is indicated with
the keyword PRECONDITIONER. For parallel computing, the ILUD preconditioner is a good
choice. However, the ILU preconditioner is more robust. For instance, when high waves
or very short waves are involved, or when the bottom topography exhibits steep slopes,
or when a considerable number of layers (> 20) is involved, it may be wise to choose the
ILU preconditioner. The weighting parameter , as indicated by [relax], may improve
the rate of convergence. With this parameter a combination of the classical ILU and the
modified ILU (MILU) can be given. This combination is given by (1-)ILU + MILU,
and is also hold for ILUD and its modified variant (MILUD). Based on several numerical
experiments, an optimum in the convergence rate is found by taking 55% of MILU and
45% of ILU or ILUD in case of the Keller-box scheme, while for the standard discretization
of the vertical pressure gradient, a combination of 99% of MILU(D) and 1% of ILU(D) is
chosen.
It is common to use the reduction of the residual as a stopping criterion, because the
BiCGSTAB method requires calculation of the residual. When solving the system Ax = b,
after m iterations we have an approximate solution xm and the residual rm = b Axm is
related to the convergence error em = x xm by Aem = rm , so the reduction of the residual
results in the reduction of the convergence error. This does not necessarily mean that the
relative error of the solver is identical to the decrease of the residual. The iteration process
stops at each time step if the ratio of the 2-norm of the residual and of the right-hand
side or initial residual is less than a given accuracy: krm k2 /kbk2 < and krm k2 /kr0 k2 < ,
respectively. They are indicated by the parameters [rhsaccur] and [initaccur], respectively. If both these accuracies are given, the sum of the two is used as termination
criterion. Often, the stopping criterion for the iterative methods is basically a compromise
between efficiency and accuracy. Decreasing the required accuracy can save a considerable
amount of CPU time. Numerical experiments showed = 0.01 gives the optimum.
The default option is the Keller-box scheme with [theta] = 1.0, while the Poisson pressure equation is solved with either SIP with [rhsaccur]=0.01, in the case of depthaveraged mode, or ILUD-BiCGSTAB with [rhsaccur]=0.01 and [initaccur]=0, in the

62

Chapter 4

case of multi-layered mode.

this option indicates that the classical central differencing for the
vertical pressure gradient will be employed.
BOX
this option indicates that the Keller-box scheme will be adopted.
This is the default.
[theta]
parameter for the method. [theta] = 0.5 corresponds to the
Crank-Nicolson scheme and [theta] = 1 to the implicit Euler
scheme.
Default: [theta] = 1.0
SOLVER
With this option the user can influence some of the numerical parameters
of iterative solvers.
[rhsaccur] relative accuracy with respect to the right-hand side.
Default: [rhsaccur] = 0.01
[initaccur] Relative accuracy with respect to the initial residual.
Default: [initaccur] = 0.0
[maxiter]
maximum number of iterations.
Default: [maxiter] = 500
[relax]
parameter for a linear solver:

relaxation parameter for the ILU(D) preconditioning. [relax] = 0

corresponds to ILU(D) and [relax] = 1 corresponds to MILU(D).
Default: model dependent (see above).

under relaxation parameter for the SIP solver.

Default: [relax] = 0.91
PRECONDI
With this option the user can choose a preconditioner.
ILUD
indicates the ILUD preconditioner.
This is the default.
ILU
indicates the ILU postconditioner.
STANDARD

|
| UMOM
|
|
| UPWind <
|
| WMOM
DISCRETization <
|
|
| CORRdep
|
| TRANSPort / ->
|
\

MOMentum|HEAD

/ -> Horizontal
\
Vertical

/ -> Horizontal
\
Vertical

Horizontal
Vertical

|
|
|
|
>
|
|
|
|
|

&

63

Description of commands
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<

NONe
FIRstorder
HIGherorder [kappa]
| -> SWEBy [phi]
|
LIMiter < RKAPpa [kappa]
|
| PLKAPpa [kappa] [mbound]
FROmm
-> BDF|LUDs

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

QUIck
|
|
|
|
|
|
|
|
|
|
|
|
|
|

CUI
MINMod
SUPerbee
VANLeer
MUScl
KORen
SMArt

>
|
|
|
|
|
|
|
|
|
|
|
|
|
|

With this optional command the user can influence the space discretization.
For convection-dominated flows it is possible that wiggles in the solution arise. In that case
upwind discretization may be necessary. At this moment, three types of upwind schemes
are implemented:
the standard first order upwind scheme
higher order upwind schemes obtained with the formulation
TVD schemes with several classes of flux limiters:
Sweby limiter

64

Chapter 4
R limiter
PL limiter

Schemes of up to third order accuracy can be constructed by piecewise polynomial interpolation, the so-called formulation. For all values of [1, 1], a blended form arises
between second order backward difference scheme (BDF) and second order central differencing. The schemes BDF, QUICK and CUI are obtained by setting = 1, 1/2 and
1/3, respectively. The value = 0 gives the Fromms scheme, while = 1 corresponds to
central differencing. For 6=1/3 the local truncation error is of second order; for =1/3 it
is of third order. All upwind schemes are applied in each computational direction. Hence
no streamline upwinding is used.
In case of transport equations for salinity, temperature, or suspended sediment (keyword
TRANSPORT) a TVD scheme must be applied to prevent wiggles in the solution or to avoid
negative concentration values.
The water depth in velocity points is not uniquely defined. An appropriate approximation
is based on first order upwinding instead of the usual interpolation. To achieve second order accuracy in space, we add a higher order interpolation augmented with a flux limiter.
See keyword CORRDEP.
Conservation properties become crucial for rapidly varied flows. These properties are often
sufficient to get solutions that are acceptable in terms of local energy losses, location of incipient wave breaking, propagation speed of a bore, etc. In flow expansions, the horizontal
advective terms in u and vmomentum equations are approximated such that they are
consistent with momentum conservation; see option MOMENTUM. In flow contractions, the
approximation is such that constant energy head is preserved along a streamline, i.e. the
Bernoulli equation; see option HEAD.
The default option is the second order backward difference (BDF) scheme ( = 1) for
all horizontal advective terms in both u/vmomentum and wmomentum equations, and
first order upwinding for the vertical term in the u/vmomentum equation and in the
wmomentum equation. Moreover, the water depth in velocity points is approximated
with the MUSCL limiter. All the advection terms in any transport equation are approximated with the second order Van Leer limiter. By default, SWASH decides whether energy
head or momentum conservation is to be applied. In principle, energy head conservation
will be applied only in strong flow contractions, while elsewhere the momentum conservation is applied.
UPWIND
UMOM
MOMENTUM
HEAD
HORIZONTAL

indicates
indicates
indicates
indicates
indicates

the type of discretization for momentum equations.

the discretization employed for u/vmomentum equation.
that momentum must be conserved everywhere.
that energy head must be conserved everywhere.
the discretization of the horizontal advective terms.

Description of commands
VERTICAL
WMOM
CORRDEP
TRANSPORT
NONE

FIRSTORDER
HIGHERORDE
[kappa]

LIMITER
SWEBY
[phi]

RKAPPA
PLKAPPA
[mbound]
FROMM
BDF
QUICK
CUI
MINMOD
SUPERBEE
VANLEER
MUSCL
KOREN
SMART

65

indicates the discretization of the vertical advective terms.

indicates the discretization employed for wmomentum equation.
indicates the type of discretization for water depth in velocity points.
indicates the discretization employed for transport equation(s).
indicates that no upwinding is applied, hence the standard
central difference scheme is used.
This is the default in case of vertical advective terms.
indicates that the standard first order upwind scheme is used.
a higher order upwind scheme is activated.
parameter defining the type of scheme used.
For instance, [kappa] = 0.5 gives the QUICK scheme
and [kappa] = 0 the Fromms scheme.
Note: 1 [kappa] 1.
indicates that a TVD scheme with flux limiter must be applied.
a Sweby limiter is activated.
parameter defining the type of Sweby limiter used. For instance,
[phi] = 1 defines the minmod limiter.
Note: 1 [phi] 2.
an R limiter is activated.
a PL limiter is activated.
parameter indicating the upper bound of the PL limiter.
Note: [mbound] > 0.
indicates the Fromms scheme.
indicates the second order backward upwind scheme.
This is the default in case of horizontal advective terms.
indicates the QUICK scheme.
indicates the CUI scheme.
indicates the minmod limiter.
indicates the superbee limiter.
indicates the Van Leer limiter.
indicates the MUSCL limiter.
This is the default in case of CORRDEP.
indicates the Koren limiter.
indicates the SMART limiter.

| -> EXPL [cfllow] [cflhig]

TIMEI METH <

> &
|

IMPL [thetac] [thetas] SOLVer [tol] [maxiter] [weight] |

VERTical [thetau] [thetaw] [thetat]

66

Chapter 4

With this optional command the user can influence the time integration.
If time integration is explicit, a time step restriction must be applied based on a Courant
number associated with the long wave speed. For definition, see Appendix A. Note that
a maximum Courant number of 0.5 is advised in case of high waves, nonlinearities (e.g.
wave breaking, wave-wave interactions), and wave interaction with structures with steep
slopes (e.g. quays, piers).
An automatic time step control is implemented as follows. The actual maximum of the
Courant number over all wet grid points is determined. The time step is halved when this
number becomes larger than a preset constant [cflhig] < 1, and the time step is doubled
when this number is smaller than another constant [cfllow], which is small enough to be
sure the time step can be doubled. Information on the actual time step changes is provided
in the PRINT file.
If time integration is semi-implicit, then the gradient of the water level in the momentum
equations and the velocity divergence in the (global) continuity equation are discretized
implicitly by means of the method, while both the horizontal advective and viscosity
terms are discretized explicitly. As a consequence, the stability of the method will not
depend upon the long wave speed. However, the time step will be restricted owing to the
explicit treatment of the horizontal advective terms, although this restriction is mild. This
method is particular useful and efficient for the simulation of three-dimensional circulation
driven by buoyancy, tides and winds, as the Courant number can easily be larger than 1
while still providing sufficiently accurate solution.
This semi-implicit time stepping requires the solution of a system of linear equations to
obtain the water levels. This system is symmetric and positive definite and can be solved
efficiently by using a preconditioned conjugate gradient method. The keyword SOLVER
controls the use of this iterative method. The iteration process stops if the norm of the
residual falls below a small fraction of the initial residual; this small fraction is the user
prescribed error tolerance [tol]. The preconditioner is a weighted combination of ILUD
and its modified variant MILUD. For details on the weighting parameter , which may
improve the convergence, see command NONHYDROSTATIC. This parameter is indicated by
[weight].
In the multi-layered mode, the vertical advective and viscosity terms in the momentum
and transport equations are discretized implicitly by means of the method.
METHOD
EXPLICIT
[cfllow]
[cflhig]

with this option the type of time integration is indicated.

indicates that the time integration is explicit.
This is the default.
minimum Courant number to be used for automatic time step control.
Default: [cfllow] = 0.4.
maximum Courant number to be used for automatic time step control.

Description of commands

IMPLICIT
[thetac]

[thetas]

SOLVER
[tol]
[maxiter]
[weight]

VERTICAL
[thetau]

[thetaw]

[thetat]

4.6

67

Default: [cflhig] = 0.8.

indicates that the time integration is semi-implicit.
parameter for the method applied to the continuity equation.
[thetac] = 0.5 corresponds to the Crank-Nicolson scheme and
[thetac] = 1 to the implicit Euler scheme.
Default: [thetac] = 0.5.
parameter for the method applied to the water level gradient.
[thetas] = 0.5 corresponds to the Crank-Nicolson scheme and
[thetas] = 1 to the implicit Euler scheme.
Default: [thetas] = 0.5.
With this option the user can influence some of the parameters of
the preconditioned conjugate gradient method.
error tolerance to terminate the iteration process.
Default: [tol] = 0.01
maximum number of iterations.
Default: [maxiter] = 100
weighting parameter for the (M)ILUD preconditioning. [weight] = 0
corresponds to ILUD and [weight] = 1 corresponds to MILUD.
Default: [weight] = 1.
with this option the time integration of vertical terms is indicated.
parameter for the method in case of the u/vmomentum equation.
[thetau] = 0.5 corresponds to the Crank-Nicolson scheme and
[thetau] = 1 to the implicit Euler scheme.
Default: the value depends on the maximum Courant number.
parameter for the method in case of the wmomentum equation.
[thetaw] = 0.5 corresponds to the Crank-Nicolson scheme and
[thetaw] = 1 to the implicit Euler scheme.
Default: [thetaw] = 0.5.
parameter for the method in case of the transport equation.
[thetat] = 0.5 corresponds to the Crank-Nicolson scheme and
[thetat] = 1 to the implicit Euler scheme.
Default: [thetat] = 0.5.

Output

There are two categories of output commands:

1. Locations
commands defining sets of output locations at which the user requires output. Each
set is indicated with a name (sname in this manual) which must be unique and not
more than 8 characters long.

68

Chapter 4
Types of sets of output points:
FRAME
GROUP
CURVE
RAY
ISOLINE
POINTS

to define a set of
to define a set of
to define a set of
to define a set of
(with ISOLINE)
to define a set of
(with RAY)
to define a set of

output
output
output
output

locations
locations
locations
locations

on a regular grid
on a regular or curvilinear grid
along a curve
along a depth or bottom contour line

output locations along a depth or bottom contour line

isolated output locations

Commands RAY and ISOLINE cannot be used in 1D-MODE. If one gives one name for
two sets of output locations, the first set is lost (first in the sequence in the command
file). Two special names BOTTGRID and COMPGRID are reserved for use by SWASH
(see below). The user may not define sets with these names.
2. Write / plot
commands defining data file output (write) at the above defined set(s) of output
locations:
BLOCK
TABLE

write spatial distributions (only for FRAMEs and GROUPs)

write output for (set of) output location(s)

Command BLOCK cannot be used in 1D-MODE.

4.6.1

Output locations

FRAme sname [xpfr] [ypfr] [alpfr] [xlenfr] [ylenfr] [mxfr] [myfr])

With this optional command the user defines output on a rectangular, uniform grid in a
regular frame.
If the set of output locations is identical to a part of the computational grid, then the user
can use the alternative command GROUP.
sname
[xpfr]

name of the frame defined by this command

xcoordinate of the origin of the frame in problem coordinates
if Cartesian coordinates are used in m
if spherical coordinates are used in degrees (see command COORD)

Description of commands
[ypfr]

[alpfr]
[xlenfr]

[ylenfr]

[mxfr]

[myfr]

69

ycoordinate of the origin of the frame in problem coordinates

if Cartesian coordinates are used in m
if spherical coordinates are used in degrees (see command COORD)
direction of the xaxis of the frame (in degrees, Cartesian convention; must be
0 in case of spherical coordinates)
length of the frame in xdirection
if Cartesian coordinates are used in m
if spherical coordinates are used in degrees (see command COORD)
length of the frame in ydirection
if Cartesian coordinates are used in m
if spherical coordinates are used in degrees (see command COORD)
number of meshes in xdirection of the rectangular grid in the frame (one less
than the number of grid points in this direction)
Default: [mxfr]=20
number of meshes in ydirection of the rectangular grid in the frame (one less
than the number of grid points in this direction)
Default: [myfr]=20

Some output may be required on a frame that is identical with the input bottom grid
or with the computational grid. These frames need not be defined by the user with this
command FRAME; the frames are always generated automatically by SWASH under the
names sname = BOTTGRID (for the bottom grid) and sname = COMPGRID (for the
computational grid).

GROUP sname SUBGrid [ix1] [ix2] [iy1] [iy2]

With this optional command the user defines a group of output locations on a rectangular
or curvilinear grid that is identical with (part of) the computational grid (rectilinear or
curvilinear). Also, the flow variables (surface elevation, velocity components and pressure)
will be outputted in their points of definition according to the Arakawa C-grid staggering.
Such a group may be convenient for the user to obtain output that is not affected by interpolation errors.
Command CGRID should precede this command GROUP.
The subgrid contains those points (ix,iy) of the computational grid for which:
[ix1] ix [ix2] and [iy1] iy [iy2]
For convenience the size of the group, the corner coordinates and the angle with the

70

Chapter 4

problem coordinate system are written to PRINT file. The origin of the computational grid
is (ix=1,iy=1)!
sname
[ix1]
[iy1]
[ix2]
[iy2]

name of the set of output locations defined by this command

lowest grid index of subgrid in terms of computational grid in ix-direction
lowest grid index of subgrid in terms of computational grid in iy-direction
highest grid index of subgrid in terms of computational grid in ix-direction
highest grid index of subgrid in terms of computational grid in iy-direction

Limitations:
[ix1]1, [ix2][mxc]+1, [iy1]1, [iy2][myc]+1 ([mxc] and [myc] as defined in
the command CGRID).

CURve sname [xp1] [yp1]

< [int] [xp] [yp] >

With this optional command the user defines output along a curved line. Actually this
curve is a broken line, defined by the user with its corner points. The values of the output
quantities along the curve are interpolated from the computational grid. This command
may be used more than once to define more curves.
sname
name of the curve
[xp1],[yp1] problem coordinates of the first point of the curve
if Cartesian coordinates are used in m
if spherical coordinates are used in degrees (see command COORD)
[int]
SWASH will generate output at [int]1 equidistant locations between two
subsequent corner points of the curve (including the two corner points of the curve)
[xp],[yp]
problem coordinates of a corner point of the curve. Repeat the group
[int] [xp] [yp] in proper order if there are more corner points on the curve.

RAY rname [xp1] [yp1] [xq1] [yq1]

<

[int] [xp] [yp] [xq] [yq] >

CANNOT BE USED IN 1D-MODE.

With this optional command the user provides SWASH with information to determine output locations along the depth contour line(s) defined subsequently in command ISOLINE
(see below).

Description of commands

71

The locations are determined by SWASH as the intersections of the depth contour line(s)
and the set of straight rays defined in this command RAY. These rays are characterized by a
set of master rays defined by their start and end positions ([xp],[yp]) and ([xq],[yq]).
Between each pair of sequential master rays thus defined SWASH generates [int]1 intermediate rays by linear interpolation of the start and end positions.
Note that the rays thus defined have nothing in common with wave rays (e.g. as obtained
from conventional refraction computations).
rname
name of the set of rays defined by this command.
[xp1],[yp1],problem coordinates of the begin and end points of the first master ray
[xq1],[yq1] if Cartesian coordinates are used in m
if spherical coordinates are used in degrees (see command COORD)
[int]
number of subdivisions between the previous master ray and the
following master ray defined by the following data (number of
subdivisions is one more than the number of interpolated rays)
[xp],[yp], problem coordinates of the begin and end points of each subsequent master ray
[xq],[yq]
if Cartesian coordinates are used in m
if spherical coordinates are used in degrees (see command COORD)

ISOline

sname

rname

| -> DEPth

<

>
BOTtom

[dep]

CANNOT BE USED IN 1D-MODE AND IN CASE OF CURVILINEAR GRIDS.

With this optional command the user defines a set of output locations along one depth or
bottom level contour line (in combination with command RAY).
sname
rname
DEPTH

BOTTOM
[dep]

name of the set of output locations defined by this command

name of the set of rays (as defined in command RAY)
indicates the water depth, i.e. still water depth plus still water level
(see command SET) or still water depth plus initial spatially varying
water level (see command INPGRID WLEV).
indicates the still water depth, i.e. the depth with respect to datum level.
the depth (in meters) of the depth contour line along which output locations
are generated by SWASH.

The set of output locations along the depth contour lines created with this command is of
the type CURVE.

72

Chapter 4

|
POINts

sname

< [xp] [yp] >

<

>
|

FILE

fname

With this optional command the user defines a set of individual output locations (points).
The coordinates of these points are given in the command itself or read from a file (option
FILE).
name of the points
problem coordinates of one output location
if Cartesian coordinates are used in m
if spherical coordinates are used in degrees (see command COORD)
name of the file containing the output locations.

sname
[xp],[yp]

fname

4.6.2

Write or plot computed quantities

| ..........|
QUANTity <
> short long [lexp] [hexp]
| ..........|

[excv]

&

[ref]

(for output quantity TSEC)

&

[dur] SEC|MIN|HR|DAY

(for output quantities SETUP, HSIG, HRMS,

MVEL, MTKE and MSAL)

&

(for output quantity HRUN)

&

[depth]
|-> PROBLEMcoord |
<

>
|

FRAME

(for directions and vectors, e.g. VDIR and VEL)

With this command the user can influence

the naming of output quantities,
the accuracy of writing output quantities,
the definition of some output quantities,

Description of commands

73

the duration over which wave parameters and mean current are calculated, and
reference direction for vectors.
|...|
<
>
|...|
short

long

[lexp]
[hexp]

[excv]

the output parameters are the same as given in command BLOCK.

user preferred short name of the output quantity (e.g. the name appearing in
the heading of a table written by SWASH). If this option is not used, SWASH
will use a realistic name.
long name of the output quantity (e.g. the name appearing in the heading of a
block output written by SWASH). If this option is not used, SWASH will use a
realistic name.
lowest expected value of the output quantity.
highest expected value of the output quantity; the highest expected value is
used by SWASH to determine the number of decimals in a table with heading.
So the QUANTITY command can be used in case the default number of decimals
in a table is unsatisfactory.
in case there is no valid value (e.g. wave height in a dry point) this
exception value of the output quantity is written in a table or block output.

The following data are accepted only in combination with some specific output quantities.
reference time used for the quantity TSEC.
Default value: starting time of the first computation, except in cases where
this is later than the time of the earliest input. In these cases, the time of
the earliest input is used.
[dur]
the time duration over which the wave parameters (e.g. wave height and
setup), mean current or mean turbulence quantities are computed. This
corresponds to the final stage of the simulation period, which should be
long enough to establish steady-state conditions. The corresponding unit
is indicated in the next option:
SEC
unit seconds
MIN
unit minutes
HR
unit hours
DAY
unit days
[depth]
the total depth (in m) where inundation takes place. This can be used to
compute the maximum runup height; see output quantity HRUN.
PROBLEMCOORD vector components are relative to the x and yaxes of the problem
coordinate system:

directions are counterclockwise relative to the positive xaxis of the

problem coordinate system if Cartesian direction convention is used
(see command SET)
[ref]

74

Chapter 4

FRAME

directions are relative to North (clockwise) if Nautical direction

convention is used (see command SET)
If output is requested on sets created by command FRAME or automatically
(COMPGRID or BOTTGRID):

vector components are relative to the x and yaxes of the frame

coordinate system

directions are counterclockwise relative to the positive xaxis of the

frame coordinate system if Cartesian direction convention is used
(see command SET)

directions are relative to North (clockwise) if Nautical direction

convention is used (see command SET)

Examples:
QUANTITY Xp hexp=100.
QUANTITY WLEV VX excv=-9.
QUANTITY HSIG SETUP dur 30 min

QUANTITY MVEL MSALK dur 1 hr

QUANTITY HRUN depth 0.05

QUANTITY VEL VDIR frame

for simulations of lab. experiments

to change the exception value for
water level and ucomponent
to compute wave height and setup
by averaging surface elevation over
the last 30 minutes of the simulation.
to compute depth-averaged mean velocity
and mean salinity per layer by averaging
these quantities over the last 1 hour of
the simulation.
the inundation depth is set to 5 cm.
to obtain vector components and
direction with respect to the frame.

OUTPut OPTIons comment (TABle [field]) (BLOck [ndec] [len])

This command enables the user to influence the format of block and table output.
comment
field
ndec

len

a comment character; is used in comment lines in the output

Default: comment = %
length of one data field in a table. Minimum is 8 and maximum is 16.
Default: field = 12
number of decimals in block (if appearing after keyword BLOCK).
Maximum is 9.
Default: ndec = 4
number of data on one line of block output. Maximum is 9999.

Description of commands
Default: len = 6

| -> HEADer
BLOck

sname

> fname (LAYout [idla])

|

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

<

DEP
BOTL
WATL
VMAG
VDIR
VEL
VKSI
VETA
PRESS
NHPRES
QMAG
QDIR
DISCH
QKSI
QETA
WMAG
WDIR

NOHEADer |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

75

76

Chapter 4
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<

<

WIND
FRC
USTAR
UFRIC
SAL
TEMP
SED
HRUN
BRKP
SETUP
HS
HRMS
MVMAG
MVDIR
MVEL
MVKSI
MVETA
MSAL
MTEMP
MSED

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

ZK
|
| HK

>
|
|

| -> Sec
[unit] > (OUTput [tbegblk] [deltblk]) <
MIn
|
HR
|
DAy

|
>
|
|

Description of commands
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

VMAGK
VDIRK
VELK
VKSIK
VETAK
VZ
VOMEGA
SALK
TEMPK
SEDK
TKE
EPS
VISC
QMAGK
QDIRK
DISCHK
QKSIK
QETAK
PRESSK
NHPRSK
MVMAGK

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

77

78

Chapter 4
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

MVDIRK
MVELK
MVKSIK
MVETAK
MSALK
MTEMPK
MSEDK
MTKE
MEPS
MVISC
TIME
TSEC
XP
YP
DIST

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

With this optional command the user indicates that one or more spatial distributions
should be written to a file.
sname
HEADER

NOHEADER
fname

name of frame or group (see commands FRAME or GROUP)

with this option the user indicates that the output should be written to a file
with header lines. The text of the header indicates run identification (see
command PROJECT), time, frame name or group name (sname), variable and
unit. The number of header lines is 8.
Note: the numerical values in the file are in the units indicated in the header.
with this option the user indicates that the output should be written to a file
without header lines.
name of the data file where the output is to be written to. Default for option

Description of commands

LAY-OUT
[idla]

DEPTH
BOTLEV

WATLEV

VMAG
VDIR
VEL
VKSI
VETA
PRESS
NHPRES
QMAG
QDIR
DISCH
QKSI
QETA
WMAG
WDIR
WIND
FRC
USTAR
UFRIC
SAL
TEMP
SED
HRUN

79

HEADER is the PRINT file. In case of NOHEADER the filename is required. Note
that when the extension is .mat, a binary MATLAB file will be generated
automatically. This file requires less space on your computer and can be loaded
in MATLAB much faster than an ASCII file. Also note that the output
parameters are stored as single precision. (Hence, use the Matlab command
double for conversion to double precision, if necessary.)
with this option the user can prescribe the lay-out of the output to file with
the value of [idla].
see command READINP (options are: [idla]=1, 3, 4). Option 4 is recommended
for postprocessing by MATLAB, however, in case of a generated binary
MATLAB file option 3 is recommended.
Default: [idla] = 1.
water depth (in m) (not the still water depth!).
bottom level or still water depth (in m).
Output is in both active and non-active points.
Note: exception value for bottom levels must be given!
(See command INPGRID BOTTOM EXCEPTION).
water level or surface elevation (in m).
Output is in both active and non-active points.
Note: exception value for water levels must be given!
(See command INPGRID WLEVEL EXCEPTION).
velocity magnitude (in m/s).
velocity direction (in degrees; Cartesian or nautical; see command SET).
flow velocity (vector; in m/s).
grid-oriented U-velocity (in m/s).
grid-oriented V-velocity (in m/s).
pressure at bottom (in hPa).
normalised (by density) non-hydrostatic pressure at bottom (in m2 /s2 ).
magnitude of discharge per unit width (in m2 /s).
direction of discharge per unit width (in degrees; Cartesian or nautical).
discharge per unit width (vector; in m2 /s).
grid-oriented U-discharge per unit width (in m2 /s).
grid-oriented V-discharge per unit width (in m2 /s).
wind velocity at 10 m above sea level (in m/s).
wind direction at 10 m above sea level (in degrees; Cartesian or nautical).
wind velocity at 10 m above sea level (vector; in m/s).
bottom friction coefficient (see command FRICTION).
magnitude of friction velocity (in m/s).
friction velocity (vector; in m/s).
salinity (in ppt).
temperature (o C).
suspended sediment (in kg/m3 ).
represents the maximum horizontal runup by masking inundated points

80

BRKP
SETUP
HSIG
HRMS
MVMAG
MVDIR
MVEL
MVKSI
MVETA
MSAL
MTEMP
MSED
ZK
HK
VMAGK
VDIRK
VELK
VKSIK
VETAK
VZ
VOMEGA
SALK
TEMPK
SEDK
TKE
EPS
VISC
QMAGK
QDIRK
DISCHK
QKSIK
QETAK
PRESSK
NHPRSK
MVMAGK
MVDIRK
MVELK
MVKSIK
MVETAK

Chapter 4
as 1 and non-inundated points as 0.
represents area of wave breaking by masking breaking points as 1
and non-breaking points as 0.
wave-induced setup (in m).
significant wave height (in m; for definition, see Appendix A).
RMS wave height (in m; for definition, see Appendix A).
time-averaged or mean velocity magnitude (in m/s).
time-averaged or mean velocity direction (in degrees; Cartesian or nautical;
see command SET).
time-averaged or mean velocity (vector; in m/s).
time-averaged or mean grid-oriented U-velocity (in m/s).
time-averaged or mean grid-oriented V-velocity (in m/s).
time-averaged or mean salinity (in ppt).
time-averaged or mean temperature (o C).
time-averaged or mean suspended sediment (in kg/m3 ).
layer interface (in m).
layer thickness (in m).
velocity magnitude per layer (in m/s).
velocity direction per layer (in degrees; Cartesian or nautical).
flow velocity per layer (vector; in m/s).
grid-oriented U-velocity per layer (in m/s).
grid-oriented V-velocity per layer (in m/s).
velocity in z-direction (in m/s).
vertical velocity relative to sigma plane (in m/s).
salinity per layer (in ppt).
temperature per layer (o C).
suspended sediment per layer (in kg/m3 ).
turbulent kinetic energy per layer interface (in m2 /s2 ).
dissipation rate of turbulent kinetic energy per layer interface (in m2 /s3 ).
vertical eddy viscosity per layer interface (in m2 /s).
magnitude of discharge per unit width per layer (in m2 /s).
direction of discharge per unit width per layer (in degrees; Cartesian or nautical).
discharge per unit width per layer (vector; in m2 /s).
grid-oriented U-discharge per unit width per layer (in m2 /s).
grid-oriented V-discharge per unit width per layer (in m2 /s).
pressure per layer (in hPa).
normalised (by density) non-hydrostatic pressure per layer (in m2 /s2 ).
time-averaged or mean velocity magnitude per layer (in m/s).
time-averaged or mean velocity direction per layer (in degrees;
Cartesian or nautical; see command SET).
time-averaged or mean velocity per layer (vector; in m/s).
time-averaged or mean grid-oriented U-velocity per layer (in m/s).
time-averaged or mean grid-oriented V-velocity per layer (in m/s).

Description of commands
MSALK
MTEMPK
MSEDK
MTKE
MEPS
MVISC
TIME
TSEC
XP
YP
DIST

[unit]

OUTPUT
[tbegblk]

[deltblk]

81

time-averaged or mean salinity per layer (in ppt).

time-averaged or mean temperature per layer (o C).
time-averaged or mean suspended sediment per layer (in kg/m3 ).
time-averaged or mean turbulent kinetic energy per layer interface (in m2 /s2 ).
time-averaged or mean dissipation rate of turbulent kinetic energy per
layer interface (in m2 /s3 ).
time-averaged or mean vertical eddy viscosity per layer interface (in m2 /s).
full date-time string as part of line used in TABLE only.
time in seconds with respect to a reference time (see command QUANTITY).
user instructs SWASH to write the xcoordinate in the problem coordinate system
of the output location.
user instructs SWASH to write the ycoordinate in the problem coordinate system
of the output location.
if output has been requested along a curve (see command CURVE) then the distance
along the curve can be obtained with the command TABLE. DIST is the distance
along the curve measured from the first point on the curve to the output location
on the curve in meters (also in the case of spherical coordinates).
this controls the scaling of output. The program divides computed values by [unit]
before writing to file, so the user should multiply the written value by [unit] to
obtain the proper value.
Default: if HEADER is selected, value is written as a 5 position integer.
SWASH takes [unit] such that the largest number occurring in the block
can be printed.
If NOHEADER is selected, values are printed in floating-point format, [unit] = 1.
the user requests output at various times. If the user does not use this option, the
program will give BLOCK output for the last time step of the computation.
begin time of the first field of the variable, the format is:
1 : ISO-notation
19870530.153000
2 : (as in HP compiler)
30May87 15:30:00
3 : (as in Lahey compiler) 05/30/87.15:30:00
4 :
15:30:00
5 :
87/05/30 15:30:00
6 : as in WAM
8705301530
7 :
153000.000
This format is installation dependent. See Implementation Manual or ask the
person who installed SWASH on your computer. Default is option 7.
time interval between fields, the unit is indicated in the next option:
SEC
unit seconds
MIN
unit minutes
HR
unit hours
DAY
unit days

82

Chapter 4

Notes:
The x and ycomponents of the vectorial quantities VEL, DISCH, UFRIC, etc. are
always given with respect to the problem coordinate system.
For direction in Cartesian convention: relative to xaxis of the problem coordinate
system (counterclockwise). Possible exception: in the case of output with BLOCK
command in combination with command FRAME, see command QUANTITY.
For a proper use of the quantity HRUN, take into account the following notes:
1. Quantity HRUN indicates the maximum horizontal runup. So, it should be plotted
at the final time step.
2. The correct values for HRUN are 0 and 1 only. To prevent interpolation, use the
command GROUP.
3. The horizontal runup is associated with the inundation depth. The default value
is the threshold water depth; see command SET. Otherwise it is determined by
the user using the command QUANTITY HRUN depth.
4. To determine the (vertical) runup height with respect to the still water level,
also plot the quantity BOTLEV. At those locations where HRUN is for the first time
zero, the corresponding value of 1 BOTLEV indicates the runup height.

5. To find and plot the location of inundation use the following Matlab script:
BWs=edge(Hrunup,sobel);
hrp=zeros(size(BWs,1),size(BWs,2));
hrp(BWs==1)=1;
hrp(hrp==0)=NaN;
x=Xp(find(hrp==1));
y=Yp(find(hrp==1));
Note the quantities XP and YP must be included as well.

Quantity BRKP indicates areas where wave breaking occur. The correct values for
BRKP are 0 (no breaking) and 1 (breaking) only. To prevent interpolation, use the
command GROUP. In this way white spots can be visualised.
The wave parameters SETUP, HSIG and HRMS are determined by averaging the surface
elevation over the duration [dur] as specified in command QUANTITY. Hence, they
are regarded as stationary quantities and must be plotted at the final time step only.
The mean currents MVEL, MVELK, etc. are determined by averaging the velocities over
the duration [dur] as specified in command QUANTITY. Hence, they are regarded as
stationary quantities and must be plotted at the final time step only.

83

Description of commands

The mean constituents MSAL, MTEMP and MSED are determined by averaging the constituents over the duration [dur] as specified in command QUANTITY. Hence, they
are regarded as stationary quantities and must be plotted at the final time step only.
The mean turbulence quantities MTKE, MEPS and MVISC are determined by averaging
the turbulence quantities over the duration [dur] as specified in command QUANTITY.
Hence, they are regarded as stationary quantities and must be plotted at the final
time step only.

TABle

sname

<

| -> HEADer
|
<
NOHEADer
|
|
SWASH

| ...

| ...

<

>

|
|
>

fname

&

|
|

> (OUTput [tbegtbl] [delttbl]

| -> Sec
<
MIn
|
HR
|
DAy

|
>)
|
|

With this optional command the user indicates that for each location of the output location
set sname (see commands POINTS, CURVE, FRAME or GROUP) one or more variables should
be written to a file. The keywords HEADER and NOHEADER determine the appearance of the
table; the filename determines the destination of the data.
sname
HEADer

NOHEADer

SWASH

fname

|...|
<
>

name of the set of POINTS, CURVE, FRAME or GROUP

output is written in fixed format to file with headers giving name of variable
and unit per column. A disadvantage of this option is that the data are written
in fixed format; numbers too large to be written will be shown as: ****.
Number of header lines is 4.
output is written in floating point format to file and has no headers; it is
intended primarily for processing by other programs. With some spreadsheet
programs, however, the HEADER option works better.
a table on file is produced with a special fixed format appropriate for
layer-dependent quantities. This file contains headers with useful
information for a correct interpretation of the data.
name of the data file where the output is to be written to.
Default for option HEADER is output to the PRINT file.
In case of NOHEADER the filename is required.
the output parameters are the same as given in command BLOCK.

84

Chapter 4

|...|
OUTPUT
[tbegtbl]

[delttbl]

the user requests output at various times. If the user does not use this option,
the program will give TABLE output for the last time step of the computation.
begin time of the first field of the variable, the format is:
1 : ISO-notation
19870530.153000
2 : (as in HP compiler)
30May87 15:30:00
3 : (as in Lahey compiler) 05/30/87.15:30:00
4 :
15:30:00
5 :
87/05/30 15:30:00
6 : as in WAM
8705301530
7 :
153000.000
This format is installation dependent. See Implementation Manual or ask the
person who installed SWASH on your computer. Default is option 7.
time interval between fields, the unit is indicated in the next option:
SEC
unit seconds
MIN
unit minutes
HR
unit hours
DAY
unit days

Notes:
The number of decimals in the table varies for the output parameters; it depends on
the value of [hexp], given in the command QUANTITY.
It is advised to use the command HEAD or SWASH in case of outputting layer-dependent
quantities (e.g. ZK, VELK, PRESSK, etc.). With the command SWASH, the quantity TIME
is automatically included.

4.6.3

TEST

Write or plot intermediate results

[itest] [itrace]

| -> IJ < [i] [j] >

POINTS <

>
XY < [x] [y] >

&

(FILE fname)
If SWASH produces unexpected results, this optional command can be used to instruct
the program to produce intermediate results during a SWASH run (test output). A TEST
command may change between commands in the file to change the level of test output during a SWASH run. This change occurs during the execution of the run. A TEST command
controls the test output until the next TEST command. Such a next TEST command may
have level 0, thus stopping test output.

Description of commands
[itest]

[itrace]

POINTS

IJ
[i], [j]
XY
[x], [y]

FILE
fname

4.7

COMPute

the level of test output. For values under 100 the amount is usually reasonable,
for values above 200 it can be very large. For values of [itest] up to 50 the
test output can be interpreted by the user. For higher values of [itest] the
test output can only be interpreted by those who have the program source listing
at their disposal.
Default: [itest] = 1.
SWASH writes a message (name of subroutine) to the PRINT file at the first
[itrace] entries of each subroutine.
Default: [itrace] = 0.
if this option is used, the user instructs SWASH to produce detailed print output
during the computational process for a grid point of the computational grid.
Output at a maximum of 50 grid points is possible. This option can be used
only after the bathymetry has been read (see command READINP BOTTOM).
the test points are defined by means of grid indices.
grid indices of a test point. Values of [i] range from 1 to [mxc]+1
(see command CGRID), values of [j] from 1 to [myc]+1.
the test points are defined in terms of problem coordinates; SWASH will determine
the nearest grid points. Output will be made for this selected grid point.
coordinates of a test point (problem coordinates in meters in case of Cartesian
coordinates, or longitude and latitude in degrees in case of spherical coordinates,
see command COORD).
some flow variables for test points are written.
name of the file to which the output is written; default filename: DIAGNOSTIC.

Lock-up

[tbegc] [deltc] <

| -> Sec
MIn
|
HR
|
DAy

|
> [tendc]
|
|

This command orders SWASH to start the computation.

[tbegc]

85

the
1 :
2 :
3 :
4 :
5 :

start (date and) time of

ISO-notation
(as in HP compiler)
(as in Lahey compiler)

the computation, the format is

19870530.153000
30May87 15:30:00
05/30/87.15:30:00
15:30:00
87/05/30 15:30:00

86

[deltc]

[tendc]

Chapter 4
6 : as in WAM
8705301530
7 :
153000.000
This format is installation dependent. See Implementation Manual or ask the
person who installed SWASH on your computer. Default is option 7.
the time step of the computation, the unit is indicated in the
next option:
SEC
unit seconds
MIN
unit minutes
HR
unit hours
DAY
unit days
the end time of the computation, format see [tbegc].

STOP
This required command marks the end of the commands in the command file. Note that
the command STOP may be the last command in the input file; any information in the
input file beyond this command is ignored.

Chapter 5
Setting up your own command file
In this chapter some guidelines for setting up a command file is given. This file contains all
the necessary commands and data required for defining a model and running the simulation.
All the commands and keywords are listed in Appendix C. Not all the commands need to
be specified. Most of them will be taken default. Generally, a command file consists of five
parts which must be specified by the user:
1. a computational grid,
2. some input grids, most notably the bathymetry,
3. initial and boundary conditions,
4. some physical and numerical parameters, and
5. output quantities, output locations and output formats.

5.1

Computational grid

A distinction is made between the definition of grids in horizontal and vertical directions.
In the horizontal direction recti or curvilinear coordinates are used. The grid definition
in vertical direction is defined by means of a fixed number of layers in a such a way that
both the bottom topography and the free surface can be accurately represented; see also
Figure 5.1.
First we need to define the size and direction of the computational domain in the horizontal plane. The area of interest should be kept at least two wave lengths away from the
boundaries. Note that if a sponge layer needs to be included, the computational domain
needs to be extended with the size of that sponge layer. It is always wise to choose the
grid axes being aligned as much as possible with the dominant wave direction. You may
also generate a curvilinear grid.
87

88

Chapter 5

An important aspect of specifying a computational grid is the spatial resolution. In principle, most energetic wave components need to be resolved accurately on the grid. Basically,
we take sufficient number of grid points per wave length associated with the peak wave
energy. For low waves, i.e. H/d 1 with H a characteristic wave height (either significant
or RMS) and d the (still) water depth, it is sufficient to take 50 grid cells (or 51 grid
points) per peak wave length. However, for relatively high waves, it is better to take at
least 100 grid cells per peak wave length. So, at least, we need to know something about a
typical water depth and a typical peak period. Based on the linear dispersion relation the
corresponding peak wave length can be found.
An example. We have a domain of 1500 m alongshore and 1200 m crosshore of which
the deepest part is 20 m. We impose a wave spectrum at the entrance with a significant
wave height of 2 m and a peak period of 10 s. According to the linear dispersion relation
the peak wave length is about 120 m and Hs /d = 0.1. Hence, the waves are not too low
but also not too high either. So, for safety, we choose 100 grid cells per peak wave length
which implies a grid size of 1.2 m. Since the dominant wave direction is crosshore, we may
relax the grid size alongshore by choosing 3 m. So, the total number of grid cells for the
computational domain would be 500 1000.
Keep in mind, however, that waves become shorter when the water depth decreases. Hence,
for a desired number of grid cells per wave length the grid resolution must therefore be
higher locally. In this respect, a curvilinear grid may be useful. The desired number of
grid cells for this case may be lesser than the one associated with the peak wave length. A
rule of thumb is 15 to 20.
Another issue is the choice of the number of layers. This choice mainly depends on two
types of application:
vertical flow structures, and
wave transformation.
If one is interested in the vertical flow structures, e.g. undertow and stratified flows, then at
least 10 or perhaps more vertical layers should be adopted. If necessary, a non-equidistant
layer distribution can be specified; see Figure 5.1. The layer thickness hk , which is the
distance between two consecutive layer interfaces, may be defined in a relative way, i.e. a
percentage of the water depth similar to the coordinates, or in an absolute way, i.e. a
constant or fixed layer thickness as expressed in meters. To make sure that the sum of the
layer thicknesses equals the water depth, at least one layer must be defined in a relative
way. The choice for fixed layers may be useful in the case of a bathymetry exhibiting
strong variation of the depth, such as a lake with some pits, in order to keep the vertical
resolution relatively high along the bottom.
Concerning the wave transformation, the number of layers is determined by the linear
frequency dispersion. In particular, the dimensionless depth, kd with k the wave number,

89

Setting up your own command file

z0 =

zk-1
hk
zk

zK = - d

Figure 5.1: Vertical grid definition with K layers and K+1 layer interfaces.
decides the number of layers. The higher the value of kd, the more vertical layers needed. In
addition, the accuracy with which the phase velocity of the wave components, c = /k with
the angular frequency, is obtained depends on the discretization of the vertical pressure
gradient in the momentum equations. For wave transformation usually the Keller-box
scheme is adopted; see Section 5.4.3.
The range of applicability of the SWASH model to values of kd indicating the relative
importance of linear wave dispersion for primary waves is given in Table 5.1. This
range
is determined by requiring a relative error in the normalized wave celerity (= c/ gd) of
Table 5.1: Range of dimensionless depth as function of number of layers K in SWASH.
K range
error
1 kd 0.5
1%
1 kd 2.9
3%
2 kd 7.7
1%
3 kd 16.4 1%
at most 1%. An exception is the use of one vertical layer where the relative error is 3%,
which is acceptable for many applications. Here, at most three layers may be considered
enough for typical wave simulations. Moreover, the layers are assumed to have variable
thicknesses and be equally distributed, which is the usual choice for wave simulations. So,
do not use fixed layers!
It is noted that SWASH uses its own dispersion relation, which is an approximate one of
the exact linear dispersion relation, given by
2 = gk tanh(kd)

90

Chapter 5

This approximate relation is derived using the Keller-box scheme (see Section 5.4.3) and
depends on the number of equidistant layers employed in the model. The linear dispersion
relation of SWASH using one vertical layer, i.e. depth-averaged, is given by
2 = gk

kd
1 + 41 k 2 d2

while for two and three equidistant layers, it is given by

1 3 3
kd + 16
k d
= gk
3 2 2
1 4 4
1 + 8 k d + 256
k d
2

and
2 = gk

5 3 3
1
kd + 54
k d + 1296
k 5 d5
5 4 4
1
5 2 2
k d + 432
k d + 46656
k 6 d6
1 + 12

respectively. Thus the approximate dispersion relation is consistent with the model, particularly for relatively high wave frequencies. This will lead to more accurate results. The
approximate dispersion relation in SWASH is only available for one, two and three equidistant layers with variable thickness (i.e. sigma planes, not fixed layers). SWASH shall
indicate this in the PRINT file.
So, for primary waves with kd 2.9, use of one layer is sufficient, while at least two equidistant layers need to be chosen if kd 7.7. For most typical nearshore wave simulations,
two layers may be enough. In the example above, kd = 1.04, so one vertical layer would
be enough.
However, one must realized that, for a given number of layers, relatively high harmonics
may propagate too slow at a given depth. For example, using one layer, SWASH is accurate
up to a kd value of 2.9 for primary waves. For a depth of 20 m (deepest part in the example
above), the shortest wave that can accurately modelled at this depth has a frequency of
0.18 Hz (minimum wave period of 5.6 s; derived from the approximate dispersion relation
above). In other words, for a given number of layers and a water depth, there is a maximum frequency above which a wave component has an incorrect celerity; see Table 5.2.
This means, for instance, that the phase differences between the concerning harmonics are
wrong. This is particularly important when nonlinear effects are dominant1 .
Ideally, the maximum frequency is about 1.5 to 2 times the peak frequency at a given
depth. It is then assumed that all components above this maximum frequency have a
little bit amount of energy (here the presuming spectrum shape is a Jonswap one). As a
consequence, the phase differences between the representative wave components, including
the relatively short waves, are thus well controlled in the model.
1

If one is interested in propagation of very short waves in the surf zone (d 0.5 m) with f < 4 Hz, while
these waves exchange energy through nonlinear interactions, the user is advised to choose six equidistant
layers. By using these number of layers, the maximum relative error for kd < 40 remains below 0.1%.

Setting up your own command file

91

Table 5.2: Maximum frequency (in Hz) as function of still water depth (in m) and number
of layers.
d (m) K=1 K=2 K=3
1 0.82 1.37 2.00
5 0.37 0.61 0.89
10 0.26 0.43 0.63
15 0.21 0.35 0.52
20 0.18 0.31 0.45
25 0.16 0.27 0.40
30 0.15 0.25 0.36
35 0.14 0.23 0.34
40 0.13 0.22 0.32
45 0.12 0.20 0.30
50 0.12 0.19 0.28
100 0.08 0.14 0.20

Referred to the example above, the peak frequency at the wavemaker boundary is 0.1 Hz,
while the depth is 20 m. The required maximum frequency should be at least 0.15 Hz or
preferably higher. So, the use of one layer would be critical when propagation of short
waves with frequencies higher than 0.18 Hz needs to be modelled accurately.

5.2

Input grids

The most important input grid is the bathymetric grid. This grid represents the bottom
level at each grid point with land points defined as negative while wet points are defined
as positive. The resolution of bathymetric grid is not necessarily the same as that of the
computational grid. It is advised to avoid extremely steep bottom slopes or sharp obstacles
as much as possible. Some kind of smoothing or re-interpolation is therefore recommended.
Jetties, piers and quays, or other impermeable walls, may be schematized either
by including their slopes in the bathymetry, or
by means of porosity layers with a small porosity (n < 0.1), or
a combination of the first two options.
From a stability point of view, the second option is the best one. However, the first option
may be a better choice when, for instance, wave diffraction around the berm of the quay
need to be simulated accurately. To avoid unrealistically high surface elevation around
the quays or possible instabilities due to steep slopes, this first option may be combine
with a larger threshold of the water depth; see Section 5.4.6 and command SET DEPMIN.

92

Chapter 5

The default value of this threshold is 0.05 mm. Depending on the horizontal grid sizes
(x, y), and thereby the actual slope, this threshold may be increase to 0.1 mm or even
1 mm in order to get a stable solution. The higher the grid resolution, the higher this
threshold should be set. But be careful as this higher threshold may negatively influence
mass conservation.
Instead, however, a combination is also possible, i.e. to place the porosity layer on top of
the quay walls, and having a volumetric porosity of 20% and a grain size of 0.1 m.
A rubble mound breakwater must be schematized by means of porosity layers. These layers must be placed inside the computational domain. Rubble mound breakwaters have
a typical porosity value of (n=) 0.4, while the stone size of the armour layer is typically
0.5 m. The berm of the breakwater can be specified by means of the structure heights
(relative to the bottom). In case of two or more breakwaters in the domain, both porosity
and structure height are thus spatially varied, and so they need to be inputted by means
of input grids. Also stone diameters need to be specified as well.
Alternatively, the porosity layers may be placed on top of the impermeable core of the
breakwater which, in turn, is schematized by adapting the bottom level. In addition, the
berm of the breakwater is schematized by including its slope in the adapted bathymetry.
The width of the breakwater should be at least four times the grid size of the computational grid. So, the grid resolution should be high enough. When choosing a too coarse
grid size, it may lead to an overestimation of the transmission and an underestimation of
the reflection.
This way of schematization permits to simulate partial reflection and transmission of the
waves through breakwaters. Wave reflection at a breakwater is typically determined by
wave energy dissipation on the slope and wave penetration into the breakwater. Both
processes are equally important, and thus both slope angle and porosity are important
governing parameters for the wave reflection.
Using the command INPGRID BOTTOM EXCEPTION, one can introduce permanently dry
points in the computational grid. This provides a means to make a line of dams or screens
through the computational domain, separating the flow on both sides. This line of thin
dams may represent a small obstacle with subgrid dimensions that possibly influence the
local flow. It must be noted that for parallel runs using MPI the user must indicate an
exception value for bottom levels, if appropriate, in order to obtain good load balancing.
The water depth should be uniform along the wavemaker boundary where incident waves
are imposed.
If tidal currents are significant over the computational domain, the spatial distribution of
the currents u(x, y) should be specified as an input grid.

Setting up your own command file

5.3

93

Initial and boundary conditions

To solve the continuity and momentum equations, appropriate boundary conditions need
to be imposed at the boundaries of the computational grid.
In general, initial conditions are more important for relative short simulations (e.g. a few
minutes in case of short waves or a few days in case of tidal waves). Boundary conditions
are by far more important for longer simulations. Moreover, often no information is available in order to start the simulation. Therefore, the simulation will usually start with zero
velocities and a spatially constant water level, and the simulation will be long enough to
get a steady-state solution; see also Section 5.4.1.
Waves may be generated along one or two boundaries. These are called wavemaker boundaries. First, it is assumed that the variation of the depth along these wavemaker boundaries
is slowly. Second, it is advised to place these wavemaker boundaries away from the area of
interest, and from steep topography. At the wavemaker boundary, we may imposed either
regular or irregular waves. For one-dimensional cases they are by definition long-crested
or uni-directional. For a two-dimensional case short-crested or multi-directional waves can
also be specified. Usually, a time series need to be given for incident waves. This may
either be synthesized from parametric information (wave height, period, etc.) or derived
from a surface elevation time series.
For regular waves, at least the wave height and the wave period must be specified. Optionally, the wave direction can be specified as well. Alternatively, a time series can be
imposed.
For irregular waves, either a spectrum or time series can be enforced. In the case of a
spectrum, both the shape and wave characteristics need to be specified. The usual shape
is either Jonswap or Pierson-Moskowitz. Sometimes a TMA shape is desired. The wave
characteristics are determined by the following parameters: the significant or RMS wave
height, peak or first order mean period, peak wave direction, and directional spreading
(only in case of short-crested waves). The frequency range [fmin , fmax ] is such that the
highest frequency, fmax , equals 3 times the peak frequency (or mean frequency), while the
lowest one, fmin , equals half of the peak/mean frequency.
Alternatively, a spectrum file may be given. There are two types of files:
A file containing 1D or non-directional wave spectrum (usually from measurements).
A file containing 2D or directional wave spectrum (possibly from another SWAN
run).
Using a spectrum a time series of surface elevation will be synthesized. At least, the
length of this series should correspond to the time period over which surface elevation and
velocities are outputted after steady-state condition has been established. This time period
should be long enough to provide statistically reliable wave data. After this time period

94

Chapter 5

the time series repeats itself. This duration of the time series is called the cycle period
(see command BOUnd ... SPECTrum ... [cycle]). The recommended range is from
100 to 300 wave periods. If the cycle period is denoted as Tcycle , then the frequency step
f to be used for the evaluation of the parametric spectrum (e.g. Jonswap) equals
f =

1
Tcycle

Thus the spectrum is divided into N frequency bins with uniform spacing f ,
N=

fmax fmin
f

Referring to the above example, we impose a Jonswap spectrum at the wavemaker boundary. The peak period is 10 s, so that the frequencies are in between 0.05 Hz and 0.3 Hz.
The duration of the time series of surface elevation to be synthesized is set to 30 minutes,
which is supposed to be accurate enough to get sufficient statistics like wave height and
mean period. Hence, in total, 450 wave components will be generated at the entrance of
the computational domain.
Please be careful in choosing the cycle period. The larger this period the more wave components will be involved at the wavemaker boundary. Based on these components, SWASH
will synthesize time series for the orbital velocities in each grid point and each vertical layer
along the boundary. That would enhance the turn-around time of the simulation a lot.
When imposing a spectrum at the boundary, one has to realize that some so-called evanescent modes might be included as well. These modes show exponential decay with distance
from the boundary at which the spectrum is imposed. As such, they can not be seen by
the model. Evanescent waves are a general property of the underlying model equations.
The frequency at which the evanescent modes are generated is the cut-off frequency and is
determined by the dispersive properties of the model equations. It is given by
cf = 2 K

g
d

with K the number of layers used in the model. Hence, the lowest wave period to be
considered in the model simulation equals 2/cf . So, given the depth at the boundary
and the number of layers used, the cut-off frequency is determined above which the evanescent waves are generated at the wavemaker boundary where the spectrum is imposed; see
Table 5.3.
These evanescent modes will be removed by SWASH. Note that these modes carry a little
bit energy and thus negligible. SWASH will give a warning when at least 10% of the total
wave components are the evanescent modes that have been removed. If there are too much
evanescent modes on the boundary, i.e. these modes together contain a significant amount
of energy of the wave spectrum, the user is advised either to enlarge the number of layers

Setting up your own command file

95

Table 5.3: Cut-off frequency (in Hz) as function of still water depth (in m) and number of
layers.
d (m) K=1 K=2 K=3
1 1.00 1.99 2.99
5 0.45 0.89 1.34
10 0.32 0.63 0.95
15 0.26 0.51 0.77
20 0.22 0.45 0.67
25 0.20 0.40 0.60
30 0.18 0.36 0.55
35 0.17 0.34 0.51
40 0.16 0.32 0.47
45 0.15 0.30 0.45
50 0.14 0.28 0.42
100 0.10 0.20 0.30

(see also Table 5.2) or to truncate the imposed spectrum (e.g. SWAN spectrum), i.e. the
highest frequency of the spectrum is not larger than the given cut-off frequency.
In the above example, one layer (K = 1) has been chosen. We assume that along the
wavemaker boundary we have a uniform depth of 20 m. So the cut-off frequency is 0.22
Hz (see Table 5.3; the lowest wave period is thus 4.5 s). However, the highest frequency
is 0.3 Hz. So there are 144 evanescent modes on the boundary, which is about 30%, thus
reasonably. They will be removed from the boundary.
For high waves, sub and super harmonics are generated due to nonlinearity. These waves
are called bound waves as they are attached to the primary wave and travel at its phase
speed instead of that of a free wave at the same frequency. If linear wave conditions are
enforced at the boundaries, the model will generate free components with the same magnitude but 180o out of phase with the bound waves at the wavemaker in order to satisfy
the linear wave boundary condition. The presence of bound and free waves that travel at
different speeds will lead to a spatially nonhomogeneous wave field with the wave height
changing continuously over the domain. For such a case, it is recommended to add bound
waves at the wavemaker boundaries (see command BOUnd ... ADDBoundwave ...).
To simulate entering waves without some reflections at this boundary, a weakly reflective
condition allowing outgoing waves must be adopted (command BTYPE WEAK). This type of
radiation condition has been shown to lead to good results within the surf zone.
Waves propagating out of the computational domain are absorbed by means of a sponge
layer placed behind an output boundary. It is recommended to take the width of the
sponge layer at least 3 times the typical wave length. However, for long waves a Sommer-

96

Chapter 5

feld radiation condition might be a good alternative.

When no boundary conditions are specified at a boundary, this boundary is considered to
be a close one. This boundary is fully reflective. Alternatively, periodic boundary conditions can be applied at two opposite boundaries. This means that wave energy leaving
at one end of the domain enters at the other side. In this case no reflections at these
boundaries occur. This is recommended in the case of a simulation of a field case where
longshore bottom variations are negligible. In such a case the computational domain is
made repeated in a representative direction (see command CGRID ... REPeating X|Y).

5.4
5.4.1

Numerical parameters
Duration of simulation

It is recommended to take into account both the spin up time and the duration of the time
series at the wavemaker boundary. In this way a steady-state condition will be obtained.
We assume that the spin up time takes at most 10 to 15% of the total time of the simulation.
For a suitable simulation time at least 500 to 1000 waves are needed.
In the above example the cycle period equals 30 minutes, which is supposed to be at least
85% of the total simulation time. So, the duration of the intended simulation would be 35
minutes, or more safely, 40 minutes.

5.4.2

Time step

The time integration is of explicit type and thus requires strict confirmity of stability
criteria for a stable solution. The well-known CFL condition for 1D problems is given by
Cr =

gd + |u|

(5.1)

with x the mesh width, t the time step, u the flow velocity, and Cr the Courant number.
For a 2D problem, however, the following CFL condition is employed
Cr = t

q

gd +

u2

v2

 s

1
1
+
1
x2 y 2

A dynamically adjusted time step controlled by the Courant number in a user prescribed
range is implemented in SWASH as follows. The actual maximum of the Courant number
over all wet grid points is determined. The time step is halved when this number becomes
larger than a preset constant Crmax < 1, and the time step is doubled when this number
is smaller than another constant Crmin , which is small enough to be sure the time step
can be doubled. Usually, Crmin is set to 0.2, while the maximum Courant number Crmax
is specified in the range of 0.5 to 0.8. It is advised not to choose a value higher than 0.8

97

Setting up your own command file

since nonlinear processes, e.g. wave breaking and wave-wave interactions, can affect the
stability condition. For high, nonlinear waves, or wave interaction with structures with
steep slopes (e.g. jetties, quays), a Courant number of 0.5 is advised.

5.4.3

Vertical pressure gradient

Space discretization of the governing equations is carried out in a finite volume/finite difference fashion. A staggered grid arrangement is used in which the velocity components
are located at the center of the cell faces (see Figure 5.2). The water level is located at
cell center. Concerning the non-hydrostatic pressure, two layouts to assign this unknown
to grid points are employed. This variable can be given either at the cell center or at the
layer interface. The former is called the standard layout, while the latter one is called the
box layout; see Figure 5.2.

w
k1/2

k1/2
k

q
u

k
k+1/2

k+1/2
i1/2

i+1/2

i1/2

i+1/2

(a)

(b)

Figure 5.2: Applied arrangements of the unknowns in a staggered grid: (a) standard layout
and (b) box layout. Meaning of the unknowns: u is the horizontal velocity, w is the vertical
velocity and q is the non-hydrostatic pressure.
The choice depends on the discretization of the vertical pressure gradient, namely, explicit
central differences referring as the classical case and the implicit Keller-box or compact
scheme, respectively. This compact scheme allows straightforward implementation of the
zero pressure boundary condition at the free surface without the need for special attention
at interior points near that surface. Moreover, the discretization error is four to six times
smaller than the error of classical central differences of the same order and involving the
same number of vertical grid points. Hence, use of the compact scheme allows a very
few number of vertical grid points with relative low numerical dispersion and dissipation,
thereby enhancing the accuracy of the frequency dispersion for relative short waves up to
an acceptable level, see Table 5.1.

98

Chapter 5

At very low vertical resolution (one or two layers), the Keller-box scheme gives good dispersive properties. At high vertical resolutions, however, the standard layout is preferable
because it appears to be more robust while its dispersion characteristics are then usually
sufficiently accurate.
To summarize, for wave simulations with 5 layers or less, the Keller-box scheme using
the box layout is recommended, while for simulations with typically 1020 layers, the
classical central differencing employing the standard layout is preferred. See command
NONHYDrostatic STANdard|BOX.
Related to this choice, it might be useful to specify the preconditioner for solving the Poisson pressure equation. Two options are available: ILU and ILUD. For a robust solution,
the ILU preconditioner is preferred. This choice might be a good one for applications
where high and short waves are involved, or irregular beds with steep slopes (e.g. weir,
breakwater, quay, jetty), or when relatively large number of layers (> 30) are involved. On
the other hand, the ILUD preconditioner is a better choice to get an efficient solution (e.g.
parallel computing). See command NONHYDrostatic ... PREConditioner ILUD|ILU.

5.4.4

Momentum conservation

For simulation of breaking waves, hydraulic jumps and bores, momentum must be conserved. Preference should then be given to a numerical method that conserves momentum,
which ensures that the wave properties under breaking waves are modelled correctly. See
command DISCRET UPW MOM.

5.4.5

Discretization of advection terms in the momentum equations

We make a distinction between horizontal and vertical advection terms of the momentum equations. Moreover, we consider the momentum equations separately, i.e. the
umomentum equation and the wmomentum equation. Note that the vmomentum
equation will be treated as the umomentum equation in exactly the same way. So, we
have four different commands:
DISCRET UPW UMOM ...

DISCRET UPW WMOM H

DISCRET UPW UMOM ...

DISCRET UPW WMOM V

Below, they will be outlined, respectively.
Horizontal advection terms of umomentum equation

Setting up your own command file

99

We consider terms like

u
u
and v
x
y
There are many schemes to approximate these terms. Some of these schemes are accurate
but are prone to generate wiggles typically central schemes. Other schemes generate
a certain amount of numerical diffusion and thus may affect the wave amplitude or wave
energy of particularly short waves typically upwind schemes. Higher order upwind
schemes still generate small wiggles. If this is not desired, a flux-limiting scheme may be
employed instead. Upwind schemes are known to be more stable than central schemes.
u

The default scheme for the considered terms is the well-known second order BDF scheme
(or sometimes called the LUDS scheme). For many applications this is a good choice.
However, in some cases central differences (CDS) is preferred. This is especially the case
when the higher harmonics are involved or when wave breaking is present (the amount of
dissipation of higher harmonics is then important). Note that when the command BREAK is
employed, SWASH will automatically apply central differences to the horizontal advection
terms. If, for some reason, SWASH becomes unstable, possibly due to the growth of
wiggles, the user is then advised to use the BDF scheme.
Other higher upwind schemes (e.g. QUICK) may be used as well, but we did not experience
much differences compared to the BDF scheme. In any case, never apply the first order
upwind scheme to any horizontal advection term, which is usually too numerically diffusive.
Horizontal advection terms of wmomentum equation
The horizontal advection terms of the wmomentum equation are given by
u

w
w
+v
x
y

These terms are usually ignored. For some applications they are negligible small compared
to the vertical pressure gradient. However, they will be automatically taken into account
in the simulation for
applications where vertical flow structures are present (the standard layout for nonhydrostatic pressure is employed), or
applications when wave breaking is important (command BREAK is employed).
If they are included, then the second order BDF scheme will be employed. Sometimes,
central differences may be preferred, for instance, when the higher harmonics are involved.
Vertical advection term of umomentum equation
The vertical advection term of the umomentum equation reads
w

u
z

100

Chapter 5

This term is only included in the computation when more than one layer is chosen (K > 1).
The default scheme for this advection term is the first order upwind scheme. In most
cases, it will not affect the accuracy and it is robust. Especially when there are not so
many vertical layers (2 or 3), this scheme is preferable. If, for instance, many layers are
involved or the higher harmonics are present, then central differences or a higher order
upwind scheme might be a better choice.
Vertical advection term of wmomentum equation
This term is given by

w
z
and is usually ignored (even when K > 1). It will be included automatically if
w

the vertical flow structure is present (the standard layout for non-hydrostatic pressure
is employed), or
the vertical hyperbolic cosine profile for orbital velocities at the boundary is imposed.
This term is by default approximated with the first order upwind scheme. The user is
advised not to alter this.

5.4.6

Moving shorelines

For the calculation of wave runup and rundown on the beach, use of a moving boundary
condition is required. The method used in SWASH to track the moving shoreline amounts
to ensure non-negative water depths. For a one-dimensional case, one can show that if
|u|t
1
x
and if a first order upwind scheme is applied to the global continuity equation, we shall
have non-negative water depths at every time step; see Stelling and Duinmeijer (2003)
for a proof. Hence, flooding never happens faster than one grid size per time step, which
is physically correct. This implies that the calculation of the dry areas does not need
any special feature. For this reason, no complicated drying and flooding procedures are
required. Additionally, the shoreline motion in the swash zone can be simulated in a
natural manner.
For computational efficiency, the model equations are not solved and the velocities are set
to zero when the water depth is below a threshold value (see command SET DEPMIN). Its
default value is 0.05 mm. However, a higher threshold value may be chosen for scaling
reasons. For instance, at the scale of a field site, a value of 1 mm is an appropriate choice.
(As a matter of fact, the value of 0.05 mm is a suitable one under laboratory conditions.)
This will also relax the time step to some extent in case of explicit time stepping. For
a large-scale ocean simulation, a threshold value of 1 cm is probably more effective than

Setting up your own command file

101

0.05 mm. Be careful when choosing a too high value as this may negatively influence mass
conservation.
To achieve second order accuracy, the so-called MUSCL limiter may be employed (see
command DISCRET CORRDEP).
Since the CFL condition, Eq. (5.1), holds this implies that ensuring non-negative water
depths does not lead to a new time step restriction.
For some two-dimensional cases, however, ensuring non-negative water depths might lead to
a time step restriction which appears to be more restrictive than the usual CFL condition.
An example is the case where locally all velocities are directed outward of a grid cell.
Nevertheless, such a case is rarely encountered and usually the time step is restricted by
the Courant number based on the stability criterion.

5.5
5.5.1

Physical parameters
Depth-induced wave breaking

Neither Boussinesq-type wave models nor non-hydrostatic wave-flow models can be directly applied to details of breaking waves, since in both models essential processes such
as overturning, air-entrainment and wave generated turbulence, are absent. But, if only
the macro-scale effects of wave breaking are of interest, such as the effect on the statistics
of wave heights, details of the breaking process can be ignored. By observing that both
spilling and plunging breakers eventually evolve into a quasi-steady bore, where the entire
front-face of the wave is turbulent, a breaking wave becomes analogous to a hydraulic jump.
Consequently, its integral properties (rate of energy dissipation, jump height) are approximately captured by regarding the breaking wave as a discontinuity in the flow variables
(free surface, velocities). Proper treatment of such a discontinuity in a non-hydrostatic
model (conservation of mass and momentum) can therefore be used to determine the energy dissipation of waves in the surf zone; see Section 5.4.4.
Though a vertical coarse resolution (13 layers) is sufficient to describe the wave physics
outside the surf zone (e.g. refraction, shoaling, diffraction, nonlinear wave-wave interactions), dissipation due to wave breaking requires a disproportional high vertical resolution
(1020). A coarse resolution will result in an underestimation of the horizontal velocities near the wave crest, and thus an underestimation of the amplitude dispersion. This
underestimation implies that at low vertical resolution the influence of the non-hydrostatic
pressure gradient is overestimated. Consequently, the stabilizing dispersive effects (i.e. the
non-hydrostatic pressures) postpone the transition into the characteristic saw-tooth shape
and therefore also the onset of dissipation.
By enforcing a hydrostatic pressure distribution at the front of a wave, we can locally
reduce a non-hydrostatic wave-flow model to the nonlinear shallow water equations. The

102

Chapter 5

wave then rapidly transitions into the characteristic saw-tooth shape and, consistent with
the high resolution approach, dissipation is captured by ensuring momentum conservation
over the resulting discontinuity.
The subsequent dissipation is well described by assuming depth uniform velocities and
a hydrostatic pressure distribution. In fact, these assumptions often form the basis to
derive dissipation formulations to account for depth-induced breaking in energy balance
type models, e.g. Battjes and Janssen (1978) among many others. Hence, prescribing a
hydrostatic pressure distribution in the model around the discontinuity should result in
the correct bulk dissipation.
There is no need to assume a hydrostatic pressure distribution if the vertical resolution is
sufficient (i.e. 10 to 20 layers). However, imposing a hydrostatic distribution resolutions at
low resolutions (13 layers) will ensure that, due the absence of dispersive effects, the front
quickly transitions into a bore like shape. Hence, it can be used to initiate the onset of
wave breaking, thus allowing for the use of low-vertical resolutions throughout the domain.
In practice this means that once a grid point is in the front of a breaking wave, vertical
accelerations are no longer resolved, and the non-hydrostatic pressure is set to zero.
A grid point is therefore labelled for hydrostatic computation if the
local surface steepness
/x exceeds a predetermined value . Equivalenty, /t > gd. Once labelled, a
point only becomes non-hydrostatic again if the crest of the wave has passed. This is
assumed to occur when /t < 0. Furthermore, because grid points only become active
again when the crest passes (where w 0), vertical velocities w are set to zero on the front.
To represent persistence of wave breaking, we locally reduce the criterion to if a neighbouring grid point (in x or ydirection) has been labelled for hydrostatic computation.

In this case a point is thus also labelled for hydrostatic computation if /t > gd,
with < . In all other grid points, the computations are non-hydrostatic. Based on
calibration, the default value for the maximum steepness parameter is 0.6, while the
persistence parameter is set to 0.3.
To summarize, in case of a few layers (13) we must apply the command BREAK with optionally different values for and . In case of a sufficient number of layers (>10) nothing
needs to be specified with respect to wave breaking.

5.5.2

Subgrid turbulent mixing

In case of the lateral mixing of momentum, e.g. around the tips of breakwaters and dams,
it is recommended to employ the well-known Smagorinsky subgrid model in which the
mixing length is assumed to be proportional to the typical grid spacing. The default value
for the Smagorinsky constant is 0.2.

Setting up your own command file

5.5.3

103

Vertical turbulent mixing

If the user is interested in the vertical flow structure, it is advised to apply the standard k
turbulence model in order to take into account the vertical mixing. For stability reason, a
background viscosity of 0.0001 m2 /s is recommended (see command SET [backvisc]).

5.5.4

Bottom friction

When waves are travelling over a relatively long distance of order of several kilometres,
the influence of bottom friction becomes more pronounced. Moreover, it may affect long
waves close to the shoreline, e.g. infragravity waves, and nearshore circulations. For wave
simulations, a Manning coefficient of 0.019 is recommended.

5.6

Output quantities, locations and formats

SWASH calculates the time-dependent evolution of the surface elevation, velocities (both
horizontal and vertical), pressure and possibly some turbulence quantities. It would require an excessive amount of disk space to the store these quantities at every grid point
for every time step. Therefore, the user has to make some decisions on what need to be
outputted by SWASH. One can make some tables of time series of surface elevation, velocities, discharges, pressures, turbulent kinetic energy, etc. or time-averaged velocities and
turbulence quantities or wave height and wave-induced setup at specified location points.
Alternatively, one may also output several quantities over the entire domain or a part of
the domain at certain times (snapshots). They are stored as blocks in the Matlab binary
files.
The user must determine the time duration over which the wave parameters, e.g. wave
height and setup, mean current or mean turbulence quantities are computed; see command
QUANT. This corresponds to the final stage of the simulation period, which should be long
enough to establish steady-state conditions. This time duration, which should be long
enough to provide statistically reliable data, equals the duration of the simulation minus
the spin up time of the simulation; see Section 5.4.1.

5.7

The importance of parallel computing

Suppose one wants to simulate a harbour with a typical domain size of 2 2 km2 with
SWASH. In addition, we assume the following typical values:
an offshore water depth of 20 m,
an offshore wave height of 1.5 m,
a wave peak period of 8 s, and

104

Chapter 5

a simulation period of 60 minutes to get reliable wave statistics.

According to the dispersion relation, kd = 1.4 or the wave length of the primary wave is
about 90 m. We choose a grid size of 2 m, being 1/45 of the wave length. Requiring a wave
Courant number of at most 0.5, the associated time step is 0.03 s. To take into account
the higher harmonics in the simulation accurately, two layers will be chosen (see Table 5.2;
the minimum wave period is 3.2 s, which is 2.5 times smaller than the peak period of 8
s). On a present-day computer (2.0 GHz Intel Core 2 processor) SWASH requires about 6
s per grid point and per time step for a two-layer simulation. So, the simulation of our
harbour takes about 17 days on a single processor to complete the run of 60 minutes real
time. This clearly shows the need for parallel computing.
Different parallelization strategies can be considered of which the most popular are:
data parallel programming,
shared memory programming, and
message passing.
Data parallel programming uses automatic parallelizing compilers which enables loop-level
parallelization. Generally, this approach often will not yield high efficiency. The main
reason for this is that a large portion of the existing code is in most cases inherently sequential.
On shared memory platforms with all processors using a single memory, parallelization is
usually done by multithreading with the help of OpenMP compiler directives. A drawback
of this approach is that forcing good parallel performance limits the number of processors
only to about 16.
Obtaining good scalability for relatively large number of processors is usually achieved
through distributed memory parallel machines with each processor having its own private
memory. A popular example of distributed memory architecture is a cluster of Linux PCs
connected via fast networks, since it is very powerful, relatively cheap and nearly available
to all end-users. The conventional methodology for parallelization on distributed computing systems is domain decomposition, which not only achieves benefit from carrying out
the task simultaneously on many processors but also enables a large amount of memory
required. It gives efficient parallel algorithms and is easy to program within message passing environment such as MPICH2.
A parallel version of SWASH with the distributed memory parallelization paradigm using
MPI standard has been developed. The message passings are implemented by a high level
communication library MPICH2. Only simple point-to-point and collective communications have been employed. No other libraries or software are required. For a full threedimensional simulation with a high resolution we expect a good scalable performance.

Setting up your own command file

105

Refer to the example above, numerical computations have been carried out for the full
simulation period of our harbour on 1 through 32 computational cores of our Linux cluster. The results show a super linear speedup of up to a factor 8.6 on 8 cores, but then it
levels off to a factor of 26 on 32 cores. As such, the computing time has been reduced to
15 hours per 60 minutes to be simulated.

106

Chapter 5

Appendix A
Definitions of variables
In SWASH a number of variables are used in input and output. The definitions of these
variables are mostly conventional.
Hs

Significant wave height, in meters, defined as

Hs = 4

qR

E(f )df

where E(f ) is the variance density spectrum and f is the frequency.

With respect to output, this quantity is computed as four times the
standard deviation of the surface elevation over the duration [dur]
(see command QUANTITY) in the final stage of the simulation, which
should be long enough to provide statistically reliable wave height.
The simulation period should therefore be long enough to establish
steady-state conditions.
Hrms

RMS wave height, in meters, defined as

Hrms =

Tp
Tm01

2Hs

Peak period, in seconds, defined as inverse of the frequency at which

the variance density spectrum is a maximum.
Mean wave period, in seconds, defined as
Tm01

Directional spread

1
2

R
R
=

E(f )df
f E(f )df

The directional distribution of incident wave energy is given by

D() = A cosm () for all frequencies. The power m is related to
the one-sided directional spread as given in Table A.1.

107

108
Cr

Appendix A
Courant number defined as follows:
Cr = t

gd +

u2 + v 2

 q

1
x2

1
y 2

with t the time step, x and y the grid sizes in x and ydirection,
respectively, and u and v the velocity components in x and ydirection.
VEL

Current velocity components in x and ydirection of the problem

coordinate system, except in the case of output with BLOCK command in
combination with command FRAME, where x and y relate to the xaxis
and yaxis of the output frame.

MVEL

Mean or time-averaged velocity components in x and ydirection of

the problem coordinate system, except in the case of output with BLOCK
command in combination with command FRAME, where x and y relate
to the xaxis and yaxis of the output frame. Time-averaging is carried
out over the duration [dur] (see command QUANTITY) in the final stage
of the simulation.

WIND

Wind velocity components in x and ydirection of the problem

coordinate sytem, except in the case of output with BLOCK command in
combination with command FRAME, where x and y relate to the xaxis
and yaxis of the output frame.

TIME

Full date-time string.

TSEC

Time in seconds with respect to a reference time (see command QUANTITY).

Cartesian convention The direction is the angle between the vector and the positive xaxis,
measured counterclockwise. In other words: the direction where the
waves are going to or where the wind is blowing to.
Nautical convention The direction of the vector from geographic North measured
clockwise. In other words: the direction where the waves are coming
from or where the wind is blowing from.

Definitions of variables

Table A.1: Directional distribution.

m directional spread (in o )
1.
37.5
2.
31.5
3.
27.6
4.
24.9
5.
22.9
6.
21.2
7.
19.9
8.
18.8
9.
17.9
10.
17.1
15.
14.2
20.
12.4
30.
10.2
40.
8.9
50.
8.0
60.
7.3
70.
6.8
80.
6.4
90.
6.0
100.
5.7
200.
4.0
400.
2.9
800.
2.0

109

110

Appendix A

Appendix B
Command syntax
B.1

Commands and command schemes

The actual commands of the user to SWASH must be given in one file containing all
commands. This file is called the command file. It must be presented to SWASH in
ASCII. It is important to make a distinction between the description of the commands in
this User Manual and the actual commands in the command file. The descriptions of the
commands in this User Manual are called command schemes. Each such command scheme
includes a diagram and a description explaining the structure of the command and the
meaning of the keyword(s) and of the data in the command. The proper sequence of the
commands is given in Section 4.2.

B.2

Command

B.2.1

Keywords

Each command instructs SWASH to carry out a certain action which SWASH executes
before it reads the next command. A command must always start with a keyword (which
is also the name of the command) which indicates the primary function of that command;
see list in Section 4.1). A simple command may appear in its command scheme as:
KEYword data
A command may contain more than one keyword (which refines the instructions to SWASH),
e.g.,
KEY1word KEY2word data
where KEY2word is the second keyword.
111

112

Appendix B

Spelling of keywords
In every command scheme, keywords appear as words in both lower- and upper-case letters.
When typing the command or keyword in the command file, the user must at least copy
literally the part with upper-case letters. SWASH reads only this part. SWASH is case
insensitive except for one instance (character strings), see below. When typing the keyword
in the command file, any extension of the part with upper-case letters is at the users
discretion as long as the extension is limited to letters or digits, as well as the characters
and . So, in the first command outlined above one may write: KEY or KEYW or KEYword
or keyhole, etc., whereas with the abovementioned second command scheme, key1 KEY2
data may appear in the command file.
In the command file
a keyword is closed by a blank or one of the following characters = or :
a keyword is not enclosed by square brackets or quotes,
a keyword followed by a comma (,) is interpreted as a keyword followed by an empty
data field (see below).
Required and optional keywords
All keywords in a command are required except when an option is available.
Optional keywords are indicated in the command scheme with the following signs enclosing
the keywords concerned:
|

KEY1word ...... data ....... |

<

>
|

KEY2word ...... data ....... |

For the above example it may appear as:

KEY1word

KEY2word data |

KEY3word data |

<

>

In case the user does not indicate an option in a command, SWASH chooses the alternative
indicated with an arrow (->) appearing in the command scheme (the default option). In
the above example, it may appear as:
|
KEY1word

KEY2word data |

<

>
| -> KEY3word data |

where KEY3WORD is the default option.

Command syntax

113

Repetitions of keywords and/or other data

The use of keywords is sometimes repetitive, e.g. in a sequence of data and keywords
containing many locations in x, yspace. In such a case, the command scheme indicates
this repetitive nature by placing the keywords (and data) concerned between angle brackets
< >. For instance,
KEY1word <data KEY2word data>
In the actual command in the command file the user must give such a sequence. It ends
with either
end of line
a keyword other than the ones mentioned in the repetition group
the character / or ;
If more than one line is required for a command, the user may continue on the next line as
described in Section B.4. The repetition may consist of one instance (in fact, no repetition
at all).

B.2.2

Data

Most commands contain data, either character data or numerical data.

Character data and numerical data
Character data (character strings) are represented in the command schemes by names,
enclosed in quotes ( ).
Numerical data are represented in the command schemes by names enclosed in square
brackets ([ ]).
As a rule, an error message will result if numerical data is given where character data
should be given.
Spelling of data
Character data are represented as character strings (sequence of characters and blanks)
between quotes (in the command scheme and in the command file). SWASH interprets an
end of line as an end quote (a character data field can therefore never extend over more
than one line).
In a command scheme the character string is always a name (which is placed between
quotes as indicated). In the command file such a name can be entered in two ways:

114

Appendix B

Replace the name by another character string at the users discretion (between quotes;
this is the only occurrence where SWASH is case sensitive; e.g. for text to appear in
a plot.
Example:
command scheme: KEYword City data
command file: KEY Amsterdam data
Copy the name of the variable (without the quotes) literally followed by an = sign
and a name at the users discretion (between quotes). SWASH interprets the copied
name in the command file as a keyword with all the characteristics of a keyword such
as ending a sequence of optional data (see below). As with other keywords the name
of the variable is case-insensitive.
Example:
command scheme: KEYword City data
command file: KEY city=Amsterdam data
As a rule, an error message will result if numerical data is given where character data
should be given.
Numerical data are simple numbers, e.g. 15 or 7 (integer data), or 13.7 or 0.8E4 (real
data). Whether or not integer number or real number should be given by the user is
indicated in the description of the command scheme.
Note that a decimal point is not permitted in an integer number. On the other hand, an
integer number is accepted by SWASH where a real number should be given.
In a command scheme, the number is always indicated with a name (which is placed
between square brackets). In the command file such a name can be entered in two ways:
Replace the name by a number (not between square brackets).
Example:
command scheme: KEYword [nnn]
command file: KEY 314
Copy the name of the variable (without the quotes) literally followed by an = sign
and the number (not between square brackets). SWASH interprets the copied name
in the command file as a keyword with all the characteristics of a keyword such as
ending a sequence of optional data (see below). As with other keywords the name of
the variable is case-insensitive.
Example:
command scheme: KEYword [nnn]
command file: KEY nnn=314

Command syntax

115

Required data and optional data

All data must be given by the user in the command file in the same order as they appear
in the command scheme. They are separated by blanks or commas.
Required data (indicated in the description of each individual command) must be given
explicitly as character string or numbers.
Optional data are indicated
(a) in the text of each individual command or
(b) for sets of data: in parenthesis around the data concerned
( data )
For example:
KEY1word KEY2word name ([nnn] [mmm]) [zzz]
or
(c) some optional data are indicate in the same way as optional keywords are indicated:
| .....data.....|
<
>
| .....data.....|
Optional data of the kind (a) or (b) may be omitted by giving blanks between commas
(SWASH then substitutes reasonable default values). If after a required datum all data is
optional (till the next keyword or the next end-of-line), then the commas may be omitted
too. Optional data of the kind (c) are to be treated in the same way as optional keywords.

B.3

Command file and comments

All text after one $ or between two $ signs on one line in the command file is ignored by
SWASH as comment. Such comments may be important to the user e.g., to clarify the
meaning of the commands used. In fact, this option has been used to create the edit file
swash.edt (see Appendix C). Anything appearing after two $ signs is not interpreted as
comment, but again as data to be processed (possibly interrupted again by $ or two $
signs). Alternatively, the exclamation mark ! can be used as comment sign. Everthing
behind a ! is interpreted as comment, also if ! or $ are in that part of the input line.

116

B.4

Appendix B

End of line or continuation

A command in the command file may be continued on the next line if the previous line
terminates with a continuation mark & or (underscore).

Appendix C
File swash.edt
Below the file swash.edt is presented in which all the commands that can be used with
SWASH are specified.

!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!

PROJECT

name nr
title1
title2
title3

SET [level] [nor] [depmin] [maxmes] [maxerr] [seed]

[grav] [rhowat] [temp] [salinity] [dynvis] [rhoair] [rhosed]
[cdcap] [prmean] [backvisc] [kappa]
CORIolis CARTesian|NAUTical
[printf] [prtest] [outlev]
MODE

DYNamic

COORDinates

CGRID

&
&
&
&

/ -> TWODimensional
\
ONEDimensional

/ -> CARTesian
\ SPHErical

CCM|QC

/ REGular [xpc] [ypc] [alpc] [xlenc] [ylenc] [mxc] [myc]

\ CURVilinear [mxc] [myc] (EXC [xexc] [yexc])

\
/

&

REPeating X|Y
VERTical [kmax] < [thickness] M|PERC >
INPgrid

BOT|WLEV|CUR|VX|VY|FRic|WInd|WX|WY|PRessure|POROS|PSIZ|HSTRUC|
NPLAnts|SALinity|TEMPerature|SEDiment
117

&
&

118
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!

Appendix C

| REG [xpinp] [ypinp] [alpinp]

[mxinp] [myinp]

[dxinp] [dyinp] |

<

>
| CURVilinear STAGgered
(EXCeption

[excval])

&

(NONSTATionary [tbeginp] [deltinp] SEC|MIN|HR|DAY [tendinp])

(NONUNIForm

READinp

&

&

[kmax])

BOTtom|WLEVel|CURrent|FRic|WInd|PRessure|COOR|POROS|PSIZ|HSTRUC| &
NPLAnts|SALinity|TEMPerature|SEDiment
&

[fac]

<

| fname1
|
SERIes fname2 >
| LAYers fname3 |

[idla] [nhedf] ([nhedt]) (nhedvec])

&

FREE | FORMAT form | [idfm] | UNFORMATTED

INITial

| -> CONstant [wlev] [vx] [vy] [tke] [epsilon]

|
<
ZERO
|
|
STEAdy

|
BOUnd SHAPespec <

PM
|
-> JONswap [gamma] > SIG|RMS
|
TMA
|

/ -> SIDE

N|NW|W|SW|S|SE|E|NE

PEAK|MEAN

CCW|CLOCKWise

DSPR POW|DEGR

BOUndcond <

>

&

BTYPe WLEV|VEL|DISCH|RIEMann|WEAKrefl|SOMMerfeld|OUTFlow

&

LAYer [k] | HYPerbolic | LOGarithmic

&

SMOOthing [period] SEC|MIN|HR|DAY

&

SEGment

/ -> XY
\
IJ

< [x]
< [i]

[y] >
[j] >

\
/

File swash.edt
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!

119

ADDBoundwave

| UNIForm
|
|

&

| FOURier
| REGular
< SPECTrum
| SERIes
| SPECFile

[azero] < [ampl] [omega] [phase] >

[h] [per] [dir]
[h] [per] [dir] [dd] [cycle] SEC|MIN|HR|DAY
fname [itmopt]
fname [cycle] SEC|MIN|HR|DAY

<
|
|
|
|
|
|
| VARiable <
|
|

FOURier
REGular
SPECTrum
SERIes
SPECFile
SPECSwan

< [len]
< [len]
< [len]
< [len]
< [len]
fname

&
[azero] < [ampl] [omega] [phase] > >
[h] [per] [dir] >
[h] [per] [dir] [dd] [cycle] S|MI|HR|DA >
fname [itmopt] >
fname [cycle] SEC|MIN|HR|DAY >
[cycle] SEC|MIN|HR|DAY

SPONgelayer LEft|RIght|LOwer|UPper [width]

POROsity

WIND

[size] [height] [alpha0] [beta0]

| -> CONstant [cd]

|
|
|
|
CHARNock [beta] [height]
|
|
|
|
LINear [a1] [a2] [b] [wlow] [whigh] |
|
|
[vel] [dir] <
WU
> REL [alpha]
|
|
|
GARRatt
|
|
|
|
SMIthbanke
|
|
|
|
FIT
|

|
|
|
|
|
FRICtion

<

LINear [k]
CONstant [cf]
CHEZy [cf]

120
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!

Appendix C
| -> MANNing [cf]
|
|
| -> SMOOTH
|
LOGlaw <
|
ROUGHness [h]

| -> CONstant [visc]

|
| -> Horizontal <
SMAGorinsky [cs]
|
|
|
|
MIXing [lm]
VISCosity <
|
|
|

VEGEtation

TRANSPort

Vertical

< [height] [diamtr] [nstems] [drag] >

| -> Sec
[diff] [retur] <
MIn
|
HR
|
DAy
DENSity Y|N

BREaking

KEPS [cfk] [cfe]

|
> [fall] [size] [snum]

&

|
|

[alfa] [crsn] [cp] [ek]

[alpha] [beta] [nufac]

|
|
NONHYDrostatic

<

STAndard

|
|

-> BOX
|
|

> [theta]

&

|
DEPthaveraged |

SOLVer [rhsaccur] [initaccur] [maxiter] [relax] [precfq]

PREConditioner

ILUD|ILU

&

121

File swash.edt
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!

|
| UMOM
|
|
| UPWind <
|
| WMOM
DISCRETization <
|
|
| CORRdep
|
| TRANSPort / ->
|
\

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<

MOMentum|HEAD

/ -> Horizontal
\
Vertical

/ -> Horizontal
\
Vertical

>
|
|
|
|
|

Horizontal
Vertical

NONe
FIRstorder
HIGherorder [kappa]
| -> SWEBy [phi]
|
LIMiter < RKAPpa [kappa]
|
| PLKAPpa [kappa] [mbound]
FROmm
-> BDF | LUDs

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

QUIck
|
|
|
|
|
|
|
|
|
|
|
|
|
|

CUI
MINMod
SUPerbee
VANLeer
MUScl
KORen
SMArt

|
|
|
|

>
|
|
|
|
|
|
|
|
|
|
|
|
|
|

&

122
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!

Appendix C

| -> EXPL [cfllow] [cflhig]

TIMEI METH <

> &
|

IMPL [thetac] [thetas] SOLVer [tol] [maxiter] [weight] |

VERTical [thetau] [thetaw] [thetat]

FRAME

sname

[xpfr] [ypfr] [alpfr] [xlenfr] [ylenfr] [mxfr] [myfr]

GROUP

sname

SUBGRID [ix1] [ix2] [iy1] [iy2]

CURVE

sname

[xp1] [yp1]

RAY

rname

[xp1] [yp1] [xq1] [yq1]

< [int] [xp] [yp] [xq]

ISOLINE sname

rname

POINTS

< [xp]

sname

QUANTity

<

|...|
>
|...|

< [int]

DEPTH|BOTTOM
[yp]

short

>

long

[xp]

[yp] >
&
[yq]

>

[dep]
FILE fname

[lexp]

[hexp]

[excv]

[dur] SEC|MIN|HR|DAY

[ref]

&

[depth]

&

/ -> PROBLEMcoord \
\ FRAME
/
OUTPut OPTions
BLOCK

comment

(TABle [field])

(BLOck

[ndec]

[len])

sname HEAD | NOHEAD fname (LAY-OUT [idla])

< TSEC|XP|YP|DIST|DEP|BOTL|WATL|VMAG|VDIR|VEL|VKSI|VETA|
PRESS|NHPRES|QMAG|QDIR|DISCH|QKSI|QETA|WMAG|WDIR|WIND|
FRC|USTAR|UFRIC|HRUN|BRKP|ZK|HK|VMAGK|VDIRK|VELK|VKSIK|
VETAK|VZ|VOMEGA|QMAGK|QDIRK|DISCHK|QKSIK|QETAK|PRESSK|
NHPRSK|TKE|EPS|VISC|HS|HRMS|SETUP|MVMAG|MVDIR|MVEL|MVKSI|
MVETA|MVMAGK|MVDIRK|MVELK|MVKSIK|MVETAK|MTKE|MEPS|MVISC|
SAL|TEMP|SED|MSAL|MTEMP|MSED|SALK|TEMPK|SEDK|MSALK|MTEMPK|
MSEDK [unit] >

&
&
&
&
&
&
&
&
&

123

File swash.edt
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!
!

(OUTPUT [tbegblk] [deltblk] SEC|MIN|HR|DAY)

TABLE

sname HEAD | NOHEAD | STAB | SWASH | IND fname

< TIME|TSEC|XP|YP|DIST|DEP|BOTL|WATL|VMAG|VDIR|VEL|VKSI|VETA|
PRESS|NHPRES|QMAG|QDIR|DISCH|QKSI|QETA|WMAG|WDIR|WIND|FRC|
USTAR|UFRIC|HRUN|BRKP|ZK|HK|VMAGK|VDIRK|VELK|VKSIK|VETAK|VZ|
VOMEGA|QMAGK|QDIRK|DISCHK|QKSIK|QETAK|PRESSK|NHPRSK|TKE|EPS|
VISC|HS|HRMS|SETUP|MVMAG|MVDIR|MVEL|MVKSI|MVETA|MVMAGK|MVDIRK|
MVELK|MVKSIK|MVETAK|MTKE|MEPS|MVISC|SAL|TEMP|SED|MSAL|MTEMP|
MSED|SALK|TEMPK|SEDK|MSALK|MTEMPK|MSEDK >
(OUTPUT [tbegtbl] [delttbl] SEC|MIN|HR|DAY)

/ -> IJ < [i] [j] >

TEST [itest] [itrace] POINTS <

COMPute

STOP

> fname
XY < [x] [y] >

| -> Sec
[tbegc] [deltc] <
MIn
|
HR
|
DAy

|
> [tendc]
|
|

&
&
&
&
&
&
&
&

124

Bibliography
[1] Smit, P., Zijlema, M. and Stelling, G., 2013. Depth-induced wave breaking in a nonhydrostatic, near-shore wave model. Coast. Engng., 76: 116.
[2] Stelling, G.S. and Duinmeijer, S.P.A., 2003. A staggered conservative scheme for every
Froude number in rapidly varied shallow water flows. Int. J. Numer. Meth. Fluids, 43:
13291354.
[3] Stelling, G. and Zijlema, M., 2003. An accurate and efficient finite-difference algorithm
for non-hydrostatic free-surface flow with application to wave propagation. Int. J.
Numer. Meth. Fluids, 43: 123.
[4] SWASH Implementation manual. Delft University of Technology, Environmental
Fluid Mechanics Section, available from http://swash.sourceforge.net (Version 2.00,
January 2014).
[5] SWAN Programming rules. Delft University of Technology, Environmental Fluid
Mechanics Section, available from http://www.swan.tudelft.nl (Version 1.3, August
2006).
[6] Zijlema, M. and Stelling, G.S., 2005. Further experiences with computing nonhydrostatic free-surface flows involving water waves. Int. J. Numer. Meth. Fluids,
48: 169197.
[7] Zijlema, M. and Stelling, G.S., 2008. Efficient computation of surf zone waves using
the nonlinear shallow water equations with non-hydrostatic pressure. Coast. Engng.,
55: 780790.
[8] Zijlema, M., Stelling, G. and Smit, P., 2011. SWASH: An operational public domain
code for simulating wave fields and rapidly varied flows in coastal waters. Coast.
Engng., 58: 9921012.

125

Index
absorbing-generating boundary condition, 15 density, 47, 1013, 25, 26, 3234, 37, 48, 56,
5860, 79, 80, 107
advection, 14, 64, 98100
depth-averaged mode, 3, 8, 14, 5254, 57,
baroclinic forcing, 6, 8, 13
61, 62, 74, 90
bathymetry, 9, 12, 13, 85, 87, 88, 91, 92
diffraction, 6, 91, 101
BDF, 64, 65, 99
diffusivity, 5658
BLOCK, 75
directional spreading, 15, 43, 47, 48, 93, 107,
bottom friction, 5, 6, 916, 19, 2123, 3134,
109
37, 38, 41, 46, 50, 53, 54, 57, 60, 61, discharge, 15, 20, 45, 79, 80, 103
68, 69, 71, 79, 87, 88, 91, 92, 96, 103 DISCRETIZATION, 62
BOUND SHAPE, 42
dispersion relation, 5, 6, 8, 58, 8890, 97, 98,
boundary condition, 1, 5, 9, 10, 12, 1416,
101, 104
19, 22, 26, 28, 4042, 4449, 56, 57,
flux limiter, 6, 13, 14, 17, 57, 58, 6365, 99
87, 9197, 100
Fourier series, 15, 25, 45, 46
BOUNDCOND, 43
FRAME, 68
BREAKING, 59
frequency dispersion, 58, 42, 46, 48, 8891,
Cartesian coordinates, 5, 9, 10, 16, 21, 26
9395, 97, 107
28, 34, 35, 45, 46, 52, 6874, 79, 80, FRICTION, 53
82, 85, 108
Froude number, 119
CGRID, 28
GROUP, 69
Chezy formula, 37, 42, 53, 54
circulation, 4, 5, 8, 32, 51, 60, 66, 103
harbour, 4, 12, 51, 104, 105
coastal region, 4, 6, 8, 51, 119
COMPUTE, 85
INITIAL, 42
convergence, 61, 66
INPGRID, 31
COORDINATES, 27
INPTRANS, 40
Coriolis force, 4, 6, 26
instability, 16
Courant number, 9, 12, 17, 66, 67, 96, 97, inundation, 73, 74, 82
101, 104, 108
irregular wave breaking, 16, 46, 49, 59, 93,
CURVE, 70
98
curvilinear grid, 5, 10, 11, 15, 21, 22, 2830, ISOLINE, 71
33, 35, 37, 44, 68, 69, 87, 88
Jonswap spectrum, 15, 90, 93, 94
dam, 3, 4, 7, 9, 12, 22, 33, 52, 55, 92, 103,
114
latitude, 10, 27, 85
126

127
leapfrog scheme, 5
logarithmic wall-law, 46, 53, 54, 58
longitude, 10, 27, 85

runup, 3, 6, 7, 73, 79, 82, 100

salinity, 6, 8, 13, 25, 26, 40, 41, 56, 57, 64,

74, 7981
salt intrusion, 46, 13, 14, 57, 58
Manning formula, 37, 53, 54, 103
semi-implicit, 5, 66, 67
mixing length, 5, 7, 26, 5557, 103
SET, 24
MODE, 27
multi-layered mode, 3, 8, 31, 41, 5254, 61, shoaling, 6, 7, 101
shoreline, 3, 68, 12, 100, 103
62, 66
Sommerfeld radiation condition, 15, 46, 96
MUSCL limiter, 64, 65, 101
spectrum, 15, 16, 25, 43, 46, 48, 49, 88, 90,
Nautical convention, 26, 46, 52, 74, 108
9395, 107
Nikuradse roughness height, 37, 53, 54
spherical coordinates, 5, 9, 10, 16, 21, 25,
NONHYDROSTATIC, 60
2730, 34, 35, 48, 6872, 81, 85
nonhydrostatic, 22
sponge layer, 16, 22, 49, 50, 87, 95
SPONGE LAYER, 49
OUTPUT, 74
stationary, 10, 16, 21, 32, 33, 35, 38, 40, 48,
49, 56, 82, 83
partial reflection, 6, 50, 92
steepness, 59, 102
periodic, 16, 29, 96
STOP, 86
Pierson-Moskowitz, 15, 43, 93
subgrid, 7, 12, 33, 69, 70, 92, 103
plant, 55, 56
surface elevation, 36, 8, 15, 4749, 52, 53,
POINTS, 72
5759, 69, 74, 79, 82, 87, 91, 93, 94,
POROSITY, 50
97, 101103, 107, 119
porosity, 1013, 19, 21, 22, 3234, 37, 50, 91,
suspended sediment, 58, 13, 14, 41, 56, 57,
92
59, 64, 7981
porous structure, 10, 12, 3234, 37, 50
pressure, 3, 5, 7, 8, 1013, 17, 19, 20, 22,
26, 3234, 37, 5962, 69, 79, 80, 89, TABLE, 83
temperature, 6, 13, 25, 40, 41, 56, 64, 7981
97103, 119
TEST, 84
PROJECT, 24
TIME INTEGRATION, 65
propagation, 5, 6, 51, 60, 64, 90, 91, 119
TMA spectrum, 15, 43, 93
transmission, 6, 33, 50, 92
QUANTITY, 72
TRANSPORT, 56
radiation, 6, 15, 46, 95, 96
transport, 3, 68, 10, 13, 14, 21, 22, 40, 41,
RAY, 70
56, 58, 6467
READGRID COORDINATES, 29
triad, 6, 7
READINP, 36
turbidity flow, 7, 13, 58
READTRANS, 41
turbulence model, 6, 7, 9, 22, 42, 73, 83, 101,
rectilinear grid, 5, 14, 28, 29, 37, 46, 47, 69
103
refraction, 6, 71, 101
Van Leer limiter, 58, 64, 65
repeat, 23, 29, 56, 94, 96
VEGETATION, 55
Riemann invariant, 15, 45
vegetation, 3, 7, 1012, 22, 3234, 37, 55, 56
rubble mound, 33, 92

128
VERTICAL, 30
VISCOSITY, 54
viscosity, 5, 9, 22, 26, 55, 56, 58, 66, 80, 81,
103
water level, 36, 813, 15, 16, 19, 20, 25, 26,
31, 33, 37, 42, 45, 46, 5053, 5760,
6467, 71, 74, 79, 82, 88, 9093, 95,
97, 98, 100104, 119
wave breaking, 313, 15, 16, 22, 25, 26, 29,
31, 43, 46, 48, 49, 51, 53, 55, 5961,
64, 66, 71, 73, 74, 80, 82, 87104,
107, 108, 119
weakly reflective, 45, 49, 95
WIND, 50
wind, 513, 15, 17, 19, 22, 26, 3234, 37,
5153, 6366, 79, 99, 100, 108