CoherensBook PDF

COHERENS
A Coupled Hydrodynamical-Ecological Model

for Regional and Shelf Seas
User Documentation
Version 2.3, April 2012
Patrick Luyten
Royal Belgian Institute of Natural Sciences (RBINS-MUMM)

Gulledelle 100, 1200 Brussels, Belgium
Addresses
Patrick Luyten
Royal Belgian Institute of Natural Sciences (RBINS-MUMM)
Gulledelle 100
B-1200 Brussels
Belgium
Marcelo Heredia Gomez and Ivan Rocabado

ANTEA Group
Poortakkerstraat 41
B-9051 Gent
Belgium
COHERENS license agreement
c 2011 MUMM http://www.mumm.ac.be/coherens/
Copyright
Everyone is permitted to copy and distribute verbatim copies of this license

document, but changing is not allowed.
COHERENS is a open-source multi-purpose hydrodynamical model, orig-

inally developed, in the frame of European and national programs, by the
Management Unit of the North Sea Mathematical Models (MUMM), a de-
partment of the Royal Belgian Institute of Natural Sciences (RBINS). Lead-
ing author is Patrick Luyten.
In order to boost the COHERENS users community, the COHERENS Li-
cense guarantees users the freedom to receive and run COHERENS free of
charge. It also precises the terms and conditions to modify and redistribute
COHERENS. Basically, at the difference of other free Licenses as the GNU
General Public License, this License prevents any commercial exploitation of
COHERENS such as
1. Charging any price for redistributing the original and/or the modified
versions of COHERENS.
2. Including COHERENS in other programs or packages for which fees are

requested.
However, COHERENS commercial exploitation remains possible in the frame-

work of specific licenses that must be agreed by all COHERENS copyright
holder(s).
The License also requests to make reference to the COHERENS doc-
umentation in any scientific publication presenting results obtained with
COHERENS:
Luyten, P. 2011. COHERENS — A Coupled Hydrodynamical-

Ecological Model for Regional and Shelf Seas: User Documen-
tation. Version 2.1.2. RBINS-MUMM Report, Royal Belgian
Institute of Natural Sciences.
The precise terms and conditions for copying, distributing and modifying
COHERENS are given in Annex.
Contents
I Introductory Manual 1
1 General Overview 3
1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Description of the program . . . . . . . . . . . . . . . . . . . . 5
1.3 User experience . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.3.1 Programming experience . . . . . . . . . . . . . . . . . 9
1.3.2 Scientific background . . . . . . . . . . . . . . . . . . . 9
1.4 Contents of the documentation . . . . . . . . . . . . . . . . . 10
1.4.1 Structure . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.4.2 Suggestions for reading . . . . . . . . . . . . . . . . . . 12
2 Getting Started 15
2.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.2 Compilation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.2.1 compilers.cmp . . . . . . . . . . . . . . . . . . . . . . . 17
2.2.2 options.cpp . . . . . . . . . . . . . . . . . . . . . . . . 19
2.2.3 Testing compilation . . . . . . . . . . . . . . . . . . . . 20
2.3 Installing and running a test case . . . . . . . . . . . . . . . . 20
2.4 Installing a user application . . . . . . . . . . . . . . . . . . . 24
2.5 Running an application with external libraries . . . . . . . . . 25
2.5.1 Parallel application . . . . . . . . . . . . . . . . . . . . 25
2.5.2 Using netCDF output format . . . . . . . . . . . . . . 25
2.6 Setting up a user application . . . . . . . . . . . . . . . . . . . 26
3 Graphical display 29
3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.2 COHERENS output files . . . . . . . . . . . . . . . . . . . . . 30
3.3 Visualisation of model results . . . . . . . . . . . . . . . . . . 31
3.3.1 FERRET . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.3.2 NCView . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.3.3 MATLAB . . . . . . . . . . . . . . . . . . . . . . . . . . 33
i
ii CONTENTS
II Model description 35
4 Physical model 37
4.1 Model coordinates . . . . . . . . . . . . . . . . . . . . . . . . 37
4.1.1 Coordinate systems . . . . . . . . . . . . . . . . . . . . 37
4.1.2 Coordinate transforms in the horizontal . . . . . . . . . 38
4.1.3 Coordinate transforms in the vertical . . . . . . . . . . 40
4.1.3.1 σ-coordinates . . . . . . . . . . . . . . . . . . 40
4.1.3.2 generalised σ-coordinates . . . . . . . . . . . 41
4.1.3.3 normalised vertical coordinate . . . . . . . . . 44
4.2 Basic model equations . . . . . . . . . . . . . . . . . . . . . . 45
4.2.1 3-D mode equations . . . . . . . . . . . . . . . . . . . 45
4.2.1.1 Cartesian coordinates . . . . . . . . . . . . . 45
4.2.1.2 transformed coordinates . . . . . . . . . . . . 48
4.2.2 2-D mode equations . . . . . . . . . . . . . . . . . . . 51
4.2.3 Equation of state . . . . . . . . . . . . . . . . . . . . . 54
4.3 Model equations on reduced grids . . . . . . . . . . . . . . . . 57
4.3.1 Water column (1-D) mode . . . . . . . . . . . . . . . . 57
4.3.2 Depth-averaged (2-D) mode . . . . . . . . . . . . . . . 57
4.4 Turbulence schemes . . . . . . . . . . . . . . . . . . . . . . . . 58
4.4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . 58
4.4.2 Algebraic schemes . . . . . . . . . . . . . . . . . . . . . 62
4.4.2.1 Richardson number dependent formulations . 62
4.4.2.2 flow-dependent formulations . . . . . . . . . . 64
4.4.3 RANS models . . . . . . . . . . . . . . . . . . . . . . . 65
4.4.3.1 general form of the RANS equations . . . . . 66
4.4.3.2 parameterisation of the RANS equations . . 68
4.4.3.3 stability functions . . . . . . . . . . . . . . . 70
4.4.3.4 solution methods . . . . . . . . . . . . . . . . 76
4.4.3.5 mixing length formulations . . . . . . . . . . 79
4.4.3.6 background mixing . . . . . . . . . . . . . . . 80
4.5 Astronomical tidal force . . . . . . . . . . . . . . . . . . . . . 86
4.6 Solar radiation . . . . . . . . . . . . . . . . . . . . . . . . . . 94
4.7 Surface boundary conditions . . . . . . . . . . . . . . . . . . . 96
4.7.1 General form . . . . . . . . . . . . . . . . . . . . . . . 96
4.7.2 Currents . . . . . . . . . . . . . . . . . . . . . . . . . . 96
4.7.3 Temperature . . . . . . . . . . . . . . . . . . . . . . . . 97
4.7.4 Salinity . . . . . . . . . . . . . . . . . . . . . . . . . . 98
4.7.5 Turbulence . . . . . . . . . . . . . . . . . . . . . . . . 99
4.7.6 Water column mode . . . . . . . . . . . . . . . . . . . 101
4.8 Surface drag and exchange coefficients . . . . . . . . . . . . . 101
CONTENTS iii
4.8.1 Neutral formulations . . . . . . . . . . . . . . . . . . . 101

4.8.2 Kondo’s stratified formulation . . . . . . . . . . . . . . 103
4.8.3 Stratified case from Monin-Obukhov theory . . . . . . 104
4.9 Bottom boundary conditions . . . . . . . . . . . . . . . . . . . 109
4.9.1 General form . . . . . . . . . . . . . . . . . . . . . . . 109
4.9.2 Currents . . . . . . . . . . . . . . . . . . . . . . . . . . 110
4.9.3 Temperature and salinity . . . . . . . . . . . . . . . . . 112
4.9.4 Turbulence . . . . . . . . . . . . . . . . . . . . . . . . 112
4.10 Lateral boundary conditions . . . . . . . . . . . . . . . . . . . 113
4.10.1 Open boundary conditions for the 2-D mode . . . . . . 113
4.10.2 Open boundary conditions for the 3-D mode . . . . . . 119
4.10.2.1 baroclinic currents . . . . . . . . . . . . . . . 119
4.10.2.2 3-D scalars . . . . . . . . . . . . . . . . . . . 120
4.10.2.3 turbulence variables . . . . . . . . . . . . . . 121
4.10.3 Relaxation conditions . . . . . . . . . . . . . . . . . . . 121
4.10.4 Coastal boundaries . . . . . . . . . . . . . . . . . . . . 122
4.11 Initial conditions . . . . . . . . . . . . . . . . . . . . . . . . . 122
4.12 Harmonic analysis . . . . . . . . . . . . . . . . . . . . . . . . . 123
4.12.1 Residuals, amplitudes and phases . . . . . . . . . . . . 123
4.12.2 Tidal ellipses . . . . . . . . . . . . . . . . . . . . . . . 126
5 Numerical methods 129

5.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
5.2 Model grid and discretisations . . . . . . . . . . . . . . . . . . 131
5.2.1 Grid nodes and indexing system . . . . . . . . . . . . . 131
5.2.2 Open boundaries . . . . . . . . . . . . . . . . . . . . . 134
5.2.3 Conventions . . . . . . . . . . . . . . . . . . . . . . . . 135
5.2.4 Space discretisation . . . . . . . . . . . . . . . . . . . . 136
5.2.5 Time discretisation . . . . . . . . . . . . . . . . . . . . 137
5.3 Momentum equations . . . . . . . . . . . . . . . . . . . . . . . 140
5.3.1 General procedure . . . . . . . . . . . . . . . . . . . . 140
5.3.1.1 predictor step . . . . . . . . . . . . . . . . . . 142
5.3.1.2 depth-integrated equations . . . . . . . . . . . 144
5.3.1.3 corrector step . . . . . . . . . . . . . . . . . . 146
5.3.1.4 vertical current . . . . . . . . . . . . . . . . . 146
5.3.2 Advection schemes and time discretisation . . . . . . . 147
5.3.2.1 introduction . . . . . . . . . . . . . . . . . . . 147
5.3.2.2 mode splitting scheme for the 3-D momentum
equations . . . . . . . . . . . . . . . . . . . . 156
5.3.2.3 mode splitting scheme for the 2-D momentum
equations . . . . . . . . . . . . . . . . . . . . 158
iv CONTENTS
5.3.3 Discretisation of 3-D horizontal advection . . . . . . . 162

5.3.3.1 alongstream advection of u . . . . . . . . . . 162
5.3.3.2 cross-stream advection of u . . . . . . . . . . 163
5.3.3.3 cross-stream advection of v . . . . . . . . . . 164
5.3.3.4 alongstream advection of v . . . . . . . . . . 165
5.3.4 Discretisation of 2-D horizontal advection . . . . . . . 166
5.3.4.1 alongstream advection of U . . . . . . . . . . 166
5.3.4.2 cross-stream advection of U . . . . . . . . . . 167
5.3.4.3 cross-stream advection of V . . . . . . . . . . 168
5.3.4.4 alongstream advection of V . . . . . . . . . . 169
5.3.5 Integrals of the baroclinic advection terms . . . . . . . 170
5.3.6 Discretisation of vertical advection . . . . . . . . . . . 170
5.3.6.1 vertical advection of u . . . . . . . . . . . . . 170
5.3.6.2 vertical advection of v . . . . . . . . . . . . . 171
5.3.7 Discretisation of 3-D horizontal diffusion . . . . . . . . 172
5.3.8 Discretisation of 2-D horizontal diffusion . . . . . . . . 173
5.3.9 Integrals of the baroclinic diffusion terms . . . . . . . 174
5.3.10 Discretisation of vertical diffusion . . . . . . . . . . . . 174
5.3.11 Diffusion coefficients for momentum . . . . . . . . . . . 175
5.3.11.1 horizontal diffusion coefficients . . . . . . . . 175
5.3.11.2 vertical diffusion coefficient . . . . . . . . . . 176
5.3.12 Discretisation of the baroclinic pressure gradient . . . 177
5.3.12.1 second-order method . . . . . . . . . . . . . 178
5.3.12.2 z-level method . . . . . . . . . . . . . . . . . 178
5.3.12.3 cube-H method . . . . . . . . . . . . . . . . . 179
5.3.13 Tidal force . . . . . . . . . . . . . . . . . . . . . . . . . 182
5.3.14 Surface and bottom boundary conditions . . . . . . . 183
5.3.14.1 surface boundary conditions . . . . . . . . . . 183
5.3.14.2 bottom boundary conditions . . . . . . . . . . 185
5.3.15 Lateral boundary conditions for the 2-D mode . . . . 186
5.3.15.1 open boundary conditions for transports . . . 186
5.3.15.2 open boundary conditions for 2-D advective
and diffusive fluxes . . . . . . . . . . . . . . 192
5.3.15.3 boundary conditions at closed lateral boun-
daries . . . . . . . . . . . . . . . . . . . . . . 193
5.3.16 Lateral boundary conditions for the 3-D currents . . . 194
5.3.16.1 open boundary conditions for horizontal 3-D
currents . . . . . . . . . . . . . . . . . . . . . 194
5.3.16.2 open boundary conditions for the advective
and diffusive fluxes of the 3-D currents . . . . 196
CONTENTS v
5.3.16.3 boundary conditions for the 3-D mode at closed

lateral boundaries . . . . . . . . . . . . . . . 196
5.3.17 Solution of the discretised equations for momentum . 196
5.3.17.1 composition of the tridiagonal matrix . . . . 197
5.3.17.2 solution of tridiagonal systems . . . . . . . . 200
5.4 Drying/wetting and inundation schemes . . . . . . . . . . . . 200
5.4.1 Drying and wetting algorithm . . . . . . . . . . . . . . 200
5.4.2 Inundation schemes . . . . . . . . . . . . . . . . . . . . 202
5.5 Scalar transport equations . . . . . . . . . . . . . . . . . . . . 205
5.5.1 General aspects of discretisation . . . . . . . . . . . . 205
5.5.2 Alternative formulation of the transport equation . . . 206
5.5.3.1 integration without advection . . . . . . . . . 208
5.5.3.2 integration with advection but without oper-
ator splitting . . . . . . . . . . . . . . . . . . 208
5.5.3.3 integration with operator splitting . . . . . . 208
5.5.4 Discretisation of advection . . . . . . . . . . . . . . . . 209
5.5.4.1 advection in the X-direction . . . . . . . . . . 209
5.5.4.2 advection in the Y-direction . . . . . . . . . . 210
5.5.4.3 advection in the vertical direction . . . . . . . 211
5.5.4.4 corrector terms . . . . . . . . . . . . . . . . . 212
5.5.5 Discretisation of diffusion . . . . . . . . . . . . . . . . 212
5.5.5.1 diffusion in the X-direction . . . . . . . . . . 212
5.5.5.2 diffusion in the Y-direction . . . . . . . . . . 212
5.5.5.3 diffusion in the vertical direction . . . . . . . 213
5.5.6 Diffusion coefficients for scalars . . . . . . . . . . . . . 213
5.5.6.2 vertical diffusion coefficient . . . . . . . . . . 213
5.5.7 Boundary conditions . . . . . . . . . . . . . . . . . . . 213
5.5.7.3 lateral boundary conditions . . . . . . . . . . 215
5.5.8 Solution of the discretised equations for scalars . . . . 216
5.6 Turbulence transport equations . . . . . . . . . . . . . . . . . 220
5.6.1.1 integration without advection . . . . . . . . . 221
5.6.1.2 integration with advection but without oper-
ator splitting . . . . . . . . . . . . . . . . . . 221
5.6.1.3 integration with operator splitting . . . . . . 221
5.6.2 Discretisation of advection . . . . . . . . . . . . . . . . 222
5.6.2.1 advection in the X-direction . . . . . . . . . . 222
vi CONTENTS
5.6.2.2 advection in the Y-direction . . . . . . . . . . 223

5.6.2.3 advection in the vertical direction . . . . . . . 224
5.6.2.4 corrector terms . . . . . . . . . . . . . . . . . 225
5.6.3 Discretisation of diffusion . . . . . . . . . . . . . . . . 225
5.6.3.1 diffusion in the X-direction . . . . . . . . . . 225
5.6.3.2 diffusion in the Y-direction . . . . . . . . . . 225
5.6.3.3 diffusion in the vertical direction . . . . . . . 225
5.6.4 Diffusion coefficients for turbulence variables . . . . . 226
5.6.4.2 vertical diffusion coefficients . . . . . . . . . 226
5.6.5 Production and sink terms . . . . . . . . . . . . . . . . 226
5.6.6 Boundary conditions . . . . . . . . . . . . . . . . . . . 227
5.6.6.3 lateral boundary conditions . . . . . . . . . . 230
5.6.7 Solution of the discretised equations for turbulent trans-
port variables . . . . . . . . . . . . . . . . . . . . . . . 230
5.7 Discretisations on reduced grids . . . . . . . . . . . . . . . . . 234
5.7.1 Discretised 1-D mode equations . . . . . . . . . . . . . 234
5.7.2 Discretised depth-integrated equations . . . . . . . . . 235
5.8 Solution procedure . . . . . . . . . . . . . . . . . . . . . . . . 235
III Description of the model code 239

6 Program conventions and techniques 241
6.1 Implementation of FORTRAN 90 . . . . . . . . . . . . . . . . . 241
6.1.1 COHERENS programming conventions . . . . . . . . . 242
6.1.2 Data types . . . . . . . . . . . . . . . . . . . . . . . . . 246
6.1.3 Allocatable arrays . . . . . . . . . . . . . . . . . . . . . 248
6.1.4 Derived types . . . . . . . . . . . . . . . . . . . . . . . 250
6.1.5 Modules . . . . . . . . . . . . . . . . . . . . . . . . . . 253
6.1.6 Generic procedures . . . . . . . . . . . . . . . . . . . . 255
6.1.7 Internal documentation and structured layout of the
code . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
6.2 Specific program features . . . . . . . . . . . . . . . . . . . . . 267
6.2.1 Key ids . . . . . . . . . . . . . . . . . . . . . . . . . . 267
6.2.2 Date and time formats . . . . . . . . . . . . . . . . . . 267
6.2.3 Data flags . . . . . . . . . . . . . . . . . . . . . . . . . 270
6.2.4 Variable units . . . . . . . . . . . . . . . . . . . . . . . 270
CONTENTS vii
7 Model input and output 273

7.1 Classification of model files . . . . . . . . . . . . . . . . . . . . 273
7.2 Default file names . . . . . . . . . . . . . . . . . . . . . . . . . 275
7.2.1 title . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
7.2.2 pid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
7.2.3 form . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
7.2.4 filedesc . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
7.2.5 filenum . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
7.2.6 freqnum . . . . . . . . . . . . . . . . . . . . . . . . . . 278
7.2.7 dim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
7.3 Formats of monitoring files . . . . . . . . . . . . . . . . . . . . 278
7.3.1 Log files . . . . . . . . . . . . . . . . . . . . . . . . . . 278
7.3.2 Error files . . . . . . . . . . . . . . . . . . . . . . . . . 281
7.3.3 Warning file . . . . . . . . . . . . . . . . . . . . . . . . 284
7.3.4 Timer report file . . . . . . . . . . . . . . . . . . . . . 286
7.4 Central input file . . . . . . . . . . . . . . . . . . . . . . . . . 289
7.4.1 Syntax of a CIF . . . . . . . . . . . . . . . . . . . . . . 289
7.4.2 CIF blocks . . . . . . . . . . . . . . . . . . . . . . . . . 290
7.4.3 Order of definitions . . . . . . . . . . . . . . . . . . . . 292
7.5 Forcing files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
7.5.1 General aspects . . . . . . . . . . . . . . . . . . . . . . 295
7.5.2 Data contents of forcing files . . . . . . . . . . . . . . . 300
7.5.3 Standard format of forcing files . . . . . . . . . . . . . 305
7.5.3.1 ASCII files . . . . . . . . . . . . . . . . . . . 305
7.5.3.2 unformatted binary files . . . . . . . . . . . . 311
7.5.3.3 netCDF files . . . . . . . . . . . . . . . . . . 313
7.6 User output files . . . . . . . . . . . . . . . . . . . . . . . . . 317
7.6.1 General aspects . . . . . . . . . . . . . . . . . . . . . . 317
7.6.2 Structure of user output files . . . . . . . . . . . . . . . 322
7.6.3 Format of files with user-defined output . . . . . . . . 323
7.6.3.1 ASCII files . . . . . . . . . . . . . . . . . . . 323
7.6.3.2 unformatted binary files . . . . . . . . . . . . 330
7.6.3.3 netcdf files . . . . . . . . . . . . . . . . . . . 330
8 Model grid and spatial interpolation 337

8.1 Model grid arrays . . . . . . . . . . . . . . . . . . . . . . . . . 337
8.1.1 Array shapes . . . . . . . . . . . . . . . . . . . . . . . 337
8.1.2 Parameters and arrays related to the model grid . . . 338
8.1.2.1 definition of the model grid . . . . . . . . . . 338
8.1.2.2 definition of the open boundaries . . . . . . . 340
8.1.2.3 grid spacings . . . . . . . . . . . . . . . . . . 342
viii CONTENTS
8.1.2.4 pointer arrays . . . . . . . . . . . . . . . . . . 343

8.2 Interpolation of model arrays at a different node . . . . . . . 345
8.2.1 Interpolation without land flags . . . . . . . . . . . . . 345
8.2.2 Interpolation with land flags . . . . . . . . . . . . . . . 347
8.3 Curvilinear, index and relative coordinates . . . . . . . . . . . 348
8.4 Interpolation of a 2-D external data grid at the model grid . . 349
8.4.1 General description of the procedure . . . . . . . . . . 349
8.4.2 Implementation . . . . . . . . . . . . . . . . . . . . . . 351
8.5 Interpolation of model data at external locations . . . . . . . 353
8.5.1 General description of the procedure . . . . . . . . . . 353
8.5.2 Implementation . . . . . . . . . . . . . . . . . . . . . . 357
9 Aspects of parallellisation 361

9.1 Basic principles . . . . . . . . . . . . . . . . . . . . . . . . . . 361
9.1.1 Implementation of MPI . . . . . . . . . . . . . . . . . . 361
9.1.2 Principles of the parallel code . . . . . . . . . . . . . . 363
9.2 Domain decomposition . . . . . . . . . . . . . . . . . . . . . . 363
9.2.1 Definition . . . . . . . . . . . . . . . . . . . . . . . . . 363
9.2.2 Local grid indexing system . . . . . . . . . . . . . . . . 364
9.3 Halos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
9.4 Communications . . . . . . . . . . . . . . . . . . . . . . . . . 368
9.4.1 Send and receive in MPI . . . . . . . . . . . . . . . . . 368
9.4.2 Sort of communications . . . . . . . . . . . . . . . . . . 370
9.4.3 Implementation . . . . . . . . . . . . . . . . . . . . . . 373
9.4.3.1 all-to-all operations . . . . . . . . . . . . . . . 373
9.4.3.2 exchange operations . . . . . . . . . . . . . . 374
9.4.3.3 program routines for communications . . . . 375
9.5 Local versus global array indexing . . . . . . . . . . . . . . . 376
10 Structure of the model code 379

10.1 Source code files . . . . . . . . . . . . . . . . . . . . . . . . . . 379
10.2 Structure diagrams . . . . . . . . . . . . . . . . . . . . . . . . 383
10.2.1 General structure . . . . . . . . . . . . . . . . . . . . . 383
10.2.2 Initialisation procedures . . . . . . . . . . . . . . . . . 385
10.2.3 Time loop . . . . . . . . . . . . . . . . . . . . . . . . . 387
10.2.4 Open boundary and surface forcing data input . . . . 388
10.2.5 Finalisation procedures . . . . . . . . . . . . . . . . . . 391
CONTENTS ix
IV User manual 401

11 Introduction 403
12 Control parameters 409

12.1 File defruns . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
12.2 Parameters for monitoring . . . . . . . . . . . . . . . . . . . . 410
12.2.1 Cold start . . . . . . . . . . . . . . . . . . . . . . . . . 410
12.2.2 Log files . . . . . . . . . . . . . . . . . . . . . . . . . . 411
12.2.3 Error files . . . . . . . . . . . . . . . . . . . . . . . . . 411
12.2.4 Warning file . . . . . . . . . . . . . . . . . . . . . . . . 412
12.2.5 Timer file . . . . . . . . . . . . . . . . . . . . . . . . . 412
12.3 Dimensions of the process domain grid . . . . . . . . . . . . . 412
12.4 Model switches . . . . . . . . . . . . . . . . . . . . . . . . . . 413
12.4.1 Model grid . . . . . . . . . . . . . . . . . . . . . . . . . 414
12.4.2 Interpolation . . . . . . . . . . . . . . . . . . . . . . . 414
12.4.3 Hydrodynamics . . . . . . . . . . . . . . . . . . . . . . 415
12.4.4 Density . . . . . . . . . . . . . . . . . . . . . . . . . . 415
12.4.5 Biology . . . . . . . . . . . . . . . . . . . . . . . . . . 416
12.4.6 Bottom boundary conditions . . . . . . . . . . . . . . . 416
12.4.7 Advection . . . . . . . . . . . . . . . . . . . . . . . . . 417
12.4.8 Diffusion coefficients . . . . . . . . . . . . . . . . . . . 418
12.4.9 Turbulence schemes . . . . . . . . . . . . . . . . . . . . 419
12.4.10 Drying/wetting scheme . . . . . . . . . . . . . . . . . . 421
12.4.11 Time integration . . . . . . . . . . . . . . . . . . . . . 422
12.4.12 Open boundary conditions . . . . . . . . . . . . . . . . 422
12.4.13 Tides . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
12.4.14 1-D applications . . . . . . . . . . . . . . . . . . . . . . 424
12.4.15 Meteorological forcing . . . . . . . . . . . . . . . . . . 424
12.4.16 Surface boundary conditions . . . . . . . . . . . . . . . 425
12.4.17 Nesting . . . . . . . . . . . . . . . . . . . . . . . . . . 426
12.4.18 MPI mode . . . . . . . . . . . . . . . . . . . . . . . . . 426
12.4.19 User output . . . . . . . . . . . . . . . . . . . . . . . . 427
12.4.20 NetCDF . . . . . . . . . . . . . . . . . . . . . . . . . . 427
12.5 Model parameters . . . . . . . . . . . . . . . . . . . . . . . . . 428
12.5.1 Date and time parameters . . . . . . . . . . . . . . . . 428
12.5.2 Grid parameters . . . . . . . . . . . . . . . . . . . . . . 429
12.5.3 Other integer model parameters . . . . . . . . . . . . . 429
12.5.4 Physical model parameters . . . . . . . . . . . . . . . . 430
12.5.5 Turbulence model parameters . . . . . . . . . . . . . . 433
12.6 Parameters for surface data grids . . . . . . . . . . . . . . . . 435
x CONTENTS
12.6.1 Grid descriptors . . . . . . . . . . . . . . . . . . . . . . 436

12.6.2 Grid parameters . . . . . . . . . . . . . . . . . . . . . . 436
12.7 Attributes of forcing files . . . . . . . . . . . . . . . . . . . . . 437
12.7.1 File descriptors . . . . . . . . . . . . . . . . . . . . . . 438
12.7.2 File parameters for input forcing (iotype=1) . . . . . . 439
12.7.3 File parameters for output forcing (iotype=2) . . . . . 440
12.7.4 Other forcing attributes . . . . . . . . . . . . . . . . . 441
12.8 Parameters for user-defined output . . . . . . . . . . . . . . . 441
12.9 Domain decomposition . . . . . . . . . . . . . . . . . . . . . . 442
13 Model grid and initial conditions 443

13.1 Model grid and bathymetry . . . . . . . . . . . . . . . . . . . 443
13.2 Initial physical conditions . . . . . . . . . . . . . . . . . . . . 445
14 Open boundary conditions 451

14.1 2-D mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
14.1.1 Open boundary specifiers for the 2-D mode . . . . . . . 451
14.1.1.1 general specifiers . . . . . . . . . . . . . . . . 452
14.1.1.2 specifiers for the data files . . . . . . . . . . . 453
14.1.1.3 amplitudes and phases . . . . . . . . . . . . . 455
14.1.2 Open boundary data for the 2-D mode . . . . . . . . . 455
14.2 3-D mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
14.2.1 Open boundary specifiers for the 3-D mode . . . . . . . 456
14.2.1.1 general specifiers . . . . . . . . . . . . . . . . 457
14.2.1.2 specifiers for the data files . . . . . . . . . . . 458
14.2.2 Open boundary data for the 3-D mode . . . . . . . . . 459
14.3 Specifiers for relaxation open boundary conditions . . . . . . 461
15 Surface forcing and nesting 465

15.1 Water column surface forcing . . . . . . . . . . . . . . . . . . 466
15.1.1 Surface forcing specifiers for the 1-D mode . . . . . . . 466
15.1.2 Surface forcing data for the 1-D mode . . . . . . . . . 466
15.2 2-D surface forcing . . . . . . . . . . . . . . . . . . . . . . . . 467
15.2.1 Surface grid in absolute coordinates . . . . . . . . . . . 467
15.2.2 Surface grid in relative coordinates . . . . . . . . . . . 468
15.2.3 Surface forcing data . . . . . . . . . . . . . . . . . . . 470
15.3 Nesting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
15.3.1 Sub-grid specifications . . . . . . . . . . . . . . . . . . 472
15.3.2 Sub-grid locations in absolute coordinates . . . . . . . 472
15.3.3 Sub-grid locations in relative coordinates . . . . . . . 473
CONTENTS xi
16 User output 477

16.1 Time series output . . . . . . . . . . . . . . . . . . . . . . . . 477
16.1.1 Specifiers for time series output . . . . . . . . . . . . . 478
16.1.1.1 variable attributes . . . . . . . . . . . . . . . 479
16.1.1.2 file attributes . . . . . . . . . . . . . . . . . . 481
16.1.1.3 output data grid . . . . . . . . . . . . . . . . 482
16.1.1.4 station attributes . . . . . . . . . . . . . . . . 484
16.1.2 Time series output data . . . . . . . . . . . . . . . . . 484
16.1.2.1 values of 0-D time series data . . . . . . . . . 484
16.2 Time averaged output . . . . . . . . . . . . . . . . . . . . . . 486
16.2.1 Specifiers for time averaged output . . . . . . . . . . . 486
16.2.1.2 file attributes . . . . . . . . . . . . . . . . . . 489
16.2.1.3 output data grid . . . . . . . . . . . . . . . . 490
16.2.2 Time averaged output data . . . . . . . . . . . . . . . 492
16.2.2.1 values of 0-D time averaged data . . . . . . . 492
16.3 Harmonic analysis . . . . . . . . . . . . . . . . . . . . . . . . . 493
16.3.1 Harmonic frequencies . . . . . . . . . . . . . . . . . . . 494
16.3.2 Specifiers for harmonic output . . . . . . . . . . . . . . 495
16.3.2.2 file attributes . . . . . . . . . . . . . . . . . . 499
16.3.2.3 output data grid . . . . . . . . . . . . . . . . 501
16.3.3 Harmonic output data . . . . . . . . . . . . . . . . . . 503
16.3.3.1 values of 0-D harmonic data . . . . . . . . . . 503
16.4 User-defined output . . . . . . . . . . . . . . . . . . . . . . . . 504
16.5 Output grid coordinates . . . . . . . . . . . . . . . . . . . . . 505
V Test cases 511

17 Introduction 513
xii CONTENTS
18 Advection schemes 519

18.1 Test case cones . . . . . . . . . . . . . . . . . . . . . . . . . . 519
18.1.1 Description of the problem and model setup . . . . . . 519
18.1.2 Experiments and output parameters . . . . . . . . . . 520
18.1.3 Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
18.2 Test case front . . . . . . . . . . . . . . . . . . . . . . . . . . 524
18.2.3 Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
18.3 Test case seich . . . . . . . . . . . . . . . . . . . . . . . . . . 529
18.3.2 Analytical solution . . . . . . . . . . . . . . . . . . . . 530
18.3.4 Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
18.4 Test case fredy . . . . . . . . . . . . . . . . . . . . . . . . . . 536
18.4.3 Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
19 Turbulence and heat flux formulations 545

19.1 Test case pycno . . . . . . . . . . . . . . . . . . . . . . . . . 545
19.1.1 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
19.1.2 Model setup . . . . . . . . . . . . . . . . . . . . . . . . 547
19.1.4 Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 554
19.2 Test case csnsp . . . . . . . . . . . . . . . . . . . . . . . . . . 555
19.2.3 Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 558
20 Density fronts and river plumes 565

20.1 Test case river . . . . . . . . . . . . . . . . . . . . . . . . . . 565
20.1.3 Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 571
20.2 Test case plume . . . . . . . . . . . . . . . . . . . . . . . . . 572
20.2.3 Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
20.3 Test case rhone . . . . . . . . . . . . . . . . . . . . . . . . . 584
CONTENTS xiii

20.3.3 Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 588
21 Inundation schemes 597

21.1 Test case flood2d . . . . . . . . . . . . . . . . . . . . . . . . . 597
21.1.3 Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
21.2 Test case flood3d . . . . . . . . . . . . . . . . . . . . . . . . . 606
21.2.3 Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
22 Shelf sea modelling 619

22.1 Test case bohai . . . . . . . . . . . . . . . . . . . . . . . . . . 619
22.1.2 Results . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
A Transformed model equations 627

A.1 Horizontal transformation . . . . . . . . . . . . . . . . . . . . 627
A.2 Vertical transformation . . . . . . . . . . . . . . . . . . . . . . 628
B Solutions of the RANS equations 633

B.1 Non-equilibrium method . . . . . . . . . . . . . . . . . . . . . 633
B.2 Quasi-equilibrium method . . . . . . . . . . . . . . . . . . . . 634
B.3 Equilibrium method . . . . . . . . . . . . . . . . . . . . . . . 636
C Discretisation of the Coriolis force 637
D Energy balance equation 639
E List of standard output variables 641
Bibliography 644
VI Reference manual 659

22 Description of external routines 661
22.1 Advection Terms.F90 . . . . . . . . . . . . . . . . . . . . . . . 661
22.2 Allocate Arrays.f90 . . . . . . . . . . . . . . . . . . . . . . . . 674
22.3 Bottom Fluxes.f90 . . . . . . . . . . . . . . . . . . . . . . . . 675
xiv CONTENTS
22.4 Coherens Program.f90 . . . . . . . . . . . . . . . . . . . . . . 678

22.5 Corrector Terms.F90 . . . . . . . . . . . . . . . . . . . . . . . 679
22.6 Density Equations.F90 . . . . . . . . . . . . . . . . . . . . . . 684
22.7 Diffusion Coefficients.F90 . . . . . . . . . . . . . . . . . . . . 688
22.8 Diffusion Terms.F90 . . . . . . . . . . . . . . . . . . . . . . . 689
22.9 Grid Arrays.F90 . . . . . . . . . . . . . . . . . . . . . . . . . . 704
22.10Harmonic Analysis.f90 . . . . . . . . . . . . . . . . . . . . . . 708
22.11Hydrodynamic Equations.F90 . . . . . . . . . . . . . . . . . . 712
22.12Inundation Schemes.f90 . . . . . . . . . . . . . . . . . . . . . . 716
22.13Model Finalisation.f90 . . . . . . . . . . . . . . . . . . . . . . 718
22.14Model Initialisation.F90 . . . . . . . . . . . . . . . . . . . . . 720
22.15Model Parameters.f90 . . . . . . . . . . . . . . . . . . . . . . . 723
22.16Nested Grids.F90 . . . . . . . . . . . . . . . . . . . . . . . . . 725
22.17Open Boundary Conditions.f90 . . . . . . . . . . . . . . . . . 736
22.18Open Boundary Data Prof.f90 . . . . . . . . . . . . . . . . . 740
22.19Open Boundary Data 2D.f90 . . . . . . . . . . . . . . . . . . 748
22.20Parallel Initialisation.f90 . . . . . . . . . . . . . . . . . . . . . 752
22.21Relaxation Zones.f90 . . . . . . . . . . . . . . . . . . . . . . . 757
22.22Surface Boundary Data 1D.f90 . . . . . . . . . . . . . . . . . 761
22.23Surface Data.f90 . . . . . . . . . . . . . . . . . . . . . . . . . 765
22.24Surface Fluxes.F90 . . . . . . . . . . . . . . . . . . . . . . . . 769
22.25Surface Grids.f90 . . . . . . . . . . . . . . . . . . . . . . . . . 774
22.26Tidal Forcing.F90 . . . . . . . . . . . . . . . . . . . . . . . . . 779
22.27Time Averages.f90 . . . . . . . . . . . . . . . . . . . . . . . . 781
22.28Time Series.f90 . . . . . . . . . . . . . . . . . . . . . . . . . . 783
22.29Transport Equations.F90 . . . . . . . . . . . . . . . . . . . . . 785
22.30Turbulence Equations.F90 . . . . . . . . . . . . . . . . . . . . 797
23 Description of modules routines 803

23.1 Array interpolation . . . . . . . . . . . . . . . . . . . . . . . . 803
23.2 NetCDF routine library . . . . . . . . . . . . . . . . . . . . . 865
23.3 Checking of model setup . . . . . . . . . . . . . . . . . . . . . 886
23.4 CIF utility routines . . . . . . . . . . . . . . . . . . . . . . . . 891
23.5 MPI routine library . . . . . . . . . . . . . . . . . . . . . . . . 901
23.6 Initialisation of derived types variables . . . . . . . . . . . . . 931
23.7 Default model setup . . . . . . . . . . . . . . . . . . . . . . . 935
23.8 Error checking routines . . . . . . . . . . . . . . . . . . . . . . 938
23.9 Grid interpolation from and to the model grid . . . . . . . . . 962
23.10Routines performing operations on the model grid . . . . . . 975
23.11Routines combining communication and I/O operations . . . 987
23.12Input/output operations . . . . . . . . . . . . . . . . . . . . . 995
CONTENTS xv
23.13Library of mathematical routines . . . . . . . . . . . . . . . . 1009

23.14Output data for standard variables . . . . . . . . . . . . . . . 1015
23.15Standard attributes for variables and forcing files . . . . . . . 1019
23.16Library routines for linear algebra . . . . . . . . . . . . . . . . 1022
23.17Parallel communications . . . . . . . . . . . . . . . . . . . . . 1030
23.18Utility routines for parallel application . . . . . . . . . . . . . 1045
23.19Reset of setup parameters . . . . . . . . . . . . . . . . . . . . 1053
23.20Random generators . . . . . . . . . . . . . . . . . . . . . . . . 1056
23.21Time and calendar date routines . . . . . . . . . . . . . . . . . 1063
23.22Routines used by the turbulence model . . . . . . . . . . . . 1077
23.23Miscellaneous utility routines . . . . . . . . . . . . . . . . . . 1081
24 Description of user defined routines 1091

24.1 Harmonic analysis and output . . . . . . . . . . . . . . . . . . 1091
24.2 Model setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1094
24.3 Setup of nested sub-grids . . . . . . . . . . . . . . . . . . . . . 1101
24.4 User-formatted output . . . . . . . . . . . . . . . . . . . . . . 1103
24.5 Surface grids and data . . . . . . . . . . . . . . . . . . . . . . 1103
24.6 Time averaged output . . . . . . . . . . . . . . . . . . . . . . 1106
24.7 Time series output . . . . . . . . . . . . . . . . . . . . . . . . 1108
25 Description of program variables 1111

25.1 Currents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1111
25.2 Derived type definitions . . . . . . . . . . . . . . . . . . . . . 1113
25.3 Density . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122
25.4 Water depths . . . . . . . . . . . . . . . . . . . . . . . . . . . 1123
25.5 Diffusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1124
25.6 Fluxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1125
25.7 Model grid arrays . . . . . . . . . . . . . . . . . . . . . . . . . 1127
25.8 Model grid parameters . . . . . . . . . . . . . . . . . . . . . . 1133
25.9 General and I/O parameters . . . . . . . . . . . . . . . . . . . 1136
25.10Meteorological arrays . . . . . . . . . . . . . . . . . . . . . . . 1151
25.11Key ids of model variables . . . . . . . . . . . . . . . . . . . . 1152
25.12Nested sub-grids . . . . . . . . . . . . . . . . . . . . . . . . . 1153
25.13Open boundary conditions . . . . . . . . . . . . . . . . . . . . 1155
25.14Optical arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . 1160
25.15Parameters for parallel processing . . . . . . . . . . . . . . . . 1160
25.16Physical and numerical model parameters . . . . . . . . . . . 1163
25.17Relaxation zones . . . . . . . . . . . . . . . . . . . . . . . . . 1168
25.18Model switches . . . . . . . . . . . . . . . . . . . . . . . . . . 1170
25.19Constants and system parameters . . . . . . . . . . . . . . . . 1184
xvi CONTENTS
25.20Tidal forcing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1189

25.21Time parameters . . . . . . . . . . . . . . . . . . . . . . . . . 1191
25.22Turbulence model parameters . . . . . . . . . . . . . . . . . . 1193
25.23Turbulence arrays . . . . . . . . . . . . . . . . . . . . . . . . . 1197
List of Figures
4.1 Examples of horizontal grids. . . . . . . . . . . . . . . . . . . 39

4.2 Transformed coordinate σ̂ = F (σ) (a) and vertical grid spacing
normalised to the total water depth ∆σ̂ = ∂F/∂σ/N (b) . . . 42
4.3 Distribution of vertical levels along a transect from Denmark
to Norway: uniform σ-coordinates (a), non-uniform σ-coordinates
using (4.24) (b). . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.4 Stability coefficients Su , Sb as a function of the Richardson
number using the equilibrium method for different RANS models 75
4.5 Surface drag and exchange coefficients as function of wind
speed and according to different formulations . . . . . . . . . . 108
5.1 Layout of the (global) computational grid in the horizontal. . . 131

5.2 Grid indexing in the horizontal plane. . . . . . . . . . . . . . . 132
5.3 Layout of the computational grid in the vertical. . . . . . . . . 133
5.4 Grid indexing in three-dimensional space. . . . . . . . . . . . . 135
5.5 Numerical grid for the 1-D advection problem. . . . . . . . . . 149
5.6 Illustration of the z-level interpolation scheme. . . . . . . . . . 180
8.1 Interpolation of model grid arrays at a different node. . . . . . 346

8.2 Curvilinear versus index coordinates. . . . . . . . . . . . . . . 349
8.3 Interpolation of external data to the model grid. . . . . . . . . 350
8.4 Illustration of the nesting procedure in the horizontal plane. . 355
8.5 Definition of vertical relative coordinates. . . . . . . . . . . . . 356
9.1 CPU efficiency, defined as the CPU time for a serial run di-
vided by the one obtained for the parallel run, as function of
the number of processes. . . . . . . . . . . . . . . . . . . . . . 362
9.2 Examples of allowed and non-allowed domain decompositions. 364
9.3 Domain decomposition for the North Sea area with 128 pro-
cesses based on a 10×19 domain grid. . . . . . . . . . . . . . . 365
xvii
xviii LIST OF FIGURES
9.4 Horizontal layout of the computational grid on a local sub-

domain. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366
9.5 Illustration of an halo for an array defined on a local sub-domain.367
9.6 Partitioning of a sub-domain halo. . . . . . . . . . . . . . . . . 368
9.7 Communication pattern for exchange operations. . . . . . . . . 375
9.8 Example of index mapping between global and local arrays. . . 376
10.1 General structure of COHERENS. . . . . . . . . . . . . . . . . 384

10.2 Schematic diagram of all initialisation procedures. . . . . . . . 393
10.3 Structure diagram of the time loop. . . . . . . . . . . . . . . . 394
10.4 Diagram of routine current 2d which solves the 2-D mode equa-
tions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
10.5 Diagrams of the routines current pred and current corr which
solve the 3-D momentum equation at the predictor and cor-
rector step. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
10.6 Diagrams of the routines temperature equation and salinity equation
which solve the temperature and salinity equations. . . . . . . 397
10.7 Diagrams of the routines used for defining and updating 2-D
open boundary conditions and data. . . . . . . . . . . . . . . . 398
10.8 Diagrams of the routines used for defining and updating 3-D
open boundary conditions and data. . . . . . . . . . . . . . . . 398
10.9 Diagram of the routines used for defining and updating data
from an external 2-D grid. . . . . . . . . . . . . . . . . . . . . 399
14.1 Example showing how to define the arrays no2dobc and in-
dex2dobc. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
14.2 Example how to define the open boundary specifier arrays. . . 460
14.3 Example definitions of open boundary zones for application of
the relaxation scheme. . . . . . . . . . . . . . . . . . . . . . . 463
18.1 The initial configuration of the cones test case. . . . . . . . 520

18.2 Surface concentrations after two periods of revolution for the
cones test cases. . . . . . . . . . . . . . . . . . . . . . . . . . 522
18.3 Test case cones. Surface concentrations along different tran-
sects at the end of the simulation. . . . . . . . . . . . . . . . . 523
18.4 Contaminant distribution and current field at different times
for test case frontC. . . . . . . . . . . . . . . . . . . . . . . . 526
18.5 Test case front. Contaminant concentration after 27 hours. . 527
18.6 Test case front. Contaminant concentration after 27 hours:
horizontal profile at 5 m below the surface, vertical profile at
30 km from the left boundary. . . . . . . . . . . . . . . . . . . 528
LIST OF FIGURES xix
18.7 The initial configuration of the seich test case. . . . . . . . . 532

18.8 Evolution of the current field, salinity and the frontal system
after 1, 3, and 6 hours according to the analytical theory and
experiment seichC. . . . . . . . . . . . . . . . . . . . . . . . 533
18.9 Test case seich. Current field and salinity distribution after
4 hours. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
18.10Initial salinity distribution for the fredy test case along the
surface and along a transect parallel to the X-axis and through
the patch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
18.11Test case fredy. Surface current and salinity after 6 days . . . 541
18.12Test case fredy. Surface vorticity normalised by the Coriolis
frequency. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
18.13Test case fredy. Current and salinity along a transect parallel
to the X-axis and through the centre of the patch after 6 days 543
18.14Test case fredy. Time series of the kinetic energy Ekin , the
available potential energy Epot , the enstrophy and the fresh
water area A1%. . . . . . . . . . . . . . . . . . . . . . . . . . 544
19.1 Test case pycno. Time series of the mixed layer depth, the
surface current and the surface density difference ∆ρ(0, t). . . 551
19.2 Test case pycno. Vertical profiles of the current, the den-
sity minus its initial surface value, ρ(z, t) − ρ(0, 0) and the
Richardson number after one day. . . . . . . . . . . . . . . . . 552
19.3 Test case pycno. Vertical profile of the vertical diffusion co-
efficient λT after one day and time series of λT at 10 m depth
during the last hour of the simulation for experiment A. . . . 553
19.4 Test case csnsp. Time series (3-day average) of surface and
bottom temperatures. . . . . . . . . . . . . . . . . . . . . . . . 561
19.5 Test case csnsp.Time series (3-day average) of mixed layer
depth. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
19.6 Test case csnsp. Temperature profile on August 4. . . . . . . 563
19.7 Test case csnsp. Time series (3-day average) of (upward)
non-solar heat flux and surface exchange coefficient . . . . . . 564
20.1 Initial position of the salinity front and evolution of the current
and salinity fields during the last tidal cycle for experiment
riverA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
20.2 Test case river. Residual salinity and current fields. . . . . . 569
20.3 Test case river. Distributions of current and salinity at the
end of the simulation. . . . . . . . . . . . . . . . . . . . . . . . 570
xx LIST OF FIGURES
20.4 Test case river. Time series of the distance to the left boun-
dary of the point where the front outcrops the surface. . . . . 571
20.5 The computational domain for the test case plume. . . . . . . 574
20.6 Test case plume. Surface distributions of currents and salinity 579
20.7 Test case plume. Residual surface distributions of currents
and salinity for the last tidal cycle . . . . . . . . . . . . . . . . 580
20.8 Test case plume. Residual distributions of currents and sali-
nity for the last tidal cycle along a cross-shore transect . . . . 581
20.9 Test case plume. Time series of the plume width and plume
length. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581
20.10Test case plume. Surface and bottom ellipticity distributions. 582
20.11Test case plume. Major axis (m/s) of the tidal ellipse for the
depth-averaged current and amplitude of the surface elevation. 583
20.12Bathymetry of the Rhone plume area. . . . . . . . . . . . . . . 586
20.13Surface distributions for salinity and currents for Rhone plume
experiments A–C. . . . . . . . . . . . . . . . . . . . . . . . . 588
20.14Distribution of currents and salinity along a vertical transect
at 4.850 E through the river mouth for Rhone plume experi-
ments A–C. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
20.15Distribution of currents and salinity along a vertical transect
at 4.450 E for Rhone plume experiments A–C. . . . . . . . . . 590
20.16Surface distributions for salinity and currents for Rhone plume
experiments D–G. . . . . . . . . . . . . . . . . . . . . . . . . 591
20.17Distribution of currents and salinity along different vertical
transects for Rhone plume experiments D–G. . . . . . . . . . 592
20.18Plume area as defined as the area between the coast and the
34 PSU contour line. . . . . . . . . . . . . . . . . . . . . . . . 593
21.1 Bathymetry and initial water level for the two configurations
used in flood2d. . . . . . . . . . . . . . . . . . . . . . . . . . 598
21.2 Time series of currents and surface elevations during the first
tidal cycle and experiment flood2dB. . . . . . . . . . . . . . . 602
21.3 Time series of currents and surface elevations during the first
tidal cycle and experiment flood2dD. . . . . . . . . . . . . . 603
21.4 Time series of the dry area for the four flood2d experiments. . 604
21.5 Time series of the maximum and mean water depth error for
the flood2d experiments A and B. . . . . . . . . . . . . . . . 605
21.6 Bathymetry and water level for the three configurations used
in flood3d. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607
21.7 Time series of currents and water depths along a transect for
experiment flood3dA. . . . . . . . . . . . . . . . . . . . . . . 609
LIST OF FIGURES xxi
21.8 Time series of horizontal depth mean currents and water depths
during the first tidal cycle and experiment flood3dA. . . . . . 610
21.9 Time series of currents and water depths along a transect for
experiment flood3dB. . . . . . . . . . . . . . . . . . . . . . . 611
21.10Time series of horizontal depth mean currents and water depths
during the first tidal cycle and experiment flood3dB. . . . . . 612
21.11Time series of currents and water depths along a transect for
experiment flood3dC. . . . . . . . . . . . . . . . . . . . . . . 613
during the first tidal cycle and experiment flood3dC. . . . . . 614
during the first tidal cycle and experiment flood3dD. . . . . . 615
21.14Time series of the dry area for the all flood3d experiments. . 616
21.15Time series of the maximum water depth error for all flood3d
experiments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
22.1 Bathymetry of the Bohai Sea. The diamond symbols locate

the position of the 4 four stations used in the definition of the
output parameters. . . . . . . . . . . . . . . . . . . . . . . . . 620
22.2 Amplitudes in cm, phases in degrees of the surface elevation,
major axis in m/s and ellipticity for the M2 tide and experi-
ment bohaiA. . . . . . . . . . . . . . . . . . . . . . . . . . . . 623
22.3 Amplitudes in cm, phases in degrees of the surface elevation,
major axis in m/s and ellipticity for the S2 tide and experi-
ment bohaiA. . . . . . . . . . . . . . . . . . . . . . . . . . . . 624
22.4 Time series of the domain-integrated kinetic energy, potential
energy, total energy and energy dissipation for experiment bo-
haiA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
22.5 Distribution of the depth-integrated residual tidal energy, depth-
integrated energy dissipation and energy flux for experiment
bohaiA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626
xxii LIST OF FIGURES
List of Tables
2.1 Test case descriptions . . . . . . . . . . . . . . . . . . . . . . . 21
4.1 Values of the empirical parameters in the McDougall et al.

(2003) equation of state. . . . . . . . . . . . . . . . . . . . . . 56
4.2 Values of the turbulence constants in the RANS equations
according to the different models implemented in COHERENS. 70
4.3 Values of critical parameters according to different RANS mo-
dels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
4.4 Parameters used in different turbulence schemes (except those
listed in Tables 4.2 and 4.3) and their default values. . . . . . 84
4.5 Doodson numbers, frequencies (degrees/h), amplitudes (cm)
and Greenwich arguments (degrees) of the tidal constituents
which can be used for astronomical and open boundary forcing. 91
4.6 Doodson numbers, origin, frequencies (degrees/h) and Green-
wich arguments (degrees) of the overtides which can be used
for the open boundary forcing. . . . . . . . . . . . . . . . . . 93
4.7 Empirical parameters used in the Kondo (1975) formulations
for the neutral surface drag and exchange coefficients. . . . . . 102
5.1 Upper bounds for the grid indices (i,j,k) as function of nodal
type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
5.2 Subscript and superscript notation used in the numerical dis-
cretisation formulae. . . . . . . . . . . . . . . . . . . . . . . . 138
5.3 Parameters and variables used in the numerical description.Global
and local FORTRAN names refer to the variables as defined on
respectively the global and local (parallel) grid. . . . . . . . . 141
5.4 Overview of the operators used in the numerical discretisations.152
5.5 Definitions of the fluxes used in the numerical discretisations. . 160
5.6 Discretisation schemes for each of the available surface and
bottom boundary conditions for turbulent variables. . . . . . . 228
xxiii
xxiv LIST OF TABLES
6.1 Model data types. . . . . . . . . . . . . . . . . . . . . . . . . . 247

6.2 List of available key classes . . . . . . . . . . . . . . . . . . . 268
6.3 Units of principal variables . . . . . . . . . . . . . . . . . . . 271
7.1 Key ids for error coding and associated error messages. . . . . 283
7.2 Timer key ids and their meaning. . . . . . . . . . . . . . . . . 285
7.3 Data contents for each type of input forcing file. In the last
column ‘R’, ‘I’, ‘C’, ‘D’ denote respectively real, integer, char-
acter and derived type data. . . . . . . . . . . . . . . . . . . . 301
8.1 Model grid parameters and arrays. . . . . . . . . . . . . . . . 339

8.2 Open boundary parameters and arrays. . . . . . . . . . . . . . 341
10.1 List of declaration module files. . . . . . . . . . . . . . . . . . 380

10.2 List of module routine files. . . . . . . . . . . . . . . . . . . . 381
10.3 List of files with external procedures. . . . . . . . . . . . . . . 382
10.4 List of user-defined routine files. . . . . . . . . . . . . . . . . . 383
11.1 Overview of all Usrdef files and usrdef routines in the program.406
11.2 List of usrdef routines which have a related read and write
routine for reading from or writing to a file in standard COHERENS
format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
16.1 List of available elliptic parameters (corresponding variable

key id, description of the parameter and the dimension of the
vector which determines the ellipse). . . . . . . . . . . . . . . 500
17.1 Calculation times (in seconds) for test case experiments on a

LINUX serial PC using gfortran and a parallel cluster using
XL Fortran at ECMWF. The number after the ’-’ sign denotes
the number of processes. . . . . . . . . . . . . . . . . . . . . 517
18.1 Output values for the analytical solution of test case seich. . 532
19.1 Settings of the turbulence switches for the pycno experiments. 548
19.2 Output values for the parameters of test case pycno. . . . . . 550
19.3 Settings of the model switches for the csnsp experiments. . . 557
20.1 Settings of the model switches for the river experiments. . . . 566
E.1 Key ids of the variables which can be used for defining stan-
dard output variables. The variables denoted by a ∗ are W-
node variables for which the node variable attribute can be
reset to ‘W’. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641
Preface
This report is the User Documentation of COHERENS version V2.3. Changes

with respect to earlier release(s) are documented in the accompanying Release
Notes.
Version 1.0
COHERENS is a three-dimensional multi-purpose numerical model, designed
for application in coastal and shelf seas, estuaries, lakes and reservoirs. The
model is available as a free source code for the scientific community and can
be considered as a tool for a better understanding of the physical and ecologi-
cal processes and for the prediction and monitoring of waste material in shelf
seas, the coastal zone and estuaries. The design, testing and validation of a
three-dimensional model required years of efforts. Its ease of implementation
across a range of computing platforms means that it is attractive to groups
who have a sufficient modelling expertise and have need for sophisticated
model products. Important advantages of the model are its transparency
due to its modular structure and its flexibility because of the possibility to
select different processes, specific schemes and different types of forcing for a
particular application. The program structure allows users to perform pro-
cess as well as predictive and operational setups without knowledge of the
detailed model structure.
The first version of the program, now denoted as COHERENS V1 was
developed over the period 1990-1998 by a multinational group, as part of
several European projects. The physical core part was written and coupled
with biological and resuspension modules during the PROFILE project. The
aim, at that time, was to apply the model for the study of coastal regions
of freshwater influence (ROFIs). A Lagrangian particle tracer and Eulerian
contaminant module were added as part of the model intercomparison exper-
iments conducted in NOMADS. The question arose at that time whether the
model could be released as a public domain community model. This was the
start of the COHERENS project. The objectives were to reshape the model
xxv
into portable code, develop verification tests, perform further validation and
provide an extensive documentation which covers all aspects of the program
so that users can make their setup independently. Partners in the project
were MUMM-RBINS (Brussels, Belgium), Proudman Oceanographic Labo-
ratory (POL, Liverpool, UK), Napier University (NU, Edinburgh, UK) and
the Britisch Oceanographic Data Centre (BODC, Liverpool, UK).
The model code and documentation have been made available for the
scientific community and management authorities in April 2000. Since then,
users can register on the COHERENS Web site
http://www.mumm.ac.be/coherens
The program was, in the first years after the release, distributed through
CD-ROMs, but can now easily be downloaded after electronic registration.
The registration list now counts more than thousand users.
Acknowledgements
Principal authors of COHERENS V1 are Patrick Luyten (MUMM-RBINS),
Eric Jones and Roger Proctor (POL), Paul Tett and Karen Wild-Allen (NU)
and Andy Tabor (BODC). The following persons, who made an important
contribution to the development of COHERENS V1 are acknowledged: : Ju-
dith Wolf (general concept of the program), Kevin Ruddick (circulation and
transport modules), Eric Deleersnijder (numerical methods), Claire Smith
(biology), Sarah Jones (resuspension and sediment module) and Kajo Mir-
bach (Lagrangian tracers). The work was funded by the European Union
under contracts MAST-0050-C (Profile I), MAST-900064, MAS2-CT93-0054
(Profile II) and MAS3-CT97-0088 (Coherens).
Version 2.0
More than 10 years passed since the official release of COHERENS V1. In the
mean time the computing power increased significantly by the introduction
of parallel clusters. Improvements and additions of new schemes (such as a
drying and wetting algorithm) have been suggested. Preparation for a new
version of COHERENS V2.0 started in 2003 during the European FP5 project
ODON (2003-2005) and continued in the FP6 project ECOOP (2007-2009).
The code has been completely rewritten in FORTRAN 90 and can be used
both in sequential and parallel mode using the MPI parallel communication
library. Output can (optionally) be provided in portable netCDF format
from within the program. Both curvilinear and generalised σ-coordinates
xxvi
(also called s-coordinates) are available for creating the model grid. A more
detailed listing of all new features is given in Chapter 1. Several years were
needed for debugging and testing of the code, in particular for all aspects of
the parallellisation.
The program is now ready for release as a free software and is given the
official name of COHERENS V2.0. Modules for biology, sediments and parti-
cle tracers are not yet implemented in the current version. Contrary however
to COHERENS V1 which has not been updated in more than ten years, V2.0
is a more dynamic version then V1. To this date several COHERENS users
provide regular updates in the framework of ongoing national and interna-
tional projects. Current activities include the implementation of a generic
biological model, a more extended sediment transport module which takes
account of different size classes, a particle tracer module, structures for engi-
neering applications in portuaries and water ways, an implicit scheme which
removes the mode splitting scheme, various inundation schemes, . . . .
Acknowledgements
COHERENS V2.0 has been written by Patrick Luyten (RBINS-MUMM).

Roger Proctor (POL) is acknowledged for providing access to supercomput-
ing facilities at CSAR (Univ. of Manchester) and the POL cluster at POL
during the ODON project. Useful advice for writing the code in parallel was
given by Mike Ashworth (STFC, Daresbury Laboratory). Testing and debug-
ging was facilitated by the assistance of several beta-users. Special thanks are
for Kaat Vandekerkhove and Philippe Hyde (ANTEA, Ghent, Belgium) for
their assistance in writing this User Documentation. The following persons
at MUMM are thanked for reviewing the documentation,: Katrijn Baetens,
Valérie Duliere, Sébastien Legrand, José Ozer and Stéphanie Ponsar. The
construction of V2.0 has been made possible thanks to the funding by the
European Union within the ODON (contract no. EVK3-CT-2002-00082) and
ECOOP (contract no. 36355) projects and by the VLABEL project funded
by the Flemish Region in Belgium (Uitbouw numeriek modelinstrument voor
de Noordzeehavens, Bestek 16EF/2008/02).
February 2011
xxvii
Version 2.1.2
The following features have been implemented:
1. CIF (Central Input File) utility. An option is foreseen which permits to
define model parameters (switches, time parameters, grid parameters,
model constants, forcing attributes, definitions for user output) through
input from a CIF, instead of making calls to usrdef interface routines
(Sections 7.4, 12.1).
2. A large series of “standard” variables can be selected by the user for
output using their key id value. In that case, the variable’s attributes
and output values are automatically generated by the program (Chap-
ter 16).
3. Additional boundary conditions for the baroclinic current can be se-
lected (Sections 4.10.2.1 and 5.3.16.1).
November 2011
Version 2.2.1
This is technical version, intended for future implementation of structures
(thin dams, current deflection walls, weires, groines).
December 2011
Version 2.3
• The existing drying and wetting algorithm has been extended by the
implementation of additional mask criteria.
• The program can be used to simulate the inundation of land areas by
(e.g.) an incoming tide or storm surge.
• Two new test cases for drying and wetting have been implemented.
Developers are the ANTEA Group in collaboration with RBINS-MUMM.
April 2012
xxviii
xxix
Part I
Introductory Manual
1
Chapter 1
General Overview
1.1 Introduction
During the last 25 years several two- and three-dimensional numerical model
codes have been developed and made available for applications in the global
ocean, shelf and regional seas, the coastal zones and estuaries. Without be-
ing complete we can mention public domain codes such as the global ocean
MOM model (Modular Ocean Model; Pacanowski & Griffies, 2000), the POM
(Princeton Ocean Model; Blumberg & Mellor, 1987) and ROMS (Regional
Ocean Model System) models for regional seas, FVCOM (Chen et al., 2006)
and GETM (Burchard & Bolding, 2002) for application in coastal and es-
tuarine environments. Besides these free software codes there exist several
licensed commercial softwares like TELEMAC, MIKE, Delft3d. The advan-
tage of a public domain code is that the source code is freely available and
can be modified by an experienced user. This is obviously not the case for
commercial codes. On the other hand, developers of free codes have no obli-
gation for providing user support which should, obviously, be the case for
the commercial ones. However, the lack of a substantial support can be com-
pensated by providing a detailed manual and model documentation to the
users.
A special category of the open source codes are the integrated “Com-
munity Models” which couple a core physical component with modules for
biology, sediments, waves, . . . . The construction of such models is a multi-
disciplinary task which requires the collaboration of a variety of specialists
and consumes a substantial number of years of scientific and programming
effort for designing, developing and testing the model code and to validate
the model against observational data.
COHERENS (coupled hydrodynamical-ecological model for regional and
3
4 CHAPTER 1. GENERAL OVERVIEW
shelf seas) is a three-dimensional hydrodynamic multi-purpose model for

coastal and shelf seas, which resolves mesoscale to seasonal scale processes.
The program has been developed initially over the period of 1990–1998 by
a multinational European group as part of the MAST projects PROFILE,
NOMADS and COHERENS funded by the European Union. During its de-
velopment it was applied for studies in the North Sea and regions of fresh
water influence (ROFIs) (Huthnance, 1997; Proctor, 1997; Luyten, 1999).
The first version, COHERENS V11 , has been released in April 2000 as
open source code. Besides the source code, the release contains an extensive
User Documentation (Luyten et al., 1999) and a series of test cases which can
be used to test the installation and as an illustration of the different options
available in the program.
The program was written in FORTRAN 77 and has four major compo-
nents:
1. A physical part with a general module for solving advection-diffusion

equations.
2. A simple microbiological module which deals with the dynamics of

microplankton, detritus, dissolved inorganic nitrogen and oxygen.
3. An Eulerian sediment module which deals with deposition and resus-

pension of inorganic as well as organic particles.
4. A component with both an Eulerian and a Lagrangian transport model

for contaminant distributions.
Its ease of implementation across a range of computing platforms made the

program attractive to groups with a sufficient expertise in modelling and in
need of sophisticated model products. Important advantages of the model are
its transparency because of its modular structure and its flexibility because
of the possibility to select different processes, specific schemes or different
types of forcing for a particular application. The program structure allows
users to perform process as well as predictive and operational setups without
knowledge of the detailed model structure. Since the official release more
than 1000 registrations have been recorded on the COHERENS home Web
page.
http://www.mumm.ac.be/coherens
1
The original version number 8.4 has been replaced by V1 to be compatible with the
currently adopted versioning system.
1.2. DESCRIPTION OF THE PROGRAM 5
where a publication list can be found with applications of COHERENS.

The work on a fully updated version of COHERENS started in 2003 as part
of the EU-FP5 and FP6 projects ODON (2003–2005) and ECOOP (2006-
2009). The first objectives were to produce an optimised code so that it can
be implemented on parallel machines and to provide user interfaces for model
setup independent of the main source code and for user-defined formats for
external files representing model forcing. A first version was presented at the
2006 EUROGOOS meeting (Luyten et al., 2006). In response to various user
requests new algorithms have been implemented or existing ones have been
improved (e.g. drying/wetting scheme, additional types of open boundary
conditions, turbulence schemes, baroclinic pressure gradient, astronomical
forcing, one-way nesting . . . ). More flexible model grids can be selected
using orthogonal curvilinear coordinates in the horizontal and extended σ-
coordinates (also known as s-coordinates) in the vertical.
The new version, denoted as COHERENS V2.0, is now available for the
scientific commnunity as open source code. Despite the numerous additional
implementations the new code only contains a physical component, in con-
trast to COHERENS V1. In the framework of ongoing projects the develop-
ment of a fully integrated version is now in progress. This includes in the
first place the coupling with a generic biological model, a sediment transport
model taking account of different size classes and a bottom boundary layer,
a morphological module, a Langrangian tracer module wich can also be ap-
plied for the dispersion of oil slicks and contaminants in general, and with
surface wave models such as WAM and SWAN. Additional improvements
are an implicit time integration scheme and schemes allowing to represent
inondation over a land topography.
1.2 Description of the program

The characteristics of COHERENS V2.0 are summarised below where a (*)
marks a new implementation or a change with respect to COHERENS V1.
1. Model code
• The code has been re-written in FORTRAN 90(*) replacing the

FORTRAN 77 used in the previous version. Important advantages
are:
– dynamic allocation of model arrays. This permits a more
efficient usage of internal memory and makes it easier to im-
plement a domain decomposition for parallel applications.
– modules replacing the INCLUDE statements in FORTRAN 77

and module routines used to create “internal libraries”.
– derived type variables for storing information of different “en-
tities” (files, model variables, external grid information) in a
structured format.
– array instead of element-wise assignment within DO loops.
– generic routines.
• Simulations can (optionally) be performed on parallel clusters
using the MPI (Message Passing Interface) communication library
(*). Advantages are a much faster computing speed and the pos-
sibility to distribute internal memory over different processes.
• CPP preprocessing for conditional compilation via #ifdef state-
ments (*). The method is primarely used for an easy implemen-
tation of external libraries. In this way the user can decide to
include the MPI (for parallel processing) and netCDF libraries (for
portable data formats) by setting a compiler switch.
• The program is (in principle) compiled with the UNIX/LINUX
make utility. A generic (machine-independent) Makefile is pro-
vided (*). The program can, in principle, be compiled on a Win-
dows platform. This is however not recommended.
• Model setup has been significantly changed with respect to
COHERENS V1. Definitions of model parameters and input of
model forcing data are made by calls to “usrdef ” routines (*)
which can be considered as a kind of user interfaces. These rou-
tines have to provided by the user. Although this requires some
programming skill of the user, model forcing can now be given in
any kind of user-defined format and independently from the main
source code. An option is foreseen to re-write each kind of for-
cing into a standard COHERENS format, including netCDF files
(*). Most setup parameters have default values which, for most
applications, do not need to be defined explicitly.
• The definitions of all model parameters (including default ones)
can optionally be obtained from a Central Input File (CIF) instead
of calling usrdef routines (*).
• A total of 84 switches are implemented for the selection of different
physical processes (barotropic or baroclinic, turbulence closures,
density effects, tidal forcing, nesting . . . ), type of model grid, nu-
merical schemes (advection and diffusion, open boundary condi-
tions, surface and bottom fluxes, drying and wetting algorithm,
1.2. DESCRIPTION OF THE PROGRAM 7
time-integration, . . . ), type of parallel communication, netCDF

output.
• A series of monitoring utilities is optionally available:
– The execution of the program can be traced in a “log” file.
– The program is checked for setup errors. When the program
traps an error, the program aborts with an explanatory mes-
sage. The level of error trapping can be selected by the user.
– Suspicious values of setup parameters are reported in a “warn-
ing” file (*).
– The program optionally writes a timer report containing the
% of time spent by different model compartments (*). The
utility can be applied to optimise parallel applications.
• Several simulations can be set up and executed within one run
(*).
• Restart times can be defined where the program writes initial
conditions for an eventual restart of the program (*).
2. Model grid
• A rectangular or a curvilinear (*) grid can be selected in the ho-

rizontal directions.
• The program uses σ-coordinates in the vertical. The grid size in
σ-space can either be uniform, non-uniform vertically and non-
uniform in both vertical and horizontal directions (*) (making it
equivalent to the “so-called” s-coordinate system).
• The model can either be set up on a 3-D grid, in 2-D (depth-
averaged) mode (*) or in 1-D (water column) mode.
• One-way sub-grid nesting (*) can be applied for 2-D and 3-D
model quantities using an off-line procedure. The advantage is
that multiple sub-grids can be simultaneously defined without any
restrictions of grid sizes and sub-grid time steps.
• Interpolation of model grid arrays at a different node is performed
either with uniform or non-uniform (*) weight factors.
3. Numerics
• The model equations are discretised on an Arakawa C-grid using

either Cartesian or spherical coordinates as selected by the user.
• The mode-splitting technique is applied to solve the 2-D and 3-D

momentum and continuity equations.
• The same time step is used for 3-D currents and 3-D scalars.
• Two different advection schemes are implemented: a first order
upwind and a more accurate TVD (Total Variation Diminishing)
scheme. A separate selection can be made for 2-D transports, 3-D
currents, 3-D scalars and turbulence transport variables.
4. Physics
• The program runs by default in barotropic mode, i.e. without den-
sity effects. Temperature and salinity can be included via separate
switches.
• Density effects in the momentum and turbulence equations are
included via an equation of state. A correction has been made
with respect to COHERENS V1 since the simulated temperature
field represents potential temperature instead of the physical “in
situ” one.
• The absorption of solar radiation in the upper part of the water
column is implemented by an optical module.
• The program incorporates a variety of turbulence schemes rang-
ing from simple algebraic formulations to one- or two-equation
schemes (Mellor-Yamada, k − ε). Additional RANS models have
been implemented (*).
• On request of the users, additional types of open boundary con-
ditions have been implemented (*), while corrections have been
made to some of the existing ones.
• Different formulations for the wind stress and surface heat fluxes
are available. Additional schemes have been added (*).
• A drying/wetting algorithm is implemented in Version V2.0. An
extended scheme for simulating the flooding of land areas and the
flows over obstacles has been added in Version 2.3.
• A wave-current interaction module has not yet been implemented
in COHERENS V2.0.
1.3 User experience

The COHERENS program has been designed such that it can be applied by
users with a “low” or a “high” level of model experience. In the former
1.3. USER EXPERIENCE 9
case the program is set up by defining a limited number of parameters (e.g.

time steps, a few model switches, attributes for model forcing, . . . ) whereas
default values can be taken for most model parameters. Bathymetry, initial
conditions, open boundary and surface forcing conditions are provided by the
user via the usrdef model setup routines. To facilitate its use for experienced
modellers, the program is supplied in modular form. This allows to replace a
module by a user-defined version without affecting the core of the program.
It is clear that this practice is not without danger especially when the module
is linked with other program units. Changing the default settings of switches
and model parameters is easily performed but not always without risk.
For a user it is important to know which specific experience is required to
run COHERENS for a particular type of application. There are two basic cri-
teria: programming experience and scientific background. They are further
discussed below.
1.3.1 Programming experience

A basic knowledge of FORTRAN 90 is required. As explained in Part IV
(User manual) a series of FORTRAN source code files need to be created
for a user application. Generic example files have been made available to
facilitate this. In this files the user only needs to replace or add a number
of assignment statements or insert READ instructions for data input. All
aspects of model setup are, in principle, covered by the usrdef interfaces.
This makes this version more flexible than COHERENS V1, since there is no
need to change the main code. However, if it is the intention to implement
new schemes or to add new modules, the user must have, besides a good
skill in programming with FORTRAN 90 have a good understanding of the
general concept, including the parallellisation of the program, and internal
structure of the COHERENS code. For this reason Part III (Model code) has
been written for developers and covers all different aspects of the model code.
Installing and compiling COHERENS V2.0 only requires a limited knowl-
edge of the UNIX/LINUX operating system. For installation and linking
with external libraries the user is referred to the manuals which are provided
by the software developers and are freely available through the internet.
1.3.2 Scientific background

The default settings make it easier to run the model without a detailed
knowledge of the underlying scientific basis. Only a limited number of de-
fault values need to be changed for most applications. Detailed instructions
are given in this documentation together with a large number of examples
(see Part V). A more specific scientific background is required if for ex-
ample the user intends to perform experiments with different turbulence or
numerical schemes or with alternative settings of model parameters. It is
then recommended to read first the appropriate chapters of Part II (Model
Description).
1.4 Contents of the documentation

1.4.1 Structure
This documentation is composed of six parts covering different aspects of the
COHERENS program.
I. Introductory manual.
Instructions for installing, preparing and running a pre-defined test case
and a user application are given in Chapter 2. The graphical interface
program and visualisation of model output with netCDF are discussed
in Chapter 3.
II. Model description.

The scientific background of COHERENS is described in Chapter 4.
Numerical aspects are the subject of Chapter 5. In this chapter the
discretisized forms of the model equations are written out in full detail.
III. Description of the model code.

This part is mainly intended for model developers, although some as-
pects can be useful for beginning users as well. Program conventions
and model layout are explained in Chapter 6. Chapter 7 deals with
different aspects of model input and output: purpose of the files con-
nected to the program (monitoring, forcing, model output defined by
the user), implementation in the model, structure of a file in standard
COHERENS format. Chapter 8 explains how arrays are defined on the
model C-grid and the types, principles and implementation of interpo-
lation (internal on the model grid, from an external grid to the model
grid, from the model to external data locations as used in the nesting
procedures). Chapter 9 is devoted to the parallelisation of the code
(general principles, domain decomposition, array halos, implementa-
tion of process communication with the MPI library, index mapping).
Chapter 10 provides a listing of all source code files with their purpose
and illustrates the general structure of the code with flow diagrams.
1.4. CONTENTS OF THE DOCUMENTATION 11
IV. User manual.

This part is undoubtly the most important one of the documentation.
The meaning and contents of each usrdef routine are discussed in the
following chapters:
• Chapter 11: general priciples of model setup, listing of all usrdef

routines and files
• Chapter 12: switches, model parameters, forcing attrributes, setup
of monitoring and the parallel mode
• Chapter 13: model grid, bathymetry, initial conditions
• Chapter 14: open boundary conditions
• Chapter 15: surface boundary conditions and nesting
• Chapter 16: different kinds of user output
V. Test cases.
The test cases experiments which are provided with the distribution of
the source code, are presented. The aim is to test the portability of the
code, to illustrate how model setup is performed and to show different
types of applications.The results are briefly discussed and illustrated
with figures and tables which may be used by the user for comparison.
• Chapter 17: purpose of the test cases, CPU time table obtained
on different computing platforms
• Chapter 18: numerical tests for advection schemes
• Chapter 19: turbulence schemes and heat flux formulations
• Chapter 20: density fronts in a channel, river plumes
• Chapter 22: application in a shelf sea
VI. Reference manual.

This part provides a listing of all program routines with their syntax
and purpose and of all program variables with a global scope in the
program.
• Chapter 22: external routines
• Chapter 23: module routines which are mainly used by the pro-
gram as internal libraries
• Chapter 24: usrdef routines
• Chapter 25: program variables defined in the FORTRAN 90 mo-
dules
1.4.2 Suggestions for reading

The documentation is written, as much as possible, in a self-contained form.
Appropriate links are made, where necessary, to chapters and sections where
a specific topic is explained in more detail.
Beginning users whose prime intentions are to perform simple simula-
tions with the model and have less interest in learning all the features of
COHERENS, are not obliged to read this voluminous documentation as a
whole, but may proceed as follows:
1. Read Part I.
2. Select a few test cases from Part V to test the portability of the model.
Have a look at the source code files used to set up the selected test
cases.
3. Read those sections of Part IV which are of interest for the intended
application.
4. Create the source files for the application using the setup of an anal-
ogous test case. For more information about the model setup or the
name of certain variables for model output consult the reference ma-
nual.
On the other hand, if the user wants to learn about the full model’s
capacities or has the intention to extend the code with a new implementation
it is recommended to read this manual in more detail, especially Part III and
Chapter 5 about the discretisation methods used in the program.
Conventions used in the document

The text is typesetted in LATEX2e. The following numbering conventions are
adopted:
• Chapters and pages are numbered continuously over all Parts.
• Sections are numbered in a two-number format (Chapter-Section).
• Subsections are numbered in a three-number format (Chapter-Section-

Subsection).
• Equations, figures and tables are numbered in a two-number format

(Chapter-Equation/Figure/Table).
Specific names and keywords are outlined in different LATEX fonts:
1.4. CONTENTS OF THE DOCUMENTATION 13
• sans serif style for the FORTRAN names of program variables and spe-
cific keywords
• bold for the names of directories
• slanted style for the names of files
• emphasised bold for the names of test cases
• type-writer font for sections of model code and UNIX command

names
Chapter 2
Getting Started
The aims of this chapter are to explain program installation and compilation,
how to run one of the built-in test cases and to summarise the different steps
for setting up a user-defined application. It is assumed that the operating
system is either UNIX or LINUX1 .
This chapter is organised as follows:
• Instructions for installation and a description of the program’s file sys-
tem are given in Section 2.1.
• Compilation is explained in Section 2.2.
• The different steps needed to run a test case are explained in Sec-
tion 2.3. For a detailed description of all test cases the reader is referred
to Part V.
• An example for installing and running a user-defined application is
given in Section 2.4.
• Implementation of external libraries is discussed in Section 2.5.
• A general outline explaining how to set up a realistic application of the
model, is presented in Section 2.6. For a complete description the user
is referred to the User Manual (Part IV).
2.1 Installation
In the following it is assumed that the compressed file with the model code,e.g.
coherensV20.tar is downloaded on the user’s home directory. To retrieve the
1
Installation and compilation of COHERENS under a WINDOWS platform is not ex-
cluded a priori but is beyond the scope of this User Documentation.
15
16 CHAPTER 2. GETTING STARTED
files use:
tar -xvf coherensV2.1.2.tar.gz
This creates the root directory coherens/V2.1.2 which contains the

following subtrees:
1. code
• source: the standard COHERENS source code

• comps: files used for compilation
• scr: examples script for running the code on a UNIX platform.
For serial runs Run is the most obvious choice.
• biology: contains the source (source) and compilation (comps)
files needed for implementation of biological modules. The source
files here only contain empty routines and are only needed for a
proper compilation of the COHERENS code.
2. setups
• examples: example code for setting up a user application

• ptests: check-up tables for each test simulation on subdirectories
representing different computing platforms
• cones, . . . : setup of a pre-defined test case
3. utils: utility programs
• decomp: utility program for creating a domain decomposition

• post: (non-portable) postprocessing program
4. data: data files used in some of the test case applications
The file install test is a script, primarily intended for installing a test
case. Its purpose is further explained below.
2.2 Compilation
To compile the COHERENS source code, the following tools are essential:
• FORTRAN 90 compiler.
• C-preprocessor, usually cpp

2.2. COMPILATION 17
• a compiled MPI library which is needed (only) for simulations in parallel

mode. Note that MPI is not supported by all compilers.
• a compiled netCDF library (version 3.6 or higher) which is needed (only)

to read and write data in portable netCDF format
Compilation is performed with the UNIX/LINUX make utility. The rules

for making the executable file coherens are defined in the file Makefile located
in the comps directory. Contrary to COHERENS V1 this file is given in a
portable format, i.e. independent of the type of compiler or operating system.
Makefile reads input from a series of additional files:
• objects.cmp: defines macros with a listing of objects (*.o) files
• dependencies.cmp: describes all file dependencies for the compiler
• compilers.cmp: defines targets for different compilers and computing

platforms
• options.cpp: list of compiler options for the C-prepocessor
The first two files are portable and should not be changed unless the main
source code in source has been modified by the user. The last two are user
dependent. They are further discussed below.
2.2.1 compilers.cmp
A new target is defined by inserting the following lines, using the format
below, in compilers.cmp:
target\_name:
\$(MAKE) \$(EXEFILE) "MAINFILE=\$(MAINFILE)" "VPATH=\$(VPATH)" \
"CMPDIR=\$(CMPDIR)" \
"FC=" "FCOPTS=" "FCDEFS=" "FCDEBUG=" \
"FCIFLAGS=" "FLIBS="\
"CPP=" "CPPF=" "CPPOPTS=" "CPPDEFS="
where target name is arbitrarily defined by the user. Line 2 is intended by

one TAB position, the following ones by blanks only. The macro definitions
on lines 2 and 3 should not be changed, those on the next lines can either
be defined by the user or remain undefined. The latter have the following
meaning
FC
name of the Fortran 90 compiler, eventually preceded by its directory
path, such as f90, /usr/bin/gfortran, mpif90 for parallel runs using
MPICH). This macro has to be defined always.
FCOPTS
Optimisation options for the Fortran compiler.
FCDEFS
Set to $(CPPDFLAGS) if the C-preprocessor is implicitly invoked by
the Fortran compiler, or left undefined otherwise.
FCDEBUG
Debugging options for the FORTRAN compiler, e.g. -g (optional).
FCIFLAGS
Search path for (pre-compiled or source code) module files. This is
only needed for modules linked to external libraries (e.g. -I/usr/include
which is the default used by the netCDF installation procedure).
FLIBS
Options to link the source code to an external library (e.g., -L/usr/lib
-lnetcdf which is the default used by the netCDF installation procedure).
CPP
Name of the C-preprocessor including options (except -D options), such
as gcc -E, if invoked implicitly by the Fortran compiler, undefined other-
wise.
CPPF
Name of the C-preprocessor, if not invoked by the Fortran compiler or
set to @cp otherwise.
CPPOPTS
Options for the C-preprocessor, excluding -D options, in case that the
C-preprocessor is defined by CPPF, undefined otherwise.
CPPDEFS
Undefined if FCDEFS is defined, set to $(CPPDFLAGS) otherwise.
A number of standard targets are already defined such linux-gfort for the
gfortran and linux-iforts, linux-ifortp for compilation with the INTEL compiler
in serial, respectively parallel mode.
2.2. COMPILATION 19
2.2.2 options.cpp
The macro CPPDFLAGS is defined in the file options.cpp. The syntax is
CPPDFLAGS = -Dname1 -Dname2 ...
where name corrsponds to a C-language statement in the source code of the
form
#ifdef name
...
#endif
or
#ifdef name
...
#elseif
...
#endif
If name is defined in CPPDFLAGS, the C-preprocessor retains all statements
between #ifdef and #endif (first form) or between #ifdef and #else (second
form) and removes all statements between #else and #endif (second form).
If name is not defined, all statements are removed between #ifdef and #endif
(first form) or between #ifdef and #else (second form) and all statements are
retained between #else and #endif (second form). Finally, the lines starting
with # are removed. The remaining code is then passed to the FORTRAN
compiler.
The following values of name are implemented:
MPI
Needed for parallel execution of the program. An error is issued by
the compiler if the MPI library is not installed and linked to the main
source code.
CDF
Needed for data input/output in netCDF format. An error occurs if the
netCDF library is not installed and linked to the main source code.
ALLOC
Option for allocation of most local arrays in the model. This will
provide a more efficient memory management, but may have a negative
impact on CPU performance.
In the default version of options.cpp, supplied with the source code, CPPDFLAGS
is left undefined.
2.2.3 Testing compilation

Compilation can be tested by the following recommended procedure
1. Select a working directory, e.g.
cd /home/models/work
2. Create a link with the COHERENS root directory
ln -s path name COHERENS
where path name is the path name of the coherens/V2.1.2 root

directory, e.g. /home/models/coherens/V2.1.2.
3. Install the standard COHERENScode
COHERENS/install test
The script install test creates links to subtrees of coherens/V2.1.2,

copies the Makefile and options.cpp files and all the files in the scr sub-
directory to the current directory.
4. Compile
make target name
where target name equals one of the targets defined in compilers.cmp.
The Makefile script reads the options.cpp file residing in the working
directory, which, by default, includes no compiler options. Implementation
of the MPI or netCDF library can be tested by inserting the appropriate
compiler options (see Section 2.5 below).
2.3 Installing and running a test case

In addition to the main source code a total of 12 pre-defined test cases are
supplied to the user. Their aim is to:
• test the installation and compilation of the code
• provide examples of model setups

2.3. INSTALLING AND RUNNING A TEST CASE 21
Table 2.1: Test case descriptions
Name Experiments Description

cones A–D advection of a uniformly rotating “cone” shaped contaminant
distribution
front A–D advection of a layered contaminant distribution by a tidal
slope current
seich A–E propagation of an internal wave within a closed channel
fredy A–D generation of baroclinic instabilities by a fresh water distribu-
tion immersed in a rotating basin
pycno A–G deepening of an initiallly stratified surface layer by action of
a uniform wind stress (1-D application)
csnsp A–I evolution of temperature and seasonal stratification at station
CS in the central North Sea (1-D application)
river A–D propagation of a salinity front in a tidal channel
plume A–G formation and evolution of a tidally modulated river plume
rhone A–G simulation experiments of the Rhone plume in the Gulf of
Lions (Mediterranean Sea)
flood2d A–D flooding and drying experiments in a channel using different
bathymetries
flood3d A–D flooding and drying experiments in a rectangular basin using
different bathymetries
bohai A–F barotropic tidal simulations of the Bohai Sea (northern part
of the Yellow Sea)
• show how model results are affected by different setups (e.g. numerical
schemes, turbulence closures, different kinds of processes, . . . )
• provide a debugging tool
Table 2.1 provides a list of all test cases. Each case is composed of a series of
experiments. The first five represent idealistic cases, the others are examples
of more realistic simulations. Each experiment has a name given by the name
of the test case followed by an upper case letter. For examples, the cones
test consists of four experiments each representing a separate simulation:
conesA, conesB, conesC, conesD. A total of 57 experiments are defined
in this way.
The procedure for installing and running a specific test case is analogous
to the one presented in Section 2.2.3. The complete procedure, including
running the application, is as follows.
1. Select a working directory, e.g.
cd /home/models/work
2. Create a link with the COHERENS root directory
where path name is the path name of the coherens/V2.1.2 root di-
rectory, e.g. /home/models/coherens/V2.1.2.
3. Install the test case
COHERENS/install test test name
where test name is the name of the test case (e.g. cones). This
creates links to subtrees of coherens/V2.1.2, copies the Makefile and
options.cpp files, all the files in the scr subdirectory and the setup files
in setups/test name to the current directory.
4. Compile
make target name
where target name equals one of the targets defined in compilers.cmp.
5. Run all experiments
./Run
or equivalently,
./coherens
Instead of running all test cases at once, the user can make a selection by
editing the file defruns. This file contains the names of all experiments for
the specific test case on different lines. If a ‘!’ is inserted at the beginning of
a line, the corresponding experiment will be skipped.
To illustrate the use of the CIF utility, the test case runs can be set up
in two modes, depending on different choices for the defruns file. In the first
case, the defruns file located in the test case directory is taken and the setup
is as before. In the second case, instructions for installation are the same as
before except that the following copy has to be made in the working directory
2.3. INSTALLING AND RUNNING A TEST CASE 23
cp cifruns defruns
If Run is executed, two simulations are performed for each experiment:
1. The program creates a CIF and a series of forcing files in COHERENS

standard format. No calculations are preformed.
2. The test is run again. The program reads all model setup parameters
and forcing data from the previously created CIF and standard forcing
files.
The CIF utility is further discussed in Sections 7.4 and 12.1.
The following checks can be made for a succesfull run:
1. The Run script terminated with exit status 0.
2. The program terminates with the message, sent to standard output

(screen or batch file):
Main program terminated
3. At the start of each numerical experiment, the program creates a file

whose name equals the experiment’s name (as listed in defruns) fol-
lowed by the suffix .errlogA (e.g. conesA.errlogA). The file is used for
the writing of eventual error messages and is automatically deleted at
the end of the simulation. An error occurred if the file still exists, even
without any contents, after completion of the run.
4. The program writes run-time information to a “log”-file with suffix

.runlogA (e.g. conesA.runlogA). The last line of this file should read
Close file log file on unit 1 (A)
where log file is the name of the “log”-file.
It is clear that even when the program terminates without any noticeable
error, the results can still be incorrect. This can easily be verified. Each
experiment produces a file with suffix .tst (e.g. conesA.tst). The file contains
values of some critical parameters produced by the simulation. These can be
compared to the ones obtained from a reference run and listed in a file with
the same name located in the setups/examples subdirectory.2
2
The parameter sdev defined in some test cases is only used as a measure of rounding
errors and should not be considered as critical.
2.4 Installing a user application

The procedure below, analogous to the one followed for installing a test case,
is to be considered as an example
1. As discussed below a series of setup files needs to created by the

user. Assume now that they are located on some user directory, say
/home/user/mytest
2. Select a working path for compilation and running of the application,

e.g.
cd /tmp/user/mytest
3. Create a link with the COHERENS root directory where path name is
the path name of the coherens/V2.1.2 root directory, e.g. /home/models/
coherens/V2.1.2.
4. Install the user application on the current directory
COHERENS/install test mytest /home/user
This creates links to subtrees of coherens/V2.1.2, copies the Makefile

and options.cpp files, all the files in the scr subdirectory and all the
setup files in /home/patrick/mytest to the current directory.
5. Run the application
./Run
or equivalently,
./coherens
2.5. RUNNING AN APPLICATION WITH EXTERNAL LIBRARIES 25
2.5 Running an application with external li-

braries
2.5.1 Parallel application
The procedure is analogous to the previous ones with the following additional
steps:
1. Make sure that the MPI library is properly installed.
2. Insert the appropriate library options in compilers.cmp (if needed).
3. Insert -DMPI in options.cpp.
4. The parameter nprocs, defined in the routine usrdef mod params (file
Usrdef Model.f90) must be set to the number of processes used in the
parallel application.
5. Edit the Run script according to the guidelines for running a MPI ap-
plication on the user machine, e.g.
mpirun - np 4 ./coherens
to run the application using 4 processes with MPICH.
2.5.2 Using netCDF output format

The following additional steps are needed:
1. Make sure that the netCDF library (Version 3.6 or later) is properly
installed.
2. Insert the appropriate library options in compilers.cmp.
3. Insert -DCDF in options.cpp.
4. In subroutine usrdef tsr params within the file Usrdef Time Series.f90,
change the values of the parameters(s) ending with %form to ‘N’. When
the run is completed, all time series output will be available in netCDF
format.
2.6 Setting up a user application

Model setup consists in defining, firstly, a series of model parameters for
initialisation and, secondly, providing different kinds of input data at run-
time. This is implemented in the code via calls to routines located in Usrdef *
files. These routines need to be programmed by the user. A summary of their
contents is given below. A detailed discussion is given in Part IV.
1. Usrdef Model.f90
• parameters for “monitoring”

• model switches
- activate/deactivate program modules
- selection of a specific numerical/physical scheme
• parameters which determine the kind of forcing input (e.g. file
name, type of file, ...)
• parameters for parallel setup
• define external surface data grid(s) if regular
• model grid, bathymetry, locations of open boundaries
• initial conditions
• open boundary conditions for the 2-D and 3-D mode
• insert code to read the open boundary data
2. Usrdef Surface Data.f90 : meteorological and/or SST forcing
• define surface grid(s) if non-regular

• insert code for reading forcing data
3. Usrdef Nested Grids.f90
• define locations of nested sub-grids
4. Usrdef Time Series.f90 : time series model output
• define “metadata” information

• define output resolution in space and time
• define output parameters
• define output data
5. Usrdef Time Averages.f90 : time averaged model output

2.6. SETTING UP A USER APPLICATION 27
6. Usrdef Harmonic Analysis.f90 : harmonic analysis and output (residu-

als, amplitudes, phases, elliptic parameters)
7. Usrdef Output.f90 : output defined by the user in any kind of (non-

COHERENS) format
Remarks
1. It is clear that the user only needs to define what is needed for the
application.
2. (Almost) all parameters which can be defined, have default values.

Only a few need to be re-defined by the user.
3. Options are provided to write all parameters and forcing data to files
in a standard COHERENS format. These files can be used for model
setup in subsequent runs.
4. It is foreseen in future updates of the model code to make a complete

setup through a “central” input file.
Procedures for creating Usrdef files.
1. The simplest way is to copy the setup (Usrdef files) of a suitable test
case and make the necessary adaptations. The method is recommended
for applications which do not require a too complicated setup.
2. A generic version of each Usrdef file is located in the /setups/examples

subdirectory. All parameters are listed with their default values or with
an undefined value (given by a ?). The user may re-define the default
and either replace the question mark by a specific value or remove those
lines. There are, however, no defaults for defining the input of forcing
data unless the data are read from a file in standard COHERENS for-
mat.
Chapter 3
Graphical display
The aim of this chapter is to describe model output from COHERENS and
to illustrate how model output can be visualised.
3.1 Introduction
The ability to view the results from COHERENS, and to subsequently ma-
nipulate the output data, is an important requirement of the model sys-
tem. Since there exist many free and commercial software packages for dis-
playing model results, the objective is to provide access to the model data
in an internationally recognised format, allowing ease of transfer from one
platform to another, and access to a wide range of software for data dis-
play/manipulation.
The data format selected for standardisation of COHERENS model data
is netCDF (network Common Data Form). This is widely accepted in the
meteorological/oceanographic community as a standard data format, both
for observational data and model data, and many software packages support
a netCDF interface. NetCDF is freely available.
The netCDF software was developed at the Unidata Program Center in
Boulder, Colorado, USA. NetCDF (network Common Data Form) is an in-
terface for array-oriented data access and a freely-distributed collection of
software libraries for C, FORTRAN, C++, and perl that provide implemen-
tations of the interface. The netCDF software was developed at the Unidata
Program Center in Boulder, Colorado (Pincus & Rew, 2008) and augmented
by contributions from other netCDF users. The netCDF libraries define a
machine-independent format for representing scientific data. Together, the
interface, libraries, and format support the creation, access, and sharing of
scientific data.
29
30 CHAPTER 3. GRAPHICAL DISPLAY
Standard output in COHERENS can be provided in three formats: ASCII

(‘A’), unformatted binary (‘U’) and netCDF (‘N’). The advantages of using
netCDF output formats is the range of software available (both commercial,
shareware and freeware) which automatically recognises the data format and
the ease with which data can migrate between platforms and users.
NetCDFdata are:
• Self-Describing. A netCDF file includes information about the data it

contains.
• Network-transparent. A netCDF file is represented in a form that can

be accessed by computers with different ways of storing integers, char-
acters, and floating-point numbers.
• Non-sequential (direct) access. A small subset of a large dataset may

be accessed efficiently, without first reading through all the preceding
data.
• Appendable. Data can be appended to a netCDF dataset along one

dimension without copying the dataset or redefining its structure. The
structure of a netCDF dataset can be changed, though this sometimes
causes the dataset to be copied.
• Sharable. One writer and multiple readers may simultaneously access

the same netCDF file.
This and more info can be accessed at the home page
http://www.unidata.ucar.edu/software/netcdf/
3.2 COHERENS output files

The properties of the output data are defined by the user following the in-
structions given in Chapter 7. Model output is written by COHERENS in the
form of a data file which contains either 0-D, 2-D or 3-D output data.
For example, the names of these output files for the plume experiment
A are given by
plumeA 1.tsout3U, plumeA 2.tsout3U, plumeA 3.tsout3U,

plumeA 4.tsout2U, plumeA 1.resid2A, plumeA 1.resid3A,
plumeA 1.1amplt2A, plumeA 1.1phase2A, plumeA 1.1ellip2A,
plumeA 1.1ellip3A
3.3. VISUALISATION OF MODEL RESULTS 31
The general form of an output file name is a string of L+10 characters:

• characters 1–L: output title. In the case of a test case run the title is
given by the name of the test case (e.g. cones) followed by the name
of the experiment (1 character, e.g. A).
• character L+1: ‘ ’ (underscore)
• character L+2: file number
• character L+3: ‘.’ (dot)
• characters L+4:L+8: describes the kind of output. Allowed values are:
– tsout: time series output

– avrgd: time-averaged output
– resid: output of residuals
– amplt: output of harmonic amplitudes
– phase: output of harmonic phases
– ellip: output of tidal ellipse parameters
• characters L+9: ‘0’ for a “globally” evaluated or non-spatial model

data, ‘2’ for a 2-D (horizontal) output data file without vertical di-
mension, ‘3’ for a 3-D output data file with horizontal and vertical
dimensions.
• character L+10: type of data format
‘A’ ASCII
‘U’ unformatted binary data
‘N’ netCDF data.
‘I’ information file with metadata information in ASCII format
3.3 Visualisation of model results

In selecting a data visualisation and display package for COHERENS, several
factors have been taken into consideration: proprietary use, ease of use, user
support, output products. Many of the commercial packages, e.g. MATLAB,
PV-Wave, IDL, support a netCDF interface, i.e. data in netCDF format can
be taken as input to the package and the package “knows” what the data
looks like.
Whilst commercial packages are widely used in the marine science com-
munity, it is apparent that no single package is preferred to the others. It
therefore makes more sense to recommend the use of software which is freely
available and which can easily be obtained. It might be argued that commer-
cial software is a better option in so much as it is (usually) well documented,
well maintained and with regular upgrades, and covers a wide range of gene-
ral use.
3.3.1 FERRET
FERRET has produced and made available by PMEL (Pacific Marine En-
vironmental Laboratory) in the United States. The package has been con-
structed over many years to visualise 4-D (three space and time) meteoro-
logical and oceanographic data, is freely available over the internet, has good
documentation, a user group and help facilities. It primarily expects datasets
to be input in netCDF form but also allows data to be input in ASCII or bi-
nary form. FERRET is a recommended package for the display of COHERENS
data. One advantage for COHERENS users (apart from being simple to use)
is that the package is primarily oriented towards “real world” datasets and
installs with global coastlines. As it is envisaged that most COHERENS users
will develop real world applications, a visualisation package which supports
this makes model development much easier. However it is a simple matter
within FERRET to display data in Cartesian coordinates.
FERRET is found to be the best of the available freeware packages, it
fulfils many of the requirements of the COHERENS user: time series (single
point, space/time), contours (line and fill), vectors, surfaces (wire frame),
overlays and movie generation, both in “real world” (longitude/latitude) as
in Cartesian coordinates. FERRET can be implemented by the user for visu-
alisation or writing of data into netCDF format.
The package can be downloaded from the FERRET web page
http://ferret.wrc.noaa.gov/Ferret/
3.3.2 NCView
Another visual browser for netCDF data format files is NCView. NCView
displays a 2-dimensional, color representation of data in a netCDF file and
this in a quick and easy way. This GUI-based tool makes it possible to
show simple movies of the data, to view along various dimensions, to take
a look at raw data values, to change color maps, to invert the data, . . . .
3.3. VISUALISATION OF MODEL RESULTS 33
Although easier to use than FERRET, the number of available plot types is
more limited.
The home page of the author, David W. Pierce contains useful information
and links on how to visualise COHERENS output format with NCView. It is
located at
http://meteora.ucsd.edu/~pierce/ncview home page.html
3.3.3 MATLAB
As mentioned in this section MATLAB version 7.7 and later contains the
ability to read data from and write data to netCDF files (known as datasets
in netCDF terminology). For earlier versions a MATLAB/netCDFinterface is
necessary (i.e. NetCDF Toolbox, MexEPS, CSIRO, fanmat, etc). A MAT-
LAB script can be used to enable generate numerical data, figures and tables
from netCDF data, through more than 30 functions.
This and other info on the visualisation of model results with MATLAB
can be found at
http://www.mathworks.com/access/helpdesk/help/techdoc/ref/netcdf.html
Part II
Model description
35
Chapter 4
Physical model
4.1 Model coordinates

4.1.1 Coordinate systems
The coordinate units, used within the program, are either Cartesian (x, y, z)
or spherical (λ, φ, z), with the z-axis directed upwards along the vertical. The
Cartesian coordinates are defined in a horizontal plane tangent at a location
on the Earth’s surface. In the spherical system λ and φ represent respec-
tively the longitude (positive in the eastern, negative in the western hemi-
sphere) and the latitude (positive in the northern, negative in the southern
hemisphere). The vertical coordinate is chosen such that the surface z = 0
corresponds to the mean sea water level. This gives
z = ζ(x, y, t) or z = ζ(λ, φ, t) at the free surface (4.1)
z = −h(x, y) or z = −h(λ, φ) at the bottom (4.2)

where ζ is the sea surface elevation and h the mean water depth so that the
total water depth H is given by H = h + ζ.
Cartesian coordinates make it easier to set up a model grid in the hori-
zontal and can be used for size-limited areas where the Earth’s curvature is
negligible and the Coriolis frequency can be considered as uniform in space.
A further advantage is that the coordinate axes can be arbitrarily rotated in
the horizontal. Rotation of a spherical coordinate system is less straightfor-
warded and is considered by the program as a particular case of a curvilinear
grid (see below).
Coordinate units are meters in the Cartesian and decimal degrees in the
spherical case with −1800 ≤ λ ≤ 1800 and −900 ≤ φ ≤ 900 .
37
38 CHAPTER 4. PHYSICAL MODEL
Implementation
Coordinate systems are selected in the model with the switch iopt grid sph:
0 : Cartesian
1 : spherical
4.1.2 Coordinate transforms in the horizontal

The program allows to define horizontal grids in a more flexible way through
the introduction of curvilinear coordinates. Consider firstly the following
general horizontal coordinate transform
ξ1 = f1 (x, y) , ξ2 = f2 (x, y) (4.3)
The inverse transform becomes
x = F1 (ξ1 , ξ2 ) , y = F2 (ξ1 , ξ2 ) (4.4)
The distance between two neighbouring (grid) points is given by
∆d2 = ∆x2 + ∆y 2
 !2 !2   !2 !2 
∂F1 ∂F2  ∆ξ 2 + 
∂F1 ∂F2  ∆ξ 2
=  + 1 + 2
∂ξ1 ∂ξ1 ∂ξ2 ∂ξ2
!
∂F1 ∂F1 ∂F2 ∂F2
+ 2 + ∆ξ1 ∆ξ2 (4.5)
∂ξ1 ∂ξ2 ∂ξ1 ∂ξ2
If
∂F1 ∂F1 ∂F2 ∂F2
+ =0 (4.6)
∂ξ1 ∂ξ2 ∂ξ1 ∂ξ2
then
∆d2 = h21 ∆ξ12 + h22 ∆ξ22 (4.7)
and (ξ1 , ξ2 ) are then called orthogonal curvilinear coordinates. This means
geometrically that the coordinate curve along which ξ1 is a constant, inter-
sects the curve along which ξ2 is constant orthogonally.
Note that spherical coordinates can be considered as “pseudo”-curvilinear
coordinates with respect to Cartesian coordinates with h1 = R cos φ and
h2 = R where R is the mean radius of the Earth, defined as the radius of a
sphere having the same volume as the Earth or 6371 km (see Appendix 2 of
Gill, 1982)
4.1. MODEL COORDINATES 39
In practice ∆ξ1 , ∆ξ2 are both normalised to 1, so that the metric coeffi-
cients h1 , h2 now become the grid spacings along the curvilinear coordinate
lines.
Once the curvilinear coordinates are defined, a computational grid can
be constructed in the horizontal by drawing a sequency of coordinate lines.
Some example grids are shown in Figure 4.1.
(a) Uniform Cartesian grid (b) Cartesian non−uniform rectangular grid
(c) Spherical non−uniform rectangular grid (d) Curvilinear non−rectangular grid
Figure 4.1: Examples of horizontal grids.
Implementation
The type of horizontal grid is selected with the switch iopt grid htype:
1: uniform rectangular (i.e. non-curvilinear) grid. In the Cartesian case, the

grid lines are equidistant in the X- and Y-direction, but ∆x (distance in
the X-direction) may differ from ∆y. In the spherical case, the coordinate
lines are latitude and longitude circles, but ∆λ 6= ∆φ in general.
2: non-uniform rectangular grid, with ∆x(x) and ∆y(y), or ∆λ(λ) and ∆φ(φ).
3: curvilinear (i.e. non-rectangular) grid. In that case the grid spacings

depend on both horizontal coordinates. Without loss of generality, the
distance between two grid lines in curvilinear coordinates can be set to 1.
4.1.3 Coordinate transforms in the vertical

4.1.3.1 σ-coordinates
The σ-coordinate is defined by (Phillips, 1957)
z+h z+h
σ= = (4.8)
H h+ζ
where σ varies between 0 at the bottom and 1 at the surface1 . The reverse
formula is obviously
z = σH − h (4.9)
so that the grid spacing in the vertical becomes
∆z = H∆σ (4.10)
The spacings of vertical σ-points ∆σ are horizontally uniform, but can be

taken as either uniform or non-uniform in the vertical.
Advantages are:
• much simpler boundary conditions at the surface and bottom
• a better resolution of surface and bottom layers
However there are well-known disadvantages of using σ-coordinates:
• areas with steep bathymetric gradients are difficult to present
• large errors can be produced by discretisation of the baroclinic pressure

gradient
A non-uniform σ-grid can be obtained by means of a transformation of the

form
σ̂ = F (σ) or its inverse σ = G(σ̂) (4.11)
1
Note that the definition is different from the traditional one σ = (z − ζ)/H with
−1 ≤ σ ≤ 0.
where F and G are increasing functions and σ̂ equals 0 at the bottom and
1 at the surface. Davies & Jones (1991) defined the following logarithmic
transformations " #
1 σ̂ σ̂
σ= ln(1 + ) + (4.12)
α σ0 σ∗
" #
1 1 − σ̂ 1 − σ̂
σ =1− ln(1 + )+ (4.13)
α σ0 σ∗
where
1 1
α = ln(1 + )+ (4.14)
σ0 σ∗
The first (second) form provides a more refined resolution at the bottom (sur-
face). The extent of the logarithmic grid is set by the tunable parameter σ∗ .
Burchard & Bolding (2002) considered a formulation with refined resolu-
tions near both the bottom and surface
tanh [(dl + du )σ − dl ] + tanh dl
σ̂ = (4.15)
tanh dl + tanh du
Increasing the values of the (positive) parameters dl or du will provide a
higher resolution in respectively the bottom or surface layer at the expense
of a coarser resolution in the remaining parts of the water column.
A vertical grid is then constructed by firstly taking a series of uniformly
spaced σ-levels, i.e. σk = (k − 1)/N, k = 1, N + 1 where N is the number of
vertical layers. In the case of a non-uniform grid, the corresponding values
of σ̂k are obtained from the transformation formula. Examples are given in
Figure 4.2a-b. The first one shows that the vertical grid positions are more
densily packed and the grid spacings are smaller in the bottom (surface)
layer for a logarithmic transformation concentrated at the bottom (surface).
The Burchard & Bolding (2002) formulation (with dl = du ) has enhanced
resolutions both near the surface as near the bottom but a coarser resolution
in the middle of the water column.
4.1.3.2 generalised σ-coordinates

Instead of using the traditional σ-coordinate a generalised vertical “s” coor-
dinate can be defined by
z = F (x1 , x2 , s, t) (4.16)
with (x1 ,x2 ) = (x,y), (λ,φ) or (ξ1 ,ξ2 ) and where s = 0 at the bottom and
s = 1 at the surface so that
F (x1 , x2 , 0, t) = −h , F (x1 , x2 , 1, t) = ζ (4.17)

(a) (b)
Figure 4.2: Transformed coordinate σ̂ = F (σ) (a) and vertical grid spacing
normalised to the total water depth ∆σ̂ = ∂F/∂σ/N (b): formulation (4.12)
with σ∗ = 0.25, s0 = 0.1 (solid), (4.13) with the same parameter values
(dots), (4.15) with dl = du = 1.5 (dashes).
The vertical grid spacing now becomes

∂F
∆z = ∆s = h3 ∆s (4.18)
∂s
The distance between two neighbouring points in 3-D space now becomes
∆d2 = h21 ∆ξ12 + h22 ∆ξ22 + h23 ∆s2 (4.19)
Song & Haidvogel (1994) related the s-coordinate to the σ-coordinate by

letting
F = sH − h + hF∗ (x1 , x2 , s) , F∗ (x1 , x2 , 0) = F∗ (x1 , x2 , 1) = 0 (4.20)
Equation (4.18) is re-written as

∂F∗ h ∂F∗ ∂F∗
h3 = H + h = H(1 + ) ≃ H(1 + ) (4.21)
∂s H ∂s ∂s
where the approximation is made that h ≃ H. The assumption is reasonable
since the s-coordinate is designed for non-shallow areas with large bathymet-
ric gradients, such as shelf breaks. The s-coordinate, defined by (4.20) is
related to the σ-coordinate by
h
σ =s+ F∗ (x1 , x2 , s) ≃ s + F∗ (x1 , x2 , s) (4.22)
H
and
∆z ∂F∗
∆σ = ≃ (1 + )∆s (4.23)
H ∂s
which means that the Sung-Haidvogel s-coordinate can be seen as a gener-

alised σ-coordinate with non-uniform spacings in the horizontal if F∗ 6= 0.
The new coordinate should be defined so that it can represent surface
and bottom layers in shallow as well as deep waters and can deal with areas
with a steep topography. Song & Haidvogel (1994) proposed the following
expression for F∗ (s):
" #
h − hc
F∗ (x1 , x2 , s, t) = max 0, (C(s) + 1 − s)
h
" #
(1 − b) sinh [θ(s − 1)] b tanh [θ(s − 0.5)]
C(s) = + −1 (4.24)
sinh θ 2 tanh(0.5θ)
where hc is a critical water depth below which the s-coordinate reduces to the
σ-coordinate and b and θ are tunable parameters. The vertical grid is defined
by taking uniformly spaced s-levels, i.e. sk = (k − 1)/N, k = 1, N + 1 and
calculating the corresponding generalised σ-levels using (4.22). Figure 4.3
a) b)
Figure 4.3: Distribution of vertical levels along a transect from Denmark to

Norway: uniform σ-coordinates (a), non-uniform σ-coordinates using (4.24)
(b).
compares the distribution of vertical levels for a uniform σ-spacing with the
s-coordinate levels obtained from (4.24), using b = 1, hc = 200 and θ = 8,
for a transect across the Norwegian trench in the North Sea. While the σ-
coordinate provides an accurate resolution in the shallow waters near the
Danish coast (left side of the figure), the layer thickness is ∼30 m in the
deepest part which is clearly insufficient. A (vertically) non-uniform σ-grid

will not resolve the problem since any improvement for the deepest parts
will detoriate the solution in the coastal areas. The s-coordinate has a much
more accurate resolution in deep water as seen in the figure on the right and
reduces to the σ-coordinate when h < hc near the coasts.
A transformed vertical grid can also be constructed through the inverse
relation
s = G(x1 , x2 , z, t) (4.25)
or, after substituting from (4.9)
s = G∗ (σ, x, y, t) (4.26)
with G∗ (0, x, y, t) = 0, G∗ (1, x, y, t) = 1 and ∂G∗ /∂σ > 0. For example,

Burchard & Bolding (2002) proposed
sk = ασk + (1 − α)σ̂k (4.27)
where
h (σ̂ − σ̂
k k−1 ) − (σk − σk−1 )hc /h
i
α = min ,1 (4.28)
(σ̂k − σ̂k−1 ) − (σk − σk−1 )
and σ̂ is obtained from (4.15) with hc a critical water depth below which
s = σ.
4.1.3.3 normalised vertical coordinate

In analogy with the horizontal curvilinear coordinate system the vertical s-
coordinate is normalised using
H∆σ = h3 ∆s (4.29)
Setting ∆s = 1 between neighbouring grid points in the (transformed) verti-

cal direction and using similar normalised coordinates in the horizontal one
has
∆d2 = h21 ∆ξ12 + h22 ∆ξ22 + h23 ∆s2 = h21 + h22 + h23 (4.30)
so that h1 , h2 , h3 become the grid spacings in the three (transformed) coor-
dinate directions.
Implementation
The type of vertical grid is selected with the switch iopt grid vtype
1 : uniform σ-grid
4.2. BASIC MODEL EQUATIONS 45
2 : non-uniform vertical σ-grid

3 : non-uniform σ in the horizontal and vertical
In the following, the general vertical coordinate will be represented by its
normalised value s. This implies that
∂ 1 ∂ 1 ∂
= = (4.31)
∂z H ∂σ h3 ∂s
4.2 Basic model equations

4.2.1 3-D mode equations
4.2.1.1 Cartesian coordinates
The model equations are derived with the following (classic) assumptions.
1. The Boussinesq approximation is applied which means that the density
is constant except for the Earth’s gravity force.
2. The vertical component of the momentum equations reduces to the hy-
drostatic balance between the vertical pressure gradient and the gravity
force.
3. The horizontal component of the Earth’s rotation vector is set to zero.
The assumption becomes invalid for non-hydrostatic water masses or
near the equator.
The equations for the “3-D” mode consist of the continuity equation,
the momentum equations and the equations of temperature and salinity. In
Cartesian coordinates and using the previous assumptions these are given by
∂u ∂v ∂w
+ + =0 (4.32)
∂x ∂y ∂z
∂u ∂u ∂u ∂u
+u +v +w − fv
∂t ∂x ∂y ∂z
1 ∂p ∂ ∂u ∂ ∂
=− + Fxt + νT + τxx + τxy (4.33)
ρ0 ∂x ∂z ∂z ∂x ∂y
∂v ∂v ∂v ∂v
+u +v +w + fu
∂t ∂x ∂y ∂z
1 ∂p ∂ ∂v ∂ ∂
=− + Fyt + νT + τyx + τyy (4.34)
ρ0 ∂y ∂z ∂z ∂x ∂y
∂p
= −ρg (4.35)
∂z
∂T ∂T ∂T ∂T
+u +v +w
∂t ∂x ∂y ∂z
1 ∂I ∂ ∂T ∂ ∂T ∂ ∂T
= + λT + λH + λH (4.36)
ρ0 cp ∂z ∂z ∂z ∂x ∂x ∂y ∂y
∂S ∂S ∂S ∂S
+u +v +w
∂t ∂x ∂y ∂z
∂ ∂S ∂ ∂S ∂ ∂S
= λT + λH + λH (4.37)
∂z ∂z ∂x ∂x ∂y ∂y
where (u,v) are the horizontal components of the current, w the vertical cur-
rent, f the Coriolis frequency given by 2Ω sin φ where Ω = π/43082 radians/s
is the Earth’s rotation frequency, p the pressure, ρ the density, ρ0 a uniform
reference density, g the acceleration of gravity, (Fxt ,Fyt ) the components of
the astronomical tidal force, νT and λT the vertical turbulent diffusion co-
efficients, τij the horizontal friction tensor, T potential temperature, I the
solar irradiance within the water column, cp the specific heat capacity of sea
water at constant pressure, and S salinity.
Note that T is not the in situ temperature but potential temperature,
defined as the temperature of a fluid parcel, moved adiabatically to a certain
level (usually taken at or near the surface). The reason is that (4.36) is
derived from the conservation equation of heat. This equation contains an
extra term due to compresssibility, which vanishes if T is interpreted as
potential temperature (Gill, 1982).
Since the model does not allow for the formation of sea ice at the surface,
the temperature must stay above the freezing point of seawater, i.e.
T > αf S , αf = −0.0575 0 C/PSU (4.38)
The horizontal diffusion tensor is introduced to represent horizontal sub-
grid scale processes not resolved by the model and is parameterised as follows
τxx = −τyy = νH DT , τxy = τyx = νH DS (4.39)
∂u ∂v ∂u ∂v
DT = − DS = + (4.40)
∂x ∂y ∂y ∂x
where DT and DS are called the horizontal tension and shearing strain and νH
denotes the horizontal diffusion coefficient which is either given as a constant
or taken as proportional to the local rate of strain
q
νH = Cm ∆x∆y DT2 + DS2 (4.41)
Similarly, the scalar diffusion coefficient is either a constant or given by

q
λH = Cs ∆x∆y DT2 + DS2 (4.42)
Equations (4.41) and (4.42) are the well-known Smagorinsky (1963) param-
eterisations. The coefficients Cm and Cs usually have the same value of
the order of 0.1–0.2. The sub-grid parameterisation (4.39) and (4.40) differs
from the one implemented in COHERENS V1 and several other ocean models.
The present formulation has been introduced in the Modular Ocean Model
(Pacanowski & Griffies, 2000; Griffies, 2004) on general considerations about
basic symmetry properties of the physical system.
In the present implementation it is assumed that “horizontal” diffusion
of momentum and scalars takes place along horizontal planes. Diffusion
along the vertical is parameterised by the vertical diffusion coefficients νT
and λT . It is, however, physically more meaningfull to replace these notions
of horizontal mixing, produced by two-dimensional meso-scale eddies, and
vertical mixing, representing small scale turbulence on scales of 10−3 to 10 m,
by mixing along and across isopycnals. Since νT ≪ νH and λT ≪ λH , the
horizontal mixing scheme may produce an excessive diapycnal diffusion in
the presence of lateral fronts. Complex schemes for isopycnal mixing have
been developed and applied to global ocean models (e.g. Griffies et al., 1998).
They are not implemented in the current version of COHERENS. The main
reason is that the program is primarily developed for coastal and regional
seas where a sufficiently high resolution can be taken to resolve meso-scale
eddies in the horizontal.
The pressure can be eliminated from the above equations by rewriting
(4.35) as
∂p
= −ρ0 (g − b) (4.43)
∂z
where the buoyancy b is defined by
!
ρ − ρ0
b=− g (4.44)
ρ0
Integrating (4.43) using the surface boundary condition p = Pa at z = ζ
where Pa is the surface atmospheric pressure, the horizontal pressure gradient
terms in (4.33) and (4.34) can be written as
1 ∂p ∂ζ 1 ∂Pa ∂q
− = −g − − (4.45)
ρ0 ∂xi ∂xi ρ0 ∂xi ∂xi
where xi equals x or y and q is the vertically integrated buoyancy
Z ζ
q=− b dz (4.46)
z
The first two terms on the right of (4.45) represent the barotropic, the third
one the baroclinic component.
The following additional remarks are to be given:

• The vertical diffusion term and the diffusion coefficients νT and λT are
obtained from a turbulence model. Various schemes, including simple
algebraic schemes and more complex second order closure schemes, are
implemented (see Section 4.4).
• The acceleration due to gravity can be set in the program to a constant
value or obtained from the geodetic formula as function of latitude (see
Appendix 2 of Gill, 1982)
g = 9.78032 + 0.005172 sin2 φ − 0.00006 sin2 2φ (4.47)
• The absorption of solar irradiance within the water column is generally

a function of solar wavelength and the penetration depth of solar light.
The formulation chosen in the model follows the one given by Paulson
& Simpson (1977) whereby I is given by

I(x1 , x2 , z) = Qrad Re−z/λ1 + (1 − R)e−z/λ2 (4.48)
where R represents the absorption of the red end of the solar spectrum
in the upper (1–2) meters of the water column, 1 − R the absorption of
blue-green light over larger depths and Qrad the solar radiance incident
on the surface. Since turbidity effects are not explicitly taken into
account by the physical model, values of R, λ1 , λ2 ≫ λ1 depend on the
optical properties of the water masses and can be selected following
e.g. the optical classification scheme of Jerlov (1968). Solar radiance
is further discussed in Section 4.6.
• The astronomical force is only relevant in deep ocean waters and can
be neglected on the shelf and in the coastal zone. Expressions for its
components are given as a sum of tidal harmonics (see Section 4.5).
4.2.1.2 transformed coordinates

The forms of the model equations in orthogonal curvilinear and s-coordinates
(ξ1 ,ξ2 ,s) are derived in Appendix A. The equations of continuity and mo-
mentum, written in conservative and operator format, become
" #
1 ∂h3 1 ∂ ∂ 1 ∂ω
+ (h2 h3 u) + (h1 h3 v) + =0 (4.49)
h3 ∂t h1 h2 h3 ∂ξ1 ∂ξ2 h3 ∂s
!
1 ∂ v ∂h1 ∂h2
(h3 u) + Ah1 (u) + Ah2 (u) + Av (u) + u −v − 2Ωv sin φ
h3 ∂t h1 h2 ∂ξ2 ∂ξ1
g ∂ζ 1 ∂Pa
=− − + F1b + F1t + Dmv (u) + Dmh1 (τ11 ) + Dmh2 (τ12 )
h1 ∂ξ1 ρ0 h1 ∂ξ1
(4.50)
!
1 ∂ u ∂h2 ∂h1
(h3 v) + Ah1 (v) + Ah2 (v) + Av (v) + v −u + 2Ωu sin φ
h3 ∂t h1 h2 ∂ξ1 ∂ξ2
g ∂ζ 1 ∂Pa
=− − + F2b + F2t + Dmv (v) + Dmh1 (τ21 ) + Dmh2 (τ22 )
h2 ∂ξ2 ρ0 h2 ∂ξ2
(4.51)
where ω represents the transformed vertical velocity, further discussed below.
The spherical case is recovered from the above equations by letting h1 =
R cos φ and h2 = R.
Apart from a constant factor of proportionality, which can be set to 1
without loss of generality, the metric coefficients hi are related to the model
grid spacings along the horizontal coordinate directions (∆x,∆y) and the
vertical (∆z) by
∆x = h1 , ∆y = h2 , ∆z = h3 ∆s (4.52)
The advection and diffusion operators are defined by
1 ∂
Ah1 (F ) = (h2 h3 uF ) (4.53)
h1 h2 h3 ∂ξ1
1 ∂
Ah2 (F ) = (h1 h3 vF ) (4.54)
h1 h2 h3 ∂ξ2
1 ∂
Av (F ) = (ωF ) (4.55)
h3 ∂s
1 ∂
Dmh1 (F ) = 2
(h22 h3 F ) (4.56)
h1 h2 h3 ∂ξ1
1 ∂
Dmh2 (F ) = 2 (h2 h3 F ) (4.57)
h1 h2 h3 ∂ξ2 1
!
1 ∂ νT ∂F
Dmv (F ) = (4.58)
h3 ∂s h3 ∂s
The parameterised form of the horizontal shear stress tensor in orthogonal
curvilinear coordinates is given by Pacanowski & Griffies (2000); Griffies
(2004)
τ11 = −τ22 = νH DT , τ12 = τ21 = νH DS (4.59)
h2 ∂ u h1 ∂ v

DT = −
h1 ∂ξ1 h2 h2 ∂ξ2 h1
h1 ∂ u h2 ∂ v

DS = + (4.60)
h2 ∂ξ2 h1 h1 ∂ξ1 h2
The quantity ω in (4.49) and (4.55) is the transformed vertical current
normal to the s-coordinate surfaces. Physical and transformed vertical cur-
rent are related by
!
∂s u ∂s v ∂s
w = ω − h3 + + (4.61)
∂t h1 ∂ξ1 h2 ∂ξ2
An alternative form, more useful for numerical discretisation, is
1 ∂
w= (h3 z) + Ah1 (z) + Ah2 (z) + Av (z) (4.62)
h3 ∂t
The horizontal vector Fit represents the components of the astronomical tidal
force, discussed in Section 4.5. The expression for the baroclinic pressure
gradient now contains two terms as a consequence of the vertical coordinate
transformation
" !#
1 ∂ ∂ ∂z
Fib =− (h3 q) − q (4.63)
hi h3 ∂ξi ∂s ∂ξi
where Z 1
q=− bh3 ds (4.64)
s
The equations for potential temperature and salinity can, in the absence of
a particle sinking term, be cast in a more general form, representing the
transport of an arbitrary concentration ψ (T , S, sediment, contaminant,
biological state variable)
1 ∂
(h3 ψ) + Ah1 (ψ) + Ah2 (ψ) + Av (ψ)
h3 ∂t
= P(ψ) − S(ψ) + Dsv (ψ) + Dsh1 (ψ) + Dsh2 (ψ) (4.65)
where P(ψ), S(ψ) represent all source, respectively sinks terms. Two-dimensional
diffusion of scalars is taken along constant s-surfaces. This gives
1 ∂ h2 h3 ∂ψ
Dsh1 (ψ) = λH (4.66)
h1 h2 h3 ∂ξ1 h1 ∂ξ1
1 ∂ h1 h3 ∂ψ
Dsh2 (ψ) = λH (4.67)
h1 h2 h3 ∂ξ2 h2 ∂ξ2
ψ
1 ∂ λT ∂F
Dsv (ψ) = (4.68)
h3 ∂s h3 ∂s
where λψT is the vertical diffusion coefficient for the scalar ψ 2 .

Smagorinsky’s diffusion coefficiens in curvilinear coordinates are given by
q
νH = Cm h1 h2 DT2 + DS2 (4.69)
q
λH = Cs h1 h2 DT2 + DS2 (4.70)
Applying (4.65) for temperature and salinity one has
1 ∂
(h3 T ) + Ah1 (T ) + Ah2 (T ) + Av (T )
h3 ∂t
1 ∂I
= + Dsv (T ) + Dsh1 (T ) + Dsh2 (T ) (4.71)
ρ0 cp h3 ∂s
1 ∂
(h3 S)+Ah1 (S)+Ah2 (S)+Av (S) = Dsv (S)+Dsh1 (S)+Dsh2 (S) (4.72)
h3 ∂t
4.2.2 2-D mode equations

The 3-D continuity and momentum equations presented in the previous sec-
tion need to be supplemented by additional 2-D equations for the depth-
integrated current and surface elevation. There are two main reasons.
1. The surface elevation appearing in the momentum equations cannot be

determined from the 3-D equations only.
2. The numerical solution of the 3-D equations are constrained by the

CFL limit which poses a severe limit on the time step used in the
numerical discretisations. This can be resolved by solving the simpler
2-D equations with a smaller 2-D time step and inserting the results
into the 3-D equations which can now be solved with a larger 3-D time
step. The method, known as the mode splitting technique, is further
discussed in Chapter 5.
The 2-D mode equations consists of three equations for the surface elevation
and the depth-integrated currents, defined by
Z1
(U, V ) = (u, v)h3 ds (4.73)
0
The same vertical diffusion coefficient is taken for temperature and salinity, i.e. λTT =
2
λST = λT .
The equations are then obtained by integrating (4.49)–(4.51) over the verti-
cal. This gives
" #
∂ζ 1 ∂ ∂
+ (h2 U ) + (h1 V ) = 0 (4.74)
∂t h1 h2 ∂ξ1 ∂ξ2
!
∂U V ∂h1 ∂h2
+ Ah1 (U ) + Ah2 (U ) + U− V − 2ΩV sin φ
∂t Hh1 h2 ∂ξ2 ∂ξ1
gH ∂ζ H ∂Pa
= − − + F1b + HF1t + τs1 − τb1
h1 ∂ξ1 ρ0 h1 ∂ξ1
+ Dmh1 (τ11 ) + Dmh2 (τ12 ) − δAh1 + δDh1 (4.75)
!
∂V U ∂h2 ∂h1
+ Ah1 (V ) + Ah2 (V ) + V − U + 2ΩU sin φ
∂t Hh1 h2 ∂ξ1 ∂ξ2
gH ∂ζ H ∂Pa
= − − + F2b + HF2t + τs2 − τb2
h2 ∂ξ2 ρ0 h2 ∂ξ2
+ Dmh1 (τ21 ) + Dmh2 (τ22 ) − δAh2 + δDh2 (4.76)
where Fib are the depth-integrated components of the baroclinic pressure

gradient Fib , τsi and τbi are the components of the surface and bottom stress
(normalised with the reference density ρ0 )
νT ∂(u, v)

(τs1 , τs2 ) = (4.77)
h3 ∂s sur
νT ∂(u, v)

(τb1 , τb2 ) = (4.78)
h3 ∂s bot
The advection and diffusion operators for transports are given by
1 ∂ UF

Ah1 (F ) = h2 (4.79)
h1 h2 ∂ξ1 H
1 ∂ VF

Ah2 (F ) = h1 (4.80)
h1 h2 ∂ξ2 H
1 ∂
2

Dmh1 = h F (4.81)
h1 h22 ∂ξ1 2
1 ∂ 2
Dmh2 = 2 hF (4.82)
h1 h2 ∂ξ2 1
The 2-D equivalents of the shear stress tensor can be written as
τ11 = −τ22 = νH DT , τ12 = τ21 = νH DS (4.83)

Z1
νH = νH h3 ds (4.84)
0
h2 ∂ U h1 ∂ V

DT = −
h1 ∂ξ1 Hh2 h2 ∂ξ2 Hh1
h1 ∂ U h2 ∂ V

DS = + (4.85)
h2 ∂ξ2 Hh1 h1 ∂ξ1 Hh2
The last two terms on the right of (4.75)–(4.76) only contain the baroclinic
part of the 3-D current
U V

(δu, δv) = u − , v − (4.86)
H H
The explicit forms are
1"
1 Z ∂ ∂
δAh1 = h2 h3 δu2 + (h1 h3 δuδv)
h1 h2 ∂ξ1 ∂ξ2
0
#
∂h1 ∂h2 2
+ h3 δuδv − h3 δv ds (4.87)
∂ξ2 ∂ξ1
1"
1 Z ∂ ∂
δAh2 = (h2 h3 δuδv) + h1 h3 δv 2
h1 h2 ∂ξ1 ∂ξ2
0
#
∂h2 ∂h1 2
+ h3 δuδv − h3 δu ds (4.88)
∂ξ1 ∂ξ2
1 1
    
1  1 ∂  2Z 1 ∂  2Z
δDh1 = h2 νH δDT h3 ds + h1 νH δDS h3 ds
h1 h2 h2 ∂ξ1 h1 ∂ξ2
0 0
(4.89)
1 1
    
1  1 ∂  2Z 1 ∂  2Z
δDh2 = h2 νH δDS h3 ds −
 h1 νH δDT h3 ds
h1 h2 h2 ∂ξ1 h1 ∂ξ2
0 0
(4.90)
where δDT and δDS are given by (4.60) with (u,v) replaced by (δu,δv).
The 3-D and 2-D continuity equations involve either the 3-D and 2-D
current. An alternative form, involving the baroclinic and depth-integrated
currents, can be derived by multiplying (4.49) by h3 and substracting (4.74)
multiplied by the transformed grid spacing h3 /H. This gives

" # ! !
1 ∂ ∂ U ∂ h3 V ∂ h3 ∂ω
(h2 h3 δu) + (h1 h3 δv) + + + =0
h1 h2 ∂ξ1 ∂ξ2 h1 ∂ξ1 H h2 ∂ξ2 H ∂s
(4.91)
The second and third term only arise if the transformed grid spacing varies
in the horizontal, i.e. in case of the most general vertical coordinate trans-
formation.
Implementation
The solution method of the previous set of equations is controlled by the
following model switches
iopt mode 2D Switch to enable (1) or disable (0) the solution of the 2-D
mode equations. It is advised not to switch off the 2-D mode unless for
1-D water column applications (see Section 4.3.1 below) or for carefully
designed applications.
iopt mode 3D Switch to enable (1) or disable (0) the solution of the 3-D
hydrodynamic equations (4.49)–(4.51). It is recommended not to disable
the 3-D mode unless for purely 2-D (depth-averaged) applications (in
which case the switch is automatically disabled by the program).
iopt temp Type of update for the temperature field.
0 : Temperature is uniform in space and time.
1 : Temperature is uniform in time, but non-uniform in space.
2 : Temperature is non-uniform in space and time and obtained by
solving equation (4.71).
iopt sal Type of update for the salinity field.
0 : Salinity is uniform in space and time.
1 : Salinity is uniform in time, but non-uniform in space.
2 : Salinity is non-uniform in space and time and obtained by solving
equation (4.72).
4.2.3 Equation of state

Equations (4.50), (4.51), (4.91), (4.74)–(4.76) and (4.71)–(4.72) form a com-
plete set of equations for u, v, ω, ζ, U , V , T and S with the constraints (4.73),
provided that the density ρ, which enter the equations through the baroclinic
gradient and the turbulent diffusion coefficients νT , λT (see Section 4.4 be-
low), is known. Contrary to temperature and salinity, the density is not
obtained by an additional transport equation but by means of an equation
of state (EOS).
The International EOS (Millero et al., 1980), adopted in the previous ver-
sion of COHERENS relates the density to the three state variables T , S and
p where T is the in situ temperature. A more appropriate formulation still
based on the International EOS, but with in situ temperature replaced by
potential temperature was considered by Jacket & McDougall (1995). More
recently, McDougall et al. (2003) proposed an EOS using potential tempera-
ture, which according to the authors is more accurate than the International
EOS and computationally more efficient. The latter formulation has there-
fore been implemented in COHERENS V2.0.
With a precision of 0.003 kg/m3 the density is given by
ρ(S, T, p) = P1 (S, T, p)/P2 (S, T, p) (4.92)
P1 = a0 + a1 T + a2 T 2 + a3 T 3 + a4 S + a5 ST + a6 S 2
+ a7 p + a8 pT 2 + a9 pS + a10 p2 + a11 p2 T 2
P2 = 1 + b1 T + b2 T 2 + b3 T 3 + b4 T 4 + b5 S + b6 ST + b7 ST 3
+ b8 S 3/2 + b9 S 3/2 T 2 + b10 p + b11 p2 T 3 + b12 p3 T (4.93)
where ai and bi are empirical parameters listed in Table 4.1. Neglecting

density variations in the water column and atmospheric pressure, p can be
approximated by
p ≃ −ρg(z − ζ) (4.94)
The expansion coefficients for temperature and salinity are obtained from
(4.92)–(4.93)
1 ∂ρ 1 ∂P2 1 ∂P1
βT = − = − (4.95)
ρ ∂T P2 ∂T P1 ∂T
1 ∂ρ 1 ∂P1 1 ∂P2
βS = = − (4.96)
ρ ∂S P1 ∂S P2 ∂S
For compatibility with the previous COHERENS version and simple case stud-
ies, the model allows to use a simpler linear equations of state, obtained by
expanding (4.92)–(4.96) around a reference state
ρ = ρ0 (1 + βS (S − Sr ) − βT (T − Tr )) (4.97)
where Tr and Sr are constant reference values, and (ρ0 ,βT ,βS ) are obtained
from (4.92)–(4.93) with T = Tr , S = Sr , p = 0.
Table 4.1: Values of the empirical parameters in the McDougall et al. (2003)
equation of state.
a0 999.843699 b1 7.28606739×10−3
a1 7.3521284 b2 -4.60835542×10−5
a2 -5.45928211×10−2 b3 3.68390573×10−7
a3 3.98476704×10−4 b4 1.80809186×10−10
a4 2.96938239 b5 2.14691708×10−3
a5 -7.23268813×10−3 b6 -9.27062484×10−6
a6 2.12382341×10−3 b7 -1.78343643×10−10
a7 1.04004591×10−2 b8 4.76534122×10−6
a8 1.03970529×10−7 b9 1.63410736×10−9
a9 5.1876188×10−6 b10 5.30848875×10−6
a10 -3.24041825×10−8 b11 -3.03175128×10−16
a11 -1.2386936×10−11 b12 -1.27934137×10−17
Implementation
The following switches, used for the evaluation of density and density gradi-
ents, are available:
iopt dens Selects type of equation of state.
0 : The density is set to a uniform value, obtained from (4.92)-(4.93)

using constant reference values for T , S and p = 0. The expansion
coefficients are to zero.
1 : Density is calculated from the linear EOS (4.97). Constant values
are taken for the expansion coefficients.
2 : ρ, βT and βS are calculated from (4.92)–(4.93) with p = 0.
3 : ρ, βT and βS are calculated from (4.92)–(4.93) with a non-zero
pressure.
iopt dens grad Selects the numerical algorithm for discretisation of the baro-
clinic pressure gradient (see Section 5.3.12 for details).
0 : The gradient is set to zero in all momentum equations.

1 : Traditional σ-coordinate (second order) method.
2 : Using the z-level method.
3 : The method of Shchepetkin & McWilliams (2003)
4.3. MODEL EQUATIONS ON REDUCED GRIDS 57
4.3 Model equations on reduced grids

4.3.1 Water column (1-D) mode
In case of a water column application the horizontal grid reduces to one
singular point so that the grid becomes one-dimensional. The following sim-
plifications are made:
1. Advective and horizontal diffusion terms are set to zero.
2. All components of the horizontal pressure gradient are neglected except

for the barotropic surface slope term.
3. The continuity equation is not solved. This means in particular that

the vertical current is no longer calculated.
In the absence of an horizontal grid, the model equations can be written using
Cartesian coordinates in the horizontal and σ-coordinates in the vertical. The
momentum equations (4.50), (4.51) then reduce to
1 ∂ ∂ζ 1 ∂ νT ∂u
(h3 u) − 2f v = −g + F1t + (4.98)
h3 ∂t ∂x h3 ∂s h3 ∂s
1 ∂ ∂ζ 1 ∂ νT ∂v
(h3 v) + 2f u = −g + F2t + (4.99)
h3 ∂t ∂y h3 ∂s h3 ∂s
where
• the Coriolis frequency is defined by specifying the latitude of the loca-

tion, i.e. f = 2Ω sin(φref )
• the surface slope and the surface elevation ζ, needed to calculate the
total water depth H and the vertical grid spacing h3 are specified as
external “surface” forcing conditions
The one-dimensional version of the scalar transport equation (4.65) is given

by
1 ∂ 1 ∂ λψT ∂ψ
(h3 ψ) = P(ψ) − S(ψ) + (4.100)
h3 ∂t h3 ∂s h3 ∂s
4.3.2 Depth-averaged (2-D) mode

In depth-averaged mode it is assumed that the 3-D current and all 3-D scalar
quantities are depth-independent.
From (4.91) it follows that ω = 0. The hydrodynamic equations are then

given by (4.74)–(4.76) without the baroclinic terms, i.e.
δAh1 = δAh2 = δDh1 = δDh2 = 0 (4.101)
The depth-integrated form of the transport equation for a depth-independent

scalar ψ is obtained by integrating (4.65) over the vertical
∂
Hψ + Ah1 (Hψ) + Ah2 (Hψ) = H P(ψ) − S(ψ) + Fsψ − Fbψ
∂t
1 h ∂ h2 ∂ψ ∂ h1 ∂ψ i
+ λH + λH (4.102)
h1 h2 ∂ξ1 h1 ∂ξ1 ∂ξ2 h2 ∂ξ2
where Fsψ and Fbψ are the fluxes at respectively the surface and the bottom.
The vertically integrated horizontal diffusion coefficients take the form
q q
2 2 2 2
νH = Cm h1 h2 H D T + D S , λH = C s h 1 h 2 H D T + D S (4.103)
where DT , DS are defined by (4.85).
4.4 Turbulence schemes

4.4.1 Introduction
The objective of a turbulence scheme is to parameterise the effects of tur-
bulent motions. It is assumed that turbulence is fully developed and in a
quasi-equilibrium state. The main characteristics can be described as follows
(see e.g. Ferziger, 2005; Kantha & Clayson, 2000a):
• Three-dimensional. In contrast to the mean flow, which may be two-
dimensional, turbulent motions are fully three-dimensional. This defi-
nition excludes the two-dimensional turbulence of geophysical flows on
the meso-scale, mentioned in Section 4.2 which is parameterised by a
horizontal mixing scheme.
• Randomness. Turbulence has a “short-time” memory. This means that

turbulent states arising from slight changes in initial, boundary or for-
cing conditions become uncorrelated in time within short time intervals.
As a consequence, the only meaningfull way to analyse turbulence is
through its statistical properties.
• Broad spectrum. Turbulent motions span a large spectrum of scales in

space and time.
4.4. TURBULENCE SCHEMES 59
• Vorticity. In contrast to waves, turbulent motions are characterised

by random vorticity fluctuations. This explains why turbulence can
be visualised in laboratory experiments as a spectrum of eddies on
different spatial scales. On the largest scales, the eddies extract energy
from the mean flow, whereas on the shortest (so-called Kolmogorov)
scales this energy is converted into heat by molecular disssipation.
The spatial scales of turbulence, which need to be taken into account in

models for the ocean, shelf seas or coastal areas, range from 10−3 –102 m and
are, except eventually for the largest ones, not resolved by the model. Tur-
bulence schemes need to be developed, based upon the statistical properties
of the turbulence spectrum. Starting point are the Navier-Stokes equations
and the equations of continuity and temperature3 , written for convenience in
Cartesian coordinates and tensorial notation
∂Ui ∂Ui 1 ∂P X ∂ 2 Ui
+ Uj + ǫijk fj Uk = − + δi3 b + ν 2
(4.104)
∂t ∂xj ρ0 ∂xi j ∂xj
∂Ui
=0 (4.105)
∂xi
∂T ∂T X ∂ 2T
+ Ui = S(T ) + kT 2
(4.106)
∂t ∂xi i ∂xi
where summation is performed within each term over repeating indices, Ui

are the velocity components, ǫijk is 1(-1) if (i,j,k) are in cyclic (anticyclic)
order and 0 if any two indices are equal, δij is the Kronecker symbol (1 if i=j,
0 otherwise), ν and kT are the kinematic viscosity and molecular diffusivity
of heat, P the dynamic pressure4 and fi = 2Ω(cos φ, 0, sin φ) is twice the
Earths’s rotation vector.
All quantities are then decomposed into a mean (designated by an over-
bar) and a fluctuating turbulent part or
Ui = Ui + ui , T = T +θ, P = P + ρ0 π , b=b+β (4.107)
where the fluctuating parts have zero means. The averages can be considered
as ensemble averages over a large number of turbulent states or as a statistical
mean over the full turbulence spectrum. Since the fluctuations of density can
3
In the absence of double-diffusive mixing, which is not implemented in the current
model code, the procedure is similar if temperature is replaced by salinity.
4
The dynamic pressure is defined as the pressure minus its homogeneous hydrostatic
part, i.e. P = p + ρ0 g(z − ζ) − Pa .
be taken as small with respect to their mean value, β and θ can be related
by the linearised equation of state
β = gβT θ (4.108)
The mean flow equations are obtained by substituting (4.107) into (4.104-
4.106) and taking the average. This gives
∂Ui ∂Ui 1 ∂P X ∂ 2 Ui ∂
+ Uj + ǫijk fj Uk = − + δi3 b + ν 2
− ui uj (4.109)
∂t ∂xj ρ0 ∂xi j ∂xj ∂xj
∂Ui
=0 (4.110)
∂xi
∂T ∂T X ∂ 2T ∂
+ Ui = P(T ) + kT 2
− ui θ (4.111)
∂t ∂xi i ∂xi ∂xi
since P(T ) = P(T ) in view of (4.71). Equations (4.109)–(4.111) are the
same as (4.104)–(4.106) except for the last terms in the momentum and
temperature equations which represent the exchange of momentum and heat
between the mean and turbulent flows. The two terms appear as a divergence
of fluxes of momentum ui uj and temperature ui θ.
It remains to find suitable parameterisations for these turbulent fluxes.
The oldest approach — dating back from the time of Boussinesq in 1877 —
and also the most commonly used, is to model the momentum fluxes like the
viscous stresses in laminar flows
!
∂Ui ∂Uj 2
− ui u j = ν T + − kδij (4.112)
∂xj ∂xi 3
where
1
k = (u2 + v 2 + w2 ) (4.113)
2
is the kinetic energy of turbulent motions and νT is called the eddy viscosity
(diffusion) coefficient. In analogy with (4.112) the temperature fluxes are
usually parameterised using the down-gradient diffusion hypothesis
∂T
− ui θ = λ T (4.114)
∂xi
Despite the similarity with laminar flows, there are fundamental differences
between turbulent and laminar diffusion
• For fully developed turbulence, νT and λT are larger than their laminar
counterparts by several orders of magnitude.
• The turbulent diffusion coefficients are of the same order of magnitude

whereas the molecular coefficients for momentum, T and S are of the
order of (ν, kT , kS ) ∼ (10−6 , 10−7 , 10−9 ) m2 /s.
• Turbulence is initiated by instabilities of the mean flow. This means in

practice that νT and λT are not constant but depend on the mean flow
properties generating and controling those instabilities, i.e. the current
shear ∂Ui /∂xj and the density gradient ∂ρ/∂xi .
The vertical diffusion terms in the model equations (4.33),(4.34) and

(4.36)–(4.37) are then derived by evaluating the flux divergences using (4.112)–
(4.114) and making the shallow water approximation. This condition is com-
patible with the assumption of hydrostatic balance and states that the hori-
zontal (mean flow) scales are larger than the vertical one, or ∂/∂x, ∂/∂y ≪
∂/∂z. This gives
∂ 2 ∂ ∂ ∂ ∂ ∂U
− u − uv − uw ≃ − uw ≃ νT
∂x ∂y ∂z ∂z ∂z ∂z
∂ ∂ 2 ∂ ∂ ∂ ∂V
− uv − v − vw ≃ − vw ≃ νT (4.115)
∂x ∂y ∂z ∂z ∂z ∂z
∂ ∂ ∂ ∂ ∂ ∂T
− uθ − vθ − wθ ≃ − wθ ≃ λT
∂x ∂y ∂z ∂z ∂z ∂z
since
∂U ∂V
− uw ≃ νT , −vw ≃ νT (4.116)
∂z ∂z
by application of the shallow water approximation to (4.112). A similar
expression applies for the diffusion of salinity. It is clear that (u,v,T ,S) in
(4.32)–(4.34), (4.36)–(4.37) are now interpreted as statistical averages.
The turbulence, as stated in the beginning of this subsection, is now
reduced to the implementation of suitable expressions for the turbulent dif-
fusion coefficients. A large number of schemes, applied for hydraulic en-
gineering and in the geophysical context, are available from the scientific
literature. For detailed overviews, the reader is referred to the text books
of Kantha & Clayson (2000a); Pope (2001) and the reviews by Rodi (1984);
Burchard (2002).
The turbulence models, implemented in COHERENS, fall in three cate-
gories of increasing complexity
1. The simplest formulation is to set the diffusion coefficients to constant

values
ν T = ν c , λT = λc (4.117)
where νc and λc are set be the user. Despite its simplicity, it is rec-
ommended not to use this form. Turbulence usuallly occurs in the
surface and bottom boundary layers, which requires spatially varying
coefficients.
2. Models using simplified empirical or semi-empirical (algebraic) rela-

tions, not derived from a turbulence closure theory.
3. Models obtained from the Reynolds averaged Navier-Stokes (RANS)

equations. These models are physically more robust, but have a larger
computational overhead. The basic assumptions (4.112) and (4.114)
are then not assumed a priori but derived a posteriori from theory.
Implementation
The general type of turbulence scheme is selected with the switch iopt vdif coef:
0 : Vertical diffusion is set to zero.

1 : Constant diffusion coefficients.
2 : Algebraic schemes (Section 4.4.2).
3 : RANS models (Section 4.4.3).
4.4.2 Algebraic schemes

4.4.2.1 Richardson number dependent formulations
The Richardson number is defined by
N2
Ri = (4.118)
M2
where
1 ∂b g ∂T ∂S
N2 = = βT − βS (4.119)
h3 ∂s h3 ∂s ∂s
1 h ∂u 2 ∂v 2 i
M2 = 2 + (4.120)
h3 ∂s ∂s
are the squared buoyancy and shear frequencies. The first one measures the
degree of stratification which is stable if N 2 > 0 (Ri > 0) and unstable if
N 2 < 0 (Ri < 0). The formulations below are based on theoretical and ob-
servational evidence that turbulence decreases in the first case and increases
in the second one.
Pacanowski & Philander (1981) proposed the following formulation
νT = ν0p fpnp (Ri) + νbp (4.121)

λT = νT fp (Ri) + λbp (4.122)
h i
1/np
fp (Ri) = min (1 + αp Ri)−1 , νmax (4.123)
An upper limit has been imposed on fp to prevent that turbulence becomes

too large in the case of unstable stratification (Ri < 0).
The following default values are used5
ν0p = 10−2 , np = 2 , αp = 5 , νbp = 10−4 , λbp = 10−5 , νmax = 3 (4.124)
The upper bounds for νT and λT are then given by 0.03, respectively 0.052.
The scheme has been primarily developed for application in global ocean
models (e.g. Semtner & Chervin, 1988). It has the advantage of being less
sensitive to vertical resolution than the more advanced turbulence closures
discussed in Section 4.4.3. In the absence of stratification the coefficients take
uniform values which makes the scheme less reliable for the study of neutral
tidal and wind-driven flows. Test simulations in the Rhine plume (Ruddick
et al., 1995) showed that the results are sensitive to a calibration of the model
constants. Peters et al. (1988) derived a similar formulation using different
values of the parameters calibrated from microstructure measurements in the
Pacific Ocean.
The second scheme use the historical empirical relations proposed by
Munk & Anderson (1948):
νT = ν0m fm (Ri) + νb (4.125)

λT = ν0m gm (Ri) + λb (4.126)
with
fm (Ri) = min[(1 + αm Ri)−n1 , νmax ] (4.127)

gm (Ri) = min[(1 + βm Ri)−n2 , λmax ] (4.128)
and νb and λb are uniform background mixing coefficients selected by the

user. The following default parameter values taken
ν0m = 0.06 , αm = 10 , βm = 3.33 , n1 = 0.5 , n2 = 1.5 , νmax = 3 , λmax = 4

(4.129)
5
Note that ν0p , νbp , λbp and ν0m in (4.124) and (4.129) are expressed in the same unit
as νT and λT , i.e. m2 /s, whereas νmax , λmax are dimensionless.
4.4.2.2 flow-dependent formulations

In shelf and coastal seas tides are a prominent source of turbulence. Obser-
vations in the Irish Sea (Bowden et al., 1959) indicate that the eddy viscosity
is proportional to the magnitude of the tidal current. A suitable parameter-
isation for tidal flow can then be written as
νT = (α(ξ1 , ξ2 , t)Φ(σ) + νw )fm (Ri) + νb (4.130)
λT = (α(ξ1 , ξ2 , t)Φ(σ) + νw )gm (Ri) + λb (4.131)

The flow field is represented by the depth-independent factor α. Explicit
forms are described below. In the absence of stratification the vertical vari-
ation of turbulence is presented by a prescribed profile for Φ(σ) which takes
account of the reduction of turbulence in the near bottom and surface layers.
Following Davies (1990) the following piecewise linear profile is adopted

Φ(σ) = (1 − r1 )σ/δ1 + r1 /D for 0 ≤ σ ≤ δ1
Φ(σ) = 1/D for δ1 ≤ σ ≤ 1 − δ2

Φ(σ) r2 − (r2 − 1)(1 − σ)/δ2 /D for 1 − δ2 ≤ σ ≤ 1 (4.132)
where
1 1
D = 1 + δ1 (r1 − 1) + δ2 (r2 − 1) (4.133)
2 2
is a normalisation factor such that the depth-integral of Φ(σ) equals 1. The
parameters δ1 , δ2 are the fractional depths of the bottom and surface layers,
and r1 , r2 the ratios of the bottom and surface values of Φ with respect to
the interior value. Default values for the parameters are
δ 1 = δ 2 = 0 , r1 = r2 = 1 (4.134)
giving a uniform vertical profile. More details about a proper selection of

these parameters can be found in e.g. Davies (1993).
In analogy with the formulation used by Naimie et al. (1994) for simu-
lating the circulation around Georges Bank the damping functions fm (Ri)
and gm (Ri) take the form given by the Munk-Anderson expressions (4.127)–
(4.128). Following Glorioso & Davies (1995) wind-induced turbulence is re-
lated to the surface friction velocity using the simple form
νw = λ⋆ u∗s (4.135)
where λ⋆ is a constant tunable parameter and the surface friction velocity

u⋆s is given by
u⋆s = τs1/2 = (τs1
2 2 1/2
+ τs2 ) (4.136)
The last terms on the right of (4.130)–(4.131) are the uniform background
eddy viscosity νb and diffusivity λb .
The following three formulations for the flow factor α can be selected
α = K1 (U 2 + V 2 )1/2 (4.137)
α = K2 (U 2 + V 2 )/(H 2 ω1 ) (4.138)
α = K1 (U 2 + V 2 )1/2 ∆b /H (4.139)
where ∆b measures the thickness of the bottom boundary layer as a function

of the bottom friction velocity u∗b :
∆b = min(Cν u∗b /ω1 , H) (4.140)

1/2 2 2 1/2
u∗b = τb = (τb1 + τb2 ) (4.141)
and ω1 is a characteristic frequency. In shallow areas ∆b = H so that (4.139)
reduces to (4.137). The following default values are taken
K1 = 2.5 × 10−3 , K2 = 2 × 10−5 , Cν = 2.0 , ω1 = 10−4 s−1 (4.142)
The eddy viscosity parameterisation (4.130) without stratification has

been used for the prediction of tidal currents and surface elevations in the
Northwest European Continental Shelf (e.g. Davies, 1990; Davies et al., 1997),
the Irish and Celtic Seas (e.g. Davies & Jones, 1992; Davies, 1993) and the
shelf edge off the West coast of Scotland (Proctor & Davies, 1996).
Implementation
An algebraic scheme is taken if iopt vdif coef=2. The type of scheme is further
selected by the switch iopt turb alg:
1 : Pacanowski-Philander
2 : Munk-Anderson
3 : Flow dependent scheme with α given by (4.137)
4.4.3 RANS models

Contrary to the previous schemes, RANS models do not take the eddy
viscosity-diffusivity concept as a prior assumption. The turbulent fluxes are
derived from a series of transport equations (Section 4.4.3.1). These equa-

tions contain unknown second and third-order correlations which need to be
parameterised (Section 4.4.3.2). Analytical solutions for geophysical flows
and expresssions for the eddy viscosity and diffusivity coefficients are de-
rived in Section 4.4.3.3. The solutions contain the turbulent energy k and its
dissipation ε as unknown variables. Alternative formulations using a mixing
length are given in Section 4.4.3.5. Different schemes are presented in Sec-
tion 4.4.3.4. Alternative formulations using a mixing length are defined in
Section 4.4.3.5. Background mixing schemes are discussed in Section 4.4.3.6.
4.4.3.1 general form of the RANS equations
Equations for the turbulent fluctuations ui and β are obtained by substract-

ing the mean equations (4.109)–(4.111) from the non-averaged equations
(4.104)–(4.106) and making use of (4.108). One obtains
∂ui ∂ ∂π ∂ X ∂ 2 ui
+ (Ui uj + ui Uj + ui uj ) + ǫijk fj uk = − + βδi3 + ui u j + ν 2
∂t ∂xj ∂xi ∂xj j ∂xj
(4.143)
∂ui
=0 (4.144)
∂xi
∂β ∂ X ∂ 2β ∂ui β
+ (Ui β + gβT T ui + ui β) = kT 2
+ (4.145)
∂t ∂xi i ∂xi ∂xi
where the overbar has been omitted for convenience above mean quantities
and the temperature equation is converted to an equation for the perturbed
buoyancy β by multiplication with the factor gβT .
Adding the i-component of (4.143) multiplied by uj and the j-component
multiplied by ui and taking the average, the following system of equations
is obtained for the Reynolds stresses ui uj , making use of the zero divergence
condition (4.144)
d ∂
ui u j + ui uj uk + fk (ǫikl ul uj + ǫjkl ul ui ) =
dt ∂xk
∂ ∂ ∂Uj ∂Ui
− uj π − u i π − ui u k − u j uk
∂xi ∂xj ∂xk ∂xk
∂2
!
∂ui ∂uj ∂ui ∂uj
+ δi3 uj β + δj3 ui β + π + +ν u u − 2ν
2 i j
∂xj ∂xi ∂xk ∂xk ∂xk
(4.146)
where use is made of the zero divergence condition (4.144) and the total
derivative is defined by
d ∂ ∂
= + Uk (4.147)
dt ∂t ∂xk
The transport equation for the buoyancy fluxes ui β is derived by multiplying
(4.143) by β, (4.145) by ui adding and making the average
d ∂
ui β + ui uj β + ǫijk fj uk β =
dt ∂xj
∂ ∂b ∂Ui ∂β
− βπ − ui uj − uj β + δi3 β 2 + π
∂xi ∂xj ∂xj ∂xi
∂ ∂ui ∂ ∂β ∂ui ∂β
+ν β + kT ui − (ν + kT ) (4.148)
∂xj ∂xj ∂xj ∂xj ∂xj ∂xj
The β 2 -equation is obtained by multiplying (4.145) with 2β and averaging

!2
d 2 ∂ ∂b X ∂ 2β 2 X ∂β
β + ui β 2 = −2ui β + kT 2
− 2kT (4.149)
dt ∂xi ∂xi i ∂xi i ∂xi
Equations (4.146)–(4.149) form a complete set of equations for all second-

order correlations. An important equation is the one for turbulent kinetic
energy k, defined by (4.113) and obtained from (4.146) by taking half its
trace
!2
dk ∂ 1 ∂ 2k ∂Ui ∂ui
+ ui ( ui uj + π) − ν 2 = −ui uj + δi3 ui β − ν
dt ∂xj 2 ∂xi ∂xj ∂xj
= P +G−ε (4.150)
where summation is taken over all indices. The terms on the right have the
following meaning:
• P is a source term and equals the energy withdrawn by the “energy

containing eddies” at the largest spatial scales of the turbulence spec-
trum
• G is a buoyancy term which can shown to be (see below) a sink term

for stable stratification (Ri > 0) and a source term for an unstable
stratification (Ri < 0).
• ε represents the dissipation of turbulent energy which occurs at the

smallest scales of turbulence.
One main properties of fully developed turbulence is that it adjusts rapidly

to a state of equilibrium. This means that the terms on the right hand side
are the dominant ones and P + G ≃ ε. A further advantage is that P and G
don’t contain unknown correlations.
4.4.3.2 parameterisation of the RANS equations

The following parameterisations are adopted for the unknown correlations in
(4.146), (4.148) and (4.149).
• All Coriolis terms are set to zero. The main reason is that rotation
introduces a large level of complexity. The simplification can be con-
sidered as reasonable when the Coriolis period is much larger than the
decay time of turbulence or f ε/k ≪ 1. For an account of Coriolis
effects see Galperin et al. (1989); Kantha et al. (1989).
• Pressure-strain correlation
!
∂ui ∂uj ε 2 2
π + = −c1 (ui uj − δij k) − c21 (Pij − δij P )
∂xj ∂xi k 3 3
!
∂Ui ∂Uj 2
−c22 k + − c23 (Dij − δij P )
∂xj ∂xi 3
2
−c3 (Gij − δij G) (4.151)
3
The first term represents the Rotta (1951) hypothesis of return to
isotropy. The tensors in the remaining terms are defined by
∂Uj ∂Ui
Pij = −ui uk − u j uk (4.152)
∂xk ∂xk
∂Uk ∂Uk
Dij = −ui uk − uj u k (4.153)
∂xj ∂xi
Gij = δi3 uj β + δj3 ui β (4.154)
1 ∂Ui
P = Pii = −ui uk (4.155)
2 ∂xk
1
G = Gii = δi3 ui β = wβ (4.156)
2
• Pressure-buoyancy gradient correlation
∂β ε ∂Ui ∂Uk
π = −c1β ui β + c21β uk β − c22β uk β − c3β δi3 β 2 (4.157)
∂xi k ∂xk ∂xi
• Dissipation terms
∂ui ∂uj 2
2ν = δij ε (4.158)
∂xk ∂xk 3
!2
∂β ε β2
2kT = χ= (4.159)
∂xi k Rβ
∂ ∂ui ∂ ∂β ∂ui ∂β
ν β = kT ui = (ν + kT ) = 0 (4.160)
∂xj ∂xj ∂xj ∂xj ∂xj ∂xj
Since the laminar diffusion scales are much smaller than the scales of
the largest eddies, the laminar terms can be neglected
∂2 ∂ 2β 2
ν u i uj = 0 , kT =0 (4.161)
∂x2k ∂x2i
Equation(4.158) states that turbulence energy is dissipated isotropi-
cally. Equation(4.159) assumes that the dissipation time scale of tur-
bulence kinetic enery k/ε is proportional to the one for the buoyancy
variance β 2 /χ. The ratio is given by the parameter Rβ .
• Pressure transport is neglected
∂ ∂
uj π = 0 , βπ = 0 (4.162)
∂xi ∂xi
The expressions for the pressure-strain and pressure-buoyancy gradient are
compiled from different sources and presented in their most general form.
The parameterisations contain 10 parameters c1 , c21 , c22 , c23 , c3 , c1β , c21β ,
c22β , c3β , Rβ . The values used in COHERENS are taken from different sources:
Mellor & Yamada (1982); Kantha & Clayson (1994); Burchard & Baumert
(1995); Hossain & Rodi (1982) and two schemes taken from Canuto et al.
(2001). The six models are further denoted by MY82, KC94, BB95, HR82,
CA01 and CB01. Values of the parameters are listed in Table 4.2. For
readers, familiar with the Ai , Bi , Ci parameters used in MY82 and KC94,
the following conversion rules apply
B1
c1 = , c21 = 0 , c22 = −2C1 , c23 = 0 , c3 = 0
6A1
B1 B2
c1β = , c21β = C2 , c22β = 0 , c3β = C3 , Rβ = (4.163)
6A2 B1
Different schemes are available for the modelisation of the third-order
correlations, total derivative (i.e. time derivative and advective terms) in
(4.146)–(4.150). They are based on the classification scheme introduced by
Mellor & Yamada (1974, 1982) and Galperin et al. (1988).
Table 4.2: Values of the turbulence constants in the RANS equations accor-
ding to the different models implemented in COHERENS.
c1 c21 c22 c23 c3 c1β c21β c22β c3β Rβ
MY82 3.01 0 -0.16 0 0 3.74 0 0 0 0.61
KC94 3.01 0 -0.16 0 0 3.74 0.7 0 0.2 0.61
BB95 1.8 0.6 0 0 0.6 3.0 0.33 0 0.333 0.8
HR82 2.2 0.55 0 0 0.55 3.0 0.5 0 0.5 0.8
CA01 2.49 0.777 0.256 0.207 0.402 5.95 0.8 0.2 0.333 0.72
CA02 2.1 0.803 0.257 0.183 0.576 5.6 0.8 0.2 0.333 0.477
1. Non-equilibrium or “level 3” method. The left hand sides of (4.148)

and (4.149) are set to zero while
d ∂ 2
ui u j + ui uj uk = δij (P + G − ε) (4.164)
dt ∂xk 3
in (4.146) and
1 ∂ 2 ∂ k ∂k
ui uj = −csk uj uk (4.165)
2 ∂xj ∂xj ε ∂xk
in (4.150). The expression in the last equation was proposed by Daly &
Harlow (1970) and differs somewhat from the one given in the Mellor-
Yamada papers. This will be further discussed below.
2. Quasi-equilibrium or “level 2.5” method after Galperin et al. (1988).
This is the same as previous except that P +G is set to ε in all equations
except in the one for turbulent energy. This mean that the left hand
side of (4.146) becomes zero as well.
3. Equilibrium or “level 2” method. A full equilibrium, i.e. P + G = ε in
all equations including the k-equation.
A major simplification is additionally achieved by making the boundary
layer approximation. This means that horizontal derivatives of mean quan-
tities and the mean vertical current are all set to zero.
4.4.3.3 stability functions

Substituting the parameterisations and approximations, presented in the pre-
vious subsection into the equations for the second-order correlations, the
problem reduces to solving a system of linear equations. Solutions are pre-
sented below for each of the three equilibrium levels.
Non-equilibrium method
The following system of linear equations is obtained where a vertical deriva-
tive is denoted by a subscript z and bz = N 2 by its definition (4.119)
2h k i
u2 = k− (2 − 2c21 + c23 )uwUz − (1 − c21 − c23 )vwVz + (1 − c3 )wβ
3 εc1
2 h k i
v2 = k+ (1 − c21 − c23 )uwUz − (2 − 2c21 + c23 )vwVz − (1 − c3 )wβ
3 εc1
2h k i
w2 = k+ (1 − c21 + 2c23 )(uwUz + vwVz ) + 2(1 − c3 )wβ
3 εc1
k
uv = − (1 − c21 )(uwVz + vwUz )
εc1
k h i
uw = − (1 − c21 )w2 Uz + c22 kUz − c23 (u2 Uz + uvVz ) − (1 − c3 )uβ
εc1
k h i
vw = − (1 − c21 )w2 Vz + c22 kVz − c23 (v 2 Vz + uvUz ) − (1 − c3 )vβ
εc1
k h i
uβ = − uwN 2 + (1 − c21β )wβUz
εc1β
k h i
vβ = − vwN 2 + (1 − c21β )wβVz
εc1β
k h 2 2 i
wβ = − w N + c22β (uβUz + vβVz ) − (1 − c3β )β 2
εc1β
k
β2 = −2 Rβ N 2 wβ
ε
(4.166)
The solutions for the vertical fluxes of momentum and buoyancy can be
written as
k 2 ∂U k 2 ∂V k2
− uw = Su , −vw = Su , −wβ = Sb N 2 (4.167)
ε ∂z ε ∂z ε
Comparing with (4.116) and (4.114) the eddy viscosity and diffusivity are
given by
k2 k2
ν T = Su , λ T = Sb (4.168)
ε ε
Note that these expressions are obtained from the RANS theory and not
postulated a priori.
The coefficients Su and Sb are the so-called stability functions and can be
expressed as function of the stability parameters
k2 2 k2 2
αM = M , αN = N (4.169)
ε2 ε2
The two parameters are the squares of the ratio of respectively the shear and
buoyancy frequency with respect to the turbulence frequency and represent
the influence of shear and density gradients on the turbulent fluxes. The
solutions for Su and Sb can be written as
Su = (Ca1 + Ca2 αM + Ca3 αN )/D

Sb = (Ca4 + Ca5 αM + Ca6 αN )/D
2 2
D = 1 + Ca7 αM + Ca8 αN + Ca9 αM + Ca10 αM αN + Ca11 αN (4.170)
Explicit expressions for the coefficients Cai as function of the RANS parame-
ters are given in Appendix B.
When applying the boundary layer approximation, the diffusion term
(4.165) in the k-equation can be written as
∂ k ∂k ∂ k 2 ∂k ∂ ∂k
csk uj uk ≃ csk w = νk (4.171)
∂xj ε ∂xk ∂z ε ∂z ∂z ∂z
where the diffusion coefficient is given by
k2 w2 k2
νk = csk = Sk (4.172)
ε k ε
The stability coefficient for turbulent energy diffusion is given by
w2 2 h 1 i
Sk = csk = csk 1 − (1 − c21 + 2c23 )αM Su + 2(1 − c3 )αN Sb (4.173)
k 3 c1
Quasi-equilibrium method
The equations for the second order correlations are the same as in (4.166)
except for the components of turbulent energy
2 1 − c21 − c23 2k h 1 i
u2 = k 1− − (1 − c21 )uwUz + (c21 + c23 − c3 )wβ
3 c1 εc1 3
2 1 − c21 − c23 2k h 1 i
v2 = k 1− − (1 − c21 )vwVz + (c21 + c23 − c3 )wβ
3 c1 εc1 3
2 1 − c21 + 2c23 2k
w2 = k 1− + (3 − c21 + 223 − 2c3 )wβ
3 c1 3εc1
(4.174)
The solutions for the vertical fluxes can be written in the form (4.167)–
(4.169), obtained with the non-equilibrium method. Difference is that the
stability functions now only depend on αN . Two cases can be distinguished
1. Case c22β = 0.
Cb1 + Cb2 αN
Su =
(1 + Cb3 αN )(1 + Cb4 αN )
Cb5
Sb = (4.175)
1 + Cb3 αN
2. Case c22β 6= 0.
Cc1 + Cc2 αN Sb
Su = (4.176)
1 + Cc3 αN
Sb is obtained as solution of the quadratic equation
(Cc4 + Cc5 αN )αN Sb2 + (Cc6 + Cc7 αN )Sb + Cc8 = 0 (4.177)
giving
(Cc6 + Cc7 αN ) + sD1/2

Sb = −
2(Cc4 + Cc5 αN )αN
D = (Cc6 + Cc7 αN )2 − 4Cc8 (Cc4 + Cc5 αN )αN (4.178)
where s is the sign of Cc6 + Cc7 αN .

The expression for the turbulent energy stability coefficient now becomes
w2 2csk
Sk = csk = c1 − 1 + c21 − 2c23 − (3 − c21 + 2c23 − 2c3 )αN Sb (4.179)
k 3c1
Equilibrium method
In this case equilibrium between production and dissipation of turbulent
energy is assumed in all second moment equation and in the equation of
turbulent energy. This means that
P + G = ε or in dimensionless form Su αM − Sb αN = 1 (4.180)
since
P +G uwUz + vwVz wβ k2 k2
=− + = Su 2 M 2 − Sb 2 N 2 = Su α M − Sb α N
ε ε ε ε ε
(4.181)
Using (4.180) and the expressions for Su and Sb , the following relation be-
tween the stability parameters can be derived
2 2
1 + Cd1 αM + Cd2 αN + Cd3 αM + Cd4 αM αN + Cd5 αN =0 (4.182)
which can be rewritten as a quadratic equation for the squared inverse time
scale κ2 = ε2 /k 2
κ4 + (Cd1 M 2 + Cd2 N 2 )κ2 + Cd3 M 4 + Cd4 M 2 N 2 + Cd5 N 4 = 0 (4.183)
If the limit κ = 0 is taken, then αM = αN = ∞ so that Su = Sb = 0. From

(4.182) one therefore deduces that turbulence ceases when the Richardson
number exceeds a critical value Ric obtained by setting κ2 = 0. This gives
Cd4
Ric = − if c22β = 0
Cd5
q
2
Cd4 − 4Cd3 Cd5 − Cd4
Ric = if c22β 6= 0 (4.184)
2Cd5
From Table 4.3 it is seen that Ric strongly depends on the type of model.
Since αM = αN /Ri equation (4.182) can be rewritten as
2
(1 + Cd2 αN + Cd5 αN )Ri2 + αN (Cd1 + Cd4 αN )Ri + Cd3 αN
2
=0 (4.185)
Solving (4.185) for Ri as a function of αN and substituting into the expres-

sions (4.175)–(4.178), the stability functions can be expressed as function of
Ri only. The dependence of Su and Sb on Ri is shown in Figure 4.4 for the six
RANS models. Also shown is the case of stable stratification with limiting
conditions which is further discussed in Section 4.4.3.6.
Alternative methods
Besides the expressions given above, the COHERENS program allows to use
simpler formulations for the stability coefficients. In the first one the quasi-
equilibrium expressions (4.175)–(4.178) are reset to their constant neutral
values obtained in the absence of stratification (αN = 0)
Su = Su0 , Sb = Sb0 (4.186)
Values of Su0 and Sb0 are given in Table 4.36 . In the second form, Su and
Sb are set to their neutral values, multiplied by the Munk-Anderson damp-
ing/amplification factors, defined by (4.127) and (4.128) or
Su = Su0 fm (Ri) , Sb = Sb0 gm (Ri) (4.187)
The latter scheme resembles the one adopted in the earlier standard version
of the k − ε model (Rodi, 1984).
6
Node that Su0 is the same as the parameter cµ used in the standard k − ε theory
(Rodi, 1984).
Figure 4.4: Stability coefficients Su (left column), Sb (right column) as a

function of the Richardson number using the equilibrium method for RANS
model MY82 (solid), KC94 (dots), BB95 (dashes), HR82 (dash-dots), CA01
(dash and 3 dots), CA02 (long dashes): stable case without limiting condition
(upper row), stable case with limiting condition (middle row), unstable case
(bottom row).
Table 4.3: Values of critical parameters according to different RANS models.

Su0 Sb0 Ric Ri⋆c αmax ν0l λ0l
MY82 0.095 0.119 0.197 0.161 15.35 0.050 0.053
KC94 0.095 0.119 0.244 0.183 12.69 0.063 0.065
BB95 0.115 0.173 0.647 0.252 5.92 0.130 0.106
HR82 0.108 0.177 0.579 0.207 4.72 0.123 0.132
CA01 0.077 0.090 0.851 0.281 7.91 0.123 0.088
CA02 0.094 0.095 1.023 0.388 10.07 0.160 0.104
It is remarked that these schemes are physically less robust, but have
been implemented in the code for historical reasons or to perform sensitivity
experiments related to specific details of the turbulence schemes.
Besides the general expressions (4.173) or (4.179) for the diffusion of tur-
bulent energy, the following simpler alternative options for the stability co-
efficient Sk are implemented
Sk = Sk0 (4.188)
and
Sk = Su /σk (4.189)
where Sk0 and σk are model constants. The first form was introduced in k − l
model of Mellor & Yamada (1982), the second in the “standard” k − ε model
(Rodi, 1984), further discussed below. In the former case Sk0 is related to
the Mellor-Yamada parameter Sq by
Sk0 = 21/2 ǫ0 Sq (4.190)
3/4
with ǫ0 = Su0 (see equation (4.191) below).
4.4.3.4 solution methods

The theories presented in Section 4.4.3.3 define the eddy coefficients as func-
tion of two turbulent parameters: turbulence energy k and its dissipation
rate ε. Such theories, primarily used in hydraulic modelling, are called k − ε
models. The former is determined by solving either the equation for turbu-
lent energy or by the equilibrium relation (4.183). It remains to determine ε
appearing in the expressions for the eddy coefficients, stability parameters,
k-equation and the equilibrium relation (4.183). Different methods, using
either a prescribed analytical expression or a parameterised transport equa-
tion, are given below.
Other theories, like the one advocated by Mellor & Yamada (1974, 1982),
prefer to use the mixing lenth l, representative of the spatial scales of the
largest (energy-containing) eddies, instead. Such theories are called k − l (or

q 2 − q 2 l with q 2 = 2k in the Mellor-Yamada terminology) models. The k − ε
and k − l models are separately discussed below.
k − ε models
The schemes are divided into three categories depending on the number of
transport equations which need to be solved.
1. Zero-equation model. The dissipation rate is determined through the

relation
k 3/2
ε = ǫ0 (4.191)
l
3/4
where l is the mixing length and ǫ = Su0 where Su0 is the neutral
value of the momentum stability coefficient Su . The mixing length
is determined from one of the available analytical expressions, given
below. Turbulence energy is calculated from the equilibrium relation
(4.183). The method has the advantage that no transport equation
need to be solved in time. The problem is, however, that it may produce
numerical instabilities in the time-integration of the model equations.
This is illustrated in Section 19.1 for the test case pycno.
2. One-equation model. Turbulence energy is obtained from the k-equation.

Inserting the parameterisations of the previous subsection into the
source and sinks terms P and G and the diffusion term, this equa-
tion, written in transformed coordinates and in its most general form,
becomes
1 ∂ 1 ∂ νk ∂k
(h3 k) + Ah1 (k) + Ah2 (k) + Av (k) =
h3 ∂t h3 ∂s h3 ∂s
2 2
+ νT M − λT N − ε + Dsh1 (k) + Dsh2 (k) (4.192)
with ε given by (4.191) and the advection and diffusion operators de-
fined by (4.53)–(4.55), (4.66)–(4.67). The last two terms represent hori-
zontal diffusion of k. It is noted that advection and horizontal diffusion
are usually neglected. This is achieved in the model by the settings of
two switches (see below).
3. Two-equation model. Besides the k-equation (4.192), a second trans-

port equation is solved for ε. In transformed cordinates, this equation,
including extra horizontal diffusion terms which are usually neglected,
is given by (e.g. Rodi, 1984)
1 ∂ 1 ∂ νk ∂ε
(h3 ε) + Ah1 (ε) + Ah2 (ε) + Av (ε) =
h3 ∂t h3 ∂s h3 σε ∂s
2
ε ε
+ c1ε νT M 2 − c3ε λT N 2 − c2ε + Dsh1 (ε) + Dsh2 (ε)
k k
(4.193)
It should be remarked that, contrary to the k-equation, the ε-equation

is derived from a general equation after many parameterisations. The
parameters appearing in the (4.193) must satisfy the following con-
straint, derived from wall layer theory
κ2 Sk0
c1ε − c2ε = − (4.194)
ǫ20 σε
where Su0 and Sk0 are the neutral values of Su and Sk .
k − l models
In k − l theory all equations are written explicitly as function of k and l.
This is achieved by substituting l for ε through the relation (4.191). The
expressions for the eddy viscosity and diffusion coefficients then take the
form
νT = Sm k 1/2 l , λT = Sh k 1/2 l , νk = S̃k k 1/2 l (4.195)
where the stability functions (Sm , Sh , S˜k ) = (Su , Sb , Sk )/ǫ0 are function of
the stability parameters (Gm , Gh ) = (M 2 , N 2 ) l2 /k = ǫ20 (αM , αN ). Equations
(4.170), (4.175), (4.176)–(4.178) and (4.182) remain valid with (αM , αN ) re-
placed by (Gm , Gh ), (Su , Sb ) by (Sm , Sh ), κ by κ̃ and (Cai , Cbi , Cci , Cdi ) re-
placed by (C̃ai , C̃bi , C̃ci , C̃di ) using
1
(C̃a1 , C̃a4 ) = ǫ0 (Ca1 , Ca4 ) , (C̃a2 , C̃a3 , C̃a5 , C̃a6 ) = (Ca2 , Ca3 , Ca5 , Ca6 )
ǫ0
1 1
(C̃a7 , C̃a8 ) = (Ca7 , Ca8 ) , (C̃a9 , C̃a10 , C̃a11 ) = (Ca9 , Ca10 , Ca11 )
ǫ20 ǫ40
Cb2 1
(C̃b1 , C̃b5 ) = ǫ0 (Cb1 , Cb5 ) , C̃b2 = , (C̃b3 , C̃b4 ) = (Cb3 , Cb4 )
ǫ0 ǫ20
(C̃c1 , C̃c8 ) = ǫ0 (Cc1 , Cc8 ) , C̃c6 = Cc6
1 1 1
(C̃c2 , C̃c3 , C̃c7 ) = (Cc2 , Cc3 , Cc7 ) , C̃c4 = Cc4 , C̃c5 = Cc5
ǫ20 ǫ30 ǫ50
1 1
(C̃d1 , C̃d2 ) = (Cd1 , Cd2 ) , (C̃d3 , C̃d4 , C̃d5 ) = (Cd3 , Cd4 , Cd5 ) (4.196)
ǫ20 ǫ40
In case of a two-equation model, the ǫ-equation is replaced by an equation
for the quantity kl obtained from the Mellor-Yamada q 2 l-equation by setting
q 2 = 2k:
1 ∂ 1 ∂ νk ∂
(h3 kl) + Ah1 (kl) + Ah2 (kl) + Av (kl) = (kl)
h3 ∂t h3 ∂s h3 σkl ∂s
1 1
+ l E1 νT M 2 − E3 λT N 2 − ǫ0 k 3/2 W̃ + Dsh1 (kl) + Dsh2 (kl)
2 2
(4.197)
with the wall proximity function W̃ defined by

hl 1 1 i2
W̃ = 1 + E2 + (4.198)
κ H(1 − σ) + z0s σH + z0b
where z0s and z0b are roughness lengths at the surface, respectively the bot-
tom (see below). In analogy with the ε-equation the parameters in (4.197)–
(4.198) satisfy the constraint
2κ2 Sk0
E2 − E1 + 1 = (4.199)
ǫ20 σkl
4.4.3.5 mixing length formulations

A mixing length formulation is needed in the case of a zero- or one-equation
model. Four formulations are implemented in the program. The basic re-
quirement in each formulation is that l reduces to the following forms near,
respectively, the bottom and the surface
l ≃ l1 = κ(σH + z0b ) , l ≃ l2 = κ(H − σH + z0s ) (4.200)
where z0s and z0b are the surface and bottom roughness lengths.
The first and simplest expression is the parabolic law
1 1 1
= + (4.201)
l l1 l2
having a maximum at σ ≃ 0.5.
The second is the “quasi-parabolic” law given by
1 1 l1 + l2 1/2
= (4.202)
l l1 l2
which differs from the first one in that l has a maximum at σ ≃ 2/3 closer
to the surface.
The third, recommended by Xing & Davies (1996) has the same form as
(4.201) but with l1 replaced by
l1 = κ(σHe−β1 σ + z0b ) (4.203)
allowing for a larger reduction of the mixing length in the lower parts of the
water column.
The fourth formulation, initially proposed by Blackadar (1962), has the
form
1 1 1 1
= + + (4.204)
l l1 l2 la
so that l → la far from the boundaries. Mellor & Yamada (1974) defined la
as the ratio of the first to the zeroth moment of the vertical profile of the
turbulent velocity scale k 1/2 . Hence
Z 1 Z 1
1/2
la = α 1 (1 − σ)k H dσ / k 1/2 H dσ (4.205)
0 0
4.4.3.6 background mixing

The theory, presented above, is valid for the case of a nearly-isotropic, fully
developed turbulence under homeogeneous or weakly stratified conditions,
but becomes invalid for strongly stratified flows. The reasons are as follows:
• It is known from theory and laboratory experiments that vertical turbu-
lent excursions are impeded by stable stratification. The consequence
is that turbulence becomes anisotropic and the assumption of nearly-
isotropic turbulence can no longer be maintained.
• Even when turbulence decays for an increasing stable stratification,

additional turbulence is generated by the shear and breaking of internal
waves which are not resolved by the model.
In the absence of a comprehensive theory of both effects, simple parame-
terisations have been designed and implemented in the COHERENS code.
The methods consist in adding background mixing coefficients to the one
calculated by the RANS scheme. Two different schemes are available.
The first one is based on limiting conditions for turbulence variables.
The limitation of vertical overturns by stable stratification is expressed by a
limiting condition of the form
LT /LO < Rl (4.206)

where the constant Rl is of O(1),

q
LT = − β 2 /N 2 (4.207)
is the Thorpe scale measuring the extent of the vertical excursions, and
LO = (ε/N 3 )1/2 (4.208)
the Ozmidov scale at which buoyancy and inertial forces are of comparable
magnitude. From theory, laboratory and measurements at sea (see Luyten
et al., 2002, and references therein), it is found that Rl ≃ 1 − 1.3. Using the
last equation of (4.166), (4.167), (4.169) one obtains
L 2
T β2 3/2
= = 2Rβ Sb αN (4.209)
LO Nε
Assuming a state of quasi-equilibrium, it can be shown that the right hand
side of (4.209) is an increasing function of αN . The upper limit in (4.206)
then implies a maximum value αmax for αN . Its value is obtained by solving
3/2
2Rβ Sb αN = Rl2 = 2Rβ R⋆ (4.210)
1/2
for Z = αN after substitution of (4.175) or (4.178). The result is the poly-
nomial equation
Cb5 Z 3 − R⋆ Cb3 Z 2 − R⋆ = 0 (4.211)
if c22β = 0 or
Cc5 Cc8 Z 6 + R∗ Cc5 Cc7 Z 5 + (Cc4 Cc8 + R∗2 Cc5
2
)Z 4 + R∗ (Cc4 Cc7 + Cc5 Cc6 )Z 3
+ 2R∗2 Cc4 Cc5 Z 2 + R∗ Cc4 Cc6 Z + R∗2 Cc4
2
=0 (4.212)
if c22β 6= 0. Since Su and Sb are decreasing functions of αN , the stability
functions are limited from below by the constants Sulim and Sblim . The theory
is illustrated in Figure 4.4 where the evolution of Su and Sb as function of
the Richardson number is shown for the simplified equilibrium method and
using an upper limit for αN .
Substituting the previous limits into the definitions of the eddy coeffi-
cients and αN , the following limiting or background values are obtained
1/2 k k
νT > νT lim = Sulim αmax = ν0l
N N
1/2 k k
λT > λT lim = Sblim αmax = λ0l
N N
−1/2
ε > εlim = αmax kN
1/2
1/2 k
l < lmax = ǫ0 αmax (4.213)
N
As explained in Luyten et al. (2002) a second limiting condition needs to be

imposed for the turbulence energy
k > klim (4.214)
yielding background values of the form νT ∼ N −1 , λT ∼ N −1 and ε ∼ N .

The effect of the limiting condition can be further clarified by mak-
ing the local equilibrium assumption (4.180). Substituting αmax into equa-
tion (4.182) and setting αM = αN /Ri, this equation can be solved for Ri
yielding a second critical Richardson number Ri⋆c < Ric . The eddy coeffi-
cients are then given by the previous closure schemes or by the background
values (4.213) depending on whether Ri is lower or higher than Ri⋆c . Values
of the critical parameters αmax , ν0l , λ0l and Ri⋆ are listed in table 4.3.
The second method is a semi-empirical formulation originally proposed
by Large et al. (1994)
p 1
νbT = νT 0 + ν0s 1 − Ri/Ri0
p 1
λbT = λT 0 + ν0s 1 − Ri/Ri0 (4.215)
where νbT and λbT are background mixing coefficients added to the eddy
coefficients calculated by the model. The first terms on the right hand side
represent mixing due to unresolved internal shear, the second one mixing due
to internal wave braking. The parameters have the following default values
Ri0 = 0.7 , (ν0s , νT 0 , λT 0 ) = (0.005, 10−4 , 0.5 × 10−4 ) m2 /s

p1 = 3 ,
(4.216)
Besides the physical limiting conditions, discussed above, the following
numerical lower bounds are imposed
kmin = 10−14 , εmin = 10−12 , lmin = 1.7 × 10−10 (4.217)
The reason for adopting this lower limits is to prevent that unrealistically
large eddy coefficients are created by rounding errors within the intermittent
zone. With the above values and taking Su ∼ Sb ∼ 0.1 the values of νT
and λT are of the order of ∼ 10−17 which are clearly much smaller than the
corresponding laminar viscosity and diffusivity coefficients.
Implementation
A RANS model is selected if iopt vdif coef=3. A series of additional switches
are implemented to determine the specifications of the model.
iopt turb param Selects mixing length or dissipation rate as model variable.
1 : k − l scheme
2 : k − ε scheme
iopt turb ntrans Selects number of transport equations.
0 : zero-equation model (equilibrium method and prescribed mixing length)
1 : one-equation model (k-equation and prescribed mixing length)
2 : two-equation model (k-equation and either ε or kl-equation)
iopt turb stab form Selects general form for the stability functions
1 : constant value
2 : Munk-Anderson formulation
3 : as obtained from RANS model
iopt turb stab mod Selects type of RANS scheme
1 : MY82-model (Mellor & Yamada, 1982)
2 : KC94-model (Kantha & Clayson, 1994)
3 : BB95-model (Burchard & Baumert, 1995)
4 : HR82-model (Hossain & Rodi, 1982)
5 : CA01-model (Canuto et al., 2001)
iopt turb stab lev Selects the form of stability functions if iopt turb stab form=3.
1 : quasi-equilibrium (level 2.5) method
2 : non-equilibrium (level 3) method
iopt turb stab tke Selects the formulation for the diffusion coefficient in the
k-equation.
1 : constant stability coefficient (4.188)
2 : stability coefficient proportional to the one for momentum as given by
(4.189)
3 : using the Daly & Harlow (1970) formulation (4.173) or (4.179)
iopt turb lmix Selects the formulation for the mixing length.
1 : parabolic law
2 : quasi-parabolic law
3 : after Xing & Davies (1996)
4 : Blackadar asymptotic formulation

iopt turb iwlim Selects the type of background mixing scheme.
0 : uniform background values
1 : using limiting conditions for the turbulence variables
2 : Large et al. (1994) background mixing scheme
Table 4.4 gives an overview of all parameters used in the different schemes
and their default values.
Table 4.4: Parameters used in different turbulence schemes (except those listed in
Tables 4.2 and 4.3) and their default values.
name value unit purpose

k-l theory
E1 1.8 – constant in the shear production term of the kl-equation
(4.197)
E2 1.33 – constant in the wall proximity term (4.198) of the kl-equation
(4.197)
E3 1.0 – constant in the buocancy source/sink term of the kl-equation
(4.197)
k-ε theory
c1ε 1.44 – constant in the shear production term of the ε-equation
(4.193)
c2ε 1.92 – constant in the dissipation term of the ε-equation (4.193)
c3ε 0.2 – constant in the buoyancy sink term of the ε-equation (4.193)
in case of stable stratification (N 2 > 0)
c3ε 1.0 – constant in the buoyancy source term of the ε-equation (4.193)
in case of unstable stratification (N 2 < 0)
diffusion coefficients for turbulence variables
csk 0.15 – Daly-Harlow parameter in (4.165)
Sk0 0.09 – neutral value of the stability coefficient Sk in the k-ε model
(see equation (4.188))
Sq 0.2 – used to determine Sk0 in the Mellor-Yamada model (see equa-
tion (4.190))
σk 1.0 – used to define Sk in (4.189)
σkl 1.83 – ratio of the diffusion coefficients in the k- and kl-equations,
calculated from (4.199)
σε 1.01 – ratio of diffusion coefficients in the k- and ε-equations, calcu-
lated from (4.194)
(Continued)
Table 4.4: Continued
limiting conditions
klim 10−6 J/kg background limit for k (see equation (4.214))
kmin 10−14 J/kg numerical lower limit for k
lmin 1.7×10−10 m numerical lower limit for l
εmin 10−12 W/kg numerical lower limit for ε
background mixing
Ri0 0.7 – critical Richardson number in the Large et al. (1994) back-
ground mixing scheme (4.215)
λT 0 5×10−5 m2 /s internal wave breaking diffusion coefficient for scalars in the
Large et al. (1994) background mixing scheme (4.215)
νT 0 10−4 m2 /s internal wave breaking diffusion coefficient for momentum in
the Large et al. (1994) background mixing scheme (4.215)
s 2
ν0 0.005 m /s maximum mixing due to unresolved vertical shear in the Large
et al. (1994) background mixing scheme (4.215)
boundary conditions
cw 0.0 – surface wave factor used in the surface flux condition (4.271)
for turbulent energy
z0b 0.0 m bottom roughness length in the mixing length formulation
(4.200)
z0s 0.0 m surface roughness length in the mixing length formulation
(4.200)
mixing length formulations
α1 0.2 – constant in the Blackadar (1962) mixing length formulation
(4.205)
β1 2.0 – attenuation factor in the Xing & Davies (1996) mixing length
formulation (4.203)
algebraic schemes
np 2.0 – Pacanowski & Philander (1981) scheme (4.121)–(4.123)
αp 5.0 – Pacanowski & Philander (1981) scheme (4.121)–(4.123)
−5 2
λbp 10 m /s Pacanowski & Philander (1981) scheme (4.121)–(4.123)
νbp 10−4 m2 /s Pacanowski & Philander (1981) scheme (4.121)–(4.123)
νmax 3.0 – Pacanowski & Philander (1981) scheme (4.121)–(4.123)
ν0p 0.01 m2 /s Pacanowski & Philander (1981) scheme (4.121)–(4.123)
n1 0.5 – Munk & Anderson (1948) scheme (4.125)–(4.128)
n2 1.5 – Munk & Anderson (1948) scheme (4.125)–(4.128)
αm 10.0 – Munk & Anderson (1948) scheme (4.125)–(4.128)
βm 3.33 – Munk & Anderson (1948) scheme (4.125)–(4.128)
λmax 4.0 – Munk & Anderson (1948) scheme (4.125)–(4.128)
(Continued)
νmax 3.0 – Munk & Anderson (1948) scheme (4.125)–(4.128)

ν0m 0.06 m2 /s Munk & Anderson (1948) scheme (4.125)–(4.128)
Cν 2.0 – see equation (4.140)
K1 0.0025 – see equations (4.137) and (4.139)
K2 2×10−5 – see equation (4.138)
r1 1.0 – see equation (4.132)
r2 1.0 – see equation (4.132)
δ1 0.0 – see equation (4.132)
δ2 0.0 – see equation (4.132)
λ⋆ 0.0 m see equation (4.135)
ω1 10−4 s−1 see equation (4.140)
4.5 Astronomical tidal force

Tides are generated by the combined gravitational attraction of the sun and
the moon. The total force is calculated as the gradient of the tidal potential
Φtid . The potential can be written as a series of tidal harmonics
N0
Φtid 3
= ζe = ( cos2 φ − 1)
X
A0n (t) cos V0n (t) + u0n (t)
g 2 n=1
N1
X
+ sin 2φ A1n (t) cos λ + V1n (t) + u1n (t)
n=1
N2
+ cos2 φ
X
A2n (t) cos 2λ + V2n (t) + u2n (t)
n=1
N3
+ cos3 φ
X
A3n (t) cos 3λ + V3n (t) + u3n (t)
n=1
3 Nq
X X
= Gq (φ) Aqn (t) cos qλ + Vqn (t) + uqn (t) (4.218)
q=0 n=1
where ζe is the so-called equilibrium tide, i.e. the change of sea level due
to the tidal attraction only, i.e. in absence of all other forces (pressure,
Coriolis, ...), N0 , N1 , N2 , N3 are the number of respectively long-period,
diurnal, semi-diurnal and terdiurnal tides and q is the species index. Higher
order harmonics can shown to be negligible and are therefore not included
in the expansion. Once the tidal potential is known, the components of the
4.5. ASTRONOMICAL TIDAL FORCE 87
tidal force in the momentum equations are obtained using

!
g ∂ζe g ∂ζe ∂λ ∂ζe ∂φ
F1t = = +
h1 ∂ξ1 h1 ∂λ ∂ξ1 ∂φ ∂ξ1
!
g ∂ζe g ∂ζe ∂λ ∂ζe ∂φ
F2t = = + (4.219)
h2 ∂ξ2 h2 ∂λ ∂ξ2 ∂φ ∂ξ2
The tidal amplitudes are the product of three factors
Aqn (t) = aqn αqn fqn (t) 0≤q≤3 (4.220)
The first factor aqn is the astronomical tidal amplitude due to the lunar and
solar attractive forces. The Earth can be considered as an elastic body and is
deformed by the tidal force as well. The effect of the Earth tide is to reduce
the astronomical tide and is represented by the second factor αqn . Values
are taken from Foreman et al. (1993). The third term is the so-called nodal
factor and arises from modulations of the the lunar orbit. The term is always
close to 1 and varies with a period of 18.6 years.
The tidal phases are the sum of the geographical factor qλ, the astro-
nomical argument Vqn and the nodal correction factor uqn (further discussed
below). The astronomical phase is evaluated at the longitude of Greenwich
(λ = 0). Its time dependence is given by the astronomical ephemerides7
Vqn (t) = iτ + js + kh + lp + mN + nps (4.221)
where i = q and j, k, l, m, n are integers, called the Doodson numbers

(Doodson, 1921), characterising the constituent, and
τ the mean lunar time
s the mean longitude of the moon
h the mean longitude of the sun
p the mean longitude of the lunar perigee
N the negative mean longitude of the ascending lunar node
ps the mean longitude of the solar perigee

7
An additional phase lag of ±900 has to be added for diurnal tides and 00 or 1800 for
diurnal tides.
Since the six astronomical parameters are almost linear time, one can write
Vqn (t) ≃ Vqn (t0 ) + (t − t0 )ωqn (4.222)
where t0 is the time of the previous mid-night at Greenwich8 and ωqn the
frequency of the tidal constituent. The mean lunar time τ is related to the
mean solar time (H) by
τ =H −s+h (4.223)
From (4.221) one obtains therefore
Vqn (t0 ) = (j − i)s0 + (k + i)h0 + lp0 + mN0 + nps0 (4.224)
ωqn = iτ̇0 + j ṡ0 + k ḣ0 + lṗ0 + mṄ0 + nṗs0 (4.225)
where a ˙ (dot) represents a time derivative and the subscript 0 evaluation
at midnight (GMT). The astronomical ephemerides are calculated in time
using the reference values at the first of January 0h (GMT) of the year 1900.
Explicit expressions (in degrees), taken from Kantha & Clayson (2000b), are
s0 = 270.434358 + 481267.88314137T − 0.001133T 2 + 1.9.10−6 T 3
h0 = 279.69668 + 36000.768925485T + 3.03.10−4 T 2
p0 = 334.329653 + 4069.0340329575T − 0.10325T 2 − 1.2.10−5 T 3
N0 = −259.16 + 1934.14T − 0.0021T 2
ps0 = 281.22083 + 1.71902T + 0.00045T 2 + 3.0.10−6 T 3 (4.226)
The number of Julian centuries T is given as function of the current year y
and the day number within the current year d (between 1 and 366) and the
current year y:
T = (27393.500528 + 1.0000000356D)/36525
D = d + 365(y − 1975) + INT(y − 1973)/4 (4.227)
if the current year is 1975 or later, or
T = (0.5 + D)/36525
D = d + 365(y − 1900) + INT(y − 1901)/4 (4.228)
for years before 1975. The rate of change of the astronomical ephemerides
are obtained from the above equations (e.g. Schureman, 1941)
τ̇0 = 14.4920520 /h , ṡ0 = 0.5490170 /h , ḣ0 = 0.0410680 /h
ṗ0 = 0.0046420 /h , Ṅ0 = −0.0022060 /h , ṗs0 = 0.0000020 /h
(4.229)
8
The time t must be referenced with respect to Greenwich mean time (GMT). An
automatic conversion is made by the program if needed.
from which the frequencies ωqn are obtained using (4.225).

A total of 56 astronomical tidal constituents are defined within the pro-
gram. The user is free to select a subset of these frequencies as part of the
model setup. The characteristics of all constituents (name, Doodson num-
bers, frequency, amplitude, Greenwich phase) are given in Table 4.5.
Besides the “main” astronomical constituents, defined in Table 4.5, the
harmonic expansion of the tidal potential shows a large number of additional
harmonics with frequencies close to some “main” frequency, but with am-
plitudes much smaller than the main constituent. Their effect is taken into
account through the nodal amplitude and phase factors fqn and uqn . They
are determined as follows. Let
N
X
ζen = an0 cos θ + ank cos(θ + ∆θk ) (4.230)
k=1
be a cluster of constituents around the main component “n” (after omission

of the common factor Gq ), with amplitude an0 and total phase θ. Setting
ε = ank /an0 ≪ 1, one obtains
X
ζen = an0 cos θ + εk cos(θ + ∆θk )
k
X
= an0 cos θ + εk (cos θ cos ∆θk − sin θ sin ∆θk )
k
X X
= an0 cos θ(1 + εk cos ∆θk ) − sin θ εk sin ∆θk
k k
= an0 fn cos(θ + un ) (4.231)
Defining X X
ρ1 = 1 + εk cos ∆θk , ρ2 = εk sin ∆θk (4.232)
k k
the nodal factors are then given by

q
fn = ρ21 + ρ22 , un = arctan(ρ2 /ρ1 ) (4.233)
and making a first order Taylor expansion with respect to εk . Values of ank
are taken from the tables given by Cartwright & Tayler (1971); Cartwright
& Edden (1973).
When the tidal forcing is included in the momentum equations, the tidal
solutions for currents and elevations contain additional higher frequencies
components. These so-called “overtides” are produced by non-linearities in
the model equations and do not appear in the expansion of the tidal potential.
For applications in shelf seas, where the astronomical force becomes negligible
compared to the bottom stress, the tidal forcing is introduced as an open

boundary condition for currents and/or elevations or as a surface boundary
condition in case of a water column application. The external forcing is
usually presented by an expansion of tidal harmonics which may include
overtides. A list of the most relevant overtides is given Table 4.6.
Table 4.5: Doodson numbers, frequencies (degrees/h), amplitudes (cm) and Green-
wich arguments (degrees) of the tidal constituents which can be used for astronom-
ical and open boundary forcing.
Name Doodson numbers ωqn aqn αqn Vqn (t0 )

i j k l m n
Long-period tides (q=0)
S0 0 0 0 0 0 0 0.0000000 19.8419 0.693 0.0
Sa 0 0 1 0 0 -1 0.0410667 0.3103 0.693 h − ps
Ssa 0 0 2 0 0 0 0.0821373 1.9542 0.693 2h
058 0 0 3 0 0 -1 0.123204 0.1142 0.693 3h − ps
M sm0 1 -2 1 0 0 0.4715211 0.4239 0.693 s − 2h − p
Mm 0 1 0 -1 0 0 0.5443747 2.2191 0.693 s−p
M sf 0 2 -2 0 0 0 1.0158958 0.3677 0.693 2s − 2h
Mf 0 2 0 0 0 0 1.0980331 4.2016 0.693 2s
083 0 3 -2 1 0 0 1.5695541 0.1526 0.693 3s − 2h + p
Mt 0 3 0 -1 0 0 1.6424078 0.8049 0.693 3s − p
093 0 4 -2 0 0 0 2.1139288 0.1287 0.693 4s − 2h
095 0 4 0 -2 0 0 2.1867825 0.1066 0.693 4s − 2p
Diurnal tides (q=1)
α1 1 -4 2 1 0 0 12.3827651 0.0749 0.693 −5s + 3h + p − 900
2Q1 1 -3 0 2 0 0 12.8542862 0.2565 0.693 −4s + h + 2p − 900
σ1 1 -3 2 0 0 0 12.9271398 0.3098 0.693 −4s + 3h − 900
Q1 1 -2 0 1 0 0 13.3986609 1.9387 0.6946 −3s + h + p − 900
ρ1 1 -2 2 -1 0 0 13.4715145 0.3685 0.6948 −3s + 3h − p − 900
O1 1 -1 0 0 0 0 13.9430356 10.1266 0.695 −2s + h − 900
τ1 1 -1 2 0 0 0 14.0251729 0.1325 0.6956 −2s + 3h + 900
β1 1 0 -2 1 0 0 14.4145567 0.0749 0.693 −s − h + p + 900
M1 1 0 0 1 0 0 14.4966939 0.7965 0.6962 −s + h + p + 900
χ1 1 0 2 -1 0 0 14.5695476 0.1522 0.6994 −s + 3h − p + 900
π1 1 1 -3 0 0 1 14.9178647 0.2754 0.7027 −2h + ps − 900
P1 1 1 -2 0 0 0 14.9589314 4.7129 0.7059 −h − 900
S1 1 1 -1 0 0 1 15.0000000 0.1116 0.7126 ps + 900
K1 1 1 0 0 0 0 15.0410686 14.2408 0.7364 h + 900
ψ1 1 1 1 0 0 -1 15.0821353 0.1132 0.5285 2h − ps + 900
φ1 1 1 2 0 0 0 15.1232059 0.2028 0.6657 3h + 900
θ1 1 2 -2 1 0 0 15.5125897 0.1526 0.6784 s − h + p + 900
J1 1 2 0 -1 0 0 15.5854433 0.7965 0.6911 s + h − p + 900
SO1 1 3 -2 0 0 0 16.0569644 0.1321 0.693 2s − h + 900
OO1 1 3 0 0 0 0 16.1391017 0.4361 0.6925 2s + h + 900
(Continued)
KQ1 1 4 0 -1 0 0 16.6834764 0.0834 0.693 3s + h − p + 900

Semi-diurnal tides (q=2)
OQ2 2 -3 0 3 0 0 27.3509801 0.0695 0.693 −5s + 2h + 3p
ε2 2 -3 2 1 0 0 27.4238337 0.1804 0.693 −5s + 4h + p
2N2 2 -2 0 2 0 0 27.8593548 0.6184 0.693 −4s + 2h + 2p
µ2 2 -2 2 0 0 0 27.9682084 0.7463 0.693 −4s + 4h
238 2 -2 3 0 0 -1 28.0092751 0.0502 0.693 −4s + 5h − ps
244 2 -1 -1 1 0 1 28.3986628 0.0394 0.693 −3s + h + p + ps + 1800
N2 2 -1 0 1 0 0 28.4397295 4.6735 0.693 −3s + 2h + p
246 2 -1 1 1 0 -1 28.4807962 0.0436 0.693 −3s + 3h + p − ps
ν2 2 -1 2 -1 0 0 28.5125831 0.8877 0.693 −3s + 4h − p
248 2 -1 3 -1 0 -1 28.5536498 0.0409 0.693 −3s + 5h − p − ps
γ2 2 0 -2 2 0 0 28.9112506 0.0734 0.693 −2s + 2p + 1800
H1 2 0 -1 0 0 1 28.9430375 0.0842 0.693 −2s + h + ps + 1800
M2 2 0 0 0 0 0 28.9841042 24.4102 0.693 −2s + 2h
H2 2 0 1 0 0 -1 29.0251709 0.0746 0.693 −2s + 3h − ps
λ2 2 1 -2 1 0 0 29.4556253 0.18 0.693 −s + p + 1800
L2 2 1 0 -1 0 0 29.5284789 0.6899 0.693 −s + 2h − p + 1800
T2 2 2 -3 0 0 1 29.9589333 0.6636 0.693 −h + ps
S2 2 2 -2 0 0 0 30.0000000 11.3572 0.693 0.0
R2 2 2 -1 0 0 -1 30.0410667 0.095 0.693 h − ps + 1800
K2 2 2 0 0 0 0 30.0821373 3.0875 0.693 2h
η2 2 3 0 -1 0 0 30.6265120 0.1727 0.693 s + 2h − p
295 2 4 0 0 0 0 31.1801703 0.0452 0.693 2s + 2h
Ter-diurnal tides (q=3)
M3 3 0 0 0 0 0 43.4761563 0.3455 0.693 −3s + 3h
Implementation
The following switches are available
iopt astro tide Disables (0) or enables (1) the inclusion of the tidal force in
the momentum equations.
iopt astro pars Selects the type of astronomical forcing (tidal force and at
open boundaries)
0: The astronomical argument is set to zero, the nodal factors are set
to 1.
1: The astronomical arguments are calculated from (4.224) at Green-
wich or at a user-defined reference longitude, the nodal factors are
set to 1.
2: The astronomical arguments are determined from (4.224) at Green-
wich or at a user-defined reference longitude, the nodal factors are
calculated as function of the astronomical ephemerides
Table 4.6: Doodson numbers, origin, frequencies (degrees/h) and Greenwich argu-
ments (degrees) of the overtides which can be used for the open boundary forcing.
Name Doodson numbers source ωqn Vqn (t0 )

i j k l m n
Semi-diurnal tides (q=2)
2SM2 2 4 -4 0 0 0 2S2 − M2 31.0158958 2s − 2h
Ter-diurnal tides (q=3)
2M K3 3 -1 0 0 0 0 2M2 − K1 42.9271398 −4s+3h−900
SO3 3 1 -2 0 0 0 S2 + O1 43.9430356 −2s + h − 900
M K3 3 1 0 0 0 0 M2 + K1 44.0251729 −2s+3h+900
SK3 3 3 -2 0 0 0 S2 + K1 45.0410686 h + 900
Quarter-diurnal tides (q=4)
M N4 4 -1 0 1 0 0 M2 + N2 57.4238337 −5s + 4h
M4 4 0 0 0 0 0 2M2 57.9682084 −4s + 4h
M S4 4 2 -2 0 0 0 M2 + S2 58.9841042 −2s + 2h
M K4 4 2 0 0 0 0 M2 + K2 59.0662415 −2s + 4h
S4 4 4 -4 0 0 0 2S2 60.0000000 0.0
Sixth-diurnal tides (q=6)
2M N6 6 1 0 1 0 0 2M2 + N2 86.4079380 −7s + 6h + p
M6 6 0 0 0 0 0 3M2 86.4079380 −6s + 6h
M SN6 6 1 -2 1 0 0 M2 + S2 + N2 87.4238337 −5s + 4h + p
2M S6 6 2 -2 0 0 0 2M2 + S2 87.9682084 −4s + 4h
2SM6 6 4 -4 0 0 0 2S2 + M2 88.9841042 −2s + 2h
S6 6 6 -6 0 0 0 3S2 90.0000000 0.0
Eighth-diurnal tides (q=8)
M8 8 0 0 0 0 0 4M2 115.9364169 −8s + 8h
2M SN8 8 1 -2 1 0 0 2M2 +S2 +N2 116.4079380 −7s + 6h + p
3M S8 8 2 -2 0 0 0 3M2 + S2 116.9523127 −6s + 6h
2(M S)8 8 4 -4 0 0 0 2M2 + 2S2 117.9682084 −4s + 4h
S8 8 8 -8 0 0 0 4S2 120.0000000 0.0
4.6 Solar radiation

Deriving a suitable expression for the solar radiation flux is not straightfor-
ward in view of its dependence on atmospheric parameters (atmospherical
absorption and reflection, cloud coverage, albedo of the sea surface) whose
influence is difficult to parameterise. The approach, described here, partially
follows Rosati & Miyakoda (1988). The radiation entering at the top of the
atmosphere is given by
Qs = Q0 pcor H(sin γ⊙ ) (4.234)
where Q0 = 1367.0 W/m2 is the solar constant, γ⊙ the altitude of the sun
and H the Heaviside function (H(x) = 0 for x < 0 and = x otherwise). The
factor pcor represents a correction term due to the elliptical orbit of the earth
and is usually expressed as a function of the day number of the year J:
pcor = 1 + 0.03344 cos(J ′ − 2.80 ) (4.235)
J ′ = 0.9856J (4.236)
The altitude of the sun is calculated from
sin γ⊙ = sin φ sin δ⊙ + cos φ cos δ⊙ cos H⊙ (4.237)
where δ⊙ is the declination of the sun, H⊙ the sun’s hour angle and φ the
latitude. The angle δ⊙ , measured in degrees, is obtained from the series
expansion
3
(an cos nJ ′ + bn sin nJ ′ )
X
δ⊙ = δ0 + (4.238)
n=1
with
δ0 = 0.33281
(a1 , a2 , a3 ) = (−22.984, −0.34990, −0.13980)
(b1 , b2 , b3 ) = (3.7872, 0.03205, 0.07187) (4.239)
The sun’s hour angle, measured in hours, is computed by
H⊙ = th − 12 + T E + λh (4.240)
where th is the hour of the day, λh the longitude (expressed in hours) and
T E the equation of time which can be written as
3
(cn cos nJ ′ + dn sin nJ ′ )
X
TE = (4.241)
n=1
4.6. SOLAR RADIATION 95
with
(c1 , c2 , c3 ) = (0.0072, −0.0528, −0.0012)

(d1 , d2 , d3 ) = (−0.1229, −0.1565, −0.0041) (4.242)
Note that th must be given in GMT.

Taking account of absorption by the atmosphere, the direct solar radiation
incident on the ocean surface, is given by
Qdir = Qs e−τ (4.243)
The following form, proposed by Dogniaux (1984a,b), is considered for the

extinction factor
τ = mo δR tL (4.244)
The optical air mass mo , Rayleigh’s optical thickness δR and Linke’s factor
tL are expressed as function of the solar altitude γ⊙ in degrees, according to
δR = (0.9mo + 9.4)−1 (4.245)
tL = 0.021γ⊙ + 3.55 (4.246)

mo = [sin γ⊙ + 0.15(γ⊙ + 3.885)−1.253 ]−1 (4.247)
The formulation, given by (4.245)–(4.247), has the advantage that it does
not diverge at low solar altitudes.
The direct component of solar radiation must be supplemented by the
diffuse sky radiation Qdif . Following Rosati & Miyakoda (1988) it is assumed
that one half of the scattered radiation reaches the ocean surface so that

Qdif = (1 − Aα )Qs − Qdir /2 (4.248)
They considered the value of 0.09 for the water vapor and ozone absorption
coefficient Aα . The total radiation flux at the ocean surface under clear sky
conditions is then given by
1
Qcs = Qdir + Qdif = Qs (e−τ + 1 − Aα ) (4.249)
2
The clear sky value (4.249) must be corrected for cloud coverage and reflec-
tion by the ocean surface. The empirical formula, derived by Reed (1977),
appears to have a better agreement with observational data compared to
other formulations (Katsaros, 1990). The short-wave radiation flux at the
sea surface then finally takes the form
Qrad = Qcs (1 − 0.62fc + 0.0019γ⊙,max )(1 − As ) (4.250)

where γ⊙,max is the solar altitude at noon. A constant value of 0.06 is assumed
for the sea surface albedo As . Variations of the albedo as function of the
solar altitude and atmospheric transmittance have been tested using the
empirical fits derived by Payne (1972). No appreciable difference was found
with the formulation (4.250). The only parameter, which needs to be supplied
externally, is the fractional cloud cover fc also used in the expression (4.263)
for the long-wave radiation flux.
4.7 Surface boundary conditions

4.7.1 General form
Most of the surface boundary conditions discussed in this section are Neu-
mann type conditions for the surface fluxes and can be written into one of
the two following general forms
• A prescribed (upwards) surface flux Fsψ
λψT ∂ψ
= Fsψ (4.251)
h3 ∂s
• A surface flux describing the transfer across the surface

λψT ∂ψ
= Csψ (ψse − ψsi ) (4.252)
h3 ∂s
where Cs is the transfer rate (with the dimension of a velocity) and ψse ,
ψsi are the values of ψ just above and below the surface.
A second form of surface boundary condition is the Dirichlet type where
the value of ψ at the surface or at the first interior grid point is specified.
Examples are the conditions (4.269) for turbulence.
Note that when the model equations are given in depth-averaged mode
(Section 4.3.2), the surface boundary condition enters as an additional flux
(source or sink) term in the transport equations. It is obvious that in that
case only a Neumann flux conditions is allowed.
4.7.2 Currents
The surface condition for the horizontal current is as usual obtained by spec-
ifying the surface stress as function of the wind components
νT ∂u ∂v
ρ0 , = (τs1 , τs2 ) = ρa Cds W10 (U10 , V10 ) (4.253)
h3 ∂s ∂s
4.7. SURFACE BOUNDARY CONDITIONS 97
where (U10 , V10 ) are the components of the wind vector at a reference height
2
of 10 m, W10 = (U10 + V102 )1/2 is the wind speed, ρa = 1.2 kg/m3 the air
density and Cds the surface drag coefficient discussed in Section 4.8. The
boundary condition for the transformed vertical velocity takes the simple
form
ω=0 (4.254)
4.7.3 Temperature
The surface boundary condition for temperature can either be taken as a
Dirichlet condition in which case Ts is specified directly at (or near) the
surface or a Neumann condition in which case the surface flux of temperature
is given as
ρ0 cp ∂T
λT = Qs (4.255)
h3 ∂s
where Qs is the downwards directed heat flux at the surface and cp the
specific heat of seawater at constant pressure. The net total heat flux into
the water column is composed of a term −Qnsol of all non-solar contributions
plus the radiative flux Qrad . Only the former contributes to the surface flux
of temperature, since solar radiance is absorbed within the water column.
The (upwards directed) non-solar heat flux has three components, i.e.
Qnsol = Qla + Qse + Qlw (4.256)
where Qla is the latent heat flux released by evaporation, Qse the sensible heat
flux due to the turbulent transport of temperature across the air/sea interface
and Qlw the net long-wave radiation emitted at the sea surface. The first
two terms are related to the turbulent fluxes of humidity and temperature
Qla = ρa Lν Ce W10 (qs − qa ) (4.257)
Qse = ρa cpa Ch W10 (Ts − Ta ) (4.258)

where Ts , qs and Ta , qa are the temperature and specific humidity at respec-
tively the sea surface and a reference height, usually taken at 10 m, and
cpa = 1004.6(1 + 0.8375qa ) J kg−1 (0 C)−1 (4.259)
the specific heat of air at constant pressure. The latent heat of vaporization
is given as a function of the sea surface temperature
Lν = 2.5008 × 106 − 2300Ts J/kg (4.260)

The sea surface and air humidities qs and qa are calculated using
ǫR e
q= (4.261)
Pa0 − (1 − ǫR )e
where Pa is the atmospheric pressure (in mbar) and ǫR = 0.62197 the ratio of
molecular weight of dry water to dry air. The vapour pressure e is obtained
in mb from the empirical relation (Gill, 1982)
0.7859 + 0.03477T
log10 e = log10 RH + (4.262)
1 + 0.00412T
where RH is the relative humidity (between 0 and 1). In equations (4.261)
and (4.262) the humidity q, the vapour pressure e and the temperature T
(in 0 C) either represent sea surface or atmospheric values at the reference
height. Note that a relative humidity of 100% is taken at the sea surface.
The long-wave radiation flux term is parameterised following Gill (1982):
Qlw = ǫs σrad (Ts + 273.15)4 (0.39 − 0.05e1/2 2
a )(1 − 0.6fc ) (4.263)
where ǫs = 0.985 is the emissivity at the sea surface, σrad = 5.67 × 10−8 W
m−2 K−4 Stefan’s constant, fc the fractional cloud cover (between 0 and 1)
and ea the vapour pressure evaluated by (4.262).
The surface fluxes of momentum and heat involve the surface drag coef-
ficient Cds and two dimensionless parameters Ce , Ch sometimes referred as
the Dalton and Stanton number. Various empirical schemes for these trans-
fer coefficients have been presented in the literature (see e.g. Blanc, 1985;
Geernaert, 1990). A few formulations are available in the program. They are
further discussed in Section 4.8.
Implementation
The type of surface condition for temperature is selected with the switch
iopt temp sbc:
1: Neumann (flux) condition
2: Dirichlet condition at the first grid point below the surface
3: Dirichlet condition at the surface itself
4.7.4 Salinity
The surface salinity flux is determined using the formula given by Steinhorn
(1991):
λT ∂S Ss (Evap − Rpr )
ρ0 = (4.264)
h3 ∂s 1 − 0.001Ss
4.7. SURFACE BOUNDARY CONDITIONS 99
where Evap = Qla /Lν and Rpr are the evaporation and precipitation rates
in kg m−2 s−1 and Ss the surface salinity in PSU. The evaluation of the
surface salinity flux requires the input of precipitation data as an additional
meteorological parameter.
Implementation
The switch iopt sal sbc enables (1) or disables (0) the surface flux condition
(4.264).
4.7.5 Turbulence
The surface boundary conditions for turbulence variables are derived by mak-
ing the “wall”- (or “log”-) layer approximation. The following assumptions
are made
1. The layer is neutrally stratified (N 2 = 0).
2. The shear stress is taken as vertically uniform. Neglecting the Coriolis
force, taking the X-axis along the flow direction and using equation
(4.167) one has
q k 2 ∂U
u2⋆s = 2
τs1 2
+ τs2 = −Su0 = constant (4.265)
ε ∂z
3. The mixing length is proportional to the distance d from the “wall”

boundary as given by equation (4.200):

l = l2 = κds = κ(ζ − z + z0s ) = κ H(1 − σ) + z0s (4.266)
where κ = 0.4 is von Kármàn’s constant and z0s a surface roughness

length.
4. The velocity shear is given by
∂U u⋆ u⋆
=− =− (4.267)
∂z l κds
Integration of this equation gives the familiar linear U versus log z
dependence.
5. Turbulence is assumed to be in equilibrium, i.e.
∂U k 3/2
P = −u2⋆s = ε = ǫ0 (4.268)
∂z κds
From (4.265)–(4.268) the following Dirichlet type surface conditions are de-
rived for the k, ε and kl transport equations
u2⋆s u3⋆s
k= 1/2
, ε= , l = κds (4.269)
Su0 κds
with ds defined through (4.266). The relation

3/4
ǫ0 = Su0 (4.270)
can be readily obtained in addition to the previous relations.

The program allows to use Neumann type condition for k and ε as well.
They are given by
νk ∂k
= cw u3⋆s (4.271)
h3 ∂s
νk ∂ε νk ǫ0 k 3/2
= (4.272)
h3 σε ∂s h3 σε κd2s
The first condition was proposed by Craig & Banner (1994) with cw ∼ 100
and a non-zero surface roughness to represent the energy input of breaking
surface waves. The second one, introduced by Burchard & Petersen (1999),
can be derived from the Dirichlet conditions and has, according to these au-
thors, a better numerical performance for applications with a coarse vertical
resolution. A modification of the flux condition for ε which takes account
of wave breaking, was considered by Burchard (2001) but is currently not
implemented in the code.
Implementation
The surface boundary condition for turbulence are selected by the following
switches:
iopt turb tke sbc Type of condition for k

1: Neumann condition (4.271)
2: Dirichlet condition (4.269)
iopt turb dis sbc Type of condition for ε
4.8. SURFACE DRAG AND EXCHANGE COEFFICIENTS 101
4.7.6 Water column mode

In the water column approximation (Section 4.3.1), the surface slope and
elevations can be prescribed at the surface as the sum of a non-harmonic and
harmonic part
N
e
q0e (t)
X
q (t) = + An fn (t) cos Vn (t) + un (t) − ϕn (4.273)
n=1
where q e represents the external value of ∂ζ/∂x, ∂ζ/∂y or ζ, (fn , un ) are the
nodal amplitude and phase factors, Vn (t) the astronomical phases at Green-
wich and (An , ϕn ) the amplitudes and phases with respect to Greenwich9 .
4.8 Surface drag and exchange coefficients

The values of Cds , CE and CH depend on conditions in the lower atmosphere
and are, in general, functions of W10 , Ta , Ts , RH (relative humidity) and
Pa . Several (mainly empirical) formulations are implemented and can be
divided into neutral schemes, depending on wind speed only, and stratified
ones which take additionally account of at least the effect of the air minus
sea temperature difference.
4.8.1 Neutral formulations

The following formulations for Cds are implemented
0. Constant value. Default value is 0.0013.
1. Large & Pond (1981)
Cds = 0.0012 if W10 ≤ 11m/s

−3
Cds = 10 (0.49 + 0.065W10 ) if W10 > 11m/s (4.274)
2. Smith & Banke (1975)
Cds = 10−3 (0.63 + 0.066W10 ) (4.275)
3. Geernaert et al. (1986)
Cds = 10−3 (0.43 + 0.097W10 ) (4.276)

9
Expression (4.273) is analogous to (4.340) applied at open boundaries.
Table 4.7: Empirical parameters used in the Kondo (1975) formulations for
the neutral surface drag and exchange coefficients.
ad , b d , p d ae , b e , c e , p e ah , b h , c h , p h
W10 < 2.2 0.0, 1.08, -0.15 0.0, 1.23, 0.0, -0.16 0.0, 1.185, 0.0, -0.157
2.2 ≤ W10 < 5 0.771, 0.0858, 1.0 0.969, 0.0521, 0.0, 1.0 0.927, 0.0546, 0.0, 1.0
5 ≤ W10 < 8 0.867, 0.0667, 1.0 1.18, 0.0, 0.0, 1.0 1.15, 0.01, 0.0, 1.0
8 ≤ W10 < 25 1.2, 0.025, 1.0 1.196, 0.008, -0.0004, 1.0 1.17, 0.0075, -0.00045, 1.0
25 ≤ W10 0.0, 0.073, 1.0 1.68, -0.016, 0.0, 1.0 1.652, -0.017, 0.0, 1.0
4. Kondo (1975)
pd
Cds = 10−3 (ad + bd W10 ) (4.277)
where ad , bd and pd are function of wind speed and given in Table 4.7.
5. Wu (1980)
Cds = 0.0012Rw0.15
log10 Rw = 0.137W10 − 0.616 (4.278)
6. Charnock (1955) relation
z0s g/u2∗s = a
κ 2
Cds = (4.279)
ln(z0s /10)
where z0s is the surface roughness length, u∗ the surface friction veloc-
ity and a=0.014 Charnock’s constant. Since u2∗s = Cds W10 2
, equation
(4.279) has to be solved by iteration.
Neutral values for Ce and Ch are obtained from one of the following
schemes.
0. Constant values. Default is 0.0013.
1. Large & Pond (1982)
Ce = 0.00115
Ch = 0.00113 if Ta < Ts
= 0.00066 if Ta ≥ Ts (4.280)
2. Anderson & Smith (1981)

Ce = 10−3 (0.55 + 0.083W10 )
Ch = 0.00112 if Ta < Ts
= 0.00082 if Ta ≥ Ts (4.281)
3. Kondo (1975)

pe
Ce = 10−3 ae + be W10 + ce (W10 − 8)2

ph
Ch = 10−3 ah + bh W10 + ch (W10 − 8)2 (4.282)
where the coefficients ae , ah , be , bh , ce , ch and pe , ph are function of the
wind speed and given in Table 4.7.
4. Wu (1980)
Ce = Ch = 0.001Rw0.11
log10 Rw = 0.137W10 − 0.616 (4.283)
4.8.2 Kondo’s stratified formulation

Kondo (1975) extended the neutral formulation (4.277), (4.282) for stratified
conditions. The method consists in multiplying the neutral values by a factor
depending on the air minus sea temperature difference. The procedure is as
follows
2
R0 = (Ts − Ta )/W10 (4.284)
|R0 |
R = R0 (4.285)
|R0 | + 0.01
In case of stable conditions (Ts < Ta )
f (R) = 0.1 + 0.03R + 0.9e4.8R if − 3.3 < R < 0
f (R) = 0 if R ≤ −3.3 (4.286)
Cds = Cdn f (R), Ce = Cen f (R), Ch = Chn f (R) (4.287)
For unstable conditions (Ts > Ta )
Cds = Cdn (1.0 + 0.47R1/2 )
Ce = Cen (1.0 + 0.63R1/2 )
Ch = Chn (1.0 + 0.63R1/2 ) (4.288)
where Cdn , Cen , Chn are the neutral values in the absence of stratification.
In principle one may choose any of the previous relations for the neutral
coefficients. It is however recommended to use the ones proposed by Kondo
(1975).
4.8.3 Stratified case from Monin-Obukhov theory

The most general way, but also the most complex one, to include stratifica-
tion is based on the Monin-Obukhov similarity theory as described in e.g.
Geernaert (1990); Kantha & Clayson (2000a). Some details of the physical
theory are given here to understand how it is implemented in the program.
The surface values of the momentum, latent and sensible heat fluxes at the
air-sea interface depend on the turbulent structure of the lower atmosphere,
usually called the planetary boundary layer. It is generally assumed that the
fluxes of momentum, heat and specific humidity have nearly constant values
within this layer. Following Monin & Obukhov (1954) the structure of this
layer can be described by means of a velocity scale u∗ (friction velocity), a
temperature scale T∗ and a humidity scale q∗ defined by
u∗ = (hu′ w′ i2 + hv ′ w′ i2 )1/2 (4.289)
u∗ T∗ = −hw′ T ′ i (4.290)
u∗ q∗ = −hw′ q ′ i (4.291)
where (u′ , v ′ , w′ ), T ′ and q ′ are the turbulent fluctuations of the wind velocity,
temperature and humidity, and h i denotes an ensemble average. The vertical
gradient of the wind speed U is written as the ratio of u∗ to a mixing length,
or
∂U u∗
= (4.292)
∂z l
where z is the height above the sea surface. For neutral stratification one
has
l = κz (4.293)
Since l decreases or increases with respect to its neutral value, according as
the stratification is stable or unstable, equation (4.292) can be rewritten in
the more general form
∂U u∗
= φm (4.294)
∂z κz
The dimensionless function φm describes the effect of stratification and is
smaller (or larger) than 1 for unstable (stable) stratification. In a similar
way, the gradients of temperature and relative humidity are given by
∂T T∗
= φh (4.295)
∂z κz
∂q q∗
= φq (4.296)
∂z κz
The functions φm , φh and φq are expressed in terms of the dimensionless

height ξ = z/Lmo with the Monin-Obukhov length Lmo defined by
gκ
L−1
mo = − 3
(hw′ T ′ i + 0.61Tk hw′ q ′ i) (4.297)
T v u∗
where Tk represents the temperature in degrees Kelvin and the virtual tem-
perature Tv is given by
Tv = Tk (1 + 0.61q) (4.298)
Note that ξ > 0 for stable and ξ < 0 for unstable stratification. Based upon
atmospheric measurements (Businger et al., 1971) the following parameteri-
sations are adopted
φm = (1 − αξ)−1/4 for ξ < 0
(4.299)
φm = 1 + βξ for ξ > 0
and
φh = φ2m for ξ < 0
(4.300)
φh = φm for ξ > 0
with α = 16, β = 5, while it is further assumed that φq = φh . Integrating
(4.294)–(4.296) one obtains
u∗ z
U= (ln − ψm ) (4.301)
κ z0U
T∗ z
T − Ts = (ln − ψh ) (4.302)
κ z0T
q∗ z
q − qs = (ln − ψh ) (4.303)
κ z0q
where Z ξ 1 − φm (ξ)
ψm = dξ (4.304)
0 ξ
Z
1 − φh (ξ)
ξ
ψh = dξ (4.305)
0 ξ
The subscript s indicates a quantity evaluated at the sea surface. Expressions
(4.301)–(4.303) are valid for z ≫ z0U , z0T , z0q while it is further assumed
that U ≫ Us . The roughness lengths z0U , z0T and z0q prevent the quantities
becoming too large near the surface. Evaluating the integrals (4.304)–(4.305)
one has
π
ψm = 2 ln(1 + φ−1 −2 −1
m ) + ln(1 + φm ) − 2 arctan(φm ) + 2
− 3 ln 2 for ξ < 0
ψ m = 1 − φm for ξ > 0
(4.306)
and
ψh = 2 ln(1 + φ−1
h ) − 2 ln 2 for ξ < 0
(4.307)
ψ h = 1 − φh for ξ > 0
Parameterisations for u∗ , T∗ , q∗ are given by rewriting (4.301)–(4.303):
z
u2∗ = κ2 (ln − ψm )−2 U 2 = Cds U 2 (4.308)
z0U
z z
u∗ T∗ = κ2 (ln − ψm )−1 (ln − ψh )−1 U (T − Ts ) = Ch U (T − Ts ) (4.309)
z0U z0T
z z
u∗ q∗ = κ2 (ln − ψm )−1 (ln − ψh )−1 U (q − qs ) = Ce U (q − qs ) (4.310)
z0U z0q
where Cds , Ch and Ce are the drag coefficient, the Stanton and the Dalton
numbers. The z-dependence of the coefficients is usually eliminated by eval-
uating them at the standard height z = za = 10 m. Suitable expressions are
required for z0U , z0T , z0q . Parameterisations exist for the roughness length
as function of the wave state (e.g. Janssen, 1991). However, since little infor-
mation is available concerning the form of z0T and z0q , the simpler approach
described in Geernaert (1990) is used. This consists in defining a drag co-
efficient Cdn valid for a neutral stratification. In analogy with (4.308) one
has
−1/2 u∗n z
U = Cdn u∗n = ln (4.311)
κ z0n
where z0n is the value of z0U for neutral conditions. Eliminating z between
(4.308) and (4.311) yields the following relation between Cds and Cdn :
−1/2 z0n
Cds = [Cdn + (ln − ψm )/κ]−2 (4.312)
z0U
Following Charnock (1955) one further assumes that the roughness length
scales with the wind stress or
z0U = au2∗ /g (4.313)
so that
z0U u2 Cds
= 2∗ = (4.314)
z0n u∗n Cdn
Hence
−1/2
Cds = [Cdn + (ln(Cdn /Cds ) − ψm )/κ]−2 (4.315)
The neutral Stanton and Dalton numbers are defined in a similar way
z z −1
Chn = κ2 (ln ln ) (4.316)
z0n z0T
z z −1
Cen = κ2 (ln ln ) (4.317)
z0n z0q
Expressions for Ch and Ce in terms of their neutral counterparts are then
obtained by combining (4.316)–(4.317) with (4.309)–(4.310) (taking z0U ≃
z0n for simplicity) and (4.311). This gives
1/2 −1/2
Ch = Chn [1 − (ψm Cdn + ψh Chn Cdn )/κ + Chn ψm ψh /κ2 ]−1 (4.318)
1/2 −1/2
Ce = Cen [1 − (ψm Cdn + ψh Cen Cdn )/κ + Cen ψm ψh /κ2 ]−1 (4.319)
The neutral coefficients are obtained from one of the formulations given in
Section 4.8.1.
Since the functions ψm and ψh depend on the dimensionless height ξ, a
further equation needs to be added. Eliminating u∗ , T∗ and q∗ in (4.297)
after substituting (4.290)–(4.291), by using (4.308)–(4.310) and evaluating
at the reference height, one has
gκza Ch (Ta − Ts ) + 0.61Tk Ce (qa − qs )
ξ= 2
(4.320)
Tv W10 (Cds )3/2
In summary, the coefficients Cds , Ch and Ce are obtained by solving the
system consisting of the four equations (4.315), (4.318), (4.319) and (4.320)
using an iteration scheme. Input parameters are the wind speed W10 , the air
temperature Ta , the sea surface temperature Ts , the relative humidity RH
and the atmospheric pressure pa . The last two are needed to evaluate qa , qs
through (4.261)–(4.262).
The various schemes introduced in this section are compared in Figure 4.5.
The following observations can be made
• The Smith & Banke (1975) and Charnock (1955) formulations are
highly similar. Larger diferences between the different schemes, up
to a factor 2, are seen for the surface drag coefficient in the case of high
wind speeds.
• Stratification effects measured by the air-sea temperature difference
are important at wind speeds below 10 m/s. A significant decrease
of the exchange coefficients is observed in case of a stable (Ta > Ts )
stratification, whereas the cofficients increase in the unstable (Ta < Ts )
case.
• The Kondo and Monin-Obukhov formulations are qualitatively similar.
• The effect of relative humidity is less significant compared to the one
produced by stratification.
(a) (b)
(c) (d)
Figure 4.5: (a) Surface drag coefficient Cds as function of wind speed accor-
ding to (4.274) (solid), (4.275) (dots), (4.276) (dashes), (4.277) (dash-dots),
(4.278) (dash and 3 dots), (4.279) (long dashes). (b) Surface exchange coeffi-
cient Ce as function of wind speed according to the Kondo (1975) formulation
and ∆T =Ta −Ts =00 C (solid), -50 C (dots), -2.50 C (dashes), 2.50 C (dash-dots),
50 C (dash and 3 dots). (c) Surface exchange coefficient Ce as function of wind
speed according to Monin-Obukhov theory, using RH=75%, Ts =120 C and
∆T =Ta − Ts =00 C (solid), -50 C (dots), -2.50 C (dashes), 2.50 C (dash-dots),
50 C (dash and 3 dots). (d) Surface exchange coefficient Ce as function of
wind speed according to Monin-Obukhov theory, using Ta =Ts =120 C and
RH=100% (solid), 90% (dots), 80% (dashes), 70% (dash-dots), 60% (dash
and 3 dots), 50% (long dashes).
4.9. BOTTOM BOUNDARY CONDITIONS 109
Implementation
Evaluation of the surface drag and exchange coefficients is selected with the
following switches
iopt sflux cds Formulation for the neutral surface drag coefficient Cds .
0 : constant value as given by the parameter cds cst

1 : equation (4.274) from Large & Pond (1981)
2 : equation (4.275) from Smith & Banke (1975)
3 : equation (4.276) from Geernaert et al. (1986)
4 : equation (4.277) from Kondo (1975)
5 : equation (4.278) from Wu (1980)
6 : equation (4.279) from Charnock (1955)
iopt sflux cehs Formulation for the neutral surface (heat) exchange coeffi-
cients Ce , Ch .
0 : constant value as given by the parameter ces cst or chs cst

2 : equation (4.281) from Anderson & Smith (1981)
3 : equation (4.282 from Kondo (1975)
iopt sflux strat Selects dependence of the surface drag and exchange coeffi-
cients on atmospheric stratification effects.
0 : no dependence
1 : using the Kondo (1975) parameterisation (Section 4.8.2)
2 : using Monin-Obukhov similarity theory (Section 4.8.3)
4.9 Bottom boundary conditions

4.9.1 General form
In analogy with Section 4.7.1 most of the bottom boundary conditions are
flux (Neumann type) conditions and can be written into one of the two
following general forms
• A prescribed (upwards) bottom flux Fbψ
λψT ∂ψ
= Fbψ (4.321)
h3 ∂s
• A bottom flux describing the transfer across the sea bed
λψT ∂ψ
= Cbψ (ψbi − ψbe ) (4.322)
h3 ∂s
where Cbψ is the transfer rate (with the dimension of a velocity) and
ψbe , ψbi are the values of ψ just below and above the sea bed.
For example, the bottom conditions (4.324) and (4.328) for u and v are
of the form (4.322) with
Cbu = Cbv = Cdb (u2b + vb2 )1/2 , ueb = vbe = 0 (4.323)
An alternative form is a Dirichlet boundary condition where the value of

ψ at the bottom or the first interior point is specified. Examples are the
conditions (4.337) for turbulence.
Note that when the model equations are given in depth-averaged mode
(Section 4.3.2), the bottom boundary condition enters as an additional flux
(source or sink) term in the transport equations. It is obvious that in that
case only a Neumann flux condition is allowed.
4.9.2 Currents
A slip boundary condition is applied for the horizontal current at the bottom
which takes the form
νT ∂u ∂v
, = (τb1 , τb2 ) (4.324)
h3 ∂s ∂s
The following formulations have been implemented
• zero stress condition

(τb1 , τb2 ) = (0, 0) (4.325)
• linear friction law, either in 3-D as in 2-D mode
(τb1 , τb2 ) = klin (ub , vb ) (4.326)
or
(τb1 , τb2 ) = klin (u, v) (4.327)
4.9. BOTTOM BOUNDARY CONDITIONS 111
• quadratic friction law, either in 3-D as in 2-D mode
(τb1 , τb2 ) = Cdb (u2b + vb2 )1/2 (ub , vb ) (4.328)
or
(τb1 , τb2 ) = Cdb (u2 + v 2 )1/2 (u, v) (4.329)
where the bottom currents (ub , vb ) are evaluated at the grid point nearest
to the bottom and (u,v) are the depth-mean currents. A constant value is
taken for the linear friction coefficient klin .
In the boundary layer approximation a vertically uniform shear stress is
assumed yielding a logarithmic profile for the current. The quadratic bottom
drag coefficient can then be expressed as a function of the roughness length
z0 and the vertical grid spacing. This gives
2
Cdb = κ/ ln(zr /z0 ) (4.330)
where zr is a reference height taken at the grid centre of the bottom cell.
The value of z0 which may vary in the horizontal directions, depends on
the geometry and composition of the seabed. Values of z0 , measured from
logarithmic current profiles can be found in Heathershaw (1981); Soulsby
(1983) for various bed type forms. Note that (4.330) can only be applied
when the program is used in 3-D mode. For purely 2-D mode applications
Cdb has to be defined externally by the user.
It is clear that in case of an application in depth-averaged (2-D) mode,
the only allowed formulations for the bottom stress are (4.327) and (4.329).
In analogy with the surface condition (4.254) the bottom value of the
transformed vertical velocity equals zero, i.e.
ω=0 (4.331)
Implementation
Evaluation of the bottom stress is controlled by the following switches
iopt bstres form Type of bottom stress formulation

0: Zero bottom stress
1: Linear friction law
2: Quadratic friction law
iopt bstres nodim Type of currents used in the bottom stress formulation
2: Depth mean currents
3: 3-D current at the bottom grid cell

iopt bstres drag Type of formulation for Cdb
0: Set to zero
1: Constant prescribed value
2: Prescribed horizontally non-uniform value
3: Using (4.330) and a constant roughness length
4: Using (4.330) and a spatially dependent roughness length
4.9.3 Temperature and salinity

The bottom boundary conditions for temperature and salinity are obtained
by considering a zero flux normal to the seabed:
λT ∂T λT ∂S
=0, =0 (4.332)
h3 ∂s h3 ∂s
A similar assumption is applied for the absorption term in the temperature
equation (4.36) where solar radiance I is set to zero at the sea bottom.
It is remarked that the non-allowance of any heat exchange at the bottom
interface may not be realistic but is only imposed in the absence of a useful
parameterisation which takes account of a bottom exchange (e.g. release of
geothermal energy).
4.9.4 Turbulence
The bottom boundary conditions are obtained using the same boundary layer
assumptions as for the surface case. Equations (4.265)–(4.268) are replaced
by equations (4.333)–(4.336) below. The bottom friction velocity is defined
by
q k 2 ∂U
u2⋆b = τb1
2 2
+ τb2 = Su0 = constant (4.333)
ε ∂z
The mixing length is proportional to the distance db from the “wall” boun-
dary as given by equation (4.200):

l = l1 = κdb = κ(h + z + z0b ) = κ Hσ + z0b (4.334)
where is z0b a bottom roughness length.

∂U u⋆b u⋆b
= = (4.335)
∂z l κdb
4.10. LATERAL BOUNDARY CONDITIONS 113
∂U k 3/2
P = u2⋆b = ε = ǫ0 (4.336)
∂z κdb
The following Dirichlet conditions are derived from the previous equations
u2⋆b u3⋆b
k= 1/2
, ε= , l = κdb (4.337)
Su0 κdb
In analogy with the surface case the conditions for k and ε can be replaced
by conditions for the bottom flux
νk ∂k
= 0 (4.338)
h3 ∂s
νk ∂ε νk ǫ0 k 3/2
= (4.339)
h3 σε ∂s h3 σε κd2b
The first condition states that there is no energy flux across the bottom.
Implementation
Bottom boundary condition for turbulence are selected by the following
switches:
iopt turb tke bbc Type of condition for k

iopt turb dis bbc Type of condition for ε
4.10 Lateral boundary conditions

4.10.1 Open boundary conditions for the 2-D mode
The model uses a Arakawa C-grid (see Section 5.2). The 2-D mode equations
contain the three unknown variables U , V and ζ. The surface elevation
is obtained from the continuity equation which does not explicitly require
knowledge of ζ at the open boundaries. This means that open boundary
conditions only need to be supplied for the transports U and V . However, a
robust scheme needs to take account of the information entering or leaving
the domain which involves all three parameters and should therefore include
ζ as well.
The implemented schemes can be divided in four categories10 :
1. Conditions without externally imposed values for transports and ele-

vations (0,1,2,5,6,7,10,13).
2. Conditions with imposed elevations (3,9,12). An “external” value for

the transport is obtained by solving a local solution of the momentum
equations.
3. Conditions with imposed transports (4).
4. Conditions with specified transports and elevations (8,11).
External values (U e , V e , ζ e ) are expressed as the sum of a non-harmonic and

an harmonic part
N
e
ψ0e (ξ1 , ξ2 , t) +
X
ψ (ξ1 , ξ2 , t) = An (ξ1 , ξ2 )fn (t) cos Vn (t) + un (t) − ϕn (ξ1 , ξ2 )
n=1
(4.340)
where ψ0e
represents the non-harmonic part, fn , un are the nodal amplitude
and phase factors, Vn (t) the astronomical phases at Greenwich and An , ϕn
the space-dependent amplitudes and phases with respect to Greenwich at
the open boundaries. The Greenwich phases and nodal factors are space-
independent and obtained as function of time using the theory discussed in
Section 4.5. The amplitudes An and phases ϕn are constant in time but non-
uniform in space and needed to determine the harmonic input at the open
boundaries. The function ψ0e depends on space and time. Values for An , ϕn
and ψ0e need to be supplied by the user.
Variations in atmospheric pressure cause a displacement of the sea level.
On the other hand, when an external surface elevation is specified, usually in
the form of an harmonic expansion, the harmonic amplitudes are obtained
with respect to a reference atmospheric pressure Pref . To take account of
this “inverse barometer” an (optionally) correction term is added to ζ e , i.e.
ζ e = expression (4.340) + (Pref − Pa )/(gρ0 ) (4.341)
A relaxation condition can (optionally) be applied for all exterior 2-D

data (transports and elevation) in case the model is set up with the default
10
The numbers in parentheses refer to the numbering of the descriptions below.
initial conditions (zero transports and elevations). In that case the exterior
data function ψ e (ξ1 , ξ2 , t) is multiplied by the factor
αr (t) = min((t − t0 )/Tr , 1) (4.342)
where Tr is the relaxation period and t0 the initial time. The method avoids
the development of discontinuities during the initial propagation of (e.g.) a
tidal wave into the domain.
All available schemes for 2-D open boundary conditions are briefly des-
cribed below. Details are not given but can be found in the appropriate
references. Comparison of different schemes are discussed in e.g. Palma &
Matano (1998); Jensen (1998); Røed & Cooper (1987). Note that the con-
ditions are applied after solving the 2-D mode equations for U , V , ζ at all
interior points.
The following notations are adopted
• ± or ∓: upper (lower) sign applies at western/southern (eastern/northern)
boundaries
√
• the gravity wave speed c is defined by c = gH
• s equals 1 if ζ e is defined at an exterior node or 2 if ζ e is defined at the
open boundary (U- or V-) node
0. Clamped.
The transports are uniform in time and determined by the initial con-
ditions.
∂U ∂V
=0, =0 (4.343)
∂t ∂t
This is the default condition.
1. Zero slope.
The 2-D momentum equations are solved without surface slope, advec-
tion, horizontal diffusion, pressure gradient and astronomical force.
∂U ∂V
= f V + HF1t + τs1 − τb1 , = −f U + HF2t + τs2 − τb2 (4.344)
∂t ∂t
2. Zero volume flux.
This is a reflective boundary condition whereby the transport is set
equal to its nearest interior value.
∂U ∂V
=0, =0 (4.345)
∂ξ1 ∂ξ2
3. Specified elevation.
The 2-D momentum equations are solved without advection, horizontal
diffusion, atmospheric and baroclinic pressure gradient.
∂U c2 ∂ζ
= − + f V + HF1t + τs1 − τb1
∂t h1 ∂ξ1
∂V c2 ∂ζ
= − − f U + HF2t + τs2 − τb2 (4.346)
∂t h2 ∂ξ2
The slope term is calculated by the spatial difference of the specified ζ

value, either at the open boundary or outside the model grid, and its
nearest interior value. The solutions are called “local” since all other
horizontal gradient are suppressed. This condition is the easiest to use
if ζ is the only available data parameter.
4. Specified transport.
U = Ue , V =Ve (4.347)
This is the simplest and most appropriate condition to be used at river
boundaries.
5. Radiation condition using the shallow water wave speed.

Several types of radiation conditions, which allow the propagation of
waves approaching the open boundary, are implemented. Oblique waves
are not considered so that a normal incidence on the boundary is as-
sumed. The methods use a Sommerfeld type of equation of the form
∂ψ C ∂ψ
∓ =0 (4.348)
∂t hi ∂ξi
where C is an appropriate wave speed. The first condition uses the

surface gravity wave speed for shallow water
∂U c ∂U ∂V c ∂V
∓ =0, ∓ =0 (4.349)
∂t h1 ∂ξ1 ∂t h2 ∂ξ2
6. Orlanski (1976) condition.

This is the most popular radiation scheme using
∂ψ/∂t
C = cr = h i (4.350)
∂ψ/∂ξi
so that
!
∂U cr ∂U ∂U . 1 ∂U
∓ = 0, cr = ±
∂t h1 ∂ξ1 ∂t h1 ∂ξ1
!
∂V cr ∂V ∂V . 1 ∂V
∓ = 0, cr = ± (4.351)
∂t h2 ∂ξ2 ∂t h2 ∂ξ2
The numerical implementation (further discussed in Section 5.3.15.1)

involves the values from two previous time steps and at the nearest two
interior grid points.
7. Camerlengo & O’Brien (1980).

The scheme is a mixture of the clamped and zero flux condition and
can be considered as a simplified case of the Orlanski condition. Details
are given in Section 5.3.15.1.
8. Flather (1976) with specified elevation and transport.

This is based on (4.349) combined with the continuity equation using
only the volume flux normal to the open boundary. The condition then
requires that U ± cζ or V ± cζ is continuous across the boundary or
1 1
U = U e ∓ sc(ζ − ζ e ) , V = V e ∓ sc(ζ − ζ e ) (4.352)
2 2
9. Flather with specified elevation.

The formulation is the same as (4.352) with U e , V e replaced by the
local solutions U L , V L obtained by solving (4.346)
1 1
U = U L ∓ sc(ζ − ζ e ) , V = V L ∓ sc(ζ − ζ e ) (4.353)
2 2
10. Røed & Smedstad (1984).

The condition is the same as Flather’s condition but with all specified
exterior values replaced by local solutions
U = U L ∓ c(ζ − ζ L ) , V = V L ∓ c(ζ − ζ L ) (4.354)
where
∂ζ L 1 ∂ ∂ζ L 1 ∂
=− (h1 V ) , =− (h2 U ) (4.355)
∂t h1 h2 ∂ξ2 ∂t h1 h2 ∂ξ1
and U L , V L are obtained from (4.346) using ζ L .

11. Characteristic method with specified elevation and transport.

The method is perhaps the most robust, but also the most complex one.
The scheme is based on the theory of characteristics. The principle is
to determine which information propagates into or out of the domain.
The former is calculated using external data, the latter from the model
equations. The method is discussed in Hedstrom (1979); Hirsch (1990)
and applied in modified form to a barotropic ocean model by Røed &
Cooper (1987).
The characteristic variables are defined by
u v
R± = U ± cζ or R± = V ± cζ (4.356)
u u u u
At a western (eastern) boundary R− (R+ ) is the outgoing and R+ (R− )
u u
the incoming characteristic. Let Ri = U ± cζ, Ro = U ∓ cζ denote the
incoming and outgoing characteristics at a western or eastern boundary
and Riv = V ± cζ, Rov = V ∓ cζ their counterparts at a southern
or northern boundary. The outgoing characteristics are obtained by
solving
∂Rou c ∂Rou
!
c ∂ ∂h2
∓ =± (h1 V ) + U + f V + HF1t + τs1 − τb1
∂t h1 ∂ξ1 h1 h2 ∂ξ2 ∂ξ1
(4.357)
and
∂Rov c ∂Rov
!
c ∂ ∂h1
∓ =± (h2 U ) + V − f U + HF2t + τs2 − τb2
∂t h2 ∂ξ2 h1 h2 ∂ξ1 ∂ξ2
(4.358)
The equations are obtained by adding the continuity equation (4.74),
multiplied by ∓c, to the two momentum equations (4.75)–(4.76), where
(for convenience) the advective and horizontal diffusion terms, the baro-
clinic and atmospheric pressure gradient are neglected. These equations
are solved using values of the involved parameters evaluated inside the
domain.
The incoming characteristic is prescribed by
Riu = U e ± cζ e , Riv = V e ± cζ e (4.359)
The transports are then obtained by

1 1
U = (Riu + Rou ) , V = (Riv + Rov ) (4.360)
2 2
12. Characteristic method with specified elevation.

The method is as previous with U e , V e replaced by the local solution
U L , V L from (4.346).
13. Characteristic method using a zero normal gradient.

Following Røed & Cooper (1987) the incoming characteristic is, in
the absence of available data, obtained from (4.357) or (4.358) with
∂Riu /∂ξ1 = 0 or ∂Riv /∂ξ2 = 0. This gives
∂Riu
!
c ∂ ∂h2
=∓ (h1 V ) + U + f V + HF1t + τs1 − τb1 (4.361)
∂t h1 h2 ∂ξ2 ∂ξ1
∂Riv
!
c ∂ ∂h1
=∓ (h2 U ) + V − f U + HF2t + τs2 − τb2 (4.362)
∂t h1 h2 ∂ξ1 ∂ξ2
4.10.2 Open boundary conditions for the 3-D mode

4.10.2.1 baroclinic currents
Since U and V are obtained from the 2-D open boundary conditions, only
their baroclinic parts δu = U −u/H and δv = V −v/H need to be determined.
The following conditions can be selected
0. Zero gradient.
1 ∂ 1 ∂
(h2 h3 δu) = 0 , (h1 h3 δv) = 0 (4.363)
h1 ∂ξ1 h2 ∂ξ2
1. Specified external profile.
δu = δue , δv = δv e (4.364)
2. Second order gradient condition. In case of ragged open boundaries the

(first order) zero gradient condition may yield spurious discontinuities
of the vertical current at the first interior node. The effect is reduced
when using the second order condition
1 ∂ h 1 ∂ i 1 ∂ h 1 ∂ i
(h2 h3 δu) = 0 , (h1 h3 δv) = 0
h1 ∂ξ1 h1 h2 ∂ξ1 h2 ∂ξ2 h1 h2 ∂ξ2
(4.365)
at respectively U- and V-node open boundaries.
3. Local solution. The equation is derived from the 3-D and 2-D momen-
tum equations without advection and horizontal diffusion:
1 ∂ b F1b 1 ∂ νT ∂δu τb1 − τs1

(h3 δu) − 2Ω sin φδv = F1 − + +
h3 ∂t H h3 ∂s h3 ∂s H
(4.366)
at U-nodes and
1 ∂ Fb 1 ∂ νT ∂δv τb2 − τs2

(h3 δv) + 2Ω sin φδu = F2b − 2 + +
h3 ∂t H h3 ∂s h3 ∂s H
(4.367)
at V-node open boundaries. The diffusive fluxes at the surface and
bottom are determined by respectively (4.253) and (4.324) with u, v,
replaced by δu, δv.
4. Radiation condition using the baroclinic wave speed.

∂δu 1 ∂δu ∂δv 1 ∂δv
∓ ci =0, ∓ ci =0 (4.368)
∂t h1 ∂ξ1 ∂t h2 ∂ξ2
The baroclinic wave speed ci is generally unknown and has to be spec-
ified by the user.
5. Orlanski condition.
!
∂δu 1 ∂δu ∂δu ∂δu
∓ cr = 0, cr = ± / h1
∂t h1 ∂ξ1 ∂t ∂ξ1
!
∂δv 1 ∂δv ∂δv ∂δv
∓ cr = 0, cr = ± / h2 (4.369)
∂t h2 ∂ξ2 ∂t ∂ξ2
4.10.2.2 3-D scalars

Open boundary conditions are needed for calculation of the horizontal ad-
vective fluxes inside the domain.
0. Zero gradient.
1 ∂ 1 ∂
(h2 h3 ψ) = 0 , (h1 h3 ψ) = 0 (4.370)
h1 ∂ξ1 h2 ∂ξ2
1. Specified external profile.

ψ = ψe (4.371)
∂ψ 1 ∂ψ ∂ψ 1 ∂ψ
∓ ci =0, ∓ ci =0 (4.372)
∂t h1 ∂ξ1 ∂t h2 ∂ξ2
The baroclinic wave speed ci is generally unknown and has to be spec-

ified by the user.
3. Orlanski condition.
!
∂ψ 1 ∂ψ ∂ψ ∂ψ
∓ cr = 0, cr = ± / h 1
∂t h1 ∂ξ1 ∂t ∂ξ1
!
∂ψ 1 ∂ψ ∂ψ ∂ψ
∓ cr = 0, cr = ± / h 2 (4.373)
∂t h2 ∂ξ2 ∂t ∂ξ2
4.10.2.3 turbulence variables

Advection of turbulence is considered of minor importance and has been
disabled by default. The only available open boundary condition for k, ε or
kl therefore consists of a zero gradient condition.
4.10.3 Relaxation conditions

A known problem with open boundary conditions is that the imposed value
of a quantity at the open boundary is not always compatible with its value
calculated by the model inside. For example, the thermocline depth obtained
from an imposed vertical profile of temperature may be different from the
one calculated by the model just inside the domain, creating unrealistic dis-
continuities. A known solution is the creation of a sponge layer near the open
boundaries where the calculated interior solution is allowed to relax towards
its value imposed at the open boundary.
The method implemented in the program is the flow relaxation scheme
proposed by Martinsen & Engedahl (1987). A relaxation zone is defined near
the open boundary where the value of a model quantity ψ is written as
ψi = αψe + (1 − α)ψ̃i (4.374)
where ψe is the open boundary value, ψ̃i the calculated interior value, prior
to relaxation, and α a weighting factor which varies between 1 at the open
boundary and 0 at the inner edge of the relaxation zone. Martinsen & En-
gedahl (1987) showed for a simplified case that the procedure is equivalent
to add a relaxation term α(ψ − ψe )/∆t/(1 − α) to the right hand side of the
transport equation where ∆t is the model time step. In this way, ψ relaxes
to its open boundary value if α → 1 and to the internal solution if α → 0.
The method can be applied in the program for temperature, salinity and
baroclinic currents, but is not implemented for the 2-D mode. The following
interpolation schemes can be selected
1. linear
d
α=1− (4.375)
D
2. quadratic
d 2
α= 1− (4.376)
D
3. hyperbolic
d
α = 1 − tanh (4.377)
2∆h
where d is the distance to the boundary, D the width of the relaxation
zone and ∆h the grid spacing. Note that the interpolation assumes a
uniform grid spacing within the relaxation zone.
4.10.4 Coastal boundaries

At coastal boundaries currents and fluxes of of scalars are set to zero, or
U = 0, δu = 0 , uψ = 0 (4.378)
at western and eastern boundaries, and
V = 0, δv = 0 , vψ = 0 (4.379)
at southern and northern boundaries.
4.11 Initial conditions

The default initial conditions are
• 2-D hydrodynamics
U = 0, V = 0, ζ=0 (4.380)
• 3-D hydrodynamics
u=v=0 (4.381)
4.12. HARMONIC ANALYSIS 123
• scalars
T = Tref , S = Sref (4.382)
where Tref , Sref are uniform values selected by the user. These are also
the values taken over time if iopt temp=0 or iopt sal=0.
• turbulence
k = 10−6 J/kg (4.383)
for turbulent energy while l is obtained from one of the mixing length
prescriptions given in Section 4.4.3.5 and ε from (4.191).
Although the initial conditions for turbulence cannot be considered as re-

alistic, they are of lesser importance since turbulence is assumed to be in
quasi-equilibrium and adjusts itself rapidly to changes in the forcing condi-
tions, given by the vertical current shear and stratification. It is clear that
realistic initial conditions cannot be given in general. In practice, they need
to be obtained by the user.
4.12 Harmonic analysis

4.12.1 Residuals, amplitudes and phases
The program offers the possibility to apply an harmonic analysis on a given
number of user-defined quantities. The method is closely related to the one
described in Godin (1972). An harmonic expansion approximates a function
F (ξ1 , ξ2 , σ, t) by a series of the form
Nh
X Nh
X
F (ξ1 , ξ2 , σ, t) = a0 + an cos ωn (t − tc ) + bn sin ωn (t − tc ) (4.384)
n=1 n=1
where a0 , an and bn are spatially dependent parameters obtained with an

optimisation procedure, ωn are a series of user-defined frequencies, Nh the
number of harmonics in the analysis, tc a “central” time and t the time
since the start of the simulation. The procedure uses a least-squares fitting.
Firstly, the time tc and a period T for the analysis, given by an even number
of time steps11 , i.e. T = 2M ∆t, are defined. Secondly, the program evaluates
the values of F at times tc + k∆t with −M ≤ k ≤ M , denoted by
Fk = F (ξ1 , ξ2 , σ, tc + k∆t) (4.385)

11
Note that ∆t equals the time step for the 3-D mode calculations.
The harmonic parameters a0 , an and bn are then determined by minimising

the quantity
M Nh Nh
bn sin(ωn k∆t)]2
X X X
R= [Fk − a0 − an cos(ωn k∆t) − (4.386)
k=−M n=1 n=1
Setting the first derivatives of R with respect to a0 , am and bm (1 ≤ m ≤ Nh )

equal to zero yields the following set of 2Nh + 1 equations
M
X Nh
X Nh
X
[Fk − a0 − an cos(ωn k∆t) − bn sin(ωn k∆t)] = 0 (4.387)
k=−M n=1 n=1
M
X Nh
X Nh
X
[Fk − a0 − an cos(ωn k∆t) − bn sin(ωn k∆t)] cos(ωm k∆t) = 0
k=−M n=1 n=1
(4.388)
M
X Nh
X Nh
X
[Fk − a0 − an cos(ωn k∆t) − bn sin(ωn k∆t)] sin(ωm k∆t) = 0
k=−M n=1 n=1
(4.389)
with 1 ≤ m ≤ Nh . The system can be simplified with the aid of known sum-
mation rules for trigonometric functions (see Gradshteyn & Ryzhik, 1981).
The final result can be written as
Nh
X
Xmn an = Rm (4.390)
n=1
Nh
X
Ymn bn = Sm (4.391)
n=1
M Nh
1 h X X 2M + 1 ωn ∆t i
a0 = Fk − an sin( ωn ∆t) csc( ) (4.392)
2M + 1 k=−M n=1 2 2
where
1 2M + 1 ∆t
Xmn = sin (ωm + ωn )∆t csc (ωm + ωn )
2 2 2
1 2M + 1 ∆t
+ sin (ωm − ωn )∆t) csc (ωm − ωn )
2 2 2
1 2M + 1 ωm ∆t 2M + 1 ωn ∆t
− sin( ωm ∆t) csc( ) sin( ωn ∆t) csc( )
2M + 1 2 2 2 2
(4.393)
1 2M + 1 ∆t
Ymn = sin (ωm − ωn )∆t csc (ωm − ωn )
2 2 2
1 2M + 1 ∆t
− sin (ωm + ωn )∆t csc (ωm + ωn ) (4.394)
2 2 2
M M
X 1 2M + 1 ωm ∆t X
Rm = Fk cos(ωm k∆t) − sin( ωm ∆t) csc( ) Fk
k=−M 2M + 1 2 2 k=−M
(4.395)
M
X
Sm = Fk sin(ωm k∆t) (4.396)
k=−M
The following replacements need to be made at singular points of the csc

(cosecans) functions:
2M + 1 ω ∆t
∗
sin ω∗ ∆t csc → 2M + 1 if mod(ω∗ ∆t, 2π) = 0 (4.397)
2 2
where ω∗ equals either ωm , ωn , ωm + ωn , ωm − ωn . The matrices X and Y
are symmetric and depend only on the values of the frequencies, the time
step and the analysed period and can thus be evaluated at the start of the
program. The numerical solution of the linear system (4.390) and (4.391) is
facilitated by first performing a Cholesky decomposition on the matrices X
and Y , which only needs to be performed once. This reduces the number of
arithmetic operations and computing time since the systems are to be solved
at a number of selected grid points and for a given number of user-defined
quantities. Details of the numerical procedure are described in Press et al.
(1992).
Once the parameters a0 , an and bn are determined, the harmonic expan-
sion (4.384) is written into the form
Nh
X
F (ξ1 , ξ2 , σ, t) = A0 + An cos(ωn (t − tc ) − ϕnc ) (4.398)
n=1
where the residual A0 , the amplitudes An and the phases ϕnc (with respect
to the central time tc ) are obtained from
A0 = a0 , An = (a2n + b2n )1/2 , ϕnc = mod(arctan(bn /an ), 2π) (4.399)
The actual phase ϕn can be obtained in the program with respect to either
1. the central time

ϕn = ϕnc (4.400)
2. the astronomical Greenwich phase. Letting
ϕn = ϕnc + Vn (tc ) + un (tc ) (4.401)
One has
ωn (t − tc ) − ϕnc ≃ Vn (t) + un (t) − ϕn (4.402)
3. a given reference date defined by
tref = t + ∆ref (4.403)
where ∆ref is time difference between the initial date of the simulation
and the reference date. Letting
ϕn = ϕnc − ωn (tc + ∆ref ) (4.404)
one obtains
ωn (t − tc ) − ϕnc = ωn tref − ϕn (4.405)
Important to note is that the number and values of the frequencies ωn

used in the harmonic analysis do not need to be the same as the ones ap-
pearing in the tidal forcing, as given by the harmonic expansions (4.218) or
(4.340). For example, if the model is forced with the M2 -tide only, higher
order harmonics (M4 , M6 , . . . ) are generated by the non-linearities of the
model equations. These higher order terms can be investigated by applying
an harmonic analysis. The method can be also used to analyse the evolution
of a M2 -tide during a spring-neaps cycle, e.g. by forcing the model with a
M2 - and S2 -tide and performing the analysis with only the M2 -frequency at
different times t = tc , tc + T , . . . (e.g. Luyten, 1997). Luyten et al. (2003)
applied the same procedure for the analysis of internal waves in the North
Sea.
The period T needs to be selected with some care. A general rule is
that it must be of the same order or larger than any of the analysed periods
2π/ωn and must increase with the number of frequencies. A more stringent
restriction is imposed if two freqiencies ωi and ωj are nearly equal to avoid
aliasing effects, in which case T should larger than 2π/|ωi − ωj |.
4.12.2 Tidal ellipses

During the course of a tidal cycle the current vector describes a curve, known
as the “tidal ellipse”. Characteristic parameters of tidal ellipses are the semi-
major axis, semi-minor axis, ellipticity, orientation and elliptic angle. They
can optionally be derived by the program in the usual way (e.g. Godin, 1972)
once the harmonic parameters of the current are available using the analysis
of the preceding section. The “nth” harmonic component of the horizontal
current can be written as
un = uan cos(ωn t − ϕnu ) , vn = van cos(ωn t − ϕnv ) (4.406)
Introducing the complex notation
U = ua e−iϕu , V = va e−iϕv (4.407)
where the subscript n has been omitted for simplicity, the complex current
can then be decomposed into a cyclonically and an anticyclonically rotating
component
1 i
u + iv = (U eiωt + Ũ e−iωt ) + (V eiωt + Ṽ e−iωt )
2 2
iωt −iωt
= S+ e + S̃− e (4.408)
where a ˜denotes the complex conjugate and

1
S± = (U ± iV ) = |S± |eiα± (4.409)
2
The semi-major axis A, semi-minor axis B and ellipticity e of the ellipse,
described by the current, are then given by
A = |S+ | + |S− | , B = ||S+ | − |S− || , e = (|S+ | − |S− |)/(|S+ | + |S− |) (4.410)
The inclination Θ of the ellipse with respect to the ξ1 -axis and the elliptic
angle Φ, i.e. the angle between the initial current at t = 0 and its position
when the current achieves its first maximum, are obtained using
Θ = (α+ − α− )/2 , Φ = −(α+ + α− )/2 (4.411)
with the restriction that

0 ≤ Θ, Φ ≤ π (4.412)
The orientation of the ellipse is determined by the sign of the ellipticity. A
positive value of e means that the current vector rotates cyclonically (anti-
clockwise in the northern hemisphere) and |S+ | > |S− | whereas a negative
value indicates anticyclonic rotation (clockwise in the northern hemisphere)
and |S+ | < |S− |. If e = 0, the flow is rectilinear and |S+ | = |S− |. A useful
discussion of cyclonic and anticyclonic components and their impact on the
depth of the tidal bottom layer can be found in e.g. Prandle (1982); Soulsby
(1983); Luyten (1996).
Implementation
The following switches are available for harmonic analysis
iopt out anal Switch to enable (1) or disable (0) harmonic analysis
iopt astro anal If iopt astro anal=1 and cdate timeref is not defined, the har-
monic phases ϕn are calculated with respect to the astronom-
ical phase at Greenwich. Otherwise the phases are obtained
with respect to a given reference date or to the central time,
depending on whether cdate timeref is defined or not (see Sec-
tion 16.3.1).
Chapter 5
Numerical methods
5.1 Introduction
The numerical methods described in this chapter are based to a large extent
upon previous work described in the COHERENS V1 manual (Luyten et al.,
1999).
Conservative finite differences (equivalent to a finite volume technique for
the Cartesian mesh) are used to discretise the mathematical model in space.
The grid chosen for horizontal discretisation is the well known Arakawa
“C” grid (Mesinger & Arakawa, 1976) which staggers the currents and pres-
sure/elevation nodes to give a good representation of the crucial gravity waves
and provides simple representations of open and coastal boundaries. As dis-
cussed in Section 4.1 the model equations are solved on a rectangular or
curvilinear grid in the horizontal and a σ- or extended σ-coordinate grid in
the vertical, whereby varying surface and bottom boundaries are transformed
into constant surfaces. This provides for accurate representation of surface
and bottom boundary processes. It also results in an equal number of cells
in each vertical water column.
The momentum equations are solved with the mode-splitting technique
as in the model of Blumberg & Mellor (1987). The method consists in solving
the depth-integrated momentum and continuity equations for the “external”
or barotropic mode with a small time step to satisfy the stringent CFL sta-
bility criterium for surface gravity waves, and the 3-D momentum and scalar
transport equations for the “internal” or “baroclinic” mode with a larger time
step. A “predictor” and a “corrector” step are applied for the horizontal mo-
mentum equations to satisfy the basic requirement that the depth-integrated
currents obtained from the the 2-D and 3-D mode equations, have identical
values.
129
130 CHAPTER 5. NUMERICAL METHODS
Much effort has been made to implement suitable schemes for the advec-
tion of momentum and scalars. A variety of schemes are available from the lit-
erature, e.g. second and higher order central and upwind schemes (see Hirsch,
1990, for a review), Flux Corrected Transport (FCT; Boris & Book, 1979),
Total Variation Diminishing (TVD; Roe, 1986; Sweby, 1984), Quadratic Up-
stream Interpolation for Convective Kinematics (QUICK; Leonard, 1979),
Second Order Moments (SOM; Prather, 1986; Hofmann & Maqueda, 2006),
Piecewise Parabolic Method (PPM; Colella & Woodward, 1984; James, 1996).
Implementing different schemes within the same model code is a tedious task
since most higher order schemes impose a coupling between space and time
discretisation. The basic choice in the program will therefore be limited to
the upwind and the TVD scheme to reduce the programming and compu-
tational overhead. The latter scheme is implemented with the symmetrical
operator splitting method for time integration and can be considered as a
useful tool for the simulation of frontal structures and areas with strong cur-
rent gradients. The upwind scheme, on the other hand, is only first order
accurate and therefore more diffusive, and should be used if CPU time is
considered of more importance than accuracy.
The following additional issues are noted:

• Scalar quantities are advected with a “filtered” velocity (uf ,vf ) derived
from the “corrected” baroclinic currents and the depth-integrated cur-
rent averaged over the internal time step (Deleersnijder, 1993).
• Sink terms are discretised explicitly in time for cell-centered scalars
to make the scheme more conservative, whereas a quasi-implicit for-
mulation is implemented for turbulence transport to ensure positivity
(Patankar, 1980).
This chapter is organised as follows:
• The model grid, the grid indexing system and notational conventions
are described in Section 5.2.
• The solution of the momentum equations and the mode splitting tech-
nique are presented in Section 5.3.
• The scalar transport equations are discussed in Section 5.5.
• Numerical aspects of the turbulence module are given in Section 5.6.
• The discretisations for one-dimensional (water column) and two-dimensional
(depth-averaged) applications are discussed in Section 5.7.
5.2. MODEL GRID AND DISCRETISATIONS 131
• The general solution procedure is summarised in Section 5.8.
5.2 Model grid and discretisations

5.2.1 Grid nodes and indexing system
Figure 5.1 shows the horizontal layout of the C-grid domain as it appears in
curvilinear coordinates (ξ1 , ξ2 ). A normalisation is applied so that ∆ξ1 =∆ξ2 =1.
For convenience, the notations X and Y will be used for ξ1 and ξ2 . It is re-
marked that X and Y do not refer to Cartesian axes in general. The following
dummy land column
{
ξ2 {
nr dummy land row
11
00 1
0 00
11 1
0 1
0 00
11 1
0 11
00 00
11 1
0
00
11 0
1
0 11
00 0
1 0
1
0 11
00 0
1
0 11
00
00 00
11 0
1
00
11 1 00
11 0
1 1 00
11 1 11 00
11 0
1
11
00 1
0 11
00 1
0 1
0 11
00 1
0 11
00 11
00 1
0
00
11 0
1 00
11 0
1 0
1 00
11 0
1 00
11 00
11 0
1
00
11 0
1 00
11 0
1 0
1 00
11 0
1 00
11 00
11 0
1
00
11 0
1 00
11 0
1 0
1 00
11 0
1 00
11 00
11 0
1
00
11 0
1 00
11 0
1 0
1 00
11 0
1 00
11 00
11 0
1
00
11 0
1 00
11 0
1 0
1 00
11 0
1 00
11 00
11 0
1
00
11 0
1 00
11 0
1 0
1 00
11 0
1 00
11 00
11 0
1
00
11 0
1 00
11 0
1 0
1 00
11 0
1 00
11 00
11 0
1
11
00 1
0 11
00 1
0 1
0 11
00 1
0 11
00 11
00 1
0
00
11 0
1 00
11 0
1 0
1 00
11 0
1 00
11 00
11 0
1
3
00
11 0
1 00
11 0
1 0
1 00
11 0
1 00
11 00
11 0
1
00
11 0
1 00
11 0
1 0
1 00
11 0
1 00
11 00
11 0
1
00
11 0
1 00
11 0
1 0
1 00
11 0
1 00
11 00
11 0
1
2
11
00 1
0 11
00 1
0 1
0 11
00 1
0 11
00 11
00 1
0
00
11 0
1 00
11 0
1 0
1 00
11 0
1 00
11 00
11 0
1
1
00
11
00
11 0
1
0
1 00
11
00
11 0
1
0
1 0
1
0
1 00
11
00
11 0
1
0
1 00
11
00
11 00
11
00
11 0
1
0
1
00
11 0
1 00
11 0
1 0
1 00
11 0
1 00
11 00
11 0
1
1 2 3 nc
ξ1
C−node quantities: scalars
U−node quantities: X−component of vectors
V−node quantities: Y−component of vectors

11
00
00 UV−node (corner) quantities (e.g. grid coordinates)
11
Figure 5.1: Layout of the (global) computational grid in the horizontal.
nodes can be distinguished:

• C-nodes (empty circles): located at the centers of the grid cells, used
for 2-D and 3-D scalar quantitities (elevations, water depths, . . . ) and
wind components
Horizontal
UV(i,j+1) V(i,j+1) UV(i+1,j+1)
U(i,j) U(i+1,j)
C(i,j)
UV(i,j) V(i,j) UV(i+1,j)
Figure 5.2: Grid indexing in the horizontal plane.
• U-nodes (horizontal bars): at the centers of the left (West) and right
(East) cell faces, used for the X-components of vectors except the sur-
face wind (transports, depth-mean currents, bottom stress, ...)
• V-nodes (vertical bars): at the centers of the lower (South) and upper
(North) cell faces, used for the Y-components of vectors except the
surface wind (transports, depth-mean currents, bottom stress, ...)
• UV-nodes (solid circles): at the corners of the grid cells, used for the
horizontal coordinate arrays which determine the geographical location
of the grid
Each horizontal grid cell has an index, generally denoted by “i”, in the X-
direction between 1 and nc and an index (“j”) in the Y-direction between 1
and nr. The indices refer to the position of a variable at its “natural” node
(C-, U-, V-, UV-node). This is illustrated in Figure 5.2.
As shown in Figure 5.1, the last column (to the East) and the last row (to
the North) are open ended. In this way the domain contains the same number
of C-, U-, V- and UV-nodes. This was not implemented in COHERENS V1
but introduced in the new version to allow a more efficient domain decom-
position in case of a parallel application. The drawback is that the C-node
Vertical
sea surface
s W nz+1
C nz
W
C
W
C
W
C
W
C 2
W 2
C 1
W 1
seabed
Figure 5.3: Layout of the computational grid in the vertical.
grid points with X-index nc or Y-index nr have to be declared as spurious

dry cells. This means in practice that, whereas the computational size of the
domain is nc×nr, the physical size is (nc-1)×(nr-1) for C-node, nc×(nr-1) for
U-node, (nc-1)×nr for V-node and nc×nr for UV-node quantities.
In analogy with the horizontal directions, a staggered grid is used in the
vertical as well. The water column is divided into nz layers. The layers,
which in transformed vertical coordinates have equal sizes, are illustrated in
Figure 5.3. The previous C-nodes are vertically located at the midst of each
layer. A new type of node, the W-node, is introduced located at the layer
itself, i.e. vertically between the C-nodes and at the bottom and the surface.
The vertical position of a 3-D model variable is determined by the vertical
(Z-)index (“k”) which varies between 1 and nz for C-node and between 1 and
nz+1 for W-node quantities.
The grid indexing system for the full 3-D mode is shown in Figure 5.4.
Combining horizontal and vertical nodes, new types of “combined” nodes
arise. The following nodal types are considered in the program:
• C-nodes: at the center of a 3-D grid cell

• U-nodes: at the center of a West/East lateral face
• V-nodes: at the center of a South/North lateral face
• UV-nodes: along the intersection lines of the lateral faces horizontally,
halfway between the lower and upper surface vertically
• W-nodes: at the centers of the lower and upper boundary faces
• UW-nodes: as the U-nodes horizontally, as the W-nodes vertically
• VW-nodes: as the V-nodes horizontally, as the W-nodes vertically
• UVW-nodes: at the corners of a 3-D grid cell (as UV-nodes horizontally
and as W-nodes vertically)
The W-nodes are used for the (transformed) vertical current ω and for tur-
bulence variables (k, ε, l, vertical diffusion coefficients and related variables).
The UW-, VW- and UVW-nodes are only needed by the program for local
internal variables.
The lower bound of all grid indices is 1, the upper boundary depends
on the nodal type and on whether it is taken along the computational or
physical domain. A complete listing is given in Table 5.1.
5.2.2 Open boundaries

Open boundaries are defined as locations on the model grid where the solution
of the discretised model equations requires values of the transport variable(s)
located outside the physical domain. Open boundary conditions have to be
specified at those locations. The program distinguishes four types of open
boundaries:
• U-open boundaries at U-velocity nodes needed to determine the values
of U , u and the advective/diffusive fluxes of scalars in the X-direction
• V-open boundaries at V-velocity nodes needed to determine the values
of V , v and the advective/diffusive fluxes of scalars in the Y-direction
• X-open boundaries at UV-nodes needed to determine the cross-stream
advective/diffusive fluxes of u and U
• Y-open boundaries at UV-nodes needed to determine the cross-stream
advective/diffusive fluxes of v and V
Grid indexing system (3−D)
VW(i,j+1,k+1)
UVW(i,j+1,k+1) UVW(i+1,j+1,k+1)
UW(i,j,k+1) W(i,j,k+1) UW(i+1,j,k+1)
V(i,j+1,k)
UV(i,j+1,k) UV(i+1,j+1,k)
UVW(i,j,k+1) UVW(i+1,j,k+1)
VW(i,j,k+1)
U(i,j,k) U(i+1,j,k)
C(i,j,k)
VW(i,j+1,k)
UVW(i,j+1,k) UVW(i+1,j+1,k)
UV(i,j,k) UV(i+1,j,k)
V(i,j,k)
UW(i,j,k) W(i,j,k) UW(i+1,j,k)
UVW(i,j,k) UVW(i+1,j,k)
VW(i,j,k)
Z
Y
Figure 5.4: Grid indexing in three-dimensional space.
5.2.3 Conventions
A quantity taken at a grid point on its natural node is written as Qij for a
2-D or Qijk for a 3-D variable. To simplify the notations, the indices i, j, k
are omitted if no confusion is possible. This means e.g. that Qi,j+1,k (3-D
quantity) can be written as Qj+1 or that Qi−1 (2-D quantity) is the same as
Qi−1,j .
If a quantity needs to be evaluated at a point, different from its natural
position, its value is determined by taking an average over the neighbouring
points. This is indicated by one of the superscripts c , u , v , w , . . . referring to
the point at which the quantity is interpolated. The program allows to use
uniform averaging with equal weight factors or non-uniform averaging with
unequal weights (see Section 8.2). To illustrate the convention, uniform av-
eraging is assumed here for simplicity. The Coriolis terms in the momentum
equations require a 4-point interpolation of the u and v velocities:
1
uvijk = (uijk + ui,j−1,k + ui+1,jk + ui+1,j−1,k )
4
Table 5.1: Upper bounds for the grid indices (i,j,k) as function of nodal type.
Node Computational Physical
X-index Y-index Z-index X-index Y-index Z-index
C nc nr nz nc-1 nr-1 nz
U nc nr nz nc nr-1 nz
V nc nr nz nc-1 nr nz
UV nc nr nz nc nr nz
W nc nr nz+1 nc-1 nr-1 nz+1
UW nc nr nz+1 nc nr-1 nz+1
VW nc nr nz+1 nc-1 nr nz+1
UVW nc nr nz+1 nc nr nz+1
X nc nr nz nc nr nz
Y nc nr nz nc nr nz
u 1
vijk = (vijk + vi−1,jk + vi,j+1,k + vi−1,j+1,k )
4
(5.1)
The next example is a centered quantity Q evaluated at respectively the U-,
V-, W-, UW- and VW-node with the same index values:
1
Quijk = (Qi−1,jk + Qijk )
2
1
Qvijk = (Qi,j−1,k + Qijk )
2
1
Qw
ijk = (Qij,k−1 + Qijk )
2
1
Quw
ijk = (Qij,k−1 + Qijk + Qi−1,j,k−1 + Qi−1,j,k )
4
1
Qvw
ijk = (Qij,k−1 + Qijk + Qi,j−1,k−1 + Qi,j−1,k ) (5.2)
4
A double index notation of the form i1 : i2 or j1 : j2 is sometimes in-
troduced in expressions related to open boundary conditions, where the first
index i1 (j1 ) is used at western (southern) boundaries and the second index
i2 (j2 ) at eastern (northern) boundaries, such as in the following example
expressions
ui+1:i−1,jk , vi,j:j−1,k
5.2.4 Space discretisation

The grid is defined by specifying the following three arrays:
• the x1 -coordinates (in Cartesian or spherical coordinates) x1;ij of the

cell corners (represented by the 2-D array gxcoordglb(nc,nr))
• the x2 -coordinates (in Cartesian or spherical coordinates) x2;ij of the

cell corners (represented by the 2-D array gycoordglb(nc,nr))
• the σ-coordinates σijk of the W-nodes (represented by the array

gscoordglb(nc,nr,nz+1)). Note that σij1 = 0 (bottom) and σij,Nz +1 = 1
(surface).
As discussed in Sections 4.1.2-4.1.3, the grid spacings ∆x1 , ∆x2 , ∆z are set
equal to respectively the metric coefficients h1 , h2 , h3 by normalisation. The
latter notation will be used for convenience in the following.
Spatial differences in the x1 -, x2 - or vertical direction are represented
respectively by the operators ∆x , ∆y , ∆z . The superscript c , u , v , w , uw , vw
or uv indicates the grid (nodal) location of the result. This is illustrated with
the following examples (where Q represents a centered quantity in the third
example):
∆cx uijk = ui+1,j,k − uijk

1
∆vy ucijk = (uijk + ui+1,jk − ui,j−1,k − ui+1,j−1,k )
2
∆z Qijk = Qijk − Qij,k−1
∆cy Vij = Vi,j+1 − Vij (5.3)
Grid spacings are “naturally” evaluated at the cell centre. Conforming the
previous rules interpolated values at other grid locations are indicated by a
superscript, e.g. hu1;ij , hw
3;ijk . Note that the grid indices on the left hand side
of the expressions (5.3) refer to the destination node and not the source node
of the interpolation. An overview of all subscript and superscript notations,
used in this chapter, is given in Table 5.2.
5.2.5 Time discretisation

The time discretisation of the model equations is summarised below. A
detailed description is given in the sections below.
• A mode-splitting technique is used (Blumberg & Mellor, 1987) with

separate time steps for the 2-D “external” barotropic equations (∆τ )
and the “internal” baroclinic equations (∆t). The 2-D time step ∆τ
has to be small enough to satisfy the Courant-Friedrichs-Lewy (CFL)
criterion (see equation (5.4) below). The 3-D time step is a multiple,
Table 5.2: Subscript and superscript notation used in the numerical discreti-
sation formulae.
Type Purpose
subscripts
i X-index of the variable on the model grid (between 1 and either
nc-1 or nc)
j Y-index of the variable on the model grid (between 1 and either
nr-1 or nr)
k vertical index of the variable on the model grid (between 1 and
either nz or nz+1)
i1 :i2 expression used in the spatial discretisation of open boundary
conditions, whereby the first index is taken at the western and
the second index at the eastern boundary
j1 :j2 expression used in the spatial discretisation of open boundary
conditions, whereby the first index is taken at the southern and
the second index at the northern boundary
superscripts
c quantity evaluated or interpolated at the cell centre
u quantity evaluated or interpolated at the U-node
v quantity evaluated or interpolated at the V-node
uv quantity evaluated or interpolated at the UV-node
w quantity evaluated or interpolated at the W-node
uw quantity evaluated or interpolated at the UW-node
vw quantity evaluated or interpolated at the VW-node
n quantity evaluated at the old baroclinic time tn
n+1 quantity evaluated at the new baroclinic time tn+1
m quantity evaluated at the old barotropic time tm
m+1 quantity evaluated at the new barotropic time tm+1
p “predicted” value
f “filtered” value
Mt , of ∆τ (typically of the order of 10–20) and the model is integrated

forward in time for Nt baroclinic time steps (equal to Nt Mt = Mtot
barotropic time steps). From stability analysis for linear surface gravity
waves
∆hmin
∆τ ≤ √ (5.4)
2 ghmax
and
∆hmin
∆t ≤ √ ′ (5.5)
2 g hmax
where ∆hmin = min(h1 , h2 ) is the minimum horizontal grid spacing,
g ′ = g∆ρ/ρ0 the reduced gravity, hmax the maximum water depth and
∆ρ a typical value for the vertical density difference. Since g ′ ≪ g
the second condition is less constraining than the first one. A more
stringent condition for the 3-D mode, imposed by the explicit schemes
for horizontal advection, is that the horizontal distance travelled by a
fluid element during the internal time step ∆t, must be smaller than
the grid spacing, or
u∆t v∆t
, ≤1 (5.6)
h1 h2
• All horizontal derivatives are evaluated explicitly while vertical diffu-
sion is computed fully implicitly and vertical advection quasi-implicitly.
• A predictor-corrector method is used to solve the horizontal momentum

equations (4.50)–(4.51). This satisfies the requirement (Blumberg &
Mellor, 1987) that, when using a mode-splitting technique, the currents
in the 3-D equations should have the same depth integral as the ones
obtained from the 2-D depth-integrated equations.
• A quasi-implicit method is implemented for the Coriolis terms.
• Time integration is performed with the operator splitting method in

conjunction with the TVD scheme for advection, whereas a simpler
forward scheme is considered when advection is discretised with the
upwind scheme.
• The sink terms in the momentum and turbulent transport equations,

representing e.g. the bottom stress in the momentum equation or the
dissipation rate ε and work against stable density gradients in e.g. the
k-equation (4.192), are discretised quasi-implicitly to ensure positivity
(Patankar, 1980). The sink terms in all other transport equations will
be taken explicitly for reasons of conservation.
• The time step at which a quantity is evaluated in the discretised equa-

tions, is represented by one of the following superscripts (see also Ta-
ble 5.2):
- n: 3-D quantity at the old baroclinic time level tn = n∆t
- n+1: 3-D quantity at the new baroclinic time level tn+1 = (n + 1)∆t
- m: 2-D quantity at the old barotropic time level tm = n∆t + m∆τ
- m + 1: 2-D quantity at the new barotropic time level tm+1 =
n∆t + (m + 1)∆τ
- p: horizontal current at the “predicted” time step
The superscript is omitted if no confusion is possible. If multiple super-
scripts appear separated by semicolons, the last superscript represents
the spatial node, the one before last the time level. For example, un;c
denotes the value of u at time level n and node “C”. In case of multiple
subscripts separated by semicolons, the last one(s) is (are) the spatial
index (indices).
5.3 Momentum equations

5.3.1 General procedure
The 3-D momentum equations are solved by a predictor-corrector method in
which the sequence of operations for each baroclinic time step is as follows:
1. An initial (predictor) estimate of the currents up , v p is calculated from
the equations of three-dimensional motion.
2. An implicit correction is added to the predicted values for the Coriolis
terms.
3. The 2-D depth-integrated equations of continuity and momentum are
solved for ζ, U and V . This involves Mt integrations in time.
4. An implicit correction is added for the Coriolis terms at each barotropic
time step.
5. The 3-D horizontal current up and v p are corrected yielding un+1 and
v n+1 by adjusting up and v p to ensure that the integrated currents
obtained from the 2-D and 3-D momentum equations are identical.
6. The transformed and physical vertical current are obtained by solving
(4.91) and (4.62).
5.3. MOMENTUM EQUATIONS 141
Table 5.3: Parameters and variables used in the numerical description.Global and
local FORTRAN names refer to the variables as defined on respectively the global
and local (parallel) grid.
Symbol Global Local Purpose

name name
Nx nc ncloc number of grid cells in the X-direction
Ny nr nrloc number of grid cells in the Y-direction
Nz nz nz number of grid cells in the vertical direction
h1 — delxatc grid spacing in the X-direction at the cell centre
h2 — delyatc grid spacing in the Y-direction at the cell centre
h3 — — grid spacing in the vertical direction at the cell
centre (calculated as H∆σk )
∆σk — delsatc grid spacing in the vertical σ-space at the cell cen-
tre
∆τ delt2d delt2d (barotropic or external) time step for the 2-D mode
equations
∆t delt3d — (baroclinic or internal) time step used for the up-
date of 3-D momentum (3-D mode) and all scalar
quantities
Mt ic3d ic3d number of 2-D (barotropic) time step within one
3-D (baroclinic) time step (= ∆t/∆τ )
Ntot — — total number of 3-D time steps used in the simula-
tion
Mtot nstep nstep total number of 2-D time steps used in the simula-
tion (= Mt Ntot )
θc theta cor theta cor implicity factor for the Coriolis force with a value
between 0 (explicit) and 1 (implicit). The default
value, currently used in the program, is 0.5.
θa theta vadv theta vadv implicity factor for vertical advection with a value
value, currently used in the program, is 0.501.
θv theta vdif theta vdif implicity factor for vertical diffusion with a value
value, currently used in the program, is 1.
(Continued)
Ω(r) — — weight function between the upwind and Lax-

Wendroff (central) fluxes used in the evaluation of
the horizontal (vertical) advective fluxes. Its value
depends on the value of the advective switches
iopt adv 3D (3-D currents), iopt adv 2D (2-D cur-
rents), iopt adv scal (scalars) and iopt adv turb
(turbulent variables) as given by (5.37)–(5.40).
uf — ufvel X-component of the “filtered” advective velocity,
defined by (5.25), used for the advection of scalar
quantities
vf — vfvel Y-component of the “filtered” advective velocity,
defined by (5.26), used for the advection of scalar
quantities
Uf — udfvel value of the depth-integrated current U averaged
over one baroclinic time step, as given by (5.21)
Vf — vdfvel value of the depth-integrated current V averaged
over one baroclinic time step, as given by (5.21)
5.3.1.1 predictor step

1. Firstly, the following terms are evaluated using values of currents, T ,
S at the old time step (tn ):
• the density ρ from the equation of state (see Section 4.2.3) if
iopt dens>0
• the coefficients of vertical diffusion if iopt vdif coef>0
• the baroclinic pressure gradient (see Section 5.3.12) if iopt dens grad>0
• the coeffficients of horizontal diffusion if iopt hdif coef=2 (Smagorin-
sky scheme, see Section 5.3.11.1)
2. The 3-D momentum equations (4.50) and (4.51) are integrated in time
at each (internal) grid point (i,j,k). Their discretised forms without
operator splitting, is given by
ũp − un v n;u
= f v n − Ah1 (un ) − Ah2 (un ) − u u (un ∆uy huv 1 −v
n;u u c
∆x h2 )
∆t h1 h2
−θa Av (ũp ) − (1 − θa )Av (un ) + θv Dmv (ũp ) + (1 − θv )Dmv (un )
∆u ζ n ∆u Pa
−g xu − x u + F1b;n + F1t;n+1 + Dmh1 (τ11 n n
) + Dmh2 (τ12 )
h1 ρ0 h 1
(5.7)
ṽ p − v n un;v
= −f un − Ah1 (v n ) − Ah2 (v n ) − v v (v n ∆vx huv 2 −u
n;v v c
∆y h1 )
∆t h1 h2
−θa Av (ṽ p ) − (1 − θa )Av (v n ) + θv Dmv (ṽ p ) + (1 − θv )Dmv (v n )
∆v ζ n ∆v Pa
−g yv − y v + F2b;n + F2t;n+1 + Dmh1 (τ21 n n
) + Dmh2 (τ22 )
h2 ρ0 h 2
(5.8)
where (ũp , ṽ p ) are the “predicted” currents before implicit Coriolis
correction, f = 2Ω sin φ is the Coriolis frequency, Ahi , Av are the ho-
rizontal and vertical advection operators defined by (4.53)–(4.55) and
Dmhi , Dmv the horizontal and vertical diffusion operators defined by
(4.56)–(4.58).
3. The predictor currents are obtained by adding an implicit Coriolis cor-
rection:
f θc ∆t(∆v u − f θc ∆t∆u)
up = ũp +
1 + (f θc ∆t)2
p p f θc ∆t(∆uv + f θc ∆t∆v)
v = ṽ − (5.9)
1 + (f θc ∆t)2
where
∆u = ũp − un , ∆v = ṽ p − v n (5.10)
For details see Appendix C.
4. The “predicted” values for the depth-integrated current are obtained
by integrating up and v p over the vertical
Nz Nz
Up = upk hn;u Vp = vkp hn;v
X X
3;k , 3;k (5.11)
k=1 k=1
The following features are to be noted:

• The forward (Euler) scheme for time discretisation in (5.7)–(5.8) is
replaced by the operator splitting method, discussed in Section 5.3.2.2,
in case the TVD scheme is applied for the advective terms.
• By default the Coriolis terms are evaluated semi-implicitly (θc =0.5).
The implicity factors for vertical advection θa and diffusion θv are set
to respectively 0.5, 0.501 (semi-implicit) and 1 (fully implicit method).
This is further discussed in Section 5.3.2.1.
• The equations are solved at the predictor step with application of sur-
face and bottom boundary conditions, but without open boundary con-
ditions.
5.3.1.2 depth-integrated equations

1. The depth-integrated baroclinic advective and diffusive terms (4.87)–
(4.90) are updated using values of the baroclinic current at the old time
level tn .
2. The astronomical tidal force is updated at the new time level tn+1
(Section 5.3.13) if iopt astro tide=1.
3. The 2-D continuity equation (4.74) for the surface elevation ζ and
the depth-integrated momentum equations (4.75)–(4.76) for U , V are
solved at each (internal) grid point (i,j) for Mt = ∆t/∆τ barotropic
time steps
ζ m+1 − ζ m 1 c u m
=− ∆x (h2 U ) + ∆cy (hv1 V m ) (5.12)
∆τ h1 h2
Ũ m+1 − U m u
kb2
+ m;u Ũ m+1 = f V m;u − Ah1 (U m ) − Ah2 (U m )
∆τ H
v m;u gH m+1;u u m+1
− u u (U m ∆uy huv 1 − H m+1;u m;u u c
v ∆ h
x 2 ) − ∆x ζ
h1 h2 hu1
H m+1;u u b;n m+1;u t;m+1 u u p Up
− ∆ x Pa + F 1 + H F 1 + τ s1 − k (u
b1 b − )
ρ0 hu1 H n;u
n n
+Dmh1 (τ11 )m + Dmh2 (τ12 )m − δAh1 + δDh1 (5.13)
Ṽ m+1 − V m v
kb2
+ m;v Ṽ m+1 = −f U m;v − Ah1 (V m ) − Ah2 (V m )
∆τ H
um;v gH m+1;v v m+1
− v v (V m ∆vx huv2 − H m+1;v m;v v c
u ∆ h
y 1 ) − ∆y ζ
h1 h2 hv2
H m+1;v v b;n m+1;v t;m+1 v v p Vp
− ∆ P
y a + F 2 + H F 2 + τ s2 − k (v
b1 b − )
ρ0 hv2 H n;v
n n
+Dmh1 (τ21 )m + Dmh2 (τ22 )m − δAh2 + δDh2 (5.14)
where
(u, v) = (U/H u , V /H v ) (5.15)
are the depth-mean currents and Ahi , Dmhi are the 2-D advective and
diffusion operators defined by (4.79)–(4.82).
A quasi-implicit formulation is used for the bottom stress in the U -
equation of the form
Up u Ũ
m+1
u
τb1 u
= kb1 upb − + kb2 (5.16)
H n;u H m;u
The friction velocities kb1 and kb2 depend on the formulation for the
bottom stress (see equations (4.325)–(4.329)).
u u
no bottom stress : kb1 = kb2 =0
u u
linear bottom stress : kb1 = 0 , kb2 = klin
1/2
3-D quadratic law u
: kb1 u
= kb2 u
= Cdb (unb )2 + (vbn;u )2
1/2
u u u
2-D quadratic law : kb1 = 0 , kb2 = Cdb (um )2 + (v m;u )2
(5.17)
u
The bottom drag coefficient Cdb is either calculated from (4.330), giving
h i−2
u
Cdb;ij = κ2 ln max(0.5hu3;ij1 /z0;ij
u
), 1.5 (5.18)
or by interpolating an externally supplied C-node value at the U-node.

Note that (5.18) guarantees that Cdb remains finite, with an upper limit
of 0.97, in case of a drying condition (i.e. when zr → z0 ).
The bottom stress at the V-node is treated similarly.
4. An implicit correction is applied for the Coriolis terms:
f θc ∆τ (∆V u − f θc ∆τ ∆U )
U m+1 = Ũ m+1 +
1 + (f θc ∆τ )2
f θc ∆τ (∆U v + f θc ∆τ ∆V )
V m+1 = Ṽ m+1 − (5.19)
1 + (f θc ∆τ )2
where
∆U = Ũ m+1 − U m , ∆V = Ṽ m+1 − V m (5.20)
For details see Appendix C.
5. The 2-D open boundary conditions are applied (see Section 5.3.15.1).
6. After solving (5.12)–(5.14) Mt times, the solutions are averaged over

the baroclinic time step, giving
Mt Mt
1 X 1 X
Uf = Um , Vf = Vm (5.21)
Mt m=1 Mt m=1
where Mt = ∆t/∆τ is the number of barotropic time steps.

5.3.1.3 corrector step

1. Open boundary conditions are applied for the baroclinic part

(δu, δv) = un+1 − un+1 , v n+1 − v n+1 (5.22)
2. The predicted values up , v p of the horizontal current are corrected to

ensure that the depth-integrated currents obtained from the 2-D mode
equations (5.13)–(5.14) are identical to the depth-integrated values of
the 3-D current. The corrected values are then given by
H n;u up + U n+1 − U p
un+1 = (5.23)
H n+1;u
H n;v v p + V n+1 − V p
v n+1 = (5.24)
H n+1;v
3. The “filtered” advective velocities uf and vf , used for the advection of
scalar quantities (see Section 5.5), are obtained by adding the depth-
integrated current averaged over the baroclinic time step to the baro-
clinic part of the 3-D corrected current:
H n;u up + Uf − U p
un+1
f = (5.25)
H n+1;u
H n;v v p + Vf − V p
vfn+1 = (5.26)
H n+1;v
For details of the procedures see Ruddick (1995).
5.3.1.4 vertical current

The transformed vertical current ω is obtained by integrating the “baroclinic”
continuity equation (4.91) from the bottom. Omitting the i- and j-indices
this gives
ω1n+1 = 0
1 h i
Fk = ∆c hu hn+1;u (un+1 − un+1 ) + ∆cy hv1 hn+1;v (vkn+1 − v n+1 )
h1 h2 x 2 3;k
c c k k 3;k k
n+1;u n+1;v
U n+1;c c h3;k V n+1;c c h3;k
+ ∆x + ∆y
hc1 H n+1;u hc2 H n+1;v
n+1
ωk+1 = ωkn+1 − Fk for 2 ≤ k ≤ Nz
n+1
ωNz +1 = 0 (5.27)
n+1
The procedure guarantees that ωN z +1
= 0.
The physical vertical current w is computed at the C-nodes from (4.62):
2(H n+1;c zkn+1;c − H n;c zkn;c )

wkn+1 =
∆t(H n;c + H n+1;c )
1 h i
+ c c n+1;c ∆cx hu2 hn+1;u
3;k un+1
k zkn+1;u + ∆cy hv1 hn+1;v
3;k vkn+1 zkn+1;v
h1 h2 h3;k
∆cz (zkn+1;w ωkn+1 )
+ (5.28)
hn+1;c
3;k
where
zkn+1;c = H n+1;c σkc − hc (5.29)
and similar expressions at other nodes or time levels.
5.3.2 Advection schemes and time discretisation

5.3.2.1 introduction
The time discretisation of the momentum equations depends on the type of
advection scheme employed for the spatial discretisation of the horizontal and
vertical advection terms. Several schemes are implemented in the program,
selected with the model switches iopt adv 3D and iopt adv 2D. They may take
the following values:
0 : horizontal and vertical advection of momentum disabled
1 : upwind scheme for horizontal and vertical advection
2 : Lax-Wendroff scheme for horizontal, central scheme for vertical advec-

tion1
3 : TVD (Total Variation Diminishing) scheme using the superbee limiter

as a weighting function between the upwind scheme and either the
Lax-Wendroff scheme in the horizontal or the central scheme in the
vertical
4 : as the previous case now using the monotonic limiter.

1
The “pure” Lax-Wendroff and central schemes have only been implemented for illus-
trative purposes and should be avoided in realistic simulations.
The discretisation of the different advection schemes is illustrated with

the following simple example, describing the 1-D advection of a scalar ψ:
∂ψ ∂ψ
+a =0 (5.30)
∂t ∂x
where a is a constant advecting velocity and the equation is spatially inte-
grated for the interval xa ≤ x ≤ xb . The equation can then be rewritten in
flux form
∂ψ ∂F
+ =0 (5.31)
∂t ∂x
where F = aψ is the advective flux. The discretised form of (5.31), using
forward Euler time integration, is given by
ψ n+1 − ψ n Fi+1 − Fi
+ =0 (5.32)
∆t ∆x
where ∆t is the time step and ∆x a uniform grid spacing. The quantities
ψ and Fi are evaluated on a uniform staggered grid (see Figure 5.5) with
ψ-points located halfway between the F -points. Boundary conditions at xa
and xb are needed to determine the fluxes F1 and FN +1 . At interior points,
i.e. for 2 ≤ i ≤ N + 1, the fluxes Fi are then written as a weighting between
the upwind and Lax-Wendroff fluxes Fup;i and Flw;i :

Fi = (1 − Ω(ri ))Fup;i + Ω(ri )Flw;i (5.33)
where
1
Fup;i = a (1 + si )ψi−1 + (1 − si )ψi (5.34)
2
1
Flw;i = a (1 + ci )ψi−1 + (1 − ci )ψi (5.35)
2
where si and ci are the sign and CFL number of the advecting current
a∆t
si = Sign(a) , ci = (5.36)
∆x
The weight function Ω depends on the type of advection scheme:
• upwind
Ω(r) = 0 (5.37)
• Lax-Wendroff
Ω(r) = 1 (5.38)
F ψ F ψ F ψ F
1 1 2 2 3 Ν N+1
xa xb
Figure 5.5: Numerical grid for the 1-D advection problem.
• TVD with superbee limiter
Ω(r) = max(0, min(2r, 1), min(r, 2)) (5.39)
• TVD with monotonic limiter
r + |r|
Ω(r) = (5.40)
1 + |r|
The argument r of Ω is defined by
(1 + si )∆Fi−1 + (1 − si )∆Fi+1
ri =
2∆Fi
∆Fi = Flw;i − Fup;i (5.41)
The discretisation scheme for vertical advection is similar, except that

the Lax-Wendroff flux Flw;k is replaced by the central flux
1
Fce;k = a(ψk−1 + ψk ) (5.42)
2
The discretisation schemes, actually applied in the model, need to take

account of the following additional complexities
• non-uniform grids
• space and time dependent currents
• grid staggering (advected quantities and advecting currents can, for

example, be located at the same locations)
• extensions to 2-D and 3-D grids
• time integration using operator splitting (see below) to improve the

time accuracy of the TVD scheme
Explicit expressions of each discretisation will be presented below for the

advective terms of all model equations.
The upwind scheme has the interesting property to preserve monotonic-
ity, but has the disadvantage of being only first order accurate. The Lax-
Wendroff scheme, on the other hand, is accurate to second order in space and
time but non-monotone which means that spurious over- and undershootings
are created in regimes of strong gradients. This is clearly illustrated by the
results of the test cases cones and front described in Sections 18.1 and 18.2.
The TVD scheme has the advantage of combining the monotonicity of the
upwind scheme with the second order accuracy of the Lax-Wendroff scheme.
Horizontal advection is evaluated explicitly to prevent the solution of
large-banded matrix systems. A necessary stability condition for both the
upwind and the Lax-Wendroff scheme is given by the criterion (5.6) (see
Hirsch, 1990). The restriction to explicit schemes does not apply for the ver-
tical since the discretised equations can be written into a simpler tridiagonal
form (see Section 5.3.17). A semi-implicit scheme in the vertical allows to
replace the Lax-Wendroff by the central scheme which is a monotone scheme
and stable provided that the implicity factor θa ≥ 0.5.
The aim of the limiter function is to reduce the numerical diffusion due
to the upwind scheme in areas of low gradients and to provide sufficiently
large diffusion in regions of large gradients so that over- and undershooting
due to the non-monotonicity of the Lax-Wendroff scheme are suppressed.
Both the superbee (Roe, 1985) as the monotonic limiter are available in the
program. The cones and front test case simulations (see Sections 18.1 and
18.2) showed that the superbee limiter is the least diffusive and is therefore
taken as the default formulation in the program. The spatial discretisation of
the advective terms in the momentum equations and the form of the limiter
function are further discussed in the subsections below.
In the absence of advection or when the upwind or Lax-Wendroff/central
scheme is selected, the momentum equations are solved by forward time-
stepping as given by the time-discretised forms (5.7) and (5.8). In case of
the TVD scheme, the spatial discretisation of the advective terms involves
the Lax-Wendroff and central schemes which are both second order accurate
in space. The equations are then integrated in time with the aid of the “frac-
tional step” or “operator splitting” method as proposed by Yanenko (1971).
The procedure consists in splitting the time integration into three fractional
steps. During the first and second step only the advection-diffusion terms
in respectively the X- and Y-direction are taken into account. The vertical
advection and diffusion terms and all other terms (Coriolis force, pressure
gradient and tidal force) are included during the third time step. To preserve
the second-order accuracy of the 1-D schemes in the fractional step approach
the method of symmetric splitting (e.g. Hirsch, 1990) is implemented. This

means that the previous procedure (“A”-steps) is repeated now in reverse
order (“B”-steps) , i.e. vertical advection/diffusion and other terms followed
by advection-diffusion in the Y-direction, followed by advection-diffusion in
the X-direction. The final “predicted” value of up or v p is then obtained by
taking the average of the values at the end of the A- and B-steps. The same
method is applied for scalar quantities.
The implicity factors θa and θv have a range between 0 and 1 where a
0 corresponds to a fully explicit, 1 a fully implicit and 0.5 a semi-implicit
(Crank-Nicholson) method. The schemes are stable provided that θa , θv ≥
0.5. To retain the same accuracy in time for horizontal as well as vertical
advection the defaults are a semi-implicit option for vertical advection, i.e.
θa = 0.5012 and a fully implicit treatment of vertical diffusion (θv = 1).
Contrary to COHERENS V1, these defaults can be changed by the user and
can take any value between 0 and 1.
For a more detailed account of advection schemes and the time splitting
method see Ruddick (1995).
2
The central scheme is second accurate in time if θa = 0.5.
Table 5.4: Overview of the operators used in the numerical discretisations.
Type Purpose
difference operators
∆x difference operator in the X-direction
∆y difference operator in the Y-direction
∆z difference operator in the vertical direction
advective operators
Ah1 horizontal advection in the X-direction3

1 ∂
Ah1 (F ) = (h2 h3 uf F )
h1 h2 h3 ∂ξ1
Ah2 horizontal advection in the Y-direction3

1 ∂
Ah2 (F ) = (h1 h3 vf F )
h1 h2 h3 ∂ξ2
Av vertical advection (u, v and scalars)

1 ∂
Av (F ) = (ωF )
h3 ∂s
Ah1 horizontal advection in the X-direction (2-D mode)

1 ∂ h2 U F
Ah1 (F ) =
h1 h2 ∂ξ1 H
Ah2 horizontal advection in the Y-direction (2-D mode)

1 ∂ h1 V F
Ah2 (F ) =
h1 h2 ∂ξ2 H
extended advective operators for currents including curvature terms
(Continued)
3
Note that (uf ,vf ) is replaced by (u,v) if F represents u, v or a turbulent transport
variable (k,ε,kl).
Ãh1 (u) extended horizontal advection of u in the X-direction

v 2 ∂h2
Ãh1 (u) = Ah1 (u) −
h1 h2 ∂ξ1
Ãh2 (u) extended horizontal advection of u in the Y-direction

uv ∂h1
Ãh2 (u) = Ah2 (u) +
h1 h2 ∂ξ2
Ãh1 (v) extended horizontal advection of v in the X-direction

uv ∂h2
Ãh1 (v) = Ah1 (v) +
h1 h2 ∂ξ1
Ãh2 (v) extended horizontal advection of v in the Y-direction

u2 ∂h1
Ãh2 (v) = Ah2 (v) −
h1 h2 ∂ξ2
Ãh1 (U ) extended horizontal advection of U in the X-direction

vV ∂h2
Ãh1 (U ) = Ah1 (U ) −
h1 h2 ∂ξ1
Ãh2 (U ) extended horizontal advection of U in the Y-direction

vU ∂h1
Ãh2 (U ) = Ah2 (U ) +
h1 h2 ∂ξ2
Ãh1 (V ) extended horizontal advection of V in the X-direction

uV ∂h2
Ãh1 (V ) = Ah1 (V ) +
h1 h2 ∂ξ1
Ãh2 (V ) extended horizontal advection of V in the Y-direction

uU ∂h1
Ãh2 (V ) = Ah2 (V ) −
h1 h2 ∂ξ2
diffusion operators
(Continued)

Dsh1 horizontal diffusion in the X-direction (scalars)
1 ∂ h2 h3 ∂ψ
Dsh1 (ψ) = λH
h1 h2 h3 ∂ξ1 h1 ∂ξ1
Dsh2 horizontal diffusion in the Y-direction (scalars)

1 ∂ h1 h3 ∂ψ
Dsh2 (ψ) = λH
h1 h2 h3 ∂ξ2 h2 ∂ξ2
Dmh1 horizontal diffusion in the X-direction (3-D momentum)

1 ∂ 2
Dmh1 (F ) = h h 3 F
h1 h22 h3 ∂ξ1 2
Dmh2 horizontal diffusion in the Y-direction (3-D momentum)

1 ∂ 2
Dmh2 (F ) = 2 h1 h3 F
h1 h2 h3 ∂ξ2
τij 3-D horizontal shear stress tensor
τ11 = −τ22 = νH DT
τ12 = τ21 = νH DS
h2 ∂ u h1 ∂ v

DT = −
h1 ∂ξ1 h2 h2 ∂ξ2 h1
h1 ∂ u h2 ∂ v

DS = +
h2 ∂ξ2 h1 h1 ∂ξ1 h2
Dsv vertical diffusion (scalars)

1 ∂ λψT ∂F
Dsv (F ) =
h3 ∂s h3 ∂s
Dmv vertical diffusion (momentum)

1 ∂ νT ∂F
Dmv (F ) =
h3 ∂s h3 ∂s
Dmh1 horizontal diffusion in the X-direction (2-D momentum)

1 ∂ 2
Dmh1 (F ) = hF
h1 h22 ∂ξ1 2
Dmh2 horizontal diffusion in the Y-direction (2-D momentum)
(Continued)

1 ∂ 2
Dmh2 (F ) = hF
h21 h2 ∂ξ2 1
τij 2-D horizontal shear stress tensor
τ11 = −τ22 = νH DT
τ12 = τ21 = νH DS
h2 ∂ u h1 ∂ v

DT = −
h1 ∂ξ1 h2 h2 ∂ξ2 h1
h1 ∂ u h2 ∂ v

DS = +
h2 ∂ξ2 h1 h1 ∂ξ1 h2
other operators
P production terms in the scalar transport equations
S sink terms in the scalar transport equations
T production minus sink terms in the scalar transport equa-

tions
T =P −S
f
Cs1 X-corrector term in the scalar transport equations
f ψ ∂
Cs1 (ψ) = (h2 h3 uf )
h1 h2 h3 ∂ξ1
f
Cs2 Y-corrector term in the scalar transport equations
f ψ ∂
Cs2 (ψ) = (h1 h3 vf )
h1 h2 h3 ∂ξ2
Cs3 Z-corrector term in the scalar transport equations

ψ ∂ω
Cs3 (ψ) =
h3 ∂s
5.3.2.2 mode splitting scheme for the 3-D momentum equations

The time-discretised form of the u-equation (4.50) with mode splitting is
given by
• Part A
n+1/3
uA − un (v n;u )2 ∆ux hc2
= −Ah1 (un ) + + Dmh1 (νH DT (un , v n )) (5.43)
∆t hu1 hu2
n+2/3 n+1/3 n+1/3 n;u

uA − uA n+1/3 uA v ∆uy huv
1
= −Ah2 (uA ) − u u
∆t h1 h2
n+1/3
+ Dmh2 (νH DS (uA , v n )) (5.44)
n+2/3
ũpA − uA n+2/3
= −θa Av (ũpA ) − (1 − θa )Av (uA )
∆t
n+2/3
+θv Dmv (ũpA ) + (1 − θv )Dmv (uA ) + O1 (5.45)
• Part B
n+1/3
uB − un n+1/3
= −θa Av (uB ) − (1 − θa )Av (un )
∆t
n+1/3
+θv Dmv (uB ) + (1 − θv )Dmv (un ) + O1 (5.46)
n+2/3 n+1/3 n+1/3 n;u

uB − uB n+1/3 uB v ∆uy huv
1
= −Ah2 (uB ) −
∆t hu1 hu2
n+1/3
+ Dmh2 (νH DS (uB , v n )) (5.47)
n+2/3
ũpB − uB n+2/3 (v n;u )2 ∆ux hc2 n+2/3 n
= −Ah1 (uB )+ + Dmh1 (νH DT (uB , v ))
∆t hu1 hu2
(5.48)
• Predictor value
1
ũp = (ũpA + ũpB ) (5.49)
2
The O1 -terms are defined by
∆ux ζ n ∆ux Pa
O1 = f v n;u − g − + F1b;n + F1t;n+1 (5.50)
hu1 ρ0 hu1
A similar procedure is applied for the v-equation (4.51).
• Part A
n+1/3
vA − vn un;v v n ∆vx huv
2
= −Ah1 (v n ) − + Dmh1 (νH DS (un , v n )) (5.51)
∆t hv1 hv2
n+2/3 n+1/3
vA − vA n+1/3 (un;v )2 ∆vy hc1
= −Ah2 (vA ) +
∆t hv1 hv2
n+1/3
− Dmh2 (νH DT (un , vA )) (5.52)
n+2/3
ṽAp − vA n+2/3
= −θa Av (ṽAp ) − (1 − θa )Av (vA )
∆t
n+2/3
+θv Dmv (ṽAp ) + (1 − θv )Dmv (vA ) + O2 (5.53)
• Part B
n+1/3
vB − vn n+1/3
= −θa Av (vB ) − (1 − θa )Av (v n )
∆t
n+1/3
+θv Dmv (vB ) + (1 − θv )Dmv (v n ) + O2 (5.54)
n+2/3 n+1/3
vB − vB n+1/3 (un;v )2 ∆vy hc1
= −Ah2 (vB ) +
∆t hv1 hv2
n+1/3
− Dmh2 (νH DT (un , vB )) (5.55)
n+2/3 n+2/3
ṽBp − vB n+2/3 un;v vB ∆vx huv
2
= −Ah1 (vB ) − v v
∆t h1 h2
n+2/3
+ Dmh1 (νH DS (un , vB )) (5.56)
• Predictor value
1
ṽ p = (ṽAp + ṽBp ) (5.57)
2
∆vy ζ n ∆vy Pa
O2 = −f un;v − g − + F2b;n + F2t;n+1 (5.58)
hv2 ρ0 hv2
Once ũp and ṽ p are obtained, an implicit correction is applied as described
in Section 5.3.1.1.
Important to note again is that, compared to the simpler forward scheme,
the computation using symmetrical operator splitting increases the CPU time
for the circulation module by a factor two, but has the advantage of being
more accurate which is an important property in regions of strong horizontal
and vertical shear.
5.3.2.3 mode splitting scheme for the 2-D momentum equations

The operator splitting is applied for the 2-D case if the advective terms
are discretised with the TVD scheme (iopt adv 2D=3). Since the 2-D mode
equations are solved with a much smaller time step than the 3-D mode,
second-order accuracy is of less relevance. Contrary to the 3-D case, the
simpler upwind scheme, using only a forward Euler time integration, can be
recommended for 2-D applications.
The method is analogous to the 3-D case, but given here in detail for
completeness. Firstly, the U -equation (4.75) is solved as follows:
• Part A
m+1/3
UA − Um H m;u (v m;u )2 ∆ux hc2
= −Ah1 (U m ) +
∆τ hu1 hu2
+ Dmh1 (νH DT (U m , V m )) (5.59)
m+2/3 m+1/3 m+1/3 m;u

UA − UA m+1/3 UA v ∆uy huv
1
= −Ah2 (UA ) − u u
∆τ h1 h2
m+1/3
+ Dmh2 (νH DS (UA , V m )) (5.60)
m+2/3
ŨAm+1 − UA u
kb2
+ Ũ m+1 = O1 (5.61)
∆τ H m;u A
• Part B
m+1/3
UB − Um u
kb2 m+1/3
+ m;u UB = O1 (5.62)
∆τ H
m+2/3 m+1/3 m+1/3 m;u

UB − UB m+1/3 UB v ∆uy huv
1
= −Ah2 (UB ) − u u
∆τ h1 h2
m+1/3
+ Dmh2 (νH DS (UB , V m )) (5.63)
m+2/3
ŨBm+1 − UB H m+1;u (v m;u )2 ∆ux hc2
= −Ah1 (U m+2/3 ) +
∆τ hu1 hu2
m+2/3
+ Dmh1 (νH DT (UB , V m )) (5.64)
• Value at new time step

1
Ũ m+1 = (ŨAm+1 + ŨBm+1 ) (5.65)
2
gH m+1;u u m+1 H m+1;u b;n

O1 = f V m;u − u
∆x ζ − u
∆x Pa + F1 + H m+1;u F1t;m+1
h1 ρ0 h 1
p
p;u
U n n
u
+ τs1 − kb1 upb − n;u − δAh1 + δDh1 (5.66)
H
A similar procedure is followed for the V -equation (4.76):
• Part A
m+1/3
VA −Vm um;v V m ∆vx huv
2
= −Ah1 (V m ) −
∆τ hv1 hv2
+ Dmh1 (νH DT (U m , V m )) (5.67)
m+2/3 m+1/3
VA − VA m+1/3 H m;v (um;v )2 ∆vy hc1
= −Ah2 (VA )+
∆τ hv1 hv2
m+1/3
− Dmh2 (νH DS (U m , VA )) (5.68)
m+2/3
ṼAm+1 − VA v
kb2
+ Ṽ m+1 = O2 (5.69)
∆τ H m;v A
• Part B
m+1/3
VB −Vm v
kb2 m+1/3
+ m;v VB = O2 (5.70)
∆τ H
m+2/3 m+1/3
VB − VB m+1/3 H m;v (um;v )2 ∆vy hc1
= −Ah2 (VB )+
∆τ hv1 hv2
m+1/3
− Dmh2 (νH DS (U m , VB )) (5.71)
m+2/3
ṼBm+1 − VA m+2/3 um;v V m+2/3 ∆vx huv
2
= −Ah1 (V )− v v
∆τ h1 h2
m+2/3
+ Dmh1 (νH DT (U m , VB )) (5.72)
• Value at new time step
1
Ṽ m+1 = (ṼAm+1 + ṼBm+1 ) (5.73)
2
gH m+1;v v m+1 H m+1;v b;n

O2 = −f U m;v − ∆y ζ − ∆y Pa + F2 + H m+1;v F2t;m+1
hv2 ρ0 hv2
Vp n n
v
+ τs2 v
− kb1 vbp − n;v − δAh2 + δDh2 (5.74)
H
Once Ũ m+1 and Ṽ m+1 are obtained, an implicit correction is applied as des-
cribed in Section 5.3.1.2.
Table 5.5: Definitions of the fluxes used in the numerical discretisations.
Type Purpose
advective fluxes
F1 advective flux of a scalar in the X-direction at the U-node

F1 = uψ
F2 advective flux of a scalar in the Y-direction at the V-node
F2 = vψ
F3 advective flux of a scalar in the vertical direction at the W-node
F3 = ωψ
F11 advective flux of u in the X-direction at the C-node
F11 = uu
F12 advective flux of a u in the Y-direction at the UV-node
F12 = vu
F21 advective flux of a v in the X-direction at the UV-node
F21 = uv
F22 advective flux of v in the Y-direction at the C-node
F22 = vv
F13 advective flux of u in the vertical direction at the UW-node
F13 = ωu
F23 advective flux of v in the vertical direction at the VW-node
F23 = ωv
F 11 advective flux of U in the X-direction at the C-node
F 11 = uU
F 12 advective flux of U in the Y-direction at the UV-node
F 12 = vU
F 21 advective flux of V in the X-direction at the UV-node
F 21 = uV
F 22 advective flux of V in the Y-direction at the C-node
F 22 = vV
(Continued)
diffusive fluxes
D1 diffusive flux of a scalar in the X-direction at the U-node

λH ∂ψ
D1 =
h1 ∂ξ1
D2 diffusive flux of a scalar in the Y-direction at the V-node
λH ∂ψ
D2 =
h2 ∂ξ2
D3 diffusive flux of a scalar in the vertical direction at the W-node
λψT ∂ψ
D3 =
h3 ∂s
D11 diffusive flux in the X-direction (u-equation) at the C-node
D11 = h2 τ11 = νH h2 DT
D12 diffusive flux in the Y-direction (u-equation) at the UV-node
D12 = h1 τ12 = νH h1 DS
D21 diffusive flux in the X-direction (v-equation) at the UV-node
D21 = h2 τ21 = νH h2 DS
D22 diffusive flux in the Y-direction (v-equation) at the C-node
D22 = h1 τ22 = −νH h1 DT
D13 diffusive flux in the vertical direction (u-equation) at the UW-
node
νT ∂u
D13 =
h3 ∂s
D23 diffusive flux in the vertical direction (v-equation) at the VW-
node
νT ∂v
D23 =
h3 ∂s
D11 diffusive flux in the X-direction (U -equation) at the C-node
D11 = h2 τ11 = νH h2 DT
D12 diffusive flux in the Y-direction (U -equation) at the UV-node
D12 = h1 τ12 = νH h1 DS
D21 diffusive flux in the X-direction (V -equation) at the UV-node
D21 = h2 τ21 = νH h2 DS
D22 diffusive flux in the Y-direction (V -equation) at the C-node
D22 = h1 τ22 = −νH h1 DT
(Continued)
5.3.3 Discretisation of 3-D horizontal advection

The four horizontal advective terms in the 3-D momentum equations are
written as the divergence of the horizontal fluxes F11 , F12 , F21 , F22 , defined
in Table 5.5:
1 ∂ 1 ∂
Ah1 (u) = h 2 h 3 u2 = h2 h3 F11 (5.75)
h1 h2 h3 ∂ξ1 h1 h2 h3 ∂ξ1
1 ∂ 1 ∂
Ah2 (u) = h1 h3 uv = h1 h3 F12 (5.76)
h1 h2 h3 ∂ξ2 h1 h2 h3 ∂ξ2
1 ∂ 1 ∂
Ah1 (v) = h2 h3 uv = h2 h3 F21 (5.77)
h1 h2 h3 ∂ξ1 h1 h2 h3 ∂ξ1
1 ∂ 1 ∂
Ah2 (v) = h1 h3 v 2 = h1 h3 F22 (5.78)
h1 h2 h3 ∂ξ2 h1 h2 h3 ∂ξ2
For simplicity, the k-index and time level will be omitted from the discreti-
sation formulae.
Extended forms of the above operators which include the appropriate
curvature term, are defined by (see Table 5.4):
v 2 ∂h2
Ãh1 (u) = Ah1 (u) − (5.79)
h1 h2 ∂ξ1
uv ∂h1
Ãh2 (u) = Ah2 (u) + (5.80)
h1 h2 ∂ξ2
uv ∂h2
Ãh1 (v) = Ah1 (v) + (5.81)
h1 h2 ∂ξ1
u2 ∂h1
Ãh2 (v) = Ah2 (v) − (5.82)
h1 h2 ∂ξ2
5.3.3.1 alongstream advection of u

The alongstream advective term in the u-equation (4.50) is obtained by dif-
c
ferencing the flux F11 at the U-node
hc2;ij hc3;ij F11;ij
c
− hc2;i−1,j hc3;i−1,j F11;i−1,j
c
Ah1 (u)uij = (5.83)
hu1;ij hu2;ij hu3;ij
The flux is calculated from

c
F11;ij = 1 − Ω(rijc ) Fup;ij
c
+ Ω(rijc )Flw;ij
c
(5.84)
c c
where Fup;ij and Flw;ij are the upwind and Lax-Wendroff fluxes at the C-node:
c 1 c
Fup;ij = uij (1 + sij )uij + (1 − sij )ui+1,j (5.85)
2
c 1 c
Flw;ij = uij (1 + cij )uij + (1 − cij )ui+1,j (5.86)
2
where sij and cij are the sign and CFL number of the advecting current
ucij ∆t
sij = Sign(ucij ) , cij = (5.87)
hc1;ij
The form of the weighting function is given by (5.37)–(5.40), depending on

the type of advection scheme, selected by the switch iopt adv 3D. The argu-
ment r of the weight function is defined by
c c
(1 + sij )∆Fi−1,j + (1 − sij )∆Fi+1,j
rijc =
2∆Fijc
∆Fijc c
= Flw;ij c
− Fup;ij (5.88)
The extended advective term is discretised as

(viju )2 ∆ux hc2;ij
Ãh1 (u)uij = Ah1 (u)uij − (5.89)
hu1;ij hu2;ij
5.3.3.2 cross-stream advection of u

The cross-stream advective term in the u-equation (4.50) is obtained by dif-
uv
ferencing the flux F12 at the U-node
huv uv uv uv uv uv
1;i,j+1 h3;i,j+1 F12;i,j+1 − h1;ij h3;ij F12;ij
Ah2 (u)uij = (5.90)
hu1;ij hu2;ij hu3;ij

uv
F12;ij = 1 − Ω(rijuv ) Fup;ij
uv
+ Ω(rijuv )Flw;ij
uv
(5.91)
uv uv
where Fup;ij and Flw;ij are the upwind and Lax-Wendroff fluxes at the UV-
node:
uv 1 uv
Fup;ij = vij (αij + sij )ui,j−1 + (βij − sij )uij (5.92)
2
uv 1 uv
Flw;ij = vij (αij + cij )ui,j−1 + (βij − cij )uij (5.93)
2
where
vijuv ∆t
sij = Sign(vijuv ) , cij = uv (5.94)
h2;ij
hu2;ij hu2;i,j−1
αij = , βij = (5.95)
huv
2;ij huv2;ij

uv uv
(αij + sij )∆Fi,j−1 + (βij − sij )∆Fi,j+1
rijuv =
2∆Fijuv
∆Fijuv uv
= Flw;ij uv
− Fup;ij (5.96)

uij viju ∆uy huv
1;ij
Ãh2 (u)uij = Ah2 (u)ij + u u
(5.97)
h1;ij h2;ij
5.3.3.3 cross-stream advection of v

The cross-stream advective term in the v-equation (4.51) is obtained by dif-
uv
ferencing the flux F21 at the V-node
huv uv uv uv uv uv
2;i+1,j h3;i+1,j F21;i+1,j − h2;ij h3;ij F21;ij
Ah1 (v)vij = (5.98)
hv1;ij hv2;ij hv3;ij

uv
F21;ij = 1 − Ω(rijuv ) Fup;ij
uv
+ Ω(rijuv )Flw;ij
uv
(5.99)
uv uv
where Fup;ij and Flw;ij are the upwind and Lax-Wendroff fluxes at the UV-
node:
uv 1 uv
Fup;ij = uij (αij + sij )vi−1,j + (βij − sij )vij (5.100)
2
uv 1 uv
Flw;ij = uij (αij + cij )vi−1,j + (βij − cij )vij (5.101)
2
where
uuv ∆t
sij = Sign(uuv
ij ) , cij = ijuv (5.102)
h1;ij
hv1;ij hv1;i−1,j
αij = , βij = (5.103)
huv
1;ij huv1;ij

uv uv
(αij + sij )∆Fi−1,j + (βij − sij )∆Fi+1,j
rijuv =
2∆Fijuv
∆Fijuv uv
= Flw;ij uv
− Fup;ij (5.104)
uv vij ∆v huv
Ãh1 (v)vij = Ah1 (v)vij + ij v xv 2;ij (5.105)
h1;ij h2;ij
5.3.3.4 alongstream advection of v

The alongstream advective term in the v-equation (4.51) is obtained by dif-
c
ferencing the flux F22 at the V-node
hc1;ij hc3;ij F22;ij
c
− hc1;i,j−1 hc3;i,j−1 F22;i,j−1
c
Ah2 (v)vij = (5.106)
hv1;ij hv2;ij hv3;ij

c
F22;ij = 1 − Ω(rijc ) Fup;ij
c
+ Ω(rijc )Flw;ij
c
(5.107)
c c
where Fup;ij and Flw;ij are the upwind and Lax-Wendroff fluxes at the C-node:
c 1 c
Fup;ij = vij (1 + sij )vij + (1 − sij )vi,j+1 (5.108)
2
c 1 c
Flw;ij = vij (1 + cij )vij + (1 − cij )vi,j+1 (5.109)
2
vijc ∆t
sij = Sign(vijc ) , cij = (5.110)
hc2;ij
c c
(1 + sij )∆Fi,j−1 + (1 − sij )∆Fi,j+1
rijc =
2∆Fijc
∆Fijc c
= Flw;ij c
− Fup;ij (5.111)
v v (uvij )2 ∆vy hc1;ij
Ãh2 (v)ij = Ah2 (v)ij − (5.112)
hv1;ij hv2;ij
5.3.4 Discretisation of 2-D horizontal advection

The four horizontal advective terms in the 2-D momentum equations are
written as the divergence of the horizontal fluxes F 11 , F 12 , F 21 , F 22 , defined
in Table 5.5:
1 ∂ 1 ∂
Ah1 (U ) = (h2 uU ) = (h2 F 11 ) (5.113)
h1 h2 ∂ξ1 h1 h2 ∂ξ1
1 ∂ 1 ∂
Ah2 (U ) = (h1 vU ) = (h1 F 12 ) (5.114)
h1 h2 ∂ξ2 h1 h2 ∂ξ2
1 ∂ 1 ∂
Ah1 (V ) = (h2 uV ) = (h2 F 21 ) (5.115)
h1 h2 ∂ξ1 h1 h2 ∂ξ1
1 ∂ 1 ∂
Ah2 (V ) = (h1 vV ) = (h1 F 22 ) (5.116)
h1 h2 ∂ξ2 h1 h2 ∂ξ2
Extended forms of the above operators which include the appropriate
curvature term, are defined by (see Table 5.4):
vV ∂h2
Ãh1 (U ) = Ah1 (U ) − (5.117)
h1 h2 ∂ξ1
vU ∂h1
Ãh2 (U ) = Ah2 (U ) + (5.118)
h1 h2 ∂ξ2
uV ∂h2
Ãh1 (V ) = Ah1 (V ) + (5.119)
h1 h2 ∂ξ1
uU ∂h1
Ãh2 (V ) = Ah2 (V ) − (5.120)
h1 h2 ∂ξ2
5.3.4.1 alongstream advection of U

The alongstream advective term in the U -equation (4.75) is obtained by
c
differencing the flux F 11 at the U-node
c c
hc2;ij F 11;ij − hc2;i−1,j F 11;i−1,j
Ah1 (U )uij = (5.121)
hu1;ij hu2;ij
c c c

F 11;ij = 1 − Ω(rijc ) F up;ij + Ω(rijc )F lw;ij (5.122)
c c
where F up;ij and F lw;ij are the upwind and Lax-Wendroff fluxes at the C-
node:
c 1 c
F up;ij = uij (1 + sij )Uij + (1 − sij )Ui+1,j (5.123)
2
c 1 c
F lw;ij = uij (1 + cij )Uij + (1 − cij )Ui+1,j (5.124)
2
ucij ∆τ
sij = Sign(ucij ) , cij = (5.125)
hc1;ij

c c
(1 + sij )∆F i−1,j + (1 − sij )∆F i+1,j
rijc = c
2∆F ij
c c c
∆F ij = F lw;ij − F up;ij (5.126)
The extended advective term is discretised by

v uij Viju ∆ux hc2;ij
Ãh1 (U )uij = Ah1 (U )ij − (5.127)
hu1;ij hu2;ij
5.3.4.2 cross-stream advection of U

The cross-stream advective term in the U -equation (4.75) is obtained by
uv
differencing the flux F 12 at the U-node
uv uv
huv F − huv
1;ij F 12;ij
Ah2 (U )uij = 1;i,j+1 12;i,j+1
u u
(5.128)
h1;ij h2;ij

uv uv uv

F 12;ij = 1 − Ω(rijuv ) F up;ij + Ω(rijuv )F lw;ij (5.129)
uv uv
where F up;ij and F lw;ij are the upwind and Lax-Wendroff fluxes at the UV-
node:
uv 1 uv
F up;ij = v ij (αij + sij )Ui,j−1 + (βij − sij )Uij (5.130)
2
uv 1 uv
F lw;ij = v ij (αij + cij )Ui,j−1 + (βij − cij )Uij ) (5.131)
2
where
v uv ∆τ
sij = Sign(v uv
ij ) , cij = ijuv (5.132)
h2;ij
hu2;ij hu2;i,j−1
αij = , βij = (5.133)
huv
2;ij huv2;ij

uv uv
(αij + sij )∆F i,j−1 + (βij − sij )∆F i,j+1
rijuv = uv
2∆F ij
uv uv uv
∆F ij = F lw;ij − F up;ij (5.134)
The extended advective term is discretised by
v uij Uij ∆uy huv 1;ij
Ãh2 (U )uij = Ah2 (U )ij + (5.135)
hu1;ij hu2;ij
5.3.4.3 cross-stream advection of V

The cross-stream advective term in the V -equation (4.76) is obtained by
uv
differencing the flux F 21 at the V-node
uv uv
huv uv
2;i+1,j F 21;i+1,j − h2;ij F 21;ij
Ah1 (V )vij = (5.136)
hv1;ij hv2;ij
uv uv uv

F 21;ij = 1 − Ω(rijuv ) F up;ij + Ω(rijuv )F lw;ij (5.137)
uv uv
where F up;ij and F lw;ij are the upwind and Lax-Wendroff fluxes at the UV-
node:
uv 1 uv
F up;ij = uij (αij + sij )Vi−1,j + (βij − sij )Vi,j (5.138)
2
uv 1 uv
F lw;ij = uij (αij + cij )Vi−1,j + (βij − cij )Vij (5.139)
2
where
uuv
ij ∆τ
sij = Sign(uuvij ) , c ij = (5.140)
huv
1;ij
hv1;ij hv1;i,j−1
αij = , βij = (5.141)
huv
1;ij huv1;ij

uv uv
(αij + sij )∆F i−1,j + (βij − sij )∆F i+1,j
rijuv = uv
2∆F ij
uv uv uv
∆F ij = F lw;ij − F up;ij (5.142)

uvij Vij ∆vx huv2;ij
Ãh1 (V )vij = Ah1 (V )ij + (5.143)
hv1;ij hv2;ij
5.3.4.4 alongstream advection of V

The alongstream advective term in the V -equation (4.76) is obtained by
c
differencing the flux F 22 at the V-node
c c
hc F − hc F 22;i,j−1
Ah2 (V )vij = 1;ij 22;ij v 1;i,j−1
v
(5.144)
h1;ij h2;ij

c c c

F 22;ij = 1 − Ω(rijc ) F up;ij + Ω(rijc )F lw;ij (5.145)
c c
where F up;ij and F lw;ij are the upwind and Lax-Wendroff fluxes at the C-
node:
c 1 c
F up;ij = v ij (1 + sij )Vij + (1 − sij )Vi,j+1 (5.146)
2
c 1 c
F lw;ij = v ij (1 + cij )Vij + (1 − cij )Vi,j+1 (5.147)
2
v cij ∆τ
sij = Sign(v cij ) , cij = c (5.148)
h2;ij

c c
(1 + sij )∆F i,j−1 + (1 − sij )∆F i,j+1
rijc = c
2∆F ij
c c c
∆F ij = F lw;ij − F up;ij (5.149)

uvij Uijv ∆vy hc1;ij
Ãh2 (V )vij = Ah2 (V )ij − (5.150)
hv1;ij hv2;ij
5.3.5 Integrals of the baroclinic advection terms

The discretised versions of the advective integrals in the 2-D momentum
equations at time step tn are given by
Nz
u

Ãh1 (u)uijk + Ãh2 (u)uijk hu3;ijk − Ãh1 (U )uij − Ãh2 (U )uij
X
δAh1;ij = (5.151)
k=1
Nz
v

Ãh1 (v)vijk + Ãh2 (v)vijk hv3;ijk − Ãh1 (V )vij − Ãh2 (V )vij
X
δAh2;ij = (5.152)
k=1
5.3.6 Discretisation of vertical advection

The vertical advection terms in the 3-D momentum equations are written as
the divergence of the of the vertical fluxes F13 , F23 , defined in Table 5.5:
1 ∂ 1 ∂F13
Av (u) = (ωu) = (5.153)
h3 ∂s h3 ∂s
1 ∂ 1 ∂F23
Av (v) = (ωv) = (5.154)
h3 ∂s h3 ∂s
5.3.6.1 vertical advection of u

The vertical advective term in the u-equation (4.50) is obtained by differen-
uw
cing the flux F13 at the U-node
uw uw
F13;ij,k+1 − F13;ijk
Av (u)uijk = (5.155)
hu3;ijk

uw uw uw uw uw
F13;ijk = 1 − Ω(rijk ) Fup;ijk + Ω(rijk )Fce;ijk (5.156)
uw uw
where Fup;ijk and Fce;ijk are the upwind and central fluxes at the UW-node:
uw 1 uw
Fup;ijk = ωijk (αijk + sijk )uij,k−1 + (βijk − sijk )uijk (5.157)
2
uw 1 uw
Fce;ijk = ω (αijk uij,k−1 + βijk uijk ) (5.158)
2 ijk
where
uw hu3;ijk hu3;ij,k−1
sijk = Sign(ωijk ), αijk = , βijk = (5.159)
huw
3;ijk huw3;ijk

uw uw
uw (αijk + sijk )∆Fij,k−1 + (βijk − sijk )∆Fij,k+1
rijk = uw
2∆Fijk
uw uw uw
∆Fijk = Fce;ijk − Fup;ijk (5.160)
5.3.6.2 vertical advection of v
The vertical advective term in the v-equation (4.51) is obtained by differen-

vw
cing the flux F23 at the V-node
vw vw
F23;ij,k+1 − F23;ijk
Av (v)vijk = (5.161)
hv3;ijk

vw vw vw vw vw
vw vw
where Fup;ijk and Fce;ijk are the upwind and central fluxes at the VW-node:
vw 1 vw
Fup;ijk = ωijk (αijk + sijk )vij,k−1 + (βijk − sijk )vijk (5.163)
2
vw 1 vw
Fce;ijk = ω (αijk vij,k−1 + βijk vijk ) (5.164)
2 ijk
where
vw hv3;ijk hv3;ij,k−1
sijk = Sign(ωijk ), αijk = vw , βijk = vw (5.165)
h3;ijk h3;ijk

vw vw
vw (αijk + sijk )∆Fij,k−1 + (βijk − sijk )∆Fij,k+1
rijk = vw
2∆Fijk
vw vw vw
5.3.7 Discretisation of 3-D horizontal diffusion

The four horizontal diffusion terms in the 3-D momentum equations are
written as the divergence of the horizontal fluxes D11 , D12 , D21 , D22 , defined
in Table 5.5:
1 ∂ 2 1 ∂
Dmh1 (τ11 ) = h 2 h 3 τ 11 = h 2 h 3 D 11 (5.167)
h1 h22 h3 ∂ξ1 h1 h22 h3 ∂ξ1
1 ∂ 2 1 ∂
Dmh2 (τ12 ) = 2 h1 h3 τ12 = h h
1 3 12D (5.168)
h1 h2 h3 ∂ξ2 h21 h2 h3 ∂ξ2
1 ∂ 2 1 ∂
Dmh1 (τ21 ) = h h τ
3 21 = h h
2 3 21D (5.169)
h1 h22 h3 ∂ξ1 2 h1 h22 h3 ∂ξ1
1 ∂ 2 1 ∂
Dmh2 (τ22 ) = 2 h1 h3 τ22 = h 1 h 3 D 22 (5.170)
h1 h2 h3 ∂ξ2 h21 h2 h3 ∂ξ2
Discretisations for the horizontal diffusion terms in the 3-D momentum

equations are given below. For simplicity, the k-index and time level will be
omitted.
• alongstream diffusion in the u-equation (4.50) at the U-node
hc2;ij hc3;ij D11;ij

c
− hc2;i−1,j hc3;i−1,j D11;i−1,j
c
Dmh1 (τ11 )uij = (5.171)
hu1;ij (hu2;ij )2 hu3;ij
h hc u hc1;ij c vij i
c c 2;ij c ij
D11;ij = νH;ij hc2;ij ∆ − ∆ (5.172)
hc1;ij x hu2;ij hc2;ij y hv1;ij
• cross-stream diffusion in the u-equation (4.50) at the U-node
huv uv uv uv uv uv
1;i,j+1 h3;i,j+1 D12;i,j+1 − h1;ij h3;ij D12;ij
Dmh2 (τ12 )uij = (5.173)
(hu1;ij )2 hu2;ij hu3;ij
h huv u huv
ij 2;ij uv vij
i
uv uv 1;ij uv
D12;ij = νH;ij huv
1;ij ∆y + ∆ x (5.174)
huv
2;ij hu1;ij huv
1;ij hv2;ij
• cross-stream diffusion in the v-equation (4.51) at the V-node
huv uv uv uv uv uv
2;i+1,j h3;i+1,j D21;i+1,j − h2;ij h3;ij D21;ij
Dmh1 (τ21 )vij = (5.175)
hv1;ij (hv2;ij )2 hv3;ij
h huv u huv
ij uv vij
i
1;ij uv
uv
D21;ij = uv
νH;ij huv
2;ij ∆y + 2;ij ∆ x (5.176)
huv
2;ij hu1;ij huv
1;ij hv2;ij
• alongstream diffusion in the v-equation (4.51) at the V-node
hc1;ij hc3;ij D22;ij

c
− hc1;i,j−1 hc3;i,j−1 D22;i,j−1
c
Dmh2 (τ22 )vij = (5.177)
(hv1;ij )2 hv2;ij hv3;ij
h hc v hc2;ij c uij i
c c 1;ij c ij
D22;ij = νH;ij hc1;ij ∆ − c ∆x u (5.178)
h2;ij y
c
hv1;ij h1;ij h2;ij
5.3.8 Discretisation of 2-D horizontal diffusion

The four horizontal diffusion terms in the 2-D momentum equations are
written as the divergence of the horizontal fluxes D11 , D12 , D21 , D22 , defined
in Table 5.5:
1 ∂ 2 1 ∂
Dmh1 (τ11 ) = h τ11 = h 2 D 11 (5.179)
h1 h22 ∂ξ1 2 h1 h22 ∂ξ1
1 ∂ 2 1 ∂
Dmh2 (τ12 ) = 2 h τ12 = h1 D12 (5.180)
h1 h2 ∂ξ2 1 2
h1 h2 ∂ξ2
1 ∂ 2 1 ∂
Dmh1 (τ21 ) = h τ21 = h D
2 21 (5.181)
h1 h22 ∂ξ1 2 h1 h22 ∂ξ1
1 ∂ 2 1 ∂
Dmh2 (τ22 ) = 2 h τ22 = h D
1 22 (5.182)
h1 h2 ∂ξ2 1 h21 h2 ∂ξ2
Discretisations for the horizontal diffusion terms in the 2-D momentum

equations are given below.
• alongstream diffusion in the U -equation (4.75) at the U-node

c c
hc D − hc D11;i−1,j
Dmh1 (τ11 )uij = 2;ij 11;ij u 2;i−1,j
u
(5.183)
h1;ij (h2;ij )2
c
h hc u hc1;ij c v ij i
2;ij c ij
D11;ij = νH cij hc2;ij ∆ − c ∆y v (5.184)
h1;ij x
c
hu2;ij h2;ij h1;ij
• cross-stream diffusion in the U -equation (4.75) at the U-node

uv uv
huv D − huv 1;ij D 12;ij
Dmh2 (τ12 )uij = 1;i,j+1 12;i,j+1
u u
(5.185)
(h1;ij )2 h2;ij
h huv u huv
uv ij uv v ij
i
1;ij uv
D12;ij = νH uv uv
ij h1;ij ∆ + 2;ij ∆ (5.186)
h2;ij y
uv
hu1;ij huv
1;ij
x
hv2;ij
• cross-stream diffusion in the V -equation (4.76) at the V-node

uv uv
huv uv
2;i+1,j D 21;i+1,j − h2;ij D 21;ij
Dmh1 (τ21 )vij = (5.187)
hv1;ij (hv2;ij )2
h huv u huv
uv ij uv v ij
i
1;ij uv
D21;ij = νH uv uv
ij h2;ij ∆ + 2;ij ∆ (5.188)
h2;ij y
uv
hu1;ij huv
1;ij
x
hv2;ij
• alongstream diffusion in the V -equation (4.76) at the V-node

c c
hc1;ij D22;ij − hc2;i,j−1 D22;i,j−1
Dmh2 (τ22 )vij = (5.189)
(hv1;ij )2 hv2;ij
c
h hc v hc2;ij c uij i
1;ij c ij
D22;ij = νH cij hc1;ij ∆ − c ∆x u (5.190)
h2;ij y
c
hv1;ij h1;ij h2;ij
5.3.9 Integrals of the baroclinic diffusion terms

The discretised versions of the diffusion integrals in the 2-D momentum equa-
tions are given by
Nz
u

Dmh1 (τ11 )uijk + Dmh2 (τ12 )uijk hu3;ijk − Dmh1 (τ11 )uij − Dmh2 (τ12 )uij
X
δDh1;ij =
k=1
(5.191)
Nz
v

Dmh1 (τ21 )vijk + Dmh2 (τ22 )vijk hv3;ijk − Dmh1 (τ21 )vij − Dmh2 (τ22 )vij
X
δDh2;ij =
k=1
(5.192)
5.3.10 Discretisation of vertical diffusion

The vertical diffusion terms in the 3-D momentum equations are written as
the divergence of the vertical fluxes D13 , D23 , defined in Table 5.5:
!
1 ∂ νT ∂u 1 ∂D13
Dmv (u) = = (5.193)
h3 ∂s h3 ∂s h3 ∂s
!
1 ∂ νT ∂v 1 ∂D23
Dmv (v) = = (5.194)
h3 ∂s h3 ∂s h3 ∂s
(5.195)
• The vertical diffusion term in the u-equation (4.50) is obtained by dif-

uw
ferencing the flux D13 at the U-node
uw uw
D13;ij,k+1 − D13;ijk
Dmv (u)uijk = (5.196)
hu3;ijk

uw νTuw;ijk u
D13;ijk = uw ∆z uijk (5.197)
h3;ijk
• The vertical diffusion term in the v-equation (4.51) is obtained by dif-

vw
ferencing the flux D23 at the V-node
vw vw
D23;ij,k+1 − D23;ijk
Dmv (v)vijk = (5.198)
hv3;ijk

vw νTvw;ijk v
D23;ijk = vw ∆z vijk (5.199)
h3;ijk
5.3.11 Diffusion coefficients for momentum

5.3.11.1 horizontal diffusion coefficients
This section describes the discretisation of the horizontal diffusion coeffi-
cients for the case that a Smagorinsky scheme has been selected. Firstly, the
horizontal tension and shearing are calculated at their “natural” node
hc2;ij c uijk hc1;ij c vijk
DTc ;ijk = ∆ − c ∆y v (5.200)
hc1;ij x hu2;ij h2;ij h1;ij
uv huv
1;ij uv uijk
huv
2;ij uv vijk

DS;ijk = uv ∆y + ∆ x (5.201)
h2;ij hu1;ij huv
1;ij hv2;ij
The discretised values of the horizontal diffusion coefficient at the C- and
corner nodes are obtained by applying (4.41)
r
2 2
c
νH;ijk = Cm hc1;ij hc2;ij DTc ;ijk c
+ DS;ijk (5.202)
r
2 2
uv
νH;ijk = Cm huv uv
1;ij h2;ij DTuv;ijk uv
+ DS;ijk (5.203)
Note that the (5.202) and (5.203) only require the interpolation of either DS
at the C-node or DT at the UV-node but not both.
The 2-D coefficients are obtained by vertical integration

Nz
νH cij c
hc3;ijk
X
= νH;ijk (5.204)
k=1
Nz
νH uv uv
huv
X
ij = νH;ijk 3;ijk (5.205)
k=1
5.3.11.2 vertical diffusion coefficient

The vertical diffusion coefficient for momentum νT is obtained from one of
the available turbulence schemes, described in Section 4.4. Values are first
stored at the W-nodes and interpolated afterwards at the UW- and VW-
nodes for the calculation of the vertical diffusion fluxes in the momentum
equations. The evaluation of νT only involves algebraic expressions so that
the discretisation procedure is straightforward.
The following comments are to be given

• To avoid spurious numerical oscillations the squared buoyancy fre-
quency N 2 is spatially discretised by averaging over the neighbouring
cells in the horizontal:
2 h
w
Nijk = 2wij (Ñijk )2 + wi−1,j (Ñi−1,jk )2 + wi+1,j (Ñi+1,jk )2
i
wi,j−1 (Ñi,j−1,k )2 + wi,j+1 (Ñi,j+1,k )2
h i−1
2wij + wi−1,j + wi+1,j + wi,j−1 + wi,j+1 (5.206)
where
2 βTw;ijk (Tijk
c c
− Tij,k−1 w
) − βS;ijk c
(Sijk c
− Sij,k−1 )
Ñijk = (5.207)
hw 3;ijk
is the unfiltered value of N 2 and wij equals 0 on land and 1 on sea

cells. The expansion coefficients βT and βS are first obtained from the
equation of state at the C-node and then interpolated at the W-nodes.
• The squared shear frequency M 2 is discretised using

w 2
(ucijk − ucij,k−1 )2 + (vijk c c
− vij,k−1 )2
Mijk = (5.208)
(hw 3;ijk )
2
Note that the currents are interpolated first at the C-nodes before the
vertical derivative is taken.
• The Richardson number is obtained using its definition Ri = N 2 /M 2 .

An upper limit of 1000 is imposed to prevent division by zero if N 2 ≫
M 2.
• If the vertical diffusion coefficient is derived from a RANS model (see

Section 4.4.3), its value is not known at the surface and the bottom.
Its evaluation involves the turbulent parameters k, ε or l which are
obtained from algebraic relations or by solving additional transport
equations. This is further discussed in Section 5.6.
5.3.12 Discretisation of the baroclinic pressure gradi-

ent
A known problem is the numerical treatment of the baroclinic pressure gra-
dient for σ-coordinate models. Two types of errors may occur
• The two terms on the right hand side of (4.63) may have the same
magnitude and different signs. Significant rounding errors may arise,
especially in case of large bathymetric gradients.
• Violation of the hydrostatic consistency condition which states that a

σ-surface immediately below (above) a given σ-surface remains below
(above) the given σ-surface within a horizontal distance of one grid
interval
σ ∂H
∆xi < ∆σ (5.209)

H ∂xi

where ∆xi is the grid resolution in the X- or Y-direction and ∆σ the

vertical resolution in σ-space.
For further discussion and examples are found in Haney (1991); Kliem &
Pietrzak (1999).
Several solutions have been proposed: fourth order (McCalpin, 1994)
or sixth order (Chu & Fan, 1997) discretisations, “z”-level based methods
(Beckmann & Haidvogel, 1993; Stelling & Van Kester, 1994; Slørdal, 1997),
second order method using unequal weighting (Song, 1998), cubic polyno-
mial interpolation using harmonic averaging (Shchepetkin & McWilliams,
2003). Three algorithms are implemented in the code: the “traditional”
second-order discretisation, a simple z-level method and the Shchepetkin &
McWilliams (2003) approach.
Before discussing the implemented algorithms, the baroclinic pressure
gradient is rewritten in a more convenient form. In Cartesian coordinates,
the last term on the right of (4.45) can be written as

∂q ∂ Z ζ ρ
− = −g − 1 dz ′
∂xi ∂xi z ρ0
Z ζ
∂ ρ ρ
s
∂ζ
= −g − 1 dz ′ − g −1
z ∂xi ρ0 ρ0 ∂xi
g Z ζ ∂ρ ′
≃ − dz
ρ0 z ∂xi
Z ζ
∂T ∂S ′
≃ g βT − βS dz (5.210)
z ∂xi ∂xi
where use is made of the Boussinesq approximaion. The last line is obtained
by applying the equation of state, taking account that T represents potential
and not in situ temperature. The latter approximation is at least valid for
non-oceanic waters.
In transformed coordinates, equation (5.210) becomes
Z ζ ∂T ∂T ∂z ′ ′ Z ζ ∂S ∂S ∂z ′ ′
Fib = g βT −

′
dz − g βS −

′
dz
∂xi ∂z ∂xi ∂xi ∂z ∂xi

z σ σ z σ σ
T
= Fi + FiS (5.211)

where a means a derivative along a surface of constant σ.

σ
The implemented discretisations for F1T are discussed below. Algorithms
for the salinity and Y-component are obtained in a similar way.
5.3.12.1 second-order method

The scheme uses a straightforward discretisation of (5.211)
T giju u
FijN = β ∆u (TijNz )hu3;ijNz
z
2hu1;ij T ;ijNz x
gu
T
Fij,k−1 T
= Fijk + uij βTuw;ijk huw uw w uw u uw w
3;ijk ∆x (Tijk ) − ∆z (Tijk )∆x (zijk )
h1;ij
(5.212)
for Nz ≥ k ≥ 2.
5.3.12.2 z-level method

The z-level scheme evaluates the horizontal gradient by vertically interpo-
lating the values of T at the C-node to the vertical level of the U-node (see
u
Figure 5.6). If zijk denotes the “physical” z-level of the U-node where the
gradient has to be evaluated, the X-component of the gradient is obtained

by vertically interpolating the C-node temperature values in the adjacent
columns (i-1,j) and (i,j) to the vertical level of the U-node. Denoting this
L R
values by respectively Tijk and Tijk , the pressure gradient is readily evaluated
using (5.210):
T giju u R L
FijN = u
βT ;ijNz (Tijk − Tijk )hu3;ijNz
z
2h1;ij
gu
T
Fij,k−1 T
= Fijk + uij βTuw;ijk (Tijk
R
− TijkL
)huw
3;ijk (5.213)
h1;ij
The following restrictions apply:
L R
• If the vertical position of Tijk or Tijk is below the lowest grid point, its
value is set to Tij1 .
L R
• If the vertical position of Tijk or Tijk is above the highest grid point,
its value is set to TijNz .
Despite its simplicity and the fact that it avoids the truncation problem of the
σ-grid, the scheme may produce unrealistic results near the bottom (surface)
or adjacent to a sloping boundary.
5.3.12.3 cube-H method
The “cube-H” algorithm is probably the most robust scheme, but at the
expense of a larger CPU time. The method uses a cubic spline formalism
together with harmonic averaging. Details of the scheme are not given here
but can be found in the paper of Shchepetkin & McWilliams (2003).
Omitting the j-index for simplicity, the following procedure is taken
1. Evaluate the integral at the W-nodes

c
Z σi,k+1 ∂z
F Wik = T dσ (5.214)
c
σik ∂σ
giving
1
F Wi,Nz +1 = TiNz hc3;iNz (5.215)
2
i−1
i
T i−1,k+1
L R
T i,k+1 T i−1,k+1
T i−1,k
T i,k+1
R
L T i−1,k
T i,k
T i−1,k−1 T i,k
L R
T i,k−1 T i−1,k−1
T i,k−1
Figure 5.6: Illustration of the z-level interpolation scheme. C- and U-nodes

are represented by empty, respectively solid circles.
1 c c
F Wik = (Ti,k−1 + Tik )(zik − zi,k−1 )
2
1h
c c 1 c c

− (dz Tik − dz Ti,k−1 ) zik − zi,k−1 − (dz zi,k−1 + dz zik )
10 12
c c
1 i
− (dz zik − dz zi,k−1 ) Tik − Ti,k−1 − (dz Ti,k−1 + dz Tik )
12
(5.216)
where 2 ≤ k ≤ Nz .
2. Evaluate the integral at the UW-nodes
c
Z ξ1;i+1,k ∂z
F Uik = T dξ1 (5.217)
c
ξ1;ik ∂ξ1
giving
F Ui,Nz +1 = 0 (5.218)
1 c c
F Uik = (Ti−1,k + Tik )(zik − zi−1,k )
2
1h
c c 1 c c

− (dx Tik − dx Ti−1,k ) zik − zi−1,k − (dx zi−1,k + dx zik )
10 12
c c
1 i
− (dx zik − dx zi−1,k ) Tik − Ti−1,k − (dx Ti−1,k + dx Tik )
12
(5.219)
3. The algorithms for the derivatives in (5.216) and (5.219) are given by:
• Vertical derivatives
2(fi,k+1 − fik )(fik − fi,k−1 )
dz fik = if (fi,k+1 − fik )(fik − fi,k−1 ) > 0
fi,k+1 − fi,k−1
dz fik = 0 otherwise
(5.220)
Values at the boundaries are
6 7
dz fi1 = (fi2 − fi1 ) − dz fi2
5 15
6 7
dz fiNz = (fiNz − fi,Nz −1 ) − dz fi,Nz −1 (5.221)
5 15
• Horizontal derivatives
2(fi+1,k − fik )(fik − fi−1,k )
dx fik = if (fi+1,k − fik )(fik − fi−1,k ) > 0
fi+1,k − fi−1,k
dx fik = 0 otherwise
(5.222)
Boundary conditions are
i − 1 dry, i+1 wet : dx fik = 65 (fi+1,k − fik ) − 7
d f
15 x i+1,k
i − 1 wet, i+1 dry : dx fik = 65 (fik − fi−1,k ) − 7
d f
15 x i−1,k
i − 1 dry, i+1 dry : dx fik = 0
(5.223)
4. Evaluate the “temperature Jacobian” at the UW-node
1 ∂T ∂z 1 ∂T ∂z
I(T, z) = − (5.224)
h1 ∂ξ1 σ ∂σ h1 ∂σ ∂ξ1 σ

giving
uw giu βTuw;ik
Iik = (F Wik − F Wi−1,k − F Uik + F Ui,k−1 ) (5.225)
hu1;i
for 2 ≤ k ≤ Nz .
5. Evaluate the baroclinic gradient

NX
z +1
FikT = uw
Iik ′ (5.226)
k′ =k+1
for 1 ≤ k ≤ Nz , or
T giu u
FiN = β ∆u (TiNz )hu3;iNz
z
2hu1;i T ;iNz x
T
Fi,k−1 = FikT + Iik (5.227)
for 2 ≤ k ≤ Nz .
5.3.13 Tidal force

If the astronomical tidal force is included in the momentum equations4 , the
components of the force are updated at each internal (3-D) time step. Tidal
constituents for the harmonic expansion are selected by the user.
The procedure is the following:
• The astronomical Greenwich arguments and nodal factors are updated

using the expressions given in Section 4.5 if requested. Otherwise
fqn (tm+1 ) ≃ fqn (tm )

m+1 m
Pqn ≃ Pqn + ∆τ ωqn (5.228)
m
where Pqn = Vqn (tm ) + uqn (tm ) and ωqn are the frequencies of the tidal
constituents56 .
• The tidal amplitudes Am+1

qn are calculated using (4.220).
• The components of the tidal force are determined using (4.219) and
(4.218)
t;u giju h 3 u u c
N0
X
F1;ij = − u sin(2φij )∆x (φij ) A0n cos(P0n;ij )
h1;ij 2 n=1
N1
sin(2φuij )∆ux (λcij ) A1n sin(λuij + P1n;ij )
X
+
n=1
4
The astronomical tidal force can only be taken into account if a spherical grid is
selected.
5
Time is converted to GMT if necessary.
6
Equation (5.228) is applied in double precision arithmetic to avoid truncation errors.
N1
− 2 cos(2φuij )∆ux (φcij ) A1n cos(λuij + P1n;ij )
X
n=1
N2
+ (1 + cos(2φuij ))∆ux (λcij ) A2n sin(2λuij + P2n;ij )
X
n=1
N2
+ sin(2φuij )∆ux (φcij ) A2n cos(2λuij + P2n;ij )
X
n=1
N3
3
+ (3 cos φuij + cos(3φuij ))∆ux (λcij ) A3n sin(3λuij + P3n;ij )
X
4 n=1
N3
3 i
+ (sin φuij + sin(3φuij ))∆ux (φcij ) A3n cos(3λuij + P3n;ij )
X
4 n=1
(5.229)
and
t;v gijv h 3 v v c
N0
X
F2;ij = − sin(2φ ij )∆ y (φ ij ) A0n cos(P0n;ij )
hv2;ij 2 n=1
N1
sin(2φvij )∆vy (λcij ) A1n sin(λvij + P1n;ij )
X
+
n=1
N1
− 2 cos(2φvij )∆vy (φcij ) A1n cos(λvij + P1n;ij )
X
n=1
N2
cos(2φvij ))∆vy (λcij ) A2n sin(2λvij + P2n;ij )
X
+ (1 +
n=1
N2
+ sin(2φvij )∆vy (φcij ) A2n cos(2λvij + P2n;ij )
X
n=1
N3
3
+ (3 cos φvij + cos(3φvij ))∆vy (λcij ) A3n sin(3λvij + P3n;ij )
X
4 n=1
N3
3 i
+ (sin φvij + sin(3φvij ))∆vy (φcij ) A3n cos(3λvij + P3n;ij )
X
4 n=1
(5.230)
5.3.14 Surface and bottom boundary conditions

5.3.14.1 surface boundary conditions
Application of the surface boundary conditions (4.254) and (4.253) gives
F13;ij,Nz +1 = 0 , F23;ij,Nz +1 = 0 (5.231)

and
u v
D13;ij,Nz +1 = τs1;ij , D23;ij,Nz +1 = τs2;ij (5.232)
for respectively the vertical advective and diffusive fluxes of momentum at
the surface.
The components of the surface stress are calculated as function of me-
teorological variables. Different options are available and discussed in Sec-
tion 4.8.
The following steps are taken
• The meteorological data are interpolated at the C-nodes of the model

grid.
• The surface drag coefficient Cds and the components of the surface
stress are determined at the C-nodes.
• The stress components are interpolated at respectively the U- and V-

node.
In the case that the surface drag and exchange are calculated using the
Monin-Obukhov formulation, described in Section 4.8.3, the system of four
equations (4.315), (4.318), (4.319) and (4.320) needs to solved at each model
grid point and time step using a time-consuming iteration procedure. The
following simplifying procedure is taken in the program
• The equations generally depend on five meteorological variables: the

magnitude of the surface wind W , air temperature Ta , sea surface tem-
perature Ts , relative humidity RH and atmospheric pressure Pa . The
following simplications are made
– The atmospheric pressure enters the equations only indirectly to

evaluate the surface humidity and is taken as constant in the equa-
tions, i.e. Pa = Pref .
– Tests showed a larger dependence on the air minus sea tempe-
rature difference ∆T than on the individual values of Ta and Ts
itself. Letting Ts = Ts;ref one has Ta = Ts;ref + ∆T .
The equations now only depend on three variables: W , ∆T , RH
• The equations are solved for Cds , Ce , Ch on a “discretised” grid at the

initial time
Wmax − Wmin
W = Wmin + lδW for l = 0, NW ; NW =
δW
∆Tmax − ∆Tmin
∆T = ∆Tmin + mδ(∆T ) for m = 0, NT ; NT =
δ(∆T )
RHmax − RHmin
RH = RHmin + nδRH for n = 0, NR ; NR =
δR
(5.233)
The following default values are taken
Wmin = 3 , Wmax = 50 , δW = 0.25 (m/s)

∆Tmin = −5 , ∆Tmax = 5 , δ(∆T ) = 1 (0 C)
RHmin = 0.5 , RHmax = 1.0 , δR = 0.05 (5.234)
The lower limit Wmin =3 m/s is taken since the equations diverge in the
case of the free-convection limit W → 0 and ∆T > 0. The computed
values are stored in 3-D arrays.
• The values of the drag and exchange coefficients are then obtained at
a specific time by a tri-linear inperpolation from the discretised values.
Extrapolation is used if necessary.
5.3.14.2 bottom boundary conditions

The bottom boundary condition for vertical advection is the same as the one
applied at surface (see equation (4.331)) so that
F13;ij1 = 0 , F23;ij1 = 0 (5.235)
If the bottom stress is parameterised using the bottom values of the 3-D
current, vertical diffusion is treated implicitly. The flux bottom boundary
conditions (4.328) are then discretised as
n;u n+1 n;u n
D13;ij1 = θv kb;ij uij1 + (1 − θv )kb;ij uij1 (5.236)
n;v n+1 n;v n
D23;ij1 = θv kb;ij vij1 + (1 − θv )kb;ij vij1 (5.237)
where θv is the implicity factor for vertical diffusion and the friction velocities
are defined by
u v
no bottom stress (4.325) : kb;ij = kb;ij =0
u v
linear bottom stress (4.326) : kb;ij = kb;ij = klin
1/2
u u n;u 2
3-D quadratic law (4.328) : kb;ij = Cdb;ij (unij1 )2 + (vij1 )
1/2
v
: kb;ij v
= Cdb;ij (un;v 2 n 2
ij1 ) + (vij1 )
(5.238)
If the bottom stress is expressed in terms of the depth mean current, the
bottom flux is discretised explicitly
n;u n
D13;ij1 = kb;ij uij (5.239)
n;v n
D23;ij1 = kb;ij v ij (5.240)
where the friction velocity is given by (5.238) in the absence of a bottom

stress or a linear friction law and
1/2
u
kb;ij u
= Cdb;ij (unij )2 + (v n;u
ij )
2
1/2
v
kb;ij v
= Cdb;ij (un;v 2 n 2
ij ) + (v ij ) (5.241)
The bottom drag coefficient is discretised using (5.18) or specified externally.
5.3.15 Lateral boundary conditions for the 2-D mode

5.3.15.1 open boundary conditions for transports
Open boundary conditions for the 2-D mode are discussed in Section 4.10.1.
The aim is to provide values of U at U- and of V at V-open boundaries.
External data can be generally expressed as the sum of a non-harmonic and
an harmonic part as given by (4.340). The expression is updated at each
time step for the requested locations and variables (U , V or ζ) depending on
the type of conditions, prior to the application of the boundary conditions
itself.
The tidal constituents are selected by the user. In analogy with the
astronomical tide (see Section 5.3.13), the space-independent astronomical
phases are calculated by using either the expressions in Section 4.5 with time
converted to GMT if needed, or the linear approximation
Plm+1 = Vlm+1 + um+1

l ≃ V l m + um
l + ωl δτ (5.242)
where ωl are the tidal frequencies. Note that (5.242) is evaluated in double
precision to avoid truncation errors for long integration periods.
The following notations are introduced
• ± or ∓: The upper (lower) sign applies at a western/southern (east-

ern/northern) open boundary.
• Xi:i−1,j : The quantity X is evaluated at grid point (i,j) for a western

and at (i − 1,j) for an eastern boundary.
• Yi,j:j−1 : The quantity Y is evaluated at grid point (i,j) for a southern

and at (i,j − 1) for a northern boundary.
• Uije , Vije , ζije denote externally specified values (harmonic or time series
data).
• sij equals 1 if ζije is defined at an exterior C-node and 2 if ζije is defined

at an open boundary U- or V-node.
• The gravity wave speed at the C-node nearest to the U- or V-open

boundary location (i,j) is defined by
q q
cuij = c
gi:i−1,j c
Hi:i−1,j , cvij = c
gi,j:j−1 c
Hi,j:j−1 (5.243)
• The following auxiliary parameters are defined at U- or V-nodes
u ∆τ cuij v ∆τ cvij
αij = , αij = (5.244)
hc1;i:i−1,j hc2;i,j:j−1
hc1;i:i−1,j hc2;i,j:j−1
riju = , rijv = (5.245)
hu1;ij hv2;ij
The discretised versions of all available open boundary conditions are

listed below using the same numbering system as in Section 4.10.1.
0. Clamped (see equation (4.343)).
Uijm+1 = Uijm , Vijm+1 = Vijm (5.246)
1. Zero slope (see equation (4.344)).

m+1;c m;c
Uijm+1 = Uijm + ∆τ fiju (θc Vi:i−1,j + (1 − θc )Vi:i−1,j )

+ Hijm+1;u F1;ij
t;m+1 c
+ τs1;ij n;u
− τb1;ij (5.247)

m+1;c m;c
Vijm+1 = Vijm − ∆τ fijv (θc Ui,j:j−1 + (1 − θc )Ui,j:j−1 )

− Hijm+1;v F2;ij
t;m+1 c
− τs2;ij n;u
+ τb2;ij (5.248)
Note that the bottom stress components are evaluated at the old time
tn .
2. Zero volume flux (see equation (4.345)).
Uijm+1 = Ui+1:i−1,j
m+1
, Vijm+1 = Vi,j+1:j−1
m+1
(5.249)
3. Specified elevation (see (equation 4.346)).

Uijm+1 = UijL;m+1
= UijL;m ∓ suij αij
u u u m+1
cij rij (ζi:i−1,j − ζije )

m+1;c m;c
+ ∆τ fiju (θc Vi:i−1,j + (1 − θc )Vi:i−1,j )

+ Hijm+1;u F1;ij
t;m+1 c
+ τs1;ij n;u
− τb1;ij
(5.250)
Vijm+1 = VijL;m+1
= VijL;m ∓ svij αij
v v v m+1
cij rij (ζi,j:j−1 − ζije )

m+1;c m;c
− ∆τ fijv (θc Ui,j:j−1 + (1 − θc )Vi,j:j−1 )

− Hijm+1;v F2;ij
t;m+1 c
− τs2;ij n;v
+ τb2;ij
(5.251)
4. Specified transport (see equation (4.347)).

Uijm+1 = Uije , Vijm+1 = Vije (5.252)
5. Radiation condition using shallow water speed (see equation (4.349)).

u m+1
Uijm + αij Ui+1:i−1,j
Uijm+1 = u
1 + αij
m+1
Vijm + αij
v
Vi,j+1:j−1
Vijm+1 = v
(5.253)
1 + αij
6. Orlanski (1976) condition (see equation (4.350)).

Uijm+1 = 1 − OR (r1;ij
u u
, r2;ij u
, r3,ij ) Uijm + OR (r1;ij
u u
, r2;ij u
, r3,ij m
)Ui+1:i−1,j
(5.254)

Vijm+1 = 1 − OR (r1;ij
v v
, r2;ij v
, r3,ij ) Vijm + OR (r1;ij
v v
, r2;ij v
, r3,ij m
)Vi,j+1:j−1
(5.255)
The Orlanski weight function is defined by
r1 − r2
OR (r1 , r2 , r3 ) = min max( , 0), 1 if r2 6= r3
r3 − r2
OR (r1 , r2 , r3 ) = 0 if r2 = r3 and r1 ≤ r2
OR (r1 , r2 , r3 ) = 1 if r2 = r3 and r1 > r2
(5.256)
The arguments of the weight functions are defined by

u m u m−1 u m−1
r1;ij = Ui+1:i−1,j , r2;ij = Ui+1:i−1,j , r3;ij = Ui+2:i−2,j (5.257)
v m v m−1 v m−1
r1;ij = Vi,j+1:j−1 , r2;ij = Vi,j+1:j−1 , r3;ij = Vi,j+2:j−2 (5.258)
7. Camerlengo & O’Brien (1980).
Uijm+1 = Ui+1:i−1,j
m m
if Ui+1:i−1,j m−1
≥ Ui+2:i−2,j
(5.259)
Uijm+1 = Uijm otherwise
Vijm+1 = Vi,j+1:j−1
m m
if Vi,j+1:j−1 m−1
≥ Vi,j+2:j−2
(5.260)
Vijm+1 = Vijm otherwise
8. Flather (1976) with specified elevation and transport (see equation

(4.352)).
1
Uijm+1 = Uije ∓ suij cuij (ζi:i−1,j
m+1
− ζije )
2
1
Vijm+1 = Vije ∓ svij cvij (ζi,j:j−1
m+1
− ζije ) (5.261)
2
9. Flather with specified elevation (see equation (4.353)).
1
Uijm+1 = UijL;m+1 ∓ suij cuij (ζi:i−1,j
m+1
− ζije )
2
m+1 L;m+1 1 v v m+1
Vij = Vij ∓ sij cij (ζi,j:j−1 − ζije ) (5.262)
2
where U L , V L are the local solutions obtained from (5.250) and (5.251).
10. Røed & Smedstad (1984) (see equations (4.354)—(4.355)).

The local solution for ζ is determined from
∆τ (hv1;i:i−1,j+1 Vi:i−1,j+1
m
− hv1;i:i−1,j Vi:i−1,j
m
)
ζijL;m+1 = ζijL;m − c c
(5.263)
h1;i:i−1,j h2;i:i−1,j
at U-nodes, and
∆τ (hu2;i+1,j:j−1 Ui+1,j:j−1
m
− hu2;i,j:j−1 Ui,j:j−1
m
)
ζijL;m+1 = ζijL;m − c c
(5.264)
h1;i,j:j−1 h2;i,j:j−1
at V-nodes.
The transports U and V are obtained using
Uijm+1 = UijL;m+1 ∓ cuij (ζi:i−1,j

m+1
− ζijL;m+1 ) (5.265)
Vijm+1 = VijL;m+1 ∓ cvij (ζi,j:j−1
m+1
− ζijL;m+1 ) (5.266)
where the local solutions UijL;m+1 , UijL;m+1 are given by (5.250) and
(5.251).
11. Characteristic method with specified elevation and transport.

Using the notations of Section 4.10.1 the transports are calculated as
the average between the incoming (Ri ) and outgoing (Ro ) characteristic
1 m+1;u m+1;u
Uijm+1 = (Ri;ij + Ro;ij )
2
1 m+1;v m+1;v
Vijm+1 = (Ri;ij + Ro;ij ) (5.267)
2
The incoming characteristic Ri is defined by equations (4.359) using
prescribed values for transports and elevations
m+1;u 1
Ri;ij = Uije ± cuij suij ζije + (2 − suij )ζi:i−1,j
m+1
2
m+1;v 1
Ri;ij = Vije ± cvij svij ζije + (2 − svij )ζi,j:j−1
m+1
(5.268)
2
The outgoing characteristic Ri is obtained by solving the discretised
versions of equations (4.357)–(4.358):
3 u u m+1;u m;u
(1 + αij rij )Ro;ij = Ro;ij
2
u u m+1 1 m+1;u
+ αij rij (Ui+1:i−1,j + Ri;ij ∓ 2cuij ζi:i−1,j
m+1
)
2
u
αij
+ c ±(hv1;i:i−1,j+1 Vi:i−1,j+1
m
m
)
h2;i:i−1,j

m;c
+ Ui:i−1,j (hu2;i+1:i−1,j − hu2;ij )

m+1;c m;c
+∆τ fiju (θc Vi:i−1,j + (1 − θc )Vi:i−1,j ) + Hijm+1;u F1;ij
t;m+1 c
+ τs1;ij n;u
− τb1;ij
(5.269)
and
3 v v m+1;v m;v
(1 + αij rij )Ro;ij = Ro;ij
2
v v m+1 1 m+1;v
+ αij rij (Vi,j+1:j−1 + Ri;ij ∓ 2cvij ζi,j:j−1
m+1
)
2
αv
+ c ij ±(hu2;i+1,j:j−1 Ui+1,j:j−1
m
m
)
h1;i,j:j−1

m;c
+ Vi,j:j−1 (hv1;i,j+1:j−1 − hv1;ij )

m+1;c m;c
−∆τ fijv (θc Ui,j:j−1 + (1 − θc )Ui,j:j−1 ) − Hijm+1;v F2;ij
t;m+1 c
− τs2;ij n;v
+ τb2;ij
(5.270)
Note that the propagation term is integrated fully implicitly and Uijm+1 ,
Vijm+1 have been eliminated in (5.269)–(5.270) by substituting for Rim+1;u
and Rim+1;v from (5.268).
12. Characteristic method with specified elevation.

The method is as previous with Uije , Vije replaced by the local solutions
UijL;m+1 , VijL;m+1 from (5.250) and (5.251).
13. Characteristic method using zero normal gradient.

The method is the same as previous except that the incoming character-
istics are obtained as solutions of the discretised versions of equations
(4.361)–(4.362):
m+1;u m;u
Ri;ij = Ri;ij
αu
− c ij ±(hv1;i:i−1,j+1 Vi:i−1,j+1
m
m
)
h2;i:i−1,j

c;m
+ Ui:i−1,j (hu2;i+1:i−1,j − hu2;ij )

m+1;c m;c
+ ∆τ fiju (θc Vi:i−1,j + (1 − θc )Vi:i−1,j ) + Hijm+1;u F1;ij
t;m+1 c
+ τs1;ij n;u
− τb1;ij
(5.271)
and
m+1;v m;v
Ri;ij = Ri;ij
v
αij
− c ±(hu2;i+1,j:j−1 Ui+1,j:j−1
m
m
)
h1;i,j:j−1

c;m
+ Vi,j:j−1 (hv1;i,j+1:j−1 − hv1;ij )

m+1;c m;c
− ∆τ fijv (θc Ui,j:j−1 + (1 − θc )Ui,j:j−1 ) − Hijm+1;v F2;ij
t;m+1 c
− τs2;ij n;v
+ τb2;ij
(5.272)
5.3.15.2 open boundary conditions for 2-D advective and diffusive

fluxes
Two schemes are available to evaluate the cross-stream advective fluxes in the
U -equation at Y-open boundaries or in the V -equation at X-open boundaries
1. The first one uses a zero gradient condition
uv uv uv uv
F 12;ij = F 12;i,j+1:j−1 or F 21;ij = F 21;i+1:i−1,j (5.273)
which is the same as before.
2. The flux is determined using the upwind scheme (where possible). This
means that
uv 1 uv
F 12;ij = v ij (1 + sij )Ui,j−1:j + (1 − sij )Ui,j:j−1 or
2
uv 1 uv
F 21;ij = uij (1 + sij )Vi−1:i,j + (1 − sij )Vi:i−1,j (5.274)
2
where sij = 1 in case of an inflow condition and either
• (i,j-1:j) is a U-open boundary or (i-1:i,j) is a V-open boundary

• (i-1,j) is a closed (land or coastal) V-node or (i,j-1) is a closed
(land or coastal) U-node
• (i,j) is a closed V-node or (i,j) is a closed U-node.
In all other cases, sij = −1.

The cross-stream diffusive fluxes in the U -equation are avaluated as fol-
lows
• If either (i,j-1:j) is a U-open boundary, or (i-1,j) is a closed (land or
coastal) V-node, or (i,j) is a closed V-node, the flux is calculated by
equation (5.186) for an internal node.
• Otherwise, if (i,j-1:j) is an interior U-node, a zero gradient condition

is used
uv uv
D12;ij = D12;i,j+1:j−1 (5.275)
• Otherwise, the flux is set to zero, i.e.

uv
D12;ij = 0 (5.276)
Likewise, at the fluxes in the V -equation are given by

• If either (i-1:i,j) is a V-open boundary, or (i,j-1) is a closed (land or

coastal) U-node, or (i,j) is a closed U-node, the flux is calculated by
equation (5.188) for an internal node.
• Otherwise, if (i-1:i,j) is an interior V-node, a zero gradient condition

is used
uv uv
D21;ij = D21;i,j+1:j−1 (5.277)
• Otherwise, the flux is set to zero, i.e.

uv
D21;ij = 0 (5.278)
An optional relaxation scheme has been implemented which reduces the

impact of advection within a user-defined distance from the open boundaries.
In that case, the advective terms are multiplied by the relaxation factor
αor = min(d/dmax , 1) (5.279)
where d is the distance to the nearest open boundary. Experiments showed

that, with an appropriate choice of the maximum relaxation distance dmax ,
instabilities, due to inaccuracies at the open boundaries, are prevented to
propagate into the domain. The scheme has shown to be useful, in particular,
to reduce instabilities, observed near ragged open boundaries.
5.3.15.3 boundary conditions at closed lateral boundaries
Following (4.378)–(4.379) one has
Uij = 0 , Vij = 0 (5.280)
at coastal boundaries.
Likewise all fluxes for the cross-advective and diffusive terms are set to
zero at closed Y- or X-node boundaries:
uv uv uv uv
F 12;ij = 0.0 , D12;ij = 0.0 , F 21;ij = 0.0 , D21;ij = 0.0 (5.281)
where a Y- or X-node grid point is called “closed” if one of the neighbouring

V- or U-node points in the X- or Y-direction is a closed velocity node.
5.3.16 Lateral boundary conditions for the 3-D cur-

rents
5.3.16.1 open boundary conditions for horizontal 3-D currents
Open boundary conditions for the 3-D mode are discussed in Section 4.10.2.1.
The aim is to provide values of u at U- and of v at V-open boundaries for each
vertical level. The depth-mean parts of the currents are already determined
by the 2-D open boundary conditions which means than only the baroclinic
parts δu and δv need to be specified.
The discretised versions of all open available open boundary conditions
are listed below using the same numbering system as in Section 4.10.2.1.
0. Zero gradient condition (see equation (4.363)).
hu2;i+1:i−1,j hn+1;u
3;i+1:i−1,jk
δun+1
ijk = u n+1;u δun+1;u
i+1:i−1,jk (5.282)
h2;ij h3;ijk
n+1
hv1;i,j+1:j−1 hn+1;v
3;i,j+1:j−1,k n+1;v
δvijk = δvi,j+1:j−1,k (5.283)
hv1;ij hn+1;v
3;ijk
1. Specified external profile (see equation (4.364)).
δun+1
ijk = δueijk (5.284)
n+1 e
δvijk = δvijk (5.285)
(5.286)
2. Second order gradient condition (see equation (4.365))

hu2;i+1:i−1 hu3;i+1:i−1 hc1;i:i−1 hc2;i:i−1
δui = 1 + δui+1:i−1
hu2;i hu3;i hc1;i+1:i−2 hc2;i+1:i−2
hu2;i+2:i−2 hu3;i+2:i−2 hc1;i:i−1 hc2;i:i−1
− δui+2:i−2 (5.287)
hu2;i hu3;i hc1;i+1:i−2 hc2;i+1:i−2
hv1;j+1:j−1 hv3;j+1:j−1 hc2;j:j−1 hc1;j:j−1
δvi = 1 + δvj+1:j−1
hv1;j hv3;j hc2;j+1:j−2 hc1;j+1:j−2
hv1;j+2:j−2 hv3;j+2:j−2 hc2;j:j−1 hc1;j:j−1
− δvj+2:j−2 (5.288)
hv1;j hv3;j hc2;j+1:j−2 hc1;j+1:j−2
(5.289)
3. Local solution
hn+1;u n+1 n;u n

3;ik δuik − h3;ik δuik

n+1;c n;c

= f θc vik − (1 − θc )vik (5.290)
hn+1;u
3;ik
b;n uw uw
b;n F 1;i+1:i−1,k D13;ij,k+1 − D13;ik τb1;i − τs1;i
+ F1;i+1:i−1,k − n+1;u + +
Hi+1:i−1 hu3;i Hin+1;u
hn+1;v n+1;c
3;jk δvjk − hn;v n;c
3;jk δvjk

= −f θc un+1;c
jk − (1 − θc )un;c
jk (5.291)
hn+1;v
3;jk
b;n vw vw
b;n F 2;j+1:j−1,k D23;j,k+1 − D23;jk τb2;j − τs2;j
+ F2;j+1:j−1,k − n+1;v + +
Hj+1:j−1 v
h3;jk Hjn+1;v
The diffusive fluxes are obtained from (5.197), (5.199) using the condi-
tion (5.232) at the surface and the bottom stress formulations given in
Section 5.3.14.2.
4. Radiation condition using the baroclinic wave speed (see equation (4.368)).
δun+1
ijk
u
= (1 − wijk )δunijk + wijk
u
δuni+1:i−1,jk (5.292)
n+1 v n v n
δvijk = (1 − wijk )δvijk + wijk δvi,j+1:j−1,k (5.293)
The weight factors are given by
R∆t q
u
wijk = ± gc H n+1;c
hc1;i:i−1,j i:i−1,j i:i−1,j
R∆t q c
v
wijk = ± c g H n+1;c (5.294)
h2;i,j:j−1 i,j:j−1 i,j:j−1
where R is the prescribed ratio of the baroclinic to surface gravity wave

speed. Default value is 0.03.
5. Orlanski condition (see equation (4.369)).

In analogy with the 2-D case one has

δun+1 u u u n u u u n
ijk = 1−OR (r1;ijk , r2;ijk , r3;ijk δuijk +OR (r1;ijk , r2;ijk , r3;ijk )δui+1:i−1,jk

(5.295)
n+1 v v v n v v v n
δvijk = 1−OR (r1;ijk , r2;ijk , r3;ijk ) δvijk +OR (r1;ijk , r2;ijk , r3;ijk )δvi,j+1:j−1,k
(5.296)
where the Orlanski function OR is defined by (5.256) and

u n−1 n−1
r1;ijk = δuni+1:i−1,jk , u
r2;ijk = δui+1:i−1,jk , u
r3;ijk = δui+2:i−2,jk
(5.297)
v n v n−1 v n−1
r1;ijk = δvi,j+1:j−1,k , r2;ijk = δvi,j+1:j−1,k , r3;ijk = δvi,j+2:j−2,k
(5.298)
Once the baroclinic and mean components are known, the full 3-D cur-
rents are determined by adding the two components
n+1;c n+1;c
un+1 n+1 n+1
ijk = Uij /Hi+1:i−1,j + δuijk ,
n+1
vijk = Vijn+1 /Hi,j+1:j−1 n+1
+ δvijk (5.299)
5.3.16.2 open boundary conditions for the advective and diffusive

fluxes of the 3-D currents
The formulations are identical to the one given in Section 5.3.15.2, except
that the fluxes now include an additional k-index.
5.3.16.3 boundary conditions for the 3-D mode at closed lateral

boundaries
The formulations are identical to the one given in Section 5.3.15.3, except
that the fluxes now include an additional k-index. They are given for com-
pleteness.
Following (4.378)–(4.379) one has
uijk = 0 , vijk = 0 (5.300)
at coastal boundaries.
Likewise all fluxes for the cross-advective and diffusive terms are set to
zero at closed Y- or X-node boundaries:
uv uv uv uv
F12;ijk = 0.0 , D12;ijk = 0.0 , F21;ijk = 0.0 , D21;ijk = 0.0 (5.301)
5.3.17 Solution of the discretised equations for mo-

mentum
In the case of a 3-D current the discretised transport equations reduce to a
system of linear equations of the form
new new
Bij1 Xij1 + Cij1 Xij2 = Dij1 (X old )
new new
Aijk Xij,k−1 + Bijk Xijk + Cijk Xij,k+1 = Dijk (X old )
new
(5.302)
new new
Aij,Nz Xij,N z −1
+ BijNz XijN z
= DijNz (X old )
where X old and X new are the values of the values of the current (u or v) at
the “old” and “new” time step. Equations (5.302) form a tridiagonal matrix
system in the vertical, which has to be solved at each horizontal grid point
(i,j).
Omitting the i and j indices for simplicity, the elements Ak , Bk and Ck
can be written as the sum of different components, each representing partic-
ular term(s) in the corresponding momentum equation. Explicit expressions
are given below for the update of u at the predictor step without operator
splitting, as given by equation (5.7) so that X old = un and X new = up . They
are easily extended to the case for v-equation.
When operator splitting is used, four of the six steps are explicit inte-
grations in which case the solution is straigtforward. The two steps (5.45),
(5.46) involving implicit terms are treated in a similar way.
The discretised 2-D equations for transports are written as
Bij Xijnew = Dij Xijold (5.303)
The composition of the B- and D-matrices is readily obtained from the dis-
cretisation formulae in the preceding sections and is not given here. The
solution of (5.303) is straightforward.
5.3.17.1 composition of the tridiagonal matrix

1. Time derivative.
The contribution of the time derivative is given by
Atk = 0 , Bkt = 1 , Ckt = 0 , Dkt = unk (5.304)
2. Vertical advection.
The vertical advection term is split up into two contributions arising
from the fluxes below and above a k-level. The former are given by
a
Ak− = −θa c−
k (αk + fk )
a−
Bk = −θa c−k (βk − fk )
a−
Ck = 0

a n n
Dk − = (1 − θa )c−
k (αk + fk )uk−1 + (βk − fk )uk (5.305)
where 2 ≤ k ≤ Nz ,
∆tωkuw
c−
k = , fk = 1 − Ω(rkuw ) sk (5.306)
2hu3;k
uw
and αijk , βijk , sijk , rijk are defined by (5.159) and (5.160).
The terms arising from the flux above the k-level, are
a
Ak+ = 0
a
B k + = θa c +
k (αk+1 + fk+1 )
a+ +
Ck = θa ck (βk+1 − fk+1 )

a
Dk + = −(1 − θa )c+ n n
k (αk+1 + fk+1 )uk + (βk+1 − fk+1 )uk+1
(5.307)
where 1 ≤ k ≤ Nz − 1 and
uw
∆tωk+1
c+
k = (5.308)
2hu3;k
3. Vertical diffusion.
As for vertical advection the fluxes below and above a k-level are taken
separately. The former are given by
d ∆tνTuw;k
Ak− = −θv
hu3;k huw
3;k
uw
d ∆tν ;k
Bk − = θv u Tuw
h3;k h3;k
d
Ck − = 0
d ∆tνTuw;k n
Dk− = −(1 − θv ) (uk − unk−1 ) (5.309)
hu3;k huw
3;k
The terms taken from the flux above the k-level, are
d
Ak+ = 0
d ∆tνTuw;k+1
B k + = θv
hu3;k huw
3;k+1
d ∆tνTuw;k+1
Ck + = −θv u uw
h3;k h3;k+1
d ∆tν uw;k+1 n
Dk + = (1 − θv ) u Tuw (u − unk ) (5.310)
h3;k h3;k+1 k+1
where 1 ≤ k ≤ Nz − 1.
4. Other explicit terms.

All other terms are explicit. Their contributions can be written as
Aek = Bke = Cke = 0

Dke = ∆t O1;k − Ãh1 (u)nk − Ãh2 (u)nk + Dmh1 (τ11 )n;u n;u
k + Dmh2 (τ12 )k
(5.311)
with O1;k defined by (5.50).
5. Surface boundary conditions.

The contributions arising from the surface boundary conditions (5.231)
for advection and (5.232) for diffusion are added to the highest level:
a a a a
AN+z = BN+z = CN+z = DN+z = 0
d d d
AN+z = BN+z = CN+z = 0
u
d ∆tτs1
DN+z = (5.312)
hu3;Nz
6. Bottom boundary conditions.

The contributions arising from the bottom boundary conditions (5.235)
for advection are added to the lowest level:
a a a a
A1− = B1 − = C1 − = D1 − = 0 (5.313)
The bottom contributions for vertical diffusion depends on whether the

bottom stress is expressed as function of the bottom current (equation
(5.236))
d d d ∆tkbu d ∆tkbu un1

A1− = C1 − = 0 , B 1 − = θv , D1 − = −(1 − θv )
hu3;1 hu3;1
(5.314)
or the depth mean current (equation (5.239))
d d d d ∆tkbu un
A1− = B1 − = C1 − = 0 , D1 − = − (5.315)
hu3;1
where the friction velocity is calculated using (5.238) or (5.241).

5.3.17.2 solution of tridiagonal systems

Tridiagonal matrix systems of the form (5.302) are solved using the algorithm,
described in Press et al. (1992):
β1 = B1 , X1⋆ = D1 /β1
γk = Ck−1 /βk−1 , βk = Bk − Ak γk , Xk⋆ = (Dk − Ak Xk−1
⋆
)/βk
for k = 2, · · · , Nz
new ⋆
XNz = XNz
Xknew = Xk⋆ − γk+1 Xk+1
new
for k = Nz − 1, · · · , 1 (5.316)
5.4 Drying/wetting and inundation schemes

5.4.1 Drying and wetting algorithm
The drying and flooding algorithm implemented in COHERENS closely fol-
lows the version used in the GETM model (Burchard & Bolding, 2002) and
consists of the following steps.
1. The advective, horizontal diffusion, Coriolis, curvature and baroclinic
pressure gradient terms in the 2-D and 3-D momentum equations are
multiplied by a “drying” factor α. For example, the u-equation becomes
1 ∂ h
(h3 u) + α Ah1 (u) + Ah2 (u) + Av (u)
h3 ∂t
v ∂h1 ∂h2 i
+ u −v − 2Ωv sin φ
h1 h2 ∂ξ2 ∂ξ1
g ∂ζ 1 ∂Pa
= − − + αF1b + F1t + Dmv (u)
h1 ∂ξ1 ρ0 h1 ∂ξ1

+ α Dmh1 (τ11 ) + Dmh2 (τ12 ) (5.317)
where α decreases from 1 when the total water depth is lower than a
critical value and becomes 0 when H reaches a minimum value
α=1 if H > dcrit
H − dmin
α= if dmin ≤ H ≤ dcrit
dcrit − dmin
α=0 if H < dmin (5.318)
In this way the momentum equations reduce to a balance between
the time derivative, surface slope and vertical diffusion (bottom fric-
tion) terms when H → dmin . The formulation provides a continuous
5.4. DRYING/WETTING AND INUNDATION SCHEMES 201
transition from a wet to a dry condition in contrast to schemes, dis-

cussed below, using a “mask” function which sets cells to a dry or wet
state depending on some drying criterium. A second advantage is that
the scheme only involves two tunable parameters. Default values are
dcrit =0.1 m, dmin =0.02 m.
2. The total water depth at C-nodes is bounded below by the minimum
water depth to prevent negative water depths
Hijc = max(Hijc , dmin ) (5.319)
so that a (spurious) small amount of water remains if a cell becomes
dry. Equation (5.319) implies a second condition for the surface level
ζij ≥ dmin − hij (5.320)
This means that if the value of ζij , obtained from the continuity equa-
tion, falls below the minimum value (5.320), a (small) amount of water
is added to the water column in violation of mass conservation. No
correction is applied in the current version of COHERENS, but the spu-
riously added water is stored in the program variable δe H which mea-
sures the error in water depth and is increased by the amount dmin − H
when H drops below dmin . By its definition δe H is non-negative and
cannot decrease in time.
3. In the absence of a drying mechanism the total water depth at the
velocity nodes is calculated as the (weigthed) average of the depths
at the surrounding C-nodes. Experiments showed that this method
produces large horizontal gradients for the vertical grid spacings for
water depths close to the minimum value, and, hence, unrealistically
high vertical current magnitudes after substitution in the baroclinic
continuity equation (4.91). To smoothen the solution the depth at the
velocity is taken as the minimum of the surrounding C-node values, i.e.
Hiju = min(Hi−1,j
c
, Hijc ) if c
min(Hi−1,j , Hijc ) < dcrit
Hijv = min(Hi,j−1
c
, Hijc ) if c
min(Hi,j−1 , Hijc ) < dcrit (5.321)
Disadvantage is an unphysical retardation of the flow through the ve-
locity interfaces.
4. To prevent an unrealistic outflow from a drying cell the surface slope
is calculated with a modified surface elevation at both sides
∂ζ
= max ζi , min(dmin , Hi − hi−1 )
∂ξ1 i

− max ζi−1 , min(dmin , Hi−1 − hi )
∂ζ
= max ζj , min(dmin , Hj − hj−1 )
∂ξ2 j

− max ζj−1 , min(dmin , Hj−1 − hj )
(5.322)
5. Equation (5.18) shows that the bottom drag coefficient and hence the
bottom friction increases exponentially at small water depths. This will
slow down the water flow at water depths close to the minimum value.
Note that this effect is only present when the bottom drag coefficient
is calculated as function of a roughness length.
5.4.2 Inundation schemes

The drying/wetting scheme described in Section 5.4.1 has been extended in
Version 2.3 of COHERENS by the implementation of so-called “mask func-
tions”. The objective is to simulate inundation processes where coastal boun-
daries are moving dynamically or to simulate the flow over obstacles. There-
fore, grid cells of the computational domain will become “dry” or “wet”
depending on the value of the total water depth. In this way users have
the additional option to simulate inundation apart from the original dry-
ing/wetting scheme already present in COHERENS.
Inundation schemes are focused on simulating dynamic processes. “Dry-
ing and wetting” refers to an existent functionality used to define “wet” and
“dry” areas in the computational domain. COHERENS uses this functionality
to define the coastal boundaries, this definition is performed at the initiali-
sation stage and only once. In this way a distinction is made of three type
of grid cells
• Land cells which are always dry and where no calculation is performed.
They are defined by the user as cells where the mean water depth equals
zero7 .
• Cells which are (temporarily) dry (non-active) but can be inundated

by the rising water. Calculations in these cells are disabled until they
are inundated from a neighbouring cell. The total water depth remains
limited from below by dmin so that at least a small amount of water is
present. In this way, dynamic coastal boundaries can be simulated.
7
Negative mean water depths are not allowed in the program. An error is issued if the
bathymetry, provided by the user, has negative values.
5.4. DRYING/WETTING AND INUNDATION SCHEMES 203
• Active wet cells where all calculations are enabled.
The “mask functions” are defined as criteria for “masking” grid cells
according to their condition (dry or wet). When the criterium evaluates
as .TRUE. at a particular grid cell, the mask function will “mask in” the
cell. Hence, they will be considered for the solution of the hydrodynamic
equations. On the other hand, if grid cells become dry, the mask criterium
will “mask out” such grid cells and updates of quantitites defined at these
cells will be suspended. Dry cells are also excluded from the interpolation of
model variables on the model grid (see Section 8.2.2). The process is repeated
at the start of each predictor time step. Once a cell is set to a “dry” status,
the adjacent velocity nodes are blocked and the all currents at these nodes
are set to zero to prevent further drying of the grid cell. The criteria are
applied at the start of each predictor time step. If the criterium at a dry cell
evaluates as .FALSE. at a later time, the cell is reactivated again and water
is allowed to enter through the side faces.
Eleven mask functions are defined and can be used in combined form.
They can be divided in four groups. The first group compares the water
depths of a cell and its neighbours with a threshold value dth and is composed
of the following six criteria:
max(Hij , Hi−1,j , Hi+1,j , Hi,j−1 , Hi,j+1 ) < dth (5.323)

min(Hij , Hi−1,j , Hi+1,j , Hi,j−1 , Hi,j+1 ) < dth (5.324)
mean(Hij , Hi−1,j , Hi+1,j , Hi,j−1 , Hi,j+1 ) < dth (5.325)
max(Hi−1,j , Hi+1,j , Hi,j−1 , Hi,j+1 ) < dth (5.326)
min(Hi−1,j , Hi+1,j , Hi,j−1 , Hi,j+1 ) < dth (5.327)
mean(Hi−1,j , Hi+1,j , Hi,j−1 , Hi,j+1 ) < dtd (5.328)
where “mean” denotes an averaged value (excluding land cells which are
permanently dry).
A second group of criteria verifies the “status” of the neighbouring cells.
The status is defined by the function N which evaluates to 0 at dry and 1 at
sea cells8 . The following criteria, used to prevent the formation of isolated
dry or wet cells, have been implemented:
max(Ni−1,j , Ni+1,j , Ni,j−1 , Ni,j+1 ) = 0 (5.329)

min(Ni−1,j , Ni+1,j , Ni,j−1 , Ni,j+1 ) = 0 (5.330)
8
Represented by the model variable nodeatc (see Section 8.1.2.4).
The third group is a variant of the previous one and checks, in addition,
whether the total water depth of the grid cell is lower than the threshold
value:
max(Ni−1,j , Ni+1,j , Ni,j−1 , Ni,j+1 ) = 0 and Hij < dth (5.331)

min(Ni−1,j , Ni+1,j , Ni,j−1 , Ni,j+1 ) = 0 and Hij < dth (5.332)
The last scheme is intended for channel flows and overflowing dykes. The
criterium uses the total and mean water depths at the grid cell and its neigh-
bours
min(hi−1,j − Hi−1,j , hi+1,j − Hi+1,j ) > hij (5.333)
or
min(hi,j−1 − Hi,j−1 , hi,j+1 − Hi,j+1 ) > hij (5.334)
depending on whether the along-channel direction is along the X- or Y-axis.
The above criteria can be in applied in combination. This means that,
if several criteria have been activated by the user, the cell becomes dry if at
least one of them turns .TRUE. The cell becomes wet again if all of them
evaluate to .FALSE.
The flooding of initially dry land areas can be simulated using the follo-
wing procedure at the initial time
1. Define the topographic height (e.g. hmax ) of the highest points on land
which can potentially be flooded by a rising sea level.
2. Define an initial bathymetry. Note that grid points with a zero mean
water depth are considered by the model as permanently dry land
points and cannot be flooded. Negative depth values are not allowed.
3. Increase the reference mean sea level by adding hmax to the initial
bathymetry (with respect to the standard mean sea level).
4. Reset the initial surface elevation to take account of the changed refer-
ence level
new old
ζin = ζin − hmax (5.335)
old
where ζin is the sea level with respect to the old standard level. If,
by this procedure, the total water depth becomes negative (more pre-
cisely lower than dmin ) the total depth will be reset to dmin . In case a
dynamic mask is applied, these grid cells may be (temporarily) set to
dry (depending on the type of mask function) at the initial time9 .
9
If residual (non-harmonic) elevation data are used as open boundary forcing, the
previous change in mean sea level must be taken into account.
5.5. SCALAR TRANSPORT EQUATIONS 205
The following remarks are given for the user:
• In the 3-D case, the mask cannot be changed during a 3-D (baroclinic)
time step. This means that the mask criteria are tested after the last
corrector step and before the next predictor time step and not at each
barotropic time step. When a purely 2-D grid has been selected, the
criteria are obviously applied at each (barotropic) time step.
• In the current implementation, open boundaries cannot be blocked so

that they should be located where no drying process can take place.
• The threshold depth dth , used to determine whether a cell is dry or

wet, should be defined to a value sufficiently larger than the minimum
depth dmin , but at the same time lower than the critical depth dcrit .
5.5 Scalar transport equations

5.5.1 General aspects of discretisation
General features of the discretisation are
• With exception of turbulence variables (see Section 5.6) scalar quanti-

ties are located at C-nodes.
• Horizontal advection and diffusion terms are discretised explicitly in

time.
• In analogy with the momentum equations vertical advection is taken

semi-implicitly while vertical diffusion is treated fully implicitly. The
equations for vertical advection and diffusion are presented here in a
more general form covering both the explicit, implicit and semi-implicit
cases.
• As recommended by Ruddick (1995), the vertical spacing h3 is elimi-

nated from the time derivative (except in the absence of advection) by
adding corrector terms to the right hand side of the transport equation.
• Source terms are discretised explicitly. Contrary to the momentum

and turbulence transport equations the sink terms are evaluated ex-
plicitly. This has no impact on temperature and salinity, but has been
introduced for future implementation of biological concentrations where
conservation plays an important role.
• The advecting current (uf ,vf ) used for horizontal advection is composed
of the baroclinic current at the “predictor” step plus a filtered depth-
independent component obtained by averaging over the more rapidly
varying 2-D mode (see equations (5.25)–(5.26)).
• The transport equation is integrated in time with or without the op-

erator splitting method depending on the type of advection scheme.
Note that the program allows to use of different advection schemes in
the momentum and scalar transport modules.
In analogy with momentum the time discretisation of a scalar transport

equation depends on the type of advection scheme selected in the program.
Several schemes are available. The type is selected with the model switch
iopt adv scal which, in analogy with the switch iopt adv 3d for momentum,
has the following meaning
0: horizontal and vertical advection disabled

1: upwind scheme for horizontal and vertical advection
2: Lax-Wendroff scheme for horizontal, central scheme for vertical advec-
tion10
3: TVD (Total Variation Diminishing) scheme using the superbee limiter
as a weighting function between the upwind scheme and either the Lax-
Wendroff scheme in the horizontal or the central scheme in the vertical
4: as the previous case now using the monotonic limiter.
5.5.2 Alternative formulation of the transport equa-

tion
The general form of a scalar transport equation is given by (4.65). Before
discussing its discretisation, the following modifications are made
1. The advective velocities u, v are replaced by the “filtered” currents

uf , vf given as the sum of the “filtered” depth-mean current and the
baroclinic part of the “predicted” current (see equations (5.25)–(5.26))
so that the numerical time-integration guarantees the conservation of
the scalar quantity (Deleersnijder, 1993).
10
The “pure” Lax-Wendroff scheme has only been implemented for illustrative purposes
and should be avoided in realistic simulations.
2. Making use of the continuity equation (4.49), the time derivative term
is written as
1 ∂ ∂ψ ψ ∂h3
(h3 ψ) = +
h3 ∂t ∂t h3 ∂t
∂ψ f f
= − Cs1 (ψ) − Cs2 (ψ) − Cs3 (ψ) (5.336)
∂t
where the “corrector” terms are defined by
f ψ ∂
Cs1 (ψ) = (h2 h3 uf ) (5.337)
h1 h2 h3 ∂ξ1
f ψ ∂
Cs2 (ψ) = (h1 h3 vf ) (5.338)
h1 h2 h3 ∂ξ2
ψ ∂ω
Cs3 (ψ) = (5.339)
h3 ∂s
3. For reasons of conservation the source and sink are both discretised
explicitly. The operation is not without risk since the method may
produce negative concentrations (Burchard et al., 2003). To simplify
the notations the following operator is defined
T (ψ) = P(ψ) − S(ψ) (5.340)
An alternative method is the Patankar scheme, discussed in Section 5.6
below, which is monotone but does not guarantee conservation.
The new form of the scalar transport equation then becomes
∂ψ
+ Afh1 (ψ) + Afh2 (ψ) + Av (ψ) − Cs1
f f
(ψ) − Cs2 (ψ) − Cs3 (ψ)
∂t
= T (ψ) + Dsv (ψ) + Dsh1 (ψ) + Dsh2 (ψ) (5.341)
where Afhi are the horizontal advective operators using the filtered currents
1 ∂
Afh1 (ψ) = (h2 h3 uf ψ) (5.342)
h1 h2 h3 ∂ξ1
1 ∂
Afh2 (ψ) = (h1 h3 vf ψ) (5.343)
h1 h2 h3 ∂ξ2
(5.344)

Three cases can be distinguished for the time integration. They are discussed
in the subsections below.
5.5.3.1 integration without advection

In the absence of physical advection (iopt adv scal=0) the transport equation
is integrated in time using
hn+1
3 ψ n+1 − hn3 ψ n
= θv Dsv (ψ n+1 )+(1−θv )Dsv (ψ n )+T (ψ n )+Dsh1 (ψ n )+Dsh2 (ψ n )
hn+1
3 ∆t
(5.345)
5.5.3.2 integration with advection but without operator splitting

If iopt adv scal=1 or 2, the transport equation (5.341) is integrated in time
using
ψ n+1 − ψ n
= −Afh1 (ψ n ) + Cs1
f
(ψ n ) − Afh2 (ψ n ) + Cs2
f
(ψ n )
∆t
− θa Av (ψ n+1 ) − (1 − θa )Av (ψ n ) + Cs3 (ψ n ) + θv Dsv (ψ n+1 )
+ (1 − θv )Dsv (ψ n ) + T (ψ n ) + Dsh1 (ψ n ) + Dsh2 (ψ n )
(5.346)
5.5.3.3 integration with operator splitting

If iopt adv scal=3, integration is performed along the following steps:
• Part A
n+1/3
ψA − ψn
= −Afh1 (ψ n ) + Cs1
f
(ψ n ) + Dsh1 (ψ n ) (5.347)
∆t
n+2/3 n+1/3
ψA − ψA n+1/3 n+1/3
= −Afh2 (ψA f
) + Cs2 (ψ n ) + Dsh2 (ψA ) (5.348)
∆t
n+2/3
ψAn+1 − ψA n+2/3
= −θa Av (ψAn+1 ) − (1 − θa )Av (ψA ) + Cs3 (ψ n )
∆t
n+2/3
+ θv Dsv (ψAn+1 ) + (1 − θv )Dsv (ψA ) + T (ψ n )
(5.349)
• Part B
n+1/3
ψB − ψn n+1/3
= −θa Av (ψB ) − (1 − θa )Av (ψ n ) + Cs3 (ψ n )
∆t
n+1/3
+ θv Dv (ψB ) + (1 − θv )Dsv (ψ n ) + T (ψ n )
(5.350)
n+2/3 n+1/3
ψB − ψB n+1/3 n+1/3
= −Afh2 (ψB f
) + Cs2 (ψ n ) + Dsh2 (ψB ) (5.351)
∆t
n+2/3
ψBn+1 − ψB n+2/3 f n+2/3
= −Ah1 (ψB ) + Cs1 (ψ n ) + Dsh1 (ψB ) (5.352)
∆t
• Updated value
1
ψ n+1 = (ψAn+1 + ψBn+1 ) (5.353)
2
For the reasons discussed in Section 5.3.2.1 vertical advection is discre-

tised semi-implicitly and vertical diffusion implicitly. The default values,
taken for the implicity factors, are then given by θa = 0.501, θv = 1. The
use of the TVD scheme with the operator splitting method increases the
CPU time but has the capacity to preserve horizontal and vertical gradients
in frontal areas. The user therefore needs to make a balance between CPU
time and accuracy when selecting an appropriate scheme.
5.5.4 Discretisation of advection

The advective terms in the scalar transport equations are written as the
divergence of the fluxes F1 , F2 , F3 defined in Table 5.5:
1 ∂ 1 ∂
Afh1 (ψ) = h 2 h 3 uf ψ = h2 h3 F1 (5.354)
h1 h2 h3 ∂ξ1 h1 h2 h3 ∂ξ1
1 ∂ 1 ∂
Afh2 (ψ) = h 1 h 3 vf ψ = h1 h3 F2 (5.355)
h1 h2 h3 ∂ξ2 h1 h2 h3 ∂ξ2
1 ∂ 1 ∂F3
Av (ψ) = (ωψ) = (5.356)
h3 ∂s h3 ∂s
5.5.4.1 advection in the X-direction

The advective term in the X-direction is obtained by differencing the flux F1u
at the C-node
hu2;i+1,j hu3;i+1,jk F1;i+1,jk
u
− hu2;ij hu3;ijk F1;ijk
u
Afh1 (ψ)cijk = (5.357)
hc1;ij hc2;ij hc3;ijk

u u u u u
F1;ij = 1 − Ω(rijk ) Fup;ijk + Ω(rijk )Flw;ijk (5.358)
u u
where Fup;ijk and Flw;ijk are the upwind and Lax-Wendroff fluxes at the U-
node:
u 1
Fup;ijk = uf ;ijk (αij + sijk )ψi−1,jk + (βij − sijk )ψijk (5.359)
2
u 1
Flw;ijk = uf ;ijk (αij + cijk )ψi−1,jk + (βij − cijk )ψijk (5.360)
2
where sijk and cijk are the sign and CFL number of the advecting current
uf ;ijk ∆t
sijk = Sign(uf ;ijk ) , cijk = (5.361)
hu1;ij
hc1;ij hc1;i−1,j
αij = , βij = (5.362)
hu1;ij hu1;ij
the type of advection scheme, selected by the switch iopt adv scal. The ar-
gument r of the weight function is defined by
u u
u (αij + sijk )∆Fi−1,jk + (βij − sijk )∆Fi+1,jk
rijk = u
2∆Fijk
u u u
∆Fijk = Flw;ijk − Fup;ijk (5.363)
5.5.4.2 advection in the Y-direction

The advective term in the Y-direction is obtained by differencing the flux F1v
at the C-node
hv1;i,j+1 hv3;i,j+1,k F2;i,j+1,k
v
− hv1;ij hv3;ijk F2;ijk
v
Afh2 (ψ)cijk = (5.364)

v v v v v
v v
where Fup;ijk and Flw;ijk are the upwind and Lax-Wendroff fluxes at the V-
node:
v 1
Fup;ijk = vf ;ijk (αijk + sijk )ψi,j−1,k + (βijk − sijk )ψijk (5.366)
2
v 1
Flw;ijk = vf ;ijk (αijk + cijk )ψi,j−1,k + (βijk − cijk )ψijk (5.367)
2
vf ;ijk ∆t
sijk = Sign(vf ;ijk ) , cijk = (5.368)
hv2;ij
hc2;ij hc2;i,j−1
αij = , βij = (5.369)
hv2;ij hv2;ij

v v
v (αij + sijk )∆Fi,j−1,k + (βij − sijk )∆Fi,j+1,k
rijk = v
2∆Fijk
v v v
5.5.4.3 advection in the vertical direction
The vertical advective term is obtained by differencing the flux F3w at the
C-node
Fw w
− F3;ijk
Av (ψ)cijk = 3;ij,k+1c (5.371)
h3;ijk

w w w w w
w w
where Fup;ijk and Fce;ijk are the upwind and central fluxes at the W-node:
w 1 w
Fup;ijk = ωijk (αijk + sijk )ψij,k−1 + (βijk − sijk )ψijk (5.373)
2
w 1 w
Fce;ijk = ωijk αijk ψij,k−1 + βijk ψijk (5.374)
2
where
w hc3;ijk hc3;ij,k−1
sijk = Sign(ωijk ), αijk = , βijk = (5.375)
hw
3;ijk hw 3;ijk

w w
w (αijk + sijk )∆Fij,k−1 + (βijk − sijk )∆Fij,k+1
rijk = w
2∆Fijk
w w w
5.5.4.4 corrector terms

The corrector terms, defined by (5.337)–(5.339), are discretised using
f hu2;i+1,j hu3;i+1,jk uf ;i+1,jk − hu2;ij hu3;ijk uf ;ijk

Cs1 (ψ)c = ψijk (5.377)
hv hv vf ;i,j+1,k − hv1;ij hv3;ijk vf ;ijk
f
Cs2 (ψ)c = ψijk 1;i,j+1 3;i,j+1,kc c (5.378)
h1;ij h2;ijk hc3;ijk
ωij,k+1 − ωijk
Cs3 (ψ)c = ψijk (5.379)
hc3;ijk
5.5.5 Discretisation of diffusion

The diffusive terms in the scalar transport equations are written as the di-
vergence of the fluxes D1 , D2 , D3 defined in Table 5.5:
1 ∂ h2 h3 ∂ψ 1 ∂
Dsh1 (ψ) = λH = h2 h3 D1 (5.380)
h1 h2 h3 ∂ξ1 h1 ∂ξ1 h1 h2 h3 ∂ξ1
1 ∂ h1 h3 ∂ψ 1 ∂
Dsh2 (ψ) = λH = h1 h3 D2 (5.381)
h1 h2 h3 ∂ξ2 h2 ∂ξ2 h1 h2 h3 ∂ξ2
ψ
1 ∂ λT ∂ψ
1 ∂D3
Dsv (ψ) = = (5.382)
h3 ∂s h3 ∂s h3 ∂s
5.5.5.1 diffusion in the X-direction

The diffusion term in the X-direction is obtained by differencing the flux D1u
at the C-node
hu2;i+1,j hu3;i+1,jk D1;i+1,jk
u
− hu2;ij hu3;ijk D1;ijk
u
Dsh1 (ψ)cijk = (5.383)
The flux is given by

u λuH (ψijk − ψi−1,jk )
D1;ijk = (5.384)
hu1;ij
5.5.5.2 diffusion in the Y-direction

The diffusion term in the Y-direction is obtained by differencing the flux D2v
at the C-node
hv1;i,j+1 hv3;i,j+1,k D2;i,j+1,k
v
− hv1;ij hv3;ijk D2;ijk
v
Dsh2 (ψ)cijk = (5.385)
v λvH (ψijk − ψi,j−1,k )

D2;ijk = (5.386)
hv2;ij
5.5.5.3 diffusion in the vertical direction

The vertical diffusion term is obtained by differencing the flux D3w at the
C-node
Dw w
− D3;ijk
Dsv (ψijk )c = 3;ij,k+1c (5.387)
h3;ijk
w λψ;w
T (ψijk − ψij,k−1 )
D3;ijk = (5.388)
hw
3;ijk
5.5.6 Diffusion coefficients for scalars

The discretised values of the horizontal diffusion coefficient at the U- and
V-nodes are obtained by applying (4.70) and interpolating DTc ;ijk and DS;ijk
uv
,
given by (5.200)–(5.201), to the U- and V-nodes
r
2 2
λuH;ijk = Cs hu1;ij hu2;ij DTu ;ijk u
+ DS;ijk (5.389)
r
2 2
λvH;ijk = Cs hv1;ij hv2;ij DTv ;ijk v
+ DS;ijk (5.390)
5.5.6.2 vertical diffusion coefficient

The vertical diffusion coefficient for scalars λT is obtained from one of the
available turbulence schemes, described in Section 4.4. Values are first stored
at the W-nodes and interpolated afterwards at the U- and V-nodes for the
calculation of the vertical diffusion fluxes in the momentum equations. The
evaluation of λT only involves algebraic expressions so that the discretisation
procedure is straightforward.
For further comments see Section 5.3.11.2.
5.5.7 Boundary conditions

The program allows four type of boundary conditions
ψ;w
1. Neumann condition with a prescribed (downward) surface flux Fs;ij
w ψ;w
D3;ijN z
= Fs;ij (5.391)
2. Neumann condition using a surface transfer velocity

w ψ w n+1
D3;ijN z
= Cs;ij ψs;ij − (1 − θv )ψijNz − θv ψijN z
(5.392)
ψ w
where Cs;ij is the transfer velocity and ψs;ij a prescribed external value.
c
3. Dirichlet condition with a prescribed external value ψs;ij at the first
C-node below the surface
n+1 c
ψijN z
= ψs;ij (5.393)
w
4. Dirichlet condition with a prescribed external value ψs;ij at the surface
itself. In that case the value at the first node below the surface is
determined by interpolation
n+1
n+1 2hw w c
3;ijNz ψs;ij + h3;ijNz ψij,nz −1
ψijN = (5.394)
z
2hw c
3;ijNz + h3;ij,Nz
which can be more conveniently rewritten in “tridiagonal” form

hc3;ijNz n+1 n+1 2hw3;ijNz
− ψ ij,Nz −1 + ψ ijNz = ψ w (5.395)
w c
2h3;ijNz + h3;ijNz 2h3;ijNz + hc3;ijNz s;ij
w
Note that the second Neumann condition is semi-implicit whereas both Dirich-
let conditions use a fully implicit formulation.

The bottom boundary conditions are similar to the ones at the surface.
ψ;w
1. Neumann condition with a prescribed (upward) bottom flux Fb;ij
w ψ;w
D3;ij1 = Fb;ij (5.396)
2. Neumann condition using a bottom transfer velocity

w ψ n+1 w
D3;ij1 = Cb;ij (1 − θv )ψij1 + θv ψij1 − ψb;ij (5.397)
ψ w
where Cb;ij is the transfer velocity and ψb;ij a prescribed external value.
c
3. Dirichlet condition with a prescribed external value ψb;ij at the first
C-node above the bottom
n+1 c
ψij1 = ψb;ij (5.398)
w
4. Dirichlet condition with a prescribed external value ψb;ij at the bottom
itself. In that case the value at the first node above the sea bed is
determined by interpolation
n+1
n+1 2hw w c
3;ij2 ψb;ij + h3;ij1 ψij2
ψij1 = (5.399)
2hw c
3;ij2 + h3;ij1
which can be more conveniently rewritten in “tridiagonal” form
n+1 hc3;ij1 n+1 2hw 3;ij2 w

ψij1 − ψ ij2 = ψb;ij (5.400)
2hw
3;ij2 + h c
3;ij1 2h w
3;ij2 + h c
3;ij1
Note that the second Neumann condition is semi-implicit whereas both Dirich-
let conditions use a fully implicit formulation.
5.5.7.3 lateral boundary conditions

At the open boundaries the flux normal to the boundary is determined by
the upwind scheme. This means that
u 1
e

F1;ijk = uf ;ijk (1 ± sijk )ψijk + (1 ∓ sijk )ψi:i−1,jk (5.401)
2
at U-boundaries and
v 1
e

F2;ijk = vf ;ijk (1 ± sijk )ψijk + (1 ∓ sijk )ψi,j:j−1,k (5.402)
2
at V-boundaries, where the upper (lower) sign applies at western/southern
(eastern/northern) boundaries, the flow sign sijk is defined by (5.361) or
e
(5.368) and ψijk denotes an external profile of ψ at one-half grid distance
outside the open boundary. The open boundary problem then consists in
determining the external profile ψ e . The following four methods are available
1. Zero gradient condition.

e u
ψijk = ψi:i−1,jk or F1;ijk = uf ;ijk ψi:i−1,jk (5.403)
e v
ψijk = ψi,j:j−1,k or F2;ijk = vf ;ijk ψi,j:j−1,k (5.404)
2. The external profile is prescribed.

e;u;n+1 u e;u;n u n
ψijk = (1 − wijk )ψijk + wijk ψi:i−1,jk (5.405)
e;v;n+1 v e;v;n v n
ψijk = (1 − wijk )ψijk + wijk ψi,j:j−1,k (5.406)
The weight factors are given by
u R∆t q u n+1;c
wijk = ± gij Hi:i−1,j
hu1;ij
v R∆t q v n+1;c
wijk = ± v gij Hi,j:j−1 (5.407)
h2;ij
where R is the prescribed ratio of the baroclinic to surface gravity wave

speed. Default value is 0.03.
4. Orlanski condition (see equation (4.369)).

e;u;n+1 u u u e;u;n
ψijk = 1 − OR (r1;ijk , r2;ijk , r3;ijk ) ψijk
u u u n
+ OR (r1;ijk , r2;ijk , r3;ijk )ψi:i−1,jk (5.408)

e;v;n+1 v v v e;v;n
ψijk = 1 − OR (r1;ijk , r2;ijk , r3;ijk ) ψijk
v v v n
+ OR (r1;ijk , r2;ijk , r3;ijk )ψi,j:j−1,k (5.409)
where the Orlanski function OR is defined by (5.256) and

u n u n−1 u n−1
r1;ijk = ψi:i−1,jk , r2;ijk = ψi:i−1,jk , r3;ijk = ψi+1:i−2,jk (5.410)
v n v n−1 v n−1
r1;ijk = ψi,j:j−1,k , r2;ijk = ψi,j:j−1,k , r3;ijk = ψi,j+1:j−2,k (5.411)
Advective fluxes normal to a closed (coastal) open boundary are set to

zero.
5.5.8 Solution of the discretised equations for scalars

As for momentum, the discretised equations can be written in tridiagonal
form, as given by (5.302). Expressions for the matrix components are given
below for the case that no operator splitting is used. They are easily extended
to the case with operator splitting.
When a Dirichlet boundary condition is used at the surface (bottom), the
surface (bottom) value of ψ is determined by the boundary condition itself.
This means that k below varies between kmin and kmax where kmin equals 1
for a Neumann (flux) condition and 2 for a Dirichlet condition at the bottom.
Likewise, kmax equals Nz for a Neumann and Nz − 1 for a Dirichlet condition
at the surface.
For simplicity, the i and j indices are omitted.
1. Time derivative.
Atk = 0 , Bkt = 1 , Ckt = 0 , Dkt = ψkn (5.412)
where kmin ≤ k ≤ kmax .
a
Ak− = −θa c−
k (αk + fk )
a− −
Bk = −θa ck (βk − fk )
a
Ck − = 0

a n n
Dk − = (1 − θa )c−
k (αk + fk )ψk−1 + (βk − fk )ψk (5.413)
where 2 ≤ k ≤ kmax ,
∆tωkw
c−
k = , fk = 1 − Ω(rkw ) sk (5.414)
2hc3;k
w
and αijk , βijk , sijk , rijk are defined by (5.375) and (5.376).
a
Ak+ = 0
a
B k + = θa c +
k (αk+1 + fk+1 )
a+ +
Ck = θa ck (βk+1 − fk+1 )

a
Dk + = −(1 − θa )c+ n n
k (αk+1 + fk+1 )ψk + (βk+1 − fk+1 )ψk+1
(5.415)
where kmin ≤ k ≤ Nz − 1 and

w
∆tωk+1
c+
k = (5.416)
2hc3;k
d ∆tλψ;w
Ak− = −θv c Tw;k
h3;k h3;k
d ∆tλψ;w
Bk − = θv c Tw;k
h3;k h3;k
d
Ck − = 0
d ∆tλψ;w
Dk − = −(1 − θv ) c Tw;k (ψkn − ψk−1
n
) (5.417)
h3;k h3;k
where 2 ≤ k ≤ kmax .
d
Ak+ = 0
d ∆tλψ;w
Bk + = θv c Tw;k+1
h3;k h3;k+1
d ∆tλψ;w
Ck + = −θv c Tw;k+1
h3;k h3;k+1
d ∆tλψ;w T ;k+1 n
Dk+ = (1 − θv ) (ψk+1 − ψkn ) (5.418)
hc3;k hw3;k+1
where kmin ≤ k ≤ Nz − 1.

Aek = Bke = Cke = 0

Dke = ∆t Tkn − Ãfh1 (ψ)nk − Ãfh2 (ψ)nk + Cs1
f
(ψ)nk

f
+ Cs2 (ψ)nk + Cs3 (ψ)nk + Dsh1 (ψ)nk + Dsh2 (ψ)nk (5.419)

Contributions from the surface boundary conditions depends on the
type of condition as described in Section 5.5.7.1.
• Neumann condition with a prescribed surface flux Fsψ;w .
∆tFsψ;w
s
AsNz = BN = CNs z = 0 , s
DN = (5.420)
z z
hc3;Nz
• Neumann condition using a surface transfer velocity.

∆tCsψ ∆tCsψ w
AsNz = CNs z = 0 , s
BN = θv , s
DN = ψ s −(1−θ v )ψ n
Nz
z
hc3;Nz z
hc3;Nz
(5.421)
• Dirichlet condition with a prescribed external value ψsc at the first
node below the surface.
BN z
= 1, s
DN z
= ψsc (5.422)
• Dirichlet condition with a prescribed external value ψsw at the

surface itself.
hc3;Nz
AsNz = − w
2h3;Nz + hc3;Nz
s
BN z
= 1 , CNs z = 0
s 2hw 3;Nz ψs
w
DN = (5.423)
z
2hw c
3;Nz + h3;Nz

Contributions from the bottom boundary conditions depends on the
• Neumann condition with a prescribed bottom flux Fbψ;w .
∆tFbψ;w
Ab1 = B1b = C1b = 0, D1b = (5.424)
hc3;1
• Neumann condition using a bottom transfer velocity.
∆tCbψ ∆tCbψ w
Ab1 = C1b = 0, B1b = θv c , D1b = c ψb − (1 − θv )ψ1n
h3;1 h3;1
(5.425)
• Dirichlet condition with a prescribed external value ψbc at the first
node above the sea bed.
Ab1 = C1b = 0 , B1b = 1 , D1b = ψbc (5.426)

• Dirichlet condition with a prescribed external value ψbw at the

bottom itself.
Ab1 = 0 , B1b = 1
hc3;1
C1b = − w
2h3;2 + hc3;1
2hw 3;2 ψb
w
D1b = (5.427)
2hw3;2 + h3;1
c
5.6 Turbulence transport equations

This section deals with the numerical solution of the transport equations
(4.192) for turbulence energy k, (4.193) for the dissipation rate ε and (4.197)
for the turbulent energy times mixing length kl. The discretisation algo-
rithms are highly similar to the ones used for scalar quantities. Main differ-
ences are
• Turbulence variables are determined at W-nodes.
• Production terms are taken explicitly at the old time step tn , whereas
the sink terms are discretised in time using the “quasi-implicit” ap-
proach, proposed by Patankar (1980), or
ψ n+1
P(ψ) = P(ψ n ) , S(ψ) = P(ψ n ) (5.428)
ψn
• Since the turbulent equations are solved before the momentum equa-
tions, the horizontal advective terms are discretised using the non-
filtered current (u,v).
• The discretisation algorithms for advection and diffusion are the same
as for C-node scalar quantities, except that all quantities are displaced
in the vertical. This means that 3-D variables (fluxes, advective veloci-
ties, diffusion coefficients, . . . ), previously evaluated at (C,U,V,W,UW,
VW)-nodes are now taken at respectively (W,UW,VW,C,U,V)-nodes.
The turbulence transport equations are generally written as
∂ψ
+ Ah1 (ψ) + Ah2 (ψ) + Av (ψ) − Cs1 (ψ) − Cs2 (ψ) − Cs3 (ψ)
∂t
= P(ψ) − S(ψ) + Dsv (ψ) + Dsh1 (ψ) + Dsh2 (ψ) (5.429)
5.6. TURBULENCE TRANSPORT EQUATIONS 221
where the corrector and horizontal advective operators Csi and Ahi are given
by (5.337)–(5.339) and (5.342)–(5.343) with (uf ,vf ) replaced by (u,v).
Despite the similarities with the previous section, the discretisation me-
thods are described in detail below, to avoid any confusion.

Three cases can be distinguished for the time integration. They are discussed
in the subsections below.
5.6.1.1 integration without advection

In the absence of physical advection (iopt adv scal=0) the transport equation
is integrated in time using
hn+1;w
3 ψ n+1;w − hn;w
3 ψ
n;w
n+1;w = θv Dsv (ψ n+1;w ) + (1 − θv )Dsv (ψ n;w ) + P(ψ n;w )

h3 ∆t
ψ n+1;w
− S(ψ n;w ) n;w + Dsh1 (ψ n;w ) + Dsh2 (ψ n;w )
ψ
(5.430)
5.6.1.2 integration with advection but without operator splitting

If iopt adv turb=1 or 2, the transport equation (5.429) is integrated in time
using
ψ n+1;w − ψ n;w
= −Ah1 (ψ n;w ) + Cs1 (ψ n;w ) − Ah2 (ψ n;w ) + Cs2 (ψ n;w )
∆t
− θa Av (ψ n+1;w ) − (1 − θa )Av (ψ n;w ) + Cs3 (ψ n;w )
+ θv Dsv (ψ n+1;w ) + (1 − θv )Dsv (ψ n;w ) + P(ψ n;w )
ψ n+1;w
− S(ψ n;w ) n;w + Dsh1 (ψ n;w ) + Dsh2 (ψ n;w ) (5.431)
ψ
5.6.1.3 integration with operator splitting

If iopt adv turb=3, integration is performed along the following steps:
• Part A
n+1/3;w
ψA − ψ n;w
= −Ah1 (ψ n;w ) + Cs1 (ψ n;w ) + Dsh1 (ψ n;w ) (5.432)
∆t
n+2/3;w n+1/3;w
ψA − ψA n+1/3;w
= −Ah2 (ψA ) + Cs2 (ψ n:w )
∆t
n+1/3;w
+ Dsh2 (ψA ) (5.433)
n+2/3;w
ψAn+1;w − ψA n+2/3;w
= −θa Av (ψAn+1;w ) − (1 − θa )Av (ψA )
∆t
+ Cs3 (ψ n;w ) + θv Dsv (ψAn+1;w )
n+2/3;w
+ (1 − θv )Dsv (ψA ) + P(ψ n;w )
ψ n+1;w
− S(ψ n+2/3;w ) n+2/3;w (5.434)
ψ
• Part B
n+1/3;w
ψB − ψ n;w n+1/3;w
= −θa Av (ψB ) − (1 − θa )Av (ψ n;w )
∆t
n+1/3;w
+ Cs3 (ψ n;w ) + θv Dsv (ψB )
n;w n;w
+ (1 − θv )Dsv (ψ ) + P(ψ )
ψ n+1/3;w
− S(ψ n;w ) (5.435)
ψ n;w
n+2/3;w n+1/3;w
ψB − ψB n+1/3;w n+1/3;w
= −Ah2 (ψB ) + Cs2 (ψ n;w ) + Dsh2 (ψB )
∆t
(5.436)
n+2/3;w
ψBn+1;w − ψB n+2/3;w n+2/3;w
= −Ah1 (ψB ) + Cs1 (ψ n;w ) + Dsh1 (ψB )
∆t
(5.437)
• Updated value
1
ψ n+1;w = (ψAn+1;w + ψBn+1;w ) (5.438)
2
As before, the implicity factors are given by θa = 0.501, θv = 1.
5.6.2 Discretisation of advection

5.6.2.1 advection in the X-direction
The advective term in the X-direction is obtained by differencing the flux
F1uw at the W-node
hu2;i+1,j huw uw u uw uw
3;i+1,jk F1;i+1,jk − h2;ij h3;ijk F1;ijk
Ah1 (ψ)w
ijk = (5.439)
hc1;ij hc2;ij hw
3;ijk

uw uw uw uw uw
uw uw
where Fup;ijk and Flw;ijk are the upwind and Lax-Wendroff fluxes at the UW-
node:
uw 1 uw w w

Fup;ijk = uijk (αij + sijk )ψi−1,jk + (βij − sijk )ψijk (5.441)
2
uw 1 uw w w

Flw;ijk = uijk (αij + cijk )ψi−1,jk + (βij − cijk )ψijk (5.442)
2
uuw
ijk ∆t
sijk = Sign(uuw
ijk ) , cijk = (5.443)
hu1;ij
hc1;ij hc1;i−1,j
αij = , βij = (5.444)
hu1;ij hu1;ij
the type of advection scheme, selected by the switch iopt adv turb. The
argument r of the weight function is defined by
uw uw
u (αij + sijk )∆Fi−1,jk + (βij − sijk )∆Fi+1,jk
rijk = uw
2∆Fijk
uw uw uw
5.6.2.2 advection in the Y-direction

The advective term in the Y-direction is obtained by differencing the flux
F1vw at the W-node
hv1;i,j+1 hvw vw v vw vw
3;i,j+1,k F2;i,j+1,k − h1;ij h3;ijk F2;ijk
Ah2 (ψ)w
ijk = (5.446)
hc1;ij hc2;ij hw
3;ijk

vw vw vw vw vw
vw vw
where Fup;ijk and Flw;ijk are the upwind and Lax-Wendroff fluxes at the VW-
node:
vw 1 vw w w

Fup;ijk = vijk (αij + sijk )ψi,j−1,k + (βij − sijk )ψijk (5.448)
2
vw 1 vw w w

Flw;ijk = vijk (αij + cijk )ψi,j−1,k + (βij − cijk )ψijk ) (5.449)
2
vw
vw vijk ∆t
sijk = Sign(vijk ), cijk = v (5.450)
h2;ij
hc2;ij hc2;i,j−1
αij = , βij = (5.451)
hv2;ij hv2;ij
the type of advection scheme, selected by the switch iopt adv turb. The
argument r of the weight function is defined by
vw vw
vw (αij + sijk )∆Fi,j−1,k + (βij − sijk )∆Fi,j+1,k
rijk = vw
2∆Fijk
vw vw vw
5.6.2.3 advection in the vertical direction

The vertical advective term is obtained by differencing the flux F3c at the
W-node c c
w F3;ijk − F3;ij,k−1
Av (ψ)ijk = (5.453)
hw
3;ijk

c c c c c
c c
where Fup;ijk and Fce;ijk are the upwind and central fluxes at the C-node:
c 1 c w w

Fup;ijk = ωijk (1 + sijk )ψijk + (1 − sijk )ψij,k+1 (5.455)
2
c 1 c
Fce;ijk = ω (ψ w + ψij,k+1
w
) (5.456)
2 ijk ij,k
where
c
sijk = Sign(ωijk ) (5.457)
c c
w (1 + sijk )∆Fij,k−1 + (1 − sijk )∆Fij,k+1
rijk = c
2∆Fijk
c c c
5.6.2.4 corrector terms

The corrector terms are discretised using
3;i+1,jk ui+1,jk − h2;ij h3;ijk uijk
Cs1 (ψ)w = ψijk
w
(5.459)
hc1;ij hc2;ij hw
3;ijk
v vw vw v vw vw
w h1;i,j+1 h3;i,j+1,k vi,j+1,k − h1;ij h3;ijk vijk
Cs2 (ψ)w = ψijk (5.460)
hc1;ij hc2;ij hw
3;ijk
c c
ω ij,k+1 − ω ijk
Cs3 (ψ)w w
= ψijk (5.461)
hw
3;ijk
5.6.3 Discretisation of diffusion

5.6.3.1 diffusion in the X-direction
The diffusion term in the X-direction is obtained by differencing the flux D1uw
at the W-node
3;i+1,jk D1;i+1,jk − h2;ij h3;ijk D1;ijk
Dsh1 (ψ)w
ijk = (5.462)
hc1;ij hc2;ij hw
3;ijk
uw λuw w w
H (ψijk − ψi−1,jk )
D1;ijk = (5.463)
hu1;ij
5.6.3.2 diffusion in the Y-direction

The diffusion term in the Y-direction is obtained by differencing the flux D2w
at the W-node
hv1;i,j+1 hvw vw v vw vw
3;i,j+1,k D2;i,j+1,k − h1;ij h3;ijk D2;ijk
Dsh2 (ψ)w
ijk = (5.464)
hc1;ij hc2;ij hw
3;ijk
vw λvw w w
H (ψijk − ψi,j−1,k )
D2;ijk = (5.465)
hv2;ij
5.6.3.3 diffusion in the vertical direction

The vertical diffusion term is obtained by differencing the flux D3c at the
W-node
Dc − Dc
Dsv (ψijk )w = 3;ijk w 3;ij,k−1 (5.466)
h3;ijk
λψ;c w
(ψij,k+1 w
− ψijk )
c
D3;ijk = T c
(5.467)
h3;ijk
5.6.4 Diffusion coefficients for turbulence variables

The horizontal turbulent diffusion coefficients are the same as the one used
for scalar transport. They are obtained by vertical interpolation of λuH and
λvH , given by (5.389–(5.390) to respectively the UW and VW-nodes.
5.6.4.2 vertical diffusion coefficients

The vertical turbulent diffusion coefficients, used in the ε-equation (4.193)
and kl-equation (4.197), are proportional to νk which is the one used in
the k-equation (4.192). Different formulations for the parameterisation of
νk are available and discussed in Section 4.4.3.3. No specific discretisation
procedures are required since all expressions are purely algebraic.
The following remarks are to be given

• Values are first obtained at the W-nodes and then interpolated at the
C-nodes.
• No value is calculated at the surface and the bottom.
• Since νk is calculated prior to the solution of the turbulent transport

equations, its value is obtained using values of k, ε and l at the old
time tn .
5.6.5 Production and sink terms

All turbulence transport equations contain, besides the diffusion terms, three
terms on their right hand side. The first is the shear production term, the
second is the buoyancy term which is a production or sink term if N 2 < 0 or
N 2 > 0 and the third is a dissipation (sink) term. Defining
N 2 = max(N 2 , 0) + min(N 2 , 0) = N+2 − N−2 (5.468)
one has
P(k) = νT M 2 + λT N−2
ǫ
P(ε) = c1ε νT M 2 + c3ε λT N−2
k
1
P(kl) = l E1 νT M 2 + E3 λT N−2 (5.469)
2
and
S(k) = λT N+2 + ε
ε2
S(ε) = c1ε c3ε λT N+2 + c2ε
k
1
S(kl) = lE3 λT N+2 + ǫ0 k 3/2 W̃ (5.470)
2
The discretisation of M 2 , N±2 , νT and λT is discussed in Section 5.3.11.2.
Production terms are taken explicit in time using values of all quantities at
time tn . Sink terms are discretised quasi-implictly using (5.428):
k n+1
S(k) = (λT N+2 + εn )
kn
εn+1 εn εn+1
S(ε) = c1ε c3ε λT N+2 + c 2ε
εn kn
√
1 λT N+2 (kl)n+1 k n W̃
S(kl) = E 3 n + ǫ0 (5.471)
2 k ln
5.6.6 Boundary conditions

In analogy with the scalar case two Neumann and two Dirichlet type of
surface boundary conditions are available in the program.
ψ;w
1. Neumann condition with a prescribed flux Fs;N z +1
at the surface
w ψ;w
D3;ij,N z +1
= Fs;ij,N z +1
(5.472)
The flux at the first C-node below the surface is then determined by
interpolating the surface value and the calculated flux at the second
C-node below the surface
ψ;w
c 2hw c c
3;ijNz Fs;ij,Nz +1 + h3;ijNz D3;ij,Nz −1
D3;ijN =
z
2hw c
3;ijNz + h3;ijNz
ψ;w
2hw
3;ijNz Fs;ij,Nz +1 hc3;ijNz λψ;c w w
T ;ij,Nz −1 (ψijNz − ψij,Nz −1 )
= +
2hw c
3;ijNz + h3;ijNz hc3;ij,Nz −1 (2hw c
3;ijNz + h3;ijNz )
(5.473)
Table 5.6: Discretisation schemes for each of the available surface and bottom
boundary conditions for turbulent variables.
variable equation discretisation scheme
k (4.269) Dirichlet at the surface
ε (4.269) Dirichlet at the first W-node below the surface
l (4.269) Dirichlet at the first W-node below the surface
k (4.271) prescribed flux at the surface
ε (4.272) prescribed flux at the first C-node below the surface
k (4.337) Dirichlet at the bottom
ε (4.337) Dirichlet at the first W-node above the sea bed
l (4.337) Dirichlet at the first W-node above the sea bed
k (4.338) prescribed flux at the bottom
ε (4.339) prescribed flux at the first C-node above the sea bed
with
w w n+1;w n+1;w n;w n;w

ψijN z
− ψij,N z −1
= θv (ψijN z
− ψij,N z −1
) + (1 − θv )(ψijN z
− ψij,N z −1
)
(5.474)
ψ;c
2. Neumann using a prescribed flux Fs;ijN z
at the first C-node below the
surface
c ψ;c
D3;ijN z
= Fs;ijN z
(5.475)
w
3. Dirichlet condition with a prescribed value ψs;ij,N z +1
at the surface
w
ψij,Nz +1 = ψs;ij,N z +1
(5.476)
w
4. Dirichlet condition with a prescribed value ψs;ijN z
at the first W-node
below the surface
w
ψijNz = ψs;ijN z
(5.477)
Several formulations of surface boundary conditions have been introduced

in Section 4.7.5. The discretisation scheme for each formulation is indicated
in Table 5.6.
It is remarked that all turbulent diffusion coefficients are calculated using
those values of k, ε and l which are located within the water column and not
at the surface itself so that (5.475) and (5.477) can be considered as realistic
conditions.
In analogy with the scalar case two Neumann and two Dirichlet type of
bottom boundary conditions are available in the program.
ψ;w
1. Neumann condition with a prescribed flux Fb;ij1 at the bottom
w ψ;w
D3;ij1 = Fb;ij1 (5.478)
The flux at the first C-node above the sea bed is then determined by
interpolating the bottom value and the calculated flux at the second
C-node above the sea bed
ψ;w
c
2hw c c
3;ij2 Fb;ij + h3;ij1 D3;ij2
D3;ij1 =
2hw c
3;ij2 + h3;ij1
ψ;w
2hw3;ij2 Fb;ij hc3;ij1 λψ;c w w
T ;ij2 (ψij3 − ψij2 )
= +
2hw c
3;ij2 + h3;ij1 hc3;ij2 (2hw c
3;ij2 + h3;ij1 )
(5.479)
with
w w n+1;w n+1;w n;w n;w

ψij3 − ψij2 = θv (ψij3 − ψij2 ) + (1 − θv )(ψij3 − ψij2 ) (5.480)
ψ;c
2. Neumann using a prescribed flux Fb;ij1 at the first C-node above the
bottom
c ψ;c
D3;ij1 = Fb;ij1 (5.481)
w
3. Dirichlet condition with a prescribed value ψb;ij1 at the bottom
w
ψij1 = ψb;ij1 (5.482)
w
4. Dirichlet condition with a prescribed value ψb;ij2 at the first W-node
above the bottom
w
ψij2 = ψb;ij2 (5.483)
Several formulations of bottom boundary conditions have been introduced

in Section 4.9.4. The discretisation scheme for each formulation is indicated
in Table 5.6.
5.6.6.3 lateral boundary conditions

The fluxes normal to an open boundary are calculated using the upwind
scheme. Applying the zero gradient condition one obtains
e;w w uw
ψijk = ψi:i−1,jk or F1;ijk = uuw w
ijk ψi:i−1,jk (5.484)
e;w w vw vw w
ψijk = ψi,j:j−1,k or F2;ijk = vijk ψi,j:j−1k (5.485)
Advective fluxes normal to a closed (coastal) open boundary are set to

zero.
5.6.7 Solution of the discretised equations for turbu-

lent transport variables
As for momentum, the discretised equations can be written in the tridiagonal
form (5.302). Expressions for the matrix components are given below for the
case that no operator splitting is used. They are easily extended to the case
with operator splitting.
When a Neumann boundary condition is taken, no calculation is per-
formed at the surface or bottom itself. In case of a Dirichlet condition, the
surface (bottom) value of ψ is determined by the boundary condition itself.
This means that the vertical index k varies between kmin and kmax . The
lower limit kmin equals 3 for a Dirichlet condition at the first W-node above
the bottom and 2 otherwise. Likewise kmax equals Nz − 1 for a Dirichlet
condition at the first W-node below the surface and Nz otherwise.
For simplicity, the i and j indices are omitted.
1. Time derivative.
Atk = 0 , Bkt = 1 , Ckt = 0 , Dkt = ψkn;w (5.486)

a
Ak− = −θa c−
k (1 + fk−1 )
a− −
Bk = −θa ck (1 − fk−1 )
a
Ck − = 0

a n;w n;w
Dk − = (1 − θa )c−
k (1 + fk−1 )ψk−1 + (1 − fk−1 )ψk (5.487)
where kmin ≤ k ≤ kmax ,

c
∆tωk−1
c−
k = , fk = 1 − Ω(rkc ) sk (5.488)
2hw
3;k
w
and sijk , rijk are defined by (5.457) and (5.458).
a
Ak+ = 0
a
B k + = θa c +
k (1 + fk )
a+ +
Ck = θa ck (1 − fk )

a n;w n;w
Dk + = −(1 − θa )c+
k (1 + fk )ψk + (1 − fk )ψk+1
(5.489)
where kmin ≤ k ≤ kmax and

∆tωkc
c+
k = (5.490)
2hw
3;k
d ∆tλψ;c
Ak− = −θv c T ;k−1
h3;k−1 hw
3;k
d ∆tλψ;cT ;k−1
B k − = θv
hc3;k−1 hw3;k
d
Ck − = 0
d ∆tλψ;cT ;k−1
Dk− = −(1 − θv ) (ψkn;w − ψk−1
n;w
) (5.491)
hc3;k−1 hw3;k
where klo ≤ k ≤ kmax and klo equals 2 for a Dirichlet condition at the
bottom and 3 otherwise.
d
Ak+ = 0
d ∆tλψ;c
Bk + = θv c Tw;k
h3;k h3;k
d ∆tλψ;c T ;k
Ck + = −θv
hc3;k hw3;k
d ∆tλψ;cT ;k n;w
Dk+ = (1 − θv ) c w
(ψk+1 − ψkn;w ) (5.492)
h3;k h3;k
where kmin ≤ k ≤ kup and kup equals Nz for a Dirichlet condition at
the surface and Nz -1 otherwise.
4. Sink terms.
S(ψ n;w )k
ASk = CkS = DkS = 0 , BkS = (5.493)
ψkn;w
Aek = Bke = Cke = 0

Dke = ∆t Pkn − Ãh1 (ψ n;w )w
k − Ãh2 (ψ
n;w w
)k + Cs1 (ψ n;w )w
k

+ Cs2 (ψ n;w )w
k + Cs3 (ψ
n;w w
)k + Dsh1 (ψ n;w )w
k + Dsh2 (ψ
n;w w
)k
(5.494)

Contributions from the surface boundary conditions depends on the
ψ;w
• Neumann condition with a prescribed surface flux Fs;N z +1
.
θv ∆thc3;Nz λψ;c
T ;Nz −1
AsNz = w
h3;Nz (2h3;Nz + h3;Nz ))hc3;Nz −1
w c
s θv ∆thc3;Nz λψ;c
T ;Nz −1
BN = − w
z
h3;Nz (2h3;Nz + h3;Nz ))hc3;Nz −1
w c
CNs z = 0
s ∆t
ψ;w
DN = 2Fs;N z +1
z
2hw
3;Nz + h c
3;Nz
hc3;Nz λψ;c n;w n;w

T ;Nz −1 (ψNz − ψNz −1 )

+ (1 − θv ) w c
(5.495)
h3;Nz h3;Nz −1
ψ;c
• Neumann using a prescribed flux Fs;N z
at the first C-node below
the surface
ψ;c
∆tFs;N
AsNz = s
BN = CNs z = 0, s
DN = z
(5.496)
z z
hw
3;Nz
w
• Dirichlet condition with a prescribed value ψs;N z +1
at the surface
AsNz +1 = CNs z +1 = 0 , s
BN z +1
= 1, s
DN z +1
w
= ψs;N z +1
(5.497)
w
• Dirichlet condition with a prescribed value ψs;N z
at the first W-
node below the surface
BN z
= 1, s
DN z
w
= ψs;N z
(5.498)
Contributions from the bottom boundary conditions depends on the
ψ;w
• Neumann condition with a prescribed bottom flux Fb;1 at the
bottom
Ab2 = 0
θv ∆thc3;1 λψ;c
T ;2
B2b = −
hw
3;2 (2h w
3;2 + h c c
3;1 ))h3;2
θv ∆thc3;1 λψ;c
T ;2
C2b =
hw
3;2 (2h w
3;2 + h c c
3;1 ))h3;2
∆t
ψ;w hc3;1 λψ;c
T ;2 (ψ3
n;w
− ψ2n;w )
D2b = − w 2Fb;1 + (1 − θv )
2h3;2 + hc3;1 hw c
3;2 h3;2
(5.499)
ψ;c
• Neumann using a prescribed flux Fb;1 at the first C-node above
the bottom
ψ;c
∆tFb;1
Ab2 = B2b = C2s = 0 , D2b = − (5.500)
hw
3;2
w
• Dirichlet condition with a prescribed value ψb;1 at the bottom
Ab1 = C1b = 0 , B1b = 1 , D1b = ψb;1
w
(5.501)
w
• Dirichlet condition with a prescribed value ψb;2 at the first W-node
above the bottom
Ab2 = C2b = 0 , B2b = 1 , D2b = ψb;2
w
(5.502)
5.7 Discretisations on reduced grids

5.7.1 Discretised 1-D mode equations
1. To make the code compatible with the 3-D case which uses an Arakawa
C-grid, the model grid on which the equations are discretised, does not
not reduce to a single point but consists of 3 rows and columns (i.e.
nc=nr=3) of which the last column and the last row consist of dummy
land points (see Figure 5.1). This produces a computational overhead
since the same calculation is performed at each of the four wet C-nodes
and the two internal U and V velocity nodes.
2. Momentum equations
• The 1-D versions (4.98)–4.99) are integrated in time without op-

erator and mode splitting using the formulations given in Sec-
tions 5.3.1.1 and 5.3.1.3. Firstly, “predicted” values are calculated
ũp − un ∂ζ n+1
= f v n + θv Dmv (ũp ) + (1 − θv )Dmv (un ) − g + F1t;n+1
∆t ∂x
(5.503)
p n n+1
ṽ − v ∂ζ
= −f un + θv Dmv (ṽ p ) + (1 − θv )Dmv (v n ) − g + F2t;n+1
∆t ∂y
(5.504)
An implicit correction is added for the Coriolis force giving (up ,
v p ) by equations (5.9). “Corrected” values are obtained by
n+1 hn3;k p n+1 hn3;k p

u = n+1 u , v = n+1 v (5.505)
h3;k h3;k
where the surface slopes and the elevations used to calculate the
vertical grid spacing hn+1
3;k = (h + ζ
n+1
)∆σk are prescribed exter-
nally by expressions of the form (4.273).
• The vertical diffusion terms and coefficients are discretised using
the formulations given in Sections 5.3.10 and 5.3.11.2.
• Once the currents are updated, the depth-mean currents u and v
are evaluated (for user output only).
3. Scalar equations
• The transport equation for a scalar ψ is integrated in time without

operator splitting using the discretisation (5.345).
5.8. SOLUTION PROCEDURE 235
• The vertical diffusion term and coefficient are discretised as des-

cribed in Sections 5.5.5.3 and 5.5.6.2.
• Neumann and Dirichlet onditions can be applied as discussed in
Sections 5.5.7.1–5.5.7.2.
4. The turbulence equations are solved as in the 3-D case without advec-
tion and operator splitting.
5.7.2 Discretised depth-integrated equations

1. Momentum equations
• The surface elevation and depth-integrated currents are updated
by solving the 2-D momentum equations using the same discretisa-
tion procedures given in Sections 5.3 without the depth-integrated
baroclinic terms but with the same barotropic time step ∆τ .
• To make the code compatible with the 3-D case all “3-D” currents
are set to their depth-mean value
uf = u = U/H = u
vf = v = V /H = v (5.506)
2. Scalar equations
• Scalar transport is discretised in exactly the same way as in the
3-D case with the larger 3-D time step ∆t.
• The vertical diffusion term is retained and discretised using (5.388)
except that the upper and lower fluxes are located at the respec-
tively the surface and the bottom and therefore obtained by the
surface and bottom boundary conditions which must obviously be
of the Neumann type.
3. No turbulence transport equations need to be solved.
5.8 Solution procedure

The general solution procedure can be summarised as follows
1. Initial time t = 0.
1.1 Obtain initial conditions for U , V , ζ, u, v, ω, T , S, k, l or ε, and
quantities which are updated in time at open boundaries.
1.2 Initialise ρ, βT , βS from the equation of state.

1.3 Evaluate the astronomical force at the initial time.
1.4 Initialise meteorological data.
1.5 Initialise open boundary data for the 2-D mode, 3-D mode, tem-
perature, salinity.
1.6 Initialise surface and bottom stress.
2. Predictor step at t = tp = tn + ∆τ with n=0, . . . , Ntot − 1.
2.1 Update meteorological data (if needed).

2.2 Update ρ, βT , βS from the equation of state.
2.3 Update all vertical diffusion coefficients. In case of a RANS model,
k, l or ε are first updated at time tn+1 .
2.4 Evaluate the components of the baroclinic pressure gradient.
2.5 Evaluate the horizontal diffusion coefficients at different nodes.
2.6 Obtain up , v p by solving the 3-D momentum equations.
3. Barotropic time steps t = tn + m∆τ with m=1, . . . , Mt .
3.1 Update meteorological data (if needed).

3.2 Solve 2-D continuity equation for ζ.
3.3 Update open boundary data for the 2-D mode (if needed).
3.4 Update astronomical force.
3.5 Update U , V by solving the 2-D momentum equations.
3.6 Update the time-averaged transports Uf , Vf .
4. Corrector step at t = tn+1 = tn + ∆t with n=1, . . . , Ntot .
4.1 3-D mode

4.1.1 Update open boundary data (if needed).
4.1.2 Apply open boundary conditions.
4.1.3 Apply filter correction to obtain un+1 , v n+1 .
4.1.4 Evaluate filtered currents uf , vf .
4.1.5 Solve 3-D baroclinic continuity equation for ω.
4.1.6 Update physical vertical current.
4.1.7 Update bottom and surface stress (if needed).
5.8. SOLUTION PROCEDURE 237
4.2 Update temperature at time tn+1 .

4.2.3 Evaluate solar irradiance.
4.2.4 Evaluate surface (non-solar) heat fluxes.
4.2.5 Solve temperature equation.
4.3 Update salinity at time tn+1 .
4.3.3 Solve salinity equation.
Note that
• Some of the previous steps are only conditionally performed, depending

on the setting of model switches. For example, the temperature equa-
tion is only updated when iopt temp=2, the astronomical tidal force is
only included if iopt astro tide=1, . . . .
• Update of surface or open boundary forcing data depends on the set-

tings of the tlims attribute, discussed in Section 12.7.2 of the User
Manual.
Part III
Description of the model code
239
Chapter 6
Program conventions and

techniques
The following items are discussed in this chapter.

• The COHERENS V2.0 code is written in standard FORTRAN 90 format.
To improve portability and transparancy a number of programming
conventions, further denoted as the “COHERENS conventions”, have
been adopted. They are described in Section 6.1. These rules are of
importance for developers who are working on new developments and
have the intention to make the new code available to the COHERENS
community.
• Implementation of specific FORTRAN 90 features such as allocatable

arrays, derived types, modules and generic routines, are discussed in
Sections 6.1.3–6.1.6.
• The format for internal documentation is explained in Section 6.1.7.
• Basic aspects of the model code such as the principle of key ids, time
formats, data flags and the units of program variables are discussed in
Section 6.2.
6.1 Implementation of FORTRAN 90

A main difference between versions 1 and 2 of COHERENS is that the code
in the old version is written in FORTRAN 77 and the latter in FORTRAN
90. This section discusses the programming conventions based upon specific
features of FORTRAN 90. Users, who have no experience with FORTRAN 90
but are familiar with the FORTRAN 77 standard may consult the many books,
241
242 CHAPTER 6. PROGRAM CONVENTIONS AND TECHNIQUES
course notes and other publications available from commercial publishers or

via the internet.
6.1.1 COHERENS programming conventions

1. All source code is written in “free format”. This implies the following:
• The column position is irrelevant. The adopted rule is that all pro-
gram lines start at column 1, with exceptions of statements within
control constructs such as IF blocks, DO loops and SELECT CASE
constructs, which are intended by one TAB position to the right.
Lines within a nested construct are intended with respect to the
previous one. For clarity no indentation is applied if the DO/ENDDO
statement of a nested loop is located just below/above the DO/ENDDO
of the parent loop. This is illustrated with the following example.
idesc 360: DO idesc=1,MaxIOTypes
ifil 360: DO ifil=1,MaxIOFiles
SELECT CASE (idesc)
CASE (io mppmod,io modgrd,io metgrd,io sstgrd,io biogrd,&
& io nstgrd,io biospc,io rlxobc,io nstspc)
modfiles(idesc,ifil,:)%nocoords = 0
CASE (io 1uvsur,io 2uvobc,io 3uvobc,io salobc,io tmpobc,&
& io bioobc)
IF (ifil.EQ.1) THEN
ELSE
ENDIF
CASE (io inicon,io 2uvnst,io 3uvnst,io salnst,io tmpnst,&
& io bionst,io metsur,io sstsur,io biosur)
END SELECT
ENDDO ifil 360
ENDDO idesc 360
Example 6.1: indentation of control structures and continuation

lines.
• Although the free format allows line lengths upto 132 characters,
a length of 80 characters is taken for clarity since this is the maxi-
mum length on standard X-windows on UNIX/LINUX machines.
6.1. IMPLEMENTATION OF FORTRAN 90 243
Statements longer than this limit are continued on the next line
by appending a ‘&’ character at the end of the line and at the
start of the (possibly) intended line, as shown in Example 6.1.
• Comments lines start with a ‘!’ in the first column. Although
allowed by the FORTRAN 90 standard, the common practice is,
for reason of clarity, not to use comments after the first column
(i.e. in the middle of a line).
• Short statements may be written on one line by inserting a ‘;’
before each next statement.
• Statements labels always start at the first column.
2. Names of variables, named constants, program units (subroutines, func-

tions, modules) and dummy arguments can contain letters, digits and
underscores. The first character must be a letter. The maximum length
of a name is given by the program parameter lenname = 31, which is
also the FORTRAN 90 standard. The underscore character ‘ ’ is used in
the code for names composed of different words, e.g. density equation,
land mask, or for key ids (see Section 6.2.1) below.
3. Although names in FORTRAN 90 are case insensitive, the convention is

adopted to write all FORTRAN 90 specific names in uppercase, and all
names, defined in the code in lowercase letters. A mixed case is used
for some systems parameters (see e.g. syspars.f90).
4. The program uses explicit typing. This means that the type of each
variable, parameter or function result needs to declared explicitly in
the declaration part of a program unit. This part must be preceded by
the line:
IMPLICIT NONE
5. The indices of an array defined on the model grid, as defined in Sec-

tion 8.1.1, are denoted by i,j,k for respectively the X-, Y- and Z-
direction.
6. In FORTRAN 77 the values of a model grid array can only be accessed

element-wise within an assignment statement. The FORTRAN 90 stan-
dard allows to use assignments on whole arrays or array sections. The
rule is that the expression on the right is either a scalar or an array
with the same shape as the one on the left. In the first case the value
of the scalar is assigned to all elements in the array on the left. In
the second one, the values of the array expression on the right are as-
signed element-wise to the corrsponding elements of the array variable
on the left. The convention, adopted in COHERENS, is to use array
assignments where possible, e.g.
REAL, DIMENSION(ncloc,nrloc,nz) :: array3dc

...
array3dc = 0.0
This procedure is primarily used for the initialisation of variables. How-

ever, in most parts of the program distinction has to be made between
grid points located on land and sea points. The method consists in
maintaining a vertical (“k”) loop, whereas the (“i,j”) loops in the ho-
rizontal direction are replaced by array assignments within a WHERE
block, as in the following example:
k 434: DO k=1,nz
WHERE (maskatc int)
psic A(1:ncloc,1:nrloc,k) = tridcfc(:,:,k,4)
END WHERE
ENDDO k 434
Example 6.2: array assignment and land masks.
The array maskatc int is .TRUE. or .FALSE. for grid points located at
sea or on land and has the same shape as the array assignment(s) within
the WHERE block. In this way calculations are restricted to sea points
only.
7. Scalar and array variables must be initialised. More precisely, each
scalar or array element must have a value assigned to it, before it can
appear within an expression on the right of an assignment statement.
The standard initialisation value for variables which have no useful
default value is 0.0 for REAL, 0 for INTEGER, .FALSE. for LOGICAL
and ” (empty string) for CHARACTER variables. In this way a model
grid array is always defined at all grid points. Values at sea points
are usually re-defined within the program whereas values in land areas
remain equal to the initial (zero or .FALSE.) value.
8. As explained in Section 10.1, there are four types of program units:
main program, external routines, module routines and modules where
the main variables used in the program are declared. The following
rules are applied in the code:
• Dummy arguments of an external or module routine need to be

declared with the INTENT attribute (although this is not required
by the FORTRAN 90 standard). The INTENT attribute can have
the values IN, OUT and INOUT.
• Optional arguments are only allowed in module routine declara-
tions and not in external routines. This avoids the programming
of explicit interfaces. Optional arguments are positioned after all
non-optional arguments.
• Argument association in a routine call is positional for non-optional
arguments, whereas keyword association is used for (eventually)
optional arguments.
CALL cf90 inquire variable(iunit,ivar,name=f90 name(ivar),&

& dimids=iddims(1:ndims))
where name and dimids are the names of dummy optional argu-
ments.
• Module routines are declared in a sub-program with a USE state-
ment of the form given in Section 6.1.5.
• The last lines of a SUBROUTINE or FUNCTION consist of a RE-
TURN statement followed either by an empty line, one or more
specification or errror code lines, followed by a END proc name
statement where proc name is the name of the routine.
• Since all variables (scalars and arrays) are to be initialised, they
must be defined with a value before they can be used as an actual
argument with the INTENT(IN) or INTENT(INOUT) attribute.
This is of importance, since, for example, passing an undefined
value as argument in a read or MPI call may produce unexpected
side effects.
9. The following FORTRAN 77 features are not allowed or not recom-

mended in the COHERENS programming convention:
• COMMON and INCLUDE1 are excluded

• GOTO statements are allowed only in exceptional cases (e.g. for
error coding).
1
INCLUDE mpif.h is the only allowed exception.
6.1.2 Data types

Table 6.1 lists the data types implemented in COHERENS V2.0. The COM-
PLEX, INTEGER(KIND=8) and (derived) TYPE do not exist or are non-
standard in FORTRAN 77. The following comments are to be given:
• For the LOGICAL, INTEGER, REAL, COMPLEX types without a KIND
specifier, a default KIND value is taken, as given in the last column.
These defaults are standard on most (commercial and free software)
compilers. If this is not the case, they can usually be enforced through
compiler options.
• The INTEGER (KIND=8) type is not supported by all compilers (such

as gfortran). In that case, the KIND value is replaced 4. This poses
no problem for most program applications, since the type is only used
to designate the number of seconds since a given date (see Section 6.2.2
for a further discussion).
• Each type has a corresponding id, represented by an INTEGER para-

meter, given in the second column of Table 6.1. The id is e.g. used
in the program to identify the type of variable in a routine call. For
example, the last argument in the routine call
CALL error alloc(’depmeanatc’,2,(/ncloc+2,nrloc+2/),real type)
informs the routine error alloc that the variable ’depmeanatc’ is of type
REAL.
• The KIND value is represented by a named constant, given in column 3,

whose value is given in the fourth column of Table 6.1.
• DERIVED TYPES are a new feature of FORTRAN 90 further discussed

in Section 6.1.4.
• COMPLEX variables are currently only used for fast Fourier analysis
(file fft library.f90).
Type declaration statements have the following general FORTRAN 90
syntax:
type [, att,...] :: var name
where
type : the data type of the variable
Table 6.1: Model data types.
FORTRAN type COHERENS type KIND parameter (assumed) size in bytes

CHARACTER char type kndchar 1
LOGICAL log type kndlog 4
INTEGER int type kndint 4
INTEGER (KIND=8) longint type kndilong 4 or 8 (non-standard)
REAL real type kndreal 4
REAL (KIND=8) long type kndlong 8
COMPLEX complx type kndcmplx 8
DERIVED – –
att : one or more attribute(s) of the variable, which can take the following
forms
SAVE: the value of the variable is saved after the routines is exited
INTENT: used to declare dummy arguments only. Takes one of the
forms: INTENT(IN) if the actual argument is defined in the calling
routine and not re-defined in the called routine, INTENT(OUT) of
the variable is assumed to be undefined in the calling routine and
becomes defined within the called routine, INTENT(INOUT) if the
actual argument is defined in the calling routine and can be re-
defined in the called routine. Note that the INTENT attribute is
always given in declaration statements of dummy arguments (al-
though this is not required by the FORTRAN 90 standard).
DIMENSION: used to define the shape of an array variable. The array
shape is added in parentheses.
ALLOCATABLE: to declare an allocatable array (see Section 6.1.3)
PARAMETER: a named constant whose value cannot be changed by the
program
var name name of the variable
It is remarked that
• CHARACTER variables have an additional attribute LEN=len where len
is the length of the character string.
• Variables, sharing the same attributes are (preferentially) declared on
the same line.
• Declaration and definition of DERIVED TYPE variables is discussed in

Section 6.1.4. To improve transparancy all DERIVED TYPE defnitions
are made in the common file datatypes.f90.
For example
CHARACTER (LEN=12) :: ctype

CHARACTER (LEN=lenname), DIMENSION(MaxProgLevels) :: procname
INTEGER, PARAMETER :: lentime = 21
INTEGER, SAVE :: iunit
REAL :: xtemp, ytemp
REAL, DIMENSION(ncloc,nrloc) :: array2dc1
REAL, SAVE, ALLOCATABLE, DIMENSION(:,:) :: array2dc2, array2dc3
Example 6.3: examples of type declarations.
6.1.3 Allocatable arrays

Allocatable arrays are arrays declared with a rank but without shape. After
been allocated with the ALLOCATE statement, allocated arrays can be deal-
located with a DEALLOCATE statement at any time within the program.
Advantages are:
• An efficient programming of ALLOCATE and DEALLOCATE statements

offers the possibility for significant memory savings and a more effi-
cient use of internal memory. For example, the COHERENS V1 pro-
gram, written in FORTRAN 77, required that all memory allocations
are known at compilation, implying the consumption of unused mem-
ory.
• Array bounds can (re)assigned with non-constant values.
• Allocatable arrays can be SAVEd, even before the “ALLOCATABLE”

statement is executed (see Example 6.3)
• Contrary to automatic arrays which are usually stored on the machine’s

stack memory, allocated arrays use internal memory. This offers a clear
advantage on machines with a limited stack size.
• In parallel mode, different bounds can be defined for the same array on
different process domains.
Disadvantages are:
• Arrays, that have not been allocated yet, cannot be passed as argu-
ments to a routine call.
• Errors are difficult to debug. For example, it may occur that values are
assigned to an array which is allocated with a zero size. This causes a
memory fault which is often difficult to detect, since it usually causes
a crash at a different location within the program.
• Although this has not been observed from the performance tests per-
formed with COHERENS V2.0, an intensive use of allocation/deallocation
may decrease the performance of the program.
A source code example of array allocation is given below.
REAL, ALLOCATABLE, DIMENSION(:,:) :: array2d

...
l1 = ...; l2 = ...; u2 = ...
ALLOCATE (array2d(l1:l2,u2),STAT=ierr)
CALL error alloc(’array2d’,2,(/l2-l1+1,u2/),real type)
...
IF (ALLOCATED(array2d)) DEALLOCATE (array2d)
Example 6.4: example of an allocate statement in COHERENS.
The error alloc routine is called by the program after each ALLOCATE state-
ment to check whether an allocation error occurred.
Array allocation is applied in the model as follows.
• “Global arrays”, i.e. arrays which are accessible to all program units
such as temperature, currents, . . . , are (almost) always declared with
the ALLOCATE and SAVE attribute2 . Note that in case of a parallel
mode, the shapes of model grid arrays depend on the size of the sub-
domain.
• Local arrays are only accessible to a program unit (SUBROUTINE or

FUNCTION). They are declared either as allocatable or as automatic
arrays depending on whether the CPP option -DMPI is set (see Sec-
tion 2.2). Consider the following example
2
For technical reasons a few arrays are declared with constant array dimensions.
SUBROUTINE ....
!---declare
#ifdef ALLOC
REAL, SAVE, ALLOCATABLE, DIMENSION(:,:,:) :: source
#else
REAL, DIMENSION(ncloc,nrloc,nz) :: source
#endif /*ALLOC*/
...
!---allocate
#ifdef ALLOC
ALLOCATE (source(ncloc,nrloc,nz),STAT=errstat)
CALL error alloc(’source’,3,(/ncloc,nrloc,nz/),real_type)
#endif /*ALLOC*/
.....
!---deallocate
#ifdef ALLOC
DEALLOCATE (source)
#endif /*ALLOC*/
END SUBROUTINE
Example 6.5: allocation/deallocation of local arrays.
If the ALLOC option is set, the local array source is declared as ALLO-
CATABLE, allocated at the beginning of the routine and deallocated
before exiting the routine. Otherwise, it is declared as an automatic
array. The first case has to be taken if there is no sufficient mem-
ory available, the second if the allocation/deallocation procedures have
a negative impact on CPU time. The choice is obviously machine-
dependent.
6.1.4 Derived types

DERIVED TYPE variables can be considered as aggregated structures com-
posed of “atomic” FORTRAN data types (INTEGER, REAL, LOGICAL, CHAR-
ACTER). The aim, in COHERENS, is to store all possible information about
a specific item (e.g. a file or variable) in a structured format.
Before a DERIVED TYPE can be declared, its TYPE needs to be defined.
The example below, taken from the source code, shows the definition of a
derived type variable for storing the attributes of a program variable.
TYPE :: VariableAtts
CHARACTER (LEN=lenname) :: f90 name
CHARACTER (LEN=lendesc) :: long name, vector name

CHARACTER (LEN=lenunit) :: units
CHARACTER (LEN=lennode) :: node
INTEGER :: data type, ivarid, nrank
INTEGER, DIMENSION(4) :: shape
END TYPE VariableAtts
Example 6.6: TYPE definition for storing variable attributes.
A variable of this type can be defined as
TYPE (VariableAtts) :: varatts
The components of varatt are accessed using the FORTRAN 90 syntax
• varatts%f90 name: a character string with the FORTRAN name of the

variable
• varatts%long name: a string of length lendesc describing the variable
• varatts%data type: the data type of the variable as given in the second
column of Table 6.1
• varatts%nrank: rank of the variable (0 for a scalar, 1 for a vector, . . . )
• ...
The DERIVED TYPE FileParams is used to store all atributes of a file
TYPE :: FileParams
LOGICAL :: defined, info, opened, time regular
CHARACTER (LEN=1) :: form, status
CHARACTER (LEN=leniofile) :: filename, pathname
CHARACTER (LEN=lendesc) :: filedesc
INTEGER :: endfile, header type, iostat, iunit, lenrec, maxrecs, &
& nocoords, nodim, novars, timeid, timerec, tskips, &
& varid, zetaid
INTEGER, DIMENSION(3) :: tlims
END TYPE FileParams
Example 6.7: TYPE definition for storing file attributes.

A useful property of DERIVED TYPEs is that they can de declared with

the same attributes as any other data type. This means that they can be
declared as scalars, arrays with a given shape, allocatable arrays with a
given rank and with the SAVE or INTENT attribute. The following example
illustrates how the attributes of the variables within a certain data file are
defined first and then written to the file.
!---declare
INTEGER :: numvars
TYPE (FileParams), DIMENSION(MaxIOTypes,MaxIOFiles,2) :: modfiles
TYPE (FileParams) :: filepars
TYPE (VariableAtts), ALLOCATABLE, DIMENSION(:) :: varatts
!---define file attributes

CALL set modfiles atts(io modgrd,1,2)
filepars = modfiles(io modgrd,1,2)
numvars = filepars%novars
!---open file
CALL open filepars(filepars)
!---define variable attributes

ALLOCATE (varatts(numvars),STAT=errstat)
CALL error alloc struc(’varatts’,1,(/numvars/),’VariableAtts’)
CALL set modvars atts(io modgrd,1,2,varatts,numvars)
!---write variable attributes

CALL write atts mod(filepars,varatts,numvars)
...
!---deallocate
DEALLOCATE (varatts)
Example 6.8: defining and writing variable attributes to a data file.
File formats will be discussed in Chapter 7.
The next example describes how the relative coordinates of a 2-D external
grid are obtained and stored. These type of coordinates are used to perform
interpolation of model data to each point of the data grid and are further
discussed in Sections 8.3 and 8.4.2. The following TYPEs are defined
!---attributes of surface grids
TYPE :: GridParams
INTEGER :: nhtype, n1dat, n2dat

REAL :: delxdat, delydat, x0dat, y0dat
END TYPE GridParams
!---horizontal relative coordinates
TYPE :: HRelativeCoords
INTEGER :: icoord, jcoord
REAL :: xcoord, ycoord
END TYPE HRelativeCoords
Example 6.9: DERIVED TYPE definitions for interpolation to surface grids.
Assume that the external grid is rectangular with uniform grid spacings in
either direction. The grid can then be completely defined using the attributes
stored in a variable of type GridParams. In particular the attributes n1dat
and n2dat are the dimensions of the data grid in the X- and Y-direction.
The relative coordinates of each data point are stored in a 2-D array of type
HRelativeCoords using the following procedure
!---declare
TYPE (GridParams) :: surfacegrid
TYPE (HRelativeCoords), SAVE, ALLOCATABLE, DIMENSION(:,:) :: &
& gridcoords
!---define the external data grid
surfacegrid%n1dat = ...; surfacegrid%n2dat = ...
...
!---allocate
n1dat = surfacegrid%n1dat; n2dat = surfacegrid%n2dat
ALLOCATE (gridcoords(n1dat,n2dat),STAT=errstat)
!---evaluate and store the relative coordinates of the data grid

idat 110: DO idat=1,n1dat
jdat 110: DO jdat=1,n2dat
gridcoords(idat,jdat)%icoord = ...; gridcoords(idat,jdat)%jcoord = ...
gridcoords(idat,jdat)%xcoord = ...; gridcoords(idat,jdat)%ycoord = ...
ENDDO idat 110
ENDDO jdat 110
Example 6.10: storing the relative coordinates of an external data grid.
6.1.5 Modules
Modules are program units which can be used within a FORTRAN 90 pro-
gram in two ways. Firstly, variables which need to be accessible in different
program routines can be declared within a module. These types are further
denored as “declaration modules”. In COHERENS V1, all variables with a
global scope were stored in a COMMON block located in a .inc file and are
made accessible with a INCLUDE statement. In COHERENS V2.0 there are
no COMMON blocks any more, since the declarations are made within a mo-
dule and become accessible to a program unit by putting the appropriate
USE statement.
As an example, the example below shows the declarations given in the
module currents for all arrays related to currents
MODULE currents
IMPLICIT NONE
REAL, ALLOCATABLE, DIMENSION(:,:) :: p2dbcgradatu, udevint, udfvel, udvel, &

& udvel old, umpred, umvel
REAL, ALLOCATABLE, DIMENSION(:,:) :: p2dbcgradatv, vdevint, vdfvel, vdvel, &
& vdvel old, vmpred, vmvel
REAL, ALLOCATABLE, DIMENSION(:,:,:) :: p3dbcgradatu, ufvel, uvel, uvel old
REAL, ALLOCATABLE, DIMENSION(:,:,:) :: p3dbcgradatv, vfvel, vvel, vvel old
REAL, ALLOCATABLE, DIMENSION(:,:,:) :: wvel, wphys
SAVE
END MODULE currents

Example 6.11: contents of the currents module.
If one or more of these arrays are used in a program unit, a USE statement
must appear in the declaration part:
USE currents
Other types of application of the FORTRAN 90 module concept are the so-
called “module routines”. These routines have the same form and purpose as
the usual external SUBROUTINE and FUNCTION subprograms, except that:
• Module routines accept optional arguments, keyword arguments, array

valued function results and can be used to construct generic interfaces
without the need to program explicit interfaces.
• Contrary to external sub-programs, module routines require that a

proper USE statement must be given in the calling sub-program.
Module routines are mainly used in COHERENS to construct so-called “li-

braries”, i.e. an ensemble of routines with a general common purpose usually
implemented through generic interfaces. They are quasi-independent of the
main source code. For example, all specific MPI and netCDF routine calls
are located in the files MPI comms.F90 and cf90 routines.F90. In this way,
only one of these files has to be re-programmed when an newer version of the
MPI or netCDF is implemented in the future. A list of module routine files is
given in Table 10.2.
6.1.6 Generic procedures

Generic procedures group a series of procedures with similar functionality
together under a common name. This generalises the FORTRAN 77 concept
of INTRINSIC routines. The generic name is defined via an INTERFACE
statement block. This is illustrated by the following example of the read vars
generic routine
MODULE inout routines
....
INTERFACE read vars
MODULE PROCEDURE read vars int 0d, read vars int 1d, &
& read vars int 2d, read vars int 3d, &
& read vars int 4d, read vars real 0d, &
& read vars real 1d, read vars real 2d, &
& read vars real 3d, read vars real 4d
END INTERFACE
Example 6.12: definition of a generic routine through an INTERCACE block
statement.
The generic routine read vars is called when data have to be read from an
external data file in COHERENS standard format. The appropriate routine
is selected by the program from the list in the MODULE PROCEDURE state-
ment, depending on the type and rank of the argument which returns the
data to be read. In this way the input data argument can be of type INTEGER
or REAL and represent scalars or arrays of rank 1 to 4. The FORTRAN code
of the specific routines with the same generic name needs to be located in
the same file (inout routines.f90) where the INTERFACE statement is made.
Note, that although each specific routine must have the same number of
non-optional arguments, the number and type of optional arguments may
differ.
If a call to a generic or non-generic module routine is made, the USE
statement must be given in the declaration part of the calling routine.
USE module name, ONLY: routine name

Example 6.13: syntax of a USE statement for module routines.
where module name is the name of the module and routine name the name
of the (non)-generic routine. Consider the following example in the file
Grid Arrays.F90:
SUBROUTINE read grid

...
USE inout routines, ONLY: close filepars, open filepars, &
& read glbatts mod, read varatts mod, &
& read vars
...
CALL read vars(gsigcoord,filepars,varid,varatts)
...
END SUBROUTINE read grid
Example 6.14: example of a USE statement for module routines.
since gsigcoord is a REAL array of rank 3, the actually called routine is

read vars real 3d.
6.1.7 Internal documentation and structured layout of

the code
The COHERENS programming conventions include rules for internal docu-
mentation and code layout. These rules and some of the conventions dis-
cussed in the sections above are illustrated in Example 6.15 which shows
the complete code of routine Zdif at C which calculates the vertical diffusion
term in a scalar transport equation. A line number is added for illustrative
purposes in the first four columns at each line in the example. This means
that the actual code line (in this example only) starts in column 5. Note
that the numbers in the discussion below refer to specific lines.
Five parts can be distinguished: a header with the routine declaration and
comments, declaration part, initialisation, “main” code lines and finalisation.
header lines 1–19 with the following information:
• name of the routine and a short description

• name(s) of the author(s)
• a more detailed description (if needed) under the Description header
• reference to a publication or section of the user manual

• the name(s) of the sub-programs calling the routine
• the name(s) of the routines called in this routines (the routines
log timer in and log timer out are called in most routines and may
be omitted here)
declaration part This consists of the following segments
• lines 20–29: USE statements. The ONLY attribute is given for

module routines only.
• lines 30–32 with the IMPLICIT NONE statement
• lines 33–44: declaration of the arguments with the INTENT at-
tribute (preceded by the *Arguments* comment line)
• lines 45–74: comment lines with a description of the arguments
in a three column format (name, type, purpose), the unit of the
variable is given at the end of the line
• lines 75–88: declaration of all local variables. Except for a few ex-
ceptions in the program, local arrays are declared within a #ifdef
block, either as allocatable or automatic arrays depending on the
status of the -DALLOC compiler option.
• lines 89–96: internal documentation of the most meaningfull local
variables using the same three column format
• lines 97–98: two blank lines to make a clear separation between
the header and the program code itself
initialisation
• lines 99–101: write information to the log-file
• lines 102–121: allocate local arrays in case -DALLOC is defined.
Note that each ALLOCATE statement is checked for errors.
• lines 122–161: initialise parameters and arrays
main code
• lines 162–279: calculation of the vertical diffusion term in a scalar
transport equation (including boundary conditions)
finalisation
• lines 280–289: deallocation of local arrays if -DALLOC is defined.
• line 290: write information to the log-file
• lines 291–292: two blank lines

• line 293: the RETURN statement is not required by the FORTRAN
90 standard, but has been implemented in the COHERENS pro-
gramming convention
• line 294: blank line
• line 295: END statement followed by the name of the routine
(the latter is not required in FORTRAN 90 but included in the
convention for clarity)
sectioning
The actual code, i.e. excluding the declaration part, is divided into
numbered sections, subsections, subsubsections. DO loop blocks within
one of these sections has a label composed of the name of the iteration
counter followed by , followed by the section number. An extra num-
ber is attached is there are more than one DO loops within a section,
subsection, . . . . For example the k-loop which starts on line 218, is the
second one in subsection 3.3 and has the label k 332.
1 :SUBROUTINE Zdif at C(psic,tridcfc,vdifcoefatw,novars,ibcsur,ibcbot,nbcs,&

2 : & nbcb,bcsur,bcbot,kbounds)
3 :!************************************************************************
4 :!
5 :! *Zdif at C* Vertical diffusion term for a quantity at C-nodes
6 :!
7 :! Author - Patrick Luyten
8 :!
9 :! Description -
10 :!
11 :! Reference -
12 :!
13 :! Calling program - transport at C 3d, transport at C 4d1,
14 :! transport at C 4d2
15 :!
16 :! Module calls - error alloc
17 :!
18 :!************************************************************************
19 :!
20 :USE depths
21 :USE grid
22 :USE gridpars
23 :USE iopars
24 :USE physpars
25 :USE switches
26 :USE syspars
27 :USE timepars
28 :USE error routines, ONLY: error alloc
29 :USE time routines, ONLY: log timer in, log timer out
30 :
31 :IMPLICIT NONE
32 :
33 :!
34:!* Arguments
35 :!
36 :INTEGER, INTENT(IN) :: ibcbot, ibcsur, nbcb, nbcs, novars
37 :INTEGER, INTENT(IN), DIMENSION(2) :: kbounds
38 :REAL, INTENT(IN), DIMENSION(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,&
39 : & nz,novars) :: psic
40 :REAL, INTENT(INOUT), DIMENSION(ncloc,nrloc,nz,4,novars) :: tridcfc
41 :REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nz+1) :: vdifcoefatw
42 :REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nbcs,novars) :: bcsur

43 :REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nbcb,novars) :: bcbot
44 :
45 :!
46 :! Name Type Purpose
47 :!------------------------------------------------------------------------
48 :!*psic* REAL C-node quantity to be diffused [psic]
49 :!*tridcfc* REAL Tridiagonal matrix for implicit vertical solution
50 :!*vdifcoefatw*REAL Diffusion coefficient at W-nodes [m^2/s]
51 :!*novars* INTEGER Number of variables
52 :!*ibcsur* INTEGER Type of surface boundary condition
53 :! = 0 => Neumann (zero flux)
54 :! = 1 => Neumann (prescibed flux)
55 :! = 2 => Neumann (using transfer velocity)
56 :! = 3 => Dirichlet at first C-node below the surface
57 :! = 4 => Dirichlet at the surface
58 :!*ibcbot* INTEGER Type of bottom boundary condition
59 :! = 0 => Neumann (zero flux)
60 :! = 1 => Neumann (prescibed flux)
61 :! = 2 => Neumann (using transfer velocity)
62 :! = 3 => Dirichlet at first C-node above the bottom
63 :! = 4 => Dirichlet at the bottom
64 :!*nbcs* INTEGER Last dimension of array bcsur
65 :!*nbcb* INTEGER Last dimension of array bcbot
66 :!*bcsur* REAL Data for surface boundary condition
67 :! (:,:,1,:) => prescribed surface flux or surface value
68 :! (:,:,2,:) => transfer velocity [m/s]
69 :!*bcbot* REAL Data for bottom boundary condition
70 :! (:,:,1,:) => prescribed surface flux or surface value
71 :! (:,:,2,:) => transfer velocity [m/s]
72 :!*kbounds* INTEGER Vertical bounds
73 :!
74 :!------------------------------------------------------------------------
75 :!
76 :!*Local variables
77 :!
78 :INTEGER :: ivar, k, kmax, kmin, npcc
79 :REAL :: theta vdif1, xexp, ximp
80 :#ifdef ALLOC
81 : REAL, SAVE, ALLOCATABLE, DIMENSION(:,:) :: array2dc1, array2dc2, &
82 : & array2dc3
83 : REAL, SAVE, ALLOCATABLE, DIMENSION(:,:,:) :: array3d, difflux

84 :#else
85 : REAL, DIMENSION(ncloc,nrloc) :: array2dc1, array2dc2, array2dc3
86 : REAL, DIMENSION(ncloc,nrloc,2:nz) :: array3d
87 : REAL, DIMENSION(ncloc,nrloc,nz+1) :: difflux
88 :#endif /*ALLOC*/
89 :
90 :!
91 :! Name Type Purpose
92 :!------------------------------------------------------------------------
93 :!*difflux* REAL Diffusive flux (times factor) at W-nodes [m^2/psic]
94 :!
95 :!------------------------------------------------------------------------
96 :!
97 :
98 :
99 :procname(pglev+1) = ’Zdif at C’
100:CALL log timer in(npcc)
101:
102:!
103:!1. Allocate arrays
104:!------------------
105:!
106:
107:#ifdef ALLOC
108: ALLOCATE (array2dc1(ncloc,nrloc),STAT=errstat)
109: CALL error alloc(’array2dc1’,2,(/ncloc,nrloc/),real type)
114: ALLOCATE (array3d(ncloc,nrloc,2:nz),STAT=errstat)
115: CALL error alloc(’array3d’,3,(/ncloc,nrloc,nz-1/),real type)
116: IF (iopt vdif impl.NE.2) THEN
117: ALLOCATE (difflux(ncloc,nrloc,nz+1),STAT=errstat)
118: CALL error alloc(’difflux’,3,(/ncloc,nrloc,nz+1/),real_type)
119: ENDIF
120:#endif /*ALLOC*/
121:
122:!
123:!2. Initialise
124:!-------------
125:!
126:!---fluxes
127:IF (iopt vdif impl.NE.2) THEN
128: WHERE (maskatc int)
129: difflux(:,:,1) = 0.0
130: difflux(:,:,nz+1) = 0.0
131: END WHERE
132:ENDIF
133:
134:!---work space arrays
135:WHERE (maskatc int)
136: array2dc1 = deptotatc(1:ncloc,1:nrloc)**2
137:END WHERE
138:k 201: DO k=2,nz
140: array3d(:,:,k) = vdifcoefatw(:,:,k)&
141: & /(array2dc1*delsatw(1:ncloc,1:nrloc,k))
142: END WHERE
143:ENDDO k 201
144:
145:IF (ibcsur.LE.2) THEN
147: array2dc2 = deptotatc(1:ncloc,1:nrloc)*delsatc(1:ncloc,1:nrloc,nz)
148: END WHERE
149:ENDIF
150:
151:IF (ibcbot.LE.2) THEN
153: array2dc3 = deptotatc(1:ncloc,1:nrloc)*delsatc(1:ncloc,1:nrloc,1)
154: END WHERE
155:ENDIF
156:
157:!---time factors
158:xexp = delt3d*(1.0-theta vdif)
159:ximp = delt3d*theta vdif
160:theta vdif1 = 1.0-theta vdif
161:
162:!
163:!3. Diffusion terms
164:!------------------
165:!
166:
167:ivar 300: DO ivar=1,novars
168:
169:!
170:!3.1 Explicit fluxes
171:!-------------------
172:!
173:
175: k 310: DO k=2,nz
177: difflux(:,:,k) = xexp*array3d(:,:,k)*&
178: & (psic(1:ncloc,1:nrloc,k,ivar)-&
179: & psic(1:ncloc,1:nrloc,k-1,ivar))
180: END WHERE
181: ENDDO k 310
182: ENDIF
183:
184:!
185:!3.2 Explicit terms
186:!-----------------
187:!
188:
190: k 320: DO k=kbounds(1),kbounds(2)
192: tridcfc(:,:,k,4,ivar) = tridcfc(:,:,k,4,ivar) + &
193: & (difflux(:,:,k+1)-difflux(:,:,k))&
194: & /delsatc(1:ncloc,1:nrloc,k)
195: END WHERE
196: ENDDO k 320
197: ENDIF
198:
199:!
200:!3.3 Implicit terms
201:!------------------
202:!
203:
205:
206:! ---lower flux

207: kmax = MERGE(nz,nz-1,ibcsur.LE.2)
208: k 331: DO k=2,kmax
210: array2dc1 = ximp*array3d(:,:,k)/delsatc(1:ncloc,1:nrloc,k)
211: tridcfc(:,:,k,1,ivar) = tridcfc(:,:,k,1,ivar) - array2dc1
212: tridcfc(:,:,k,2,ivar) = tridcfc(:,:,k,2,ivar) + array2dc1
213: END WHERE
214: ENDDO k 331
215:
216:! ---upper flux
217: kmin = MERGE(1,2,ibcbot.LE.2)
218: k 332: DO k=kmin,nz-1
220: array2dc1 = ximp*array3d(:,:,k+1)&
221: & /delsatc(1:ncloc,1:nrloc,k)
222: tridcfc(:,:,k,2,ivar) = tridcfc(:,:,k,2,ivar) + array2dc1
223: tridcfc(:,:,k,3,ivar) = tridcfc(:,:,k,3,ivar) - array2dc1
224: END WHERE
225: ENDDO k 332
226:
227: ENDIF
228:
229:!
230:!3.4 Boundary conditions
231:!----------------------
232:!
233:!3.4.1 Surface
234:!-------------
235:!
236:! ---Neumann (prescribed flux)
237: IF (ibcsur.EQ.1) THEN
239: tridcfc(:,:,nz,4,ivar) = tridcfc(:,:,nz,4,ivar) + &
240: & delt3d*bcsur(:,:,1,ivar)/array2dc2
241: END WHERE
242:
243:! ---Neumann (using transfer velocity)
244: ELSEIF (ibcsur.EQ.2) THEN
246: tridcfc(:,:,nz,2,ivar) = tridcfc(:,:,nz,2,ivar) + &
247: & ximp*bcsur(:,:,2,ivar)/array2dc2

248: tridcfc(:,:,nz,4,ivar) = tridcfc(:,:,nz,4,ivar) - &
249: & delt3d*bcsur(:,:,2,ivar)*&
250: & (theta vdif1*psic(1:ncloc,1:nrloc,nz,ivar)-&
251: & bcsur(:,:,1,ivar))/array2dc2
252: END WHERE
253: ENDIF
254:
255:!
256:!3.4.2 Bottom
257:!------------
258:!
259:! ---Neumann (prescribed flux)
260: IF (ibcbot.EQ.1) THEN
262: tridcfc(:,:,1,4,ivar) = tridcfc(:,:,1,4,ivar) - &
263: & delt3d*bcbot(:,:,1,ivar)/array2dc3
264: END WHERE
265:
266:! ---Neumann (using transfer velocity)
267: ELSEIF (ibcbot.EQ.2) THEN
269: tridcfc(:,:,1,2,ivar) = tridcfc(:,:,1,2,ivar) + &
270: & ximp*bcbot(:,:,2,ivar)/array2dc3
271: tridcfc(:,:,1,4,ivar) = tridcfc(:,:,1,4,ivar) - &
272: & delt3d*bcbot(:,:,2,ivar)*&
273: & (theta vdif1*psic(1:ncloc,1:nrloc,1,ivar)-&
274: & bcbot(:,:,1,ivar))/array2dc3
275: END WHERE
276: ENDIF
277:
278:ENDDO ivar 300
279:
280:!
281:!4. Deallocate arrays
282:!--------------------
283:!
284:
285:#ifdef ALLOC
286: DEALLOCATE (array2dc1,array2dc2,array2dc3,array3d)
287: IF (iopt vdif impl.NE.2) DEALLOCATE (difflux)
288:#endif /*ALLOC*/
289:
290:CALL log timer out(npcc,itm vdif)
291:
292:
293:RETURN
294:
295:END SUBROUTINE Zdif at C
Example 6.15: example layout and internal documentation of a COHERENS
routine.
Declaration modules have a similar layout and internal documentation,

except that the code only consists of the MODULE module name declaration
on the first, type declarations and the END MODULE module name statement
on the last line. This is illustrated in Example 6.16.
MODULE density
!************************************************************************
!
! *density* Density arrays
!
! Author - Patrick Luyten
!
! Version - @(COHERENS)density.f90 V2.0
!
! Description -
!
!************************************************************************
!
IMPLICIT NONE
REAL, ALLOCATABLE, DIMENSION(:,:,:) :: beta sal, beta temp, dens, sal, temp
SAVE
!
! Name Type Purpose
!--------------------------------------------------------------------------
!*beta sal* REAL Salinity expansion coefficient [1/PSU]
!*beta temp*REAL Temperature expansion coefficient [1/deg C]
6.2. SPECIFIC PROGRAM FEATURES 267
!*dens* REAL Mass density [kg/m^3]

!*sal* REAL Salinity [PSU]
!*temp* REAL Temperature [deg C]
!
!************************************************************************
END MODULE density

Example 6.16: example layout and internal documentation of a COHERENS
declaration module.
6.2 Specific program features

6.2.1 Key ids
Key ids are named constants which refer to a specific item, such as a variable,
file class, tidal constituent or error code. The name of a key id is composed
by the name of the general “class” to which the item belongs, followed by a
’ ’ and its specific name. Some examples are given below.
1. Variable key ids have the common class name iarr. Their specific names
are the same as the FORTRAN name. For example, iarr sal is the key id
of the program variable ’sal’ which is salinity. Variable ids are used to
define the variables used to set up user-defined output (see Chapter 16
for details).
2. Key ids referring to tidal constituents belong to the class icon . The spe-
cific name is given by the constituent’s traditional name, e.g. icon M2
for the M2 tide. Tidal key ids are a practical tool for defining the tidal
constituents applied in the open boundary conditions or for selecting
the constituents for the astronomical tidal force.
3. The class name for model forcing files is ’io ’. The specific name refers
to the type of forcing. For example, io metsur is the key id for the
“ensemble” of properties related to the meteorological surface data file.
A list of available key classes is displayed in Table 6.2.
6.2.2 Date and time formats

Time can be represented in the program in four different formats. The first
two are absolute calendar date and times. The next two are relative times
with respect to a reference date.
Table 6.2: List of available key classes

Class Purpose Defined in Examples
io attributes of a forcing file iopars.f90 io modgrd (model grid file)
ics initial conditions iopars.f90 ics phys (physical initial conditions)
igrd surface grids iopars.f90 igrd meteo (meteo data grid)
ierrno error codes iopars.f90 ierrno alloc (allocation error)
iarr model variables modids.f90 iarr temp (temperature)
icon tidal constituents tide.f90 icon O1 (O1 constituent)
itm timers for timing report iopars.f90 itm hydro (hydrodynamics)
1. A string format in the form of a string of lentime (23) characters:

‘yyyy/mm/dd;hh:mm:ss:mmm’ where yyyy = year, mm = month, dd
= day in month, hh = hour in day, mm = minutes, ss = seconds, mmm
= milliseconds.
• Examples
CHARACTER (LEN=lentime) :: CDateTime, CEndDateTime, &
& CStartDatetime
where the first variable represents the current date (updated at
each 2-D time step), the next two respectively the end and start
date of the simulation, defined by the user, e.g.
CStartDatetime = ’2009/06/15;05:09:00:000’
CEndDatetime = ’2009/07/01;15:45:06:000’
• These time formats are part of the model setup and are used to
calculate the solar altitude for evaluation of surface solar irradi-
ance and as date/time stamp in all time series input/output.
• Precision is 1 millisecond.
• The separators need to be at the correct positions, their values
are unimportant.
2. A vector INTEGER format in the form of a vector with 7 elements:

year, month, day, hour, minutes, seconds, milliseconds
• Examples
INTEGER, DIMENSION(7) :: IDateTime, IEndDateTime, &
& IStartDatetime
which have the same meaning as above.
• The format is only used to perform internal date/time calcula-

tions.
• Precision is 1 millisecond.
3. A scalar INTEGER format
INTEGER (KIND=kndilong) :: nosecsrun
representing the number of seconds since the start of the simulation.
• Used internally to compare the date/time in a data file with the
current one in the simulation.
• Lower precision is 1 second, upper precision ∼68 years if longint
= 4 or (practically) unlimited otherwise (longint = 8).
4. A scalar INTEGER (“index”) format
INTEGER :: nt
which equals the current time “index” defined as the number of (2-D)
time steps since the start of the simulation.
• Used both internally as externally by the user to set output times.
• Precision is the number of seconds within one time step. This
variable is defined in single precision.
The following additional time parameters are used
REAL :: delt2d User defined 2-D time step in seconds. Although de-
fined as a REAL variable, to prevent rounding errors in
the calculation of the calendar date and time its preci-
sion has been restricted to 1 millisecond for time steps
smaller than 1000 seconds and to 1 second otherwise.
REAL :: time zone User defined time zone, i.e. difference of local time
with respect to GMT in hours. Difference is posi-
tive (negative) eastwards (westwards) from Green-
wich. Default is 0. The program assumes that the
start, end and current date and time within the pro-
gram are given in local time. Important to note is
that the date and time, obtained from external data
files, must be given with respect to the same time
zone as the one used in the program.
INTEGER :: ic3d User defined number of 2-D time steps within one 3-D
time step.
6.2.3 Data flags

Data flags are commonly used in observational data sets for representing
invalid data. They have been introduced in the COHERENS code to represent
undefined values. The following variables are defined in the program for the
flagging of model variables
REAL :: real fill Large negative number used for flagging of REAL model
variables.
REAL:: real min Large negative number used to determine whether a real
variable is flagged. More specifically, the variable X is
taken as flagged if X≤real min. Obviously, real fill<real min.
INTEGER :: int fill Large negative number used for flagging of INTEGER model
variables.
LOGICAL :: log fill Large negative number used for flagging of LOGICAL model
variables.
Data flags are used (e.g.) for the following purposes:
• If a data value in a vertical open boundary profile has been flagged,
a zero gradient condition is applied at that particular point, and the
data value is no longer considered as an external value.
• Flagged values in a SST forcing file are automatically replaced by the
modelled temperature at the highest (near surface) level.
• Flags are used to disable interpolation at external locations.
• Flagging of some user-defined model parameters has been implemented
as a practical utility in the program. It informs the program that the
parameter has some specific value unknown by the user, but known to
the program.
Although most model grid arrays are not defined on land areas, no flags are,
for practical reasons, applied in this case. This behaviour may be changed in
future versions where land values can be flagged with the netCDF FillValue
attribute.
6.2.4 Variable units

Variable units are based on the ‘kg-meter-sec-PSU’ system. Table 6.3 repre-
sents the units of the principle variables used in the program. Note that the
unit for shear stress has, for convenience, been normalised with the (refer-
ence) density.
Table 6.3: Units of principal variables
variable type unit

length m
time s
mass kg
currents m/s
transports m2 /s
temperature deg C
salinity PSU (=10−3 kg/kg)
angle radians
density kg/m3
horizontal coordinates m or fractional degrees
vertical coordinates m or dimensionless
pressure Pa
diffusion coefficients m2 /s
frequencies radians/s
acceleration m/s2
stress m2 /s2 (Pa divided by density)
heat flux W/m2
salinity flux PSU m/s
turbulent energy m2 /s2 (or J/kg)
turbulent dissipation m2 /s3 (or W/kg)
Chapter 7
Model input and output
7.1 Classification of model files

The files, which can be created by the model fall to four different categories.
Exception is the file defruns (see Section 12.1).
1. Monitoring files
• log file
- Writes “tracing” information during the simulation.
- Informs about progress of the run upto a user-defined level.
A zero level means that the log file is not created. Note that
this is the default setting.
- For parallel runs a log file can be created by each process.
- The utility is useful for debugging the model code or for trac-
ing errors in model setup.
• error file
- Writes error messages.
- If an error is detected by an error checking routine, an error
message is written. In most cases the program aborts immedi-
ately afterwards while in other cases several checks are made
before the program aborts.
- For parallel runs an error file is created by each process.
• warning file
- Writes “warning” messages about suspicious values of setup
parameters or variables.
- The program will not abort.
273
274 CHAPTER 7. MODEL INPUT AND OUTPUT
• timer report
This is a file with information about the total execution time and
the percentages of time spent by different model “compartments”
(e.g. advection, 2-D mode, I/O, parallel communications, ...).
2. Central input file (CIF)
• This is a file with a complete list of parameter values used for the
setup of the application. This includes all the parameters which
can be defined by the user in the routines
usrdef init params, usrdef mod params, usrdef tsr params,
usrdef avr params, usrdef anal freqs, usrdef anal params
For further details see Chapters 12 and 16.
• The file is created on request by the user and can be used as input
to the program in a subsequent run.
• If the CIF is used for input, the above routines are no longer called
by the program.
3. Forcing files
• Those files include data arrays used for model setup, e.g. model
grid data, type of open boundary conditions, initial conditions,
forcing data (open boundaries and meteorological). The files with
open boundary data for nested sub-grids also fall within this cat-
egory.
• All files are used as input to the model, except the open boundary
data files for nested sub-grids which are defined as output files.
• All input files may be given in any user-defined format, but can
optionally be converted to a COHERENS standard format. The
output files are always in COHERENS standard format. The for-
cing file can be made “virtual”, if the forcing data are directly
defined by the user without using an external data file.
4. User output files
• These are output data files created by the program on request by

the user.
• Spatial and temporal resolution and type of output data are se-
lected by the user.
• The files are always in COHERENS standard format.
7.2. DEFAULT FILE NAMES 275
• Output specifications are defined in the user-defined routines usrdef tsr params
for time series, usrdef avr params for time averaged and usrdef anal params,
usrdef anal freqs for harmonic data output.
7.2 Default file names

Each file has a default name which can be reset by the user. A default file
name (in FORTRAN string format) is defined as:
title//’.’//filedesc//filenum//form//pid
for monitoring files, central input file(s) and forcing files, and
title//’_’//filenum//’.’//freqnum//filedesc//dim//form
for output files, where title is a simulation-specific title, filedesc the file de-
scriptor (representative for the type of the data in the file), filenum the file
number in case there is more than one file with the same descriptor, form
the format of the file, pid the process id number, dim the dimension of out-
put data and freqnum the frequency number. Values of these sub-strings are
discussed below.
7.2.1 title
Possible values are
runtitle Simulation title defined in defruns. This is the value used for moni-
toring files and CIF(s)(Categories 1 and 2).
intitle User-defined parameter used as prefix name for forcing files (Cate-
gory 3). Default value is runtitle.
outtitle User-defined parameter used as prefix name for user output files (Cat-
egory 4). Default value is runtitle.
7.2.2 pid
Process id number, used only for log and error files in parallel mode, empty
otherwise.
7.2.3 form
The file format can take the following values:
‘A’ ASCII format. This format is portable and readable but unsuitable for
large data sets because of its great comsumption of disk space and its
use of sequential storage.
‘U’ Unformatted binary format. Advantage is a more efficient use of disk
space. Disadvantages are that the file is (mainly) non-portable, not di-
rectly readable and uses sequential storage.
‘N’ NetCDF format (recommended). This format is portable, directly read-
able (with the netCDF ncdump utility). Data can be accessed directly by
specifying the appropriate record number. Only (possible) disadvantage
is that the netCDF library needs to be compiled first.
‘I’ This does not represent a specific data format but indicates that the
file is an ASCII information file containing the metadata of a forcing or
output data file.
Monitoring and central input files are always in ‘A’-format. Forcing and
output files may be in any of the first three formats.
7.2.4 filedesc
The string filedesc, further denoted as the “file descriptor”, is a character
string taking one of the values below.
1. Monitoring files
inilog log file with tracing information during the initialisation phase
of the simulation
runlog log file with tracing information during the main (time loop)
phase of the simulation
errlog error file
warlog warning file
timing timer report file
2. CIF file. Only one file is currently available.
cifmod parameters for model setup
3. Forcing files. The string filedesc refers to the contents of the file.
7.2. DEFAULT FILE NAMES 277
mppmod arrays defining the domain decomposition (parallel mode only)

phsics (physical) initial conditions
modgrd model grid, bathymetry and location of open boundaries
metgrd surface meteorological grid
sstgrd sea surface temperature (SST) grid
nstgrd locations of open boundary locations of nested sub-grids. A
file number needs to be supplied for each sub-grid.
1uvsur 1-D surface forcing
2uvobc 2-D mode open boundary forcing
3uvobc 3-D mode (baroclinic currents) open boundary forcing
salobc salinity open boundary forcing
tmpobc temperature open boundary forcing
rlxobc definitions of relaxation zones
nstspc specifiers for sub-grid nesting
2uvnst 2-D open boundary data for the nested sub-grids. A file num-
ber is supplied for each sub-grid.
3uvnst baroclinic current open boundary data for the nested sub-
grids. A file number is supplied for each sub-grid.
salnst salinity open boundary data for the nested sub-grids. A file
number needs is supplied for each sub-grid.
tmpnst temperature open boundary data for the nested sub-grids. A
file number is supplied for each sub-grid.
metsur meteorological surface data
sstsur SST surface data
usrdef user utility file (not used by the program itself)
4. Output files.
tsout time series output

avrgd time averaged output
resid output of residuals
amplt output of harmonic amplitudes
phase output of harmonic phases
ellip output of tidal ellipse parameters
7.2.5 filenum
1. If the file descriptor equals 1uvsur, 2uvobc, 3uvobc, salobc or tmpobc,
the contents of the file depends on the value of filenum:
• filenum=1: forcing specifiers (e.g. type of open boundary condi-

tions)
• filenum>1: forcing data itself. This allows to spread the data
over several files. For example, one file may contain open sea and
another river open boundary data. Each file can have its own
temporal resolution.
2. In case the file descriptor equals 2uvnst, 3uvnst, salnst or tmpnst, the file
contains nested data and filenum equals the number of the associated
sub-grid (between 1 and nonestsets).
3. In all other cases (including surface forcing data) the file number is not
used.
The maximum allowed file number is given by the system parameter Max-
IOFiles, defined in syspars.f90.
7.2.6 freqnum
Frequency number only used for output of amplitudes, phases and elliptic
parameters. Empty otherwise.
7.2.7 dim
The file dimension is only used for files of Category 4:
0 : 0-D output data grid

G : file containing the output grid coordinates but not the data themselves
7.3 Formats of monitoring files

7.3.1 Log files
Log files contain the following information:
7.3. FORMATS OF MONITORING FILES 279
• Some general information (e.g. current date, number of time steps,

value of 2-D CFL limit, ...).
• Each time a file is opened within the program, a message is written

with the name, unit number and format of the file. A similar message
is printed when a file is closed.
• A line starting with a number followed by ‘:’ and the name of a routine
means that the program entered this routine. The number denotes the
program routine level. Main program is at level 1, a routine called by
the main program has level 2, a routine called by another routine at
level n is at level n+1, . . . .
• The maximum number of levels traced by the log file, is defined by the
user. Note that large log files may be written if this maximum equals
or exceeds a value larger than 5. A value of 3 is recommended for
normal runs, a value of 7 if the log file is used for debugging. When the
program returns to the previous level (at the end of the called routine),
a line is written with the same level number followed by ‘:R’.
• Two separate log files can be written by the program: the inilog file
which traces information during the initialisation phase and is closed
when the program enters the time loop and the runlog file which is
active during the time loop only. The two program phases are discussed
in Section 10.2.
• If the maximum level for tracing is set to zero (default), no log file is
written.
• The following parameters can be defined by the user:
– The tracing level of the inilog and runlog files. In parallel mode,
different values can be selected for different sub-domains. Note
that, by default, all levels are set to zero so that no log file is
created.
– The names of the log files. In parallel mode, all inilog or runlog
files have the same standard name (which can be redefined by the
user) appended by a suffix with the process id number.
– A number of time steps can be defined after which the runlog
file is overwritten. Default is the total number of time steps (i.e.
information is written at all time steps and the file is never over-
written).
– The writing of an exit statement of the form ‘num:R’, where ‘num’

is the program level in the “log”-file on exit of a routine call if
.TRUE. (which is also the default).
For details see Section 12.2.2.
An example is given below.
Open file fredyA.runlogA on unit 1 type OUT (A)

2:update time
3:add secs to date int
3:R
3:convert date to char
3:R
3:day number int
3:R
2003/01/01;00:00:30,000
2:R
2:equation of state
2:R
2:baroclinic gradient
3:Zcoord arr
3:R
3:Carr at W: sal
3:R
...
2:R
2:hydrodynamic equations
3:current pred
3:R
3:current 2d
umax = 0.1765635E-02 (28,30)
vmax = 0.1765635E-02 (30,28)
3:R
...
Close file on unit 8 (A)
2:R
2:simulation end
3:rng finalize
3:R
3:timer report
Open file fredyA.timingA on unit 4 type OUT (A)
3:R
3:deallocate mod arrays
3:R
2:End of simulation: fredyA
Close file fredyA.warlogA on unit 3 (A)
Close file fredyA.errlogA on unit 2 (A)
Close file fredyA.runlogA on unit 1 (A)
Example 7.1: Part of the runlog file written by running test case fredyA.
Tracer level is 3.
The tracing information in the log files is implemented within the code by
defining the name of the routine and calling the routine log timer in on entry
and log timer out just before exiting the routine, e.g.
procname(pglev+1) = ’open boundary arrays’

CALL log timer in()
...
CALL log timer out()
The first line is the name of the routine which has been entered and will be
written to the log file. Routine log timer in sets the current program level by
increasing the counter pglev by 1 and writes the entry message. The call to
log timer out decreases pglev by 1. Note that if the first call is programmed
in the code, the second one must be inserted as well just before the RETURN
statement.
7.3.2 Error files

Error checking routines have been implemented in the model code. Errors
are always considered as fatal which means that the program aborts. The
program exit is usually executed after a series of checks. In this way several
error messages can be written to the errlog file. The file is created in the
beginning of the program. If no errors are found, the file is deleted at the end
of the simulation. Error checking is controlled by the following parameters
which can be set by the user:
• Level of error checking
0: Error checking is disabled and no file is created. This is the default.

1: Error checking is performed during initialisation only.
2: Error checking is enabled throughout the whole program (initiali-

sation, time loop and finalisation). This level is very useful for the
detection of read errors (e.g. end of file conditions) during an input
operation, but should be selected only to check the program for the
first time, since it may affect the CPU performance.
In parallel mode, different levels can be taken for different sub-domains.
• The name of the error file. In parallel mode, all errlog files have the
same standard name (which can be redefined by the user) appended by
a suffix with the process id number.
• The maximum number of error messages. Default is the system para-
meter MaxErrMesgs. The reason for limiting the number of messages,
is to avoid that an unnecessary amount of error messages is written,
since the program performs checks on model arrays as well.
The format of an errlog file is illustrated with the example below. Line
numbers are added for illustration purposes only.
1:Unable to open non-existing file: rhonegrid.dat

2:A total of 1 errors occurred in open filepars
3:Error type 1 : Not possible to open file
4:PROGRAM TERMINATED ABNORMALLY
Example 7.2: Contents of an errlog file.
The first line gives a description of the error. When more than one error is
found, a message line is written for each error. The second line gives the name
of the routine where the error is found. The third line writes a message code
describing the general type of the error(s). Each message code is presented
in the program by a key id of the form ierrno *. A list of available key ids
is given in Table 7.1. The last line in example 7.2 is standard for all errlog
files.
The error code is programmed as follows:
• The number of detected errors is given by the parameter nerrs. Its
initial value is zero.
• A series of routines are implemented for checking setup variables. For
example, the model parameters, defined in
usrdef mod params, are checked in check mod params. These routines
are located in check model.f90 and fully described in Section 23.3. Er-
ror checking is also performed when a file is opened or closed, metadata
Table 7.1: Key ids for error coding and associated error messages.
key id message
ierrno fopen Not possible to open file
ierrno fclose Unable to close file
ierrno read Read error
ierrno write Write error
ierrno fend End of file condition
ierrno input Wrong input values
ierrno inival Invalid initial values for model parameters or arrays
ierrno runval Invalid values for variables at run time
ierrno alloc Not possible to allocate arrays
ierrno arg Missing or invalid argument in a routine call
ierrno comms Communication error
ierrno MPI Error in a MPI call
ierrno CDF Error in a netCDF call
are read from a forcing file, or if a READ or an end-of-file condition oc-

curs.
• Within these “checking” routines, calls are made to one or more rou-
tines, defined in error routines.F90. For example, error limits var to
verify whether a switch has allowed values between certain limits. If
the routine detects an error, the error message is written and nerrs is
increased. These routines in error routines.f90 are fully described in
Section 23.8.
• The routine error abort is called with a typical error code, in the form of
a key id. If nerrs>0, lines 2–4 of the previous example are written with
an error message which corresponds to the given key id (see Table 7.1),
and the program aborts immediately afterwards. In parallel mode, the
error message will only be written by the processes where error(s) were
detected.
For example
CALL error lbound var(nc,’nc’,0,.FALSE.)

...
CALL error limits var(iopt grid htype,’iopt grid htype’,1,3)
...
CALL error lbound var date(CEndDateTime,’CEndDateTime’,CStartDateTime,&
& .FALSE.)
...
CALL error limits var(dlat ref,’dlat ref’,-90.0,90.0)
...
CALL error abort(’check mod params’,ierrno inival)
Example 7.3: Excerpts of routine check mod params illustrating the use of
error coding.
The first four calls are error checking routines. The first tests whether nc is
positive, the second whether the switch iopt grid htype has a value between
1 and 3, the third whether the end date is later than the start date, the
fourth whether the reference latitude is between -900 and 900 . If a test turns
.FALSE., an error message is written. The routine error abort is called with
the key id ierrno inival, representative for invalid setup parameters.
7.3.3 Warning file

Besides error messages which are always fatal, the program may also write
warning messages which do not cause termination of the program. The utility
can be useful for debugging. The aim is to provide information for the user
about suspicous selection of model parameters (usually switches) or arrays
or to inform the user that certain setup parameters (defined by the user or
default) have been reset. For example, if a 2-D simulation is selected with
iopt grid nodim=2 and the vertical resolution parameter nz is set to a value
larger than 1, a warning message is issued that this parameter is reset to 1.
The following control parameters can be (re)set by the user:
• The warning utility is switched on by default, but can be disabled by

the user.
• The name of the warning file. In parallel mode, only one file is permit-
ted, written by the master process.
WARNING: value of integer parameter iopt mode 2D is set from 1 to 0

WARNING: value of integer parameter iopt dens grad is set from 1 to 0
WARNING: value of integer parameter iopt bstres drag is set from 3 to 0
WARNING: value of integer parameter nprocsx is set from 0 to 1
WARNING: value of integer parameter nprocsy is set from 0 to 1
Example 7.4: Contents of the warlog file produced by running test case
pycnoA.
Table 7.2: Timer key ids and their meaning.

key id description
itm hydro hydrodynamics
itm 1dmode water column mode calculations
itm 2dmode 2-D mode calculations
itm dens total of density (including temperature and salinity) calculations
itm temp temperature
itm sal salinity
itm init initialisation procedures
itm trans transport routines
itm adv advection routines
itm hdif horizontal diffusion
itm vdif vertical diffusion (including turbulence modules)
itm phgrad baroclinic pressure gradient
itm input input operations
itm output output operations
itm inout total of input and output operations
itm com coll collect communication calls
itm com comb combine communication calls
itm com copy copy communication calls
itm com dist distribute communication calls
itm com exch exchange communication calls
itm com util utility communication calls
itm coms total of parallel communications
itm MPI total of MPI calls
itm CDF netCDF calls
itm arrint interpolation of model grid arrays
itm user usrdef routine calls
itm nest nesting procedures
itm libs internal library routine calls
itm astro astronomical tide
itm bconds boundary conditions
itm meteo meteorological routines
itm wait wait calls
7.3.4 Timer report file

A timer report is a file which contains information about the total execution
time and the percentages of time spent by different model “compartments”.
Each compartment has an associated time key id, listed in Table 7.2. The
following control parameters can be defined by the user:
• The type of information contained in the report.
0: No timer report is written. This is the default.

1: Only the total execution time is written.
2: Time information (in percentage of total time) is written for all
“timers”. In case of a parallel simulation, the percentages are given
for the process with the largest amount of time, the lowest amount
of time, as an average over all processes and for the master process.
3: The same as the previous case, but the time percentages are now
given for each individual process in addition. In the serial case,
behaviour is as for case 2.
• The name of the timer report file. In parallel mode, only one file is
permitted, written by the master process.
• The unit of time for writing the total execution can be written in sec-
onds, minutes, hours or days. Default is seconds.
The utility is useful for testing the CPU efficiency of a parallel decomposition.
An example of such test is given in Figure 9.1. Two examples are given below
using the same test case plumeC. The first shows the contents of the timer
report obtained from a serial run:
plume1C: 392s.822
Hydrodynamics : 39.152
2D mode : 12.125
3D mode : 27.939
Density : 26.150
Salinity : 22.338
Initialisation : 0.025
Transport : 50.284
Advection : 25.721
Horizontal diffusion: 13.541
Vertical diffusion : 18.450
Baroclinic pressure : 3.118
Input : 0.001
Output : 1.762
Input/output : 1.763
Array interpolation : 12.917
User calls : 14.979
Library calls : 4.284
Boundary conditions : 0.660
Example 7.5: Timer report for test case plumeC on a serial machine.
The second example is for the same test case now obtained on a parallel
machine with four processors and full timer information. For each timer
process there are now two lines. The first one gives statistical information
(maximum, minimum, mean and master). The second gives the times for
each individual processor. The report now contains additional information
about parallel communication calls, given by the compartments ‘Combine
comms’, ..., ‘MPI calls’. Note that the numbers given in ‘Parallel comms’ are
the sum of the corresponding ones for the combine, copy, exchange and utility
operations. This information is not given in the serial case since the times
related to parallel communications are, obviously zero, and zero times are
not printed in the table.
plume1C: 169s.783
Hydrodynamics : 44.064 44.009 44.037 44.044
44.044 44.064 44.009 44.039
2D mode : 18.971 18.889 18.939 19.172
19.172 18.958 18.889 18.971
3D mode : 25.648 25.584 25.620 25.568
25.568 25.648 25.584 25.627
Density : 27.339 27.210 27.285 27.176
27.176 27.339 27.210 27.306
Salinity : 23.711 23.659 23.677 23.677
23.677 23.711 23.659 23.660
Initialisation : 0.094 0.088 0.092 0.088
0.088 0.088 0.094 0.094
Transport : 45.924 45.189 45.574 45.046
45.046 45.189 45.610 45.924
Advection : 28.831 28.505 28.639 28.648
28.648 28.505 28.582 28.831
Horizontal diffusion: 12.218 11.796 12.077 12.074
12.074 11.796 12.218 12.216
Vertical diffusion : 10.446 10.359 10.412 10.189

10.189 10.359 10.446 10.431
Baroclinic pressure : 2.963 2.891 2.917 2.845
2.845 2.898 2.891 2.963
Input : 0.024 0.024 0.024 0.071
0.071 0.024 0.024 0.024
Output : 0.000 0.000 0.000 2.951
2.951 0.000 0.000 0.000
Input/output : 0.024 0.024 0.024 3.022
3.022 0.024 0.024 0.024
Combine comms : 3.351 3.239 3.290 0.353
0.353 3.239 3.280 3.351
Copy comms : 0.035 0.029 0.031 0.000
0.000 0.035 0.029 0.029
Exchange comms : 12.032 10.301 10.995 11.444
11.444 12.032 10.652 10.301
Utility comms : 0.524 0.424 0.465 0.530
0.530 0.424 0.448 0.524
Parallel comms : 15.731 14.206 14.782 12.328
12.328 15.731 14.409 14.206
MPI calls : 12.998 11.485 12.016 9.271
9.271 12.998 11.565 11.485
Array interpolation : 12.404 11.920 12.165 11.939
11.939 11.920 12.171 12.404
User calls : 9.842 9.694 9.776 10.525
10.525 9.694 9.792 9.842
Library calls : 2.544 2.385 2.463 2.645
2.645 2.544 2.461 2.385
Boundary conditions : 0.536 0.477 0.514 0.459
0.459 0.477 0.530 0.536
Example 7.6: Timer report for test case plumeC on a parallel machine
with four processors.
The following example shows how timing is implemented in the program

CALL log timer in(npcc)
...
CALL log timer out(npcc,itm adv)
A timer vector array is created at the start of the program and initialised to
zero. The routine log timer in is called in the beginning of the routine and
7.4. CENTRAL INPUT FILE 289
stores the current clock count value of the processor clock in the optional
argument npcc. The value is obtained by calling the FORTRAN 90 intrinsic
routine SYSTEM CLOCK. The call to log timer out is made at the last line
of the subprogram. The routine calls SYSTEM CLOCK again and subtracts
the new clock count from the previous one. This gives the time spent in the
routine, measured in clock counts. The result is added to the value stored
in the corresponding element of the “timer” vector array. The array index is
given by the timer key id itm adv. At the end of the program the array values
are converted to seconds, divided by the total execution time and multiplied
by 100. This gives the computation times associated with different timer key
ids in percentage.
7.4 Central input file

7.4.1 Syntax of a CIF
As shown in the example 7.7 below, each data line in the CIF has the following
syntax
varname = value 1, value 2, ..., value n
where varname is the FORTRAN name of a model parameter and value 1

to value n are the input values of the parameter, separated by the data
separator ‘,’. The file is read line-wise. The data strings value 1, value 2,
. . . are converted to the appropriate (numeric, logical, character) data format
associated with the variable FORTRAN variable varname. The following rules
apply
• If a comment character ‘!’ appears in the string, all characters in the

string, starting from this character are ignored. However, the comment
character can only appear at the first position of the data line (in which
case the entire line is ignored) or after the last character of the last data
string.
• If varname corresponds to a scalar, it is obvious that only one value

needs to be given and there is no data separator. In case of a vector,
the number of data can be lower than the size of the vector in which case
the non-defined values are set to their defaults. However if a vector has
a specified “physical” size, all expected data must be given. Examples
are the arrays index obc (physical size given by nconobc) or ntrestart
(physical size given by norestarts).
• If the model parameter represents a multi-dimensional array (of rank

m), the first m-1 data strings represent the vector index for the first m-1
dimensions, the subsequent the values for each array index of the last
dimension. As before, the number of values does not need to be equal
to the size of the last dimension, unless a “physical” size is expected.
• If the variable is a derived type scalar variable, the data strings rep-
resent the components in the order given by the TYPE definition in
datatypes.f90. Derived type arrays are initialised element-wise, i.e. a
separate line for each array element. The first data string(s) are the
array indices of the first, . . . , last array dimension.
• The first array index for the variable modfiles (see Section 12.7) is not
given by a numeric value but by its file descriptor in string format, e.g.
the string modgrid corresponds to the key id io modgrd whose numeric
value is set by the program to 3.
• If a data string contains only blanks or equals the null string, the value
of the corresponding model parameter is undefined, in which case its
default value is retained. When the CIF is written by the program, all
variables (even defaults) are defined in the data strings.
• No error occurs if a model scalar or array parameter does not appear

on any input line in which case the default value is retained.
• The characters in the string varname are case insentitive. If the CIF
is written by the program, the names are always given in upper case
characters.
• When a CIF is written by the program, all setup parameters are in-
cluded in the file. The values are either the default settings or the
re-defined values from a call to the appropriate usrdef routine or the
ones reset by the program after a call to a reset routine. Only excep-
tion to this rule is the parameter cold start which is always written as
.FALSE. and can only be changed by editing the CIF manually.
7.4.2 CIF blocks

A CIF file is composed of six blocks which much be given in a specific order.
Each block corresponds to a usrdef routine (given in parentheses below)
where the parameters could be defined in absence of the CIF.
1: monitoring parameters (usrdef init params)

2: general model setup parameters (usrdef mod params)

3: parameters for the setup of time series output (usrdef out params)
4: parameters for the setup of time averaged output (usrdef avr params)
5: definitions for making harmonic analyses (usrdef anal freqs)
6: parameters for harmonic output (usrdef anal params)
The following rules apply for CIF blocks
• A CIF block is terminated by a line whose first character is the block

separator ‘#’ (the rest of the line is ignored).
• A block may be empty but the separator lines must always be there.
This means that the file must contain 6 lines (including the last one)
starting with a ‘#’. An empty block is represented by two consecutive
separator lines.
• Empty blocks are written by the program in the following cases
– block 3: no time series output (iopt out tsers=0)

– block 4: no time averaged output (iopt out avrgd=0)
– blocks 5 and 6: no harmonic output (iopt out anal=0)
• On the other hand, the above blocks may be non-empty even when the
appropriate switch is zero. In that case the input lines are read by the
program, but no assignment is made.
CIF special characters

The CIF utility uses the following special characters
‘,’ separates the data strings on an input line

‘=’ separates the string varname from the data strings. Must be on all input
lines except those starting with a ‘!’ or ‘#’ character
‘!’ indicates the start of a comment. All characters on the input line at and
beyond this character are ignored.
‘#’ block separator. Must always be the first character on a separator line.
These special characters cannot be used in the string varname or in a data

string representing a string variable. For this reason the ‘,’ character, used
in previous versions as separator between seconds and milliseconds in a
date/time string is now replaced by a ‘:’.
7.4.3 Order of definitions

Each scalar or array parameter must be defined within its specific block.
However, the order of definition within a block is, in principle, irrelevant.
However, if the number of data on an input line depends on a “physical
size” dimension parameter defined by another model parameter, this size
parameter must appear on a previous data line.
COLD START = F
LEVPROCS INI = 3
LEVPROCS RUN = 3
INILOG FILE = plume1A.inilogA
RUNLOG FILE = plume1A.runlogA
RUNLOG COUNT = 8640
MAX ERRORS = 50
LEVPROCS ERR = 1
ERRLOG FILE = plume1A.errlogA
WARNING = T
WARLOG FILE = plume1A.warlogA
LEVTIMER = 3
TIMING FILE = plume1A.timingA
TIMER FORMAT = 1
#
IOPT ADV SCAL = 3
IOPT ADV TURB = 0
IOPT ADV TVD = 1
IOPT ADV 2D = 3
IOPT ADV 3D = 3
IOPT ARRINT HREG = 0
IOPT ARRINT VREG = 0
IOPT ASTRO ANAL = 0
IOPT ASTRO PARS = 0
IOPT ASTRO TIDE = 0
...
NC = 121
NR = 41
NZ = 20
NOSBU = 80
NOSBV = 120
NRVBU = 0
NRVBV = 1
NONESTSETS = 0
NORLXZONES = 0
NPROCS = 1
NPROCSX = 1
NPROCSY = 1
IDMASTER = 0
CSTARTDATETIME = 2003/01/03;00:00:00:000
CENDDATETIME = 2003/01/06;00:00:00:000
DELT2D = 30.
IC3D = 10
ICNODAL = 0
TIME_ZONE = 0.
NTOBCRLX = 0
ATMPRES REF = 101325.
BDRAGCOEF CST = 0.
BDRAGLIN = 0.
...
NCONOBC = 1
INDEX OBC = 46
NCONASTRO = 0
ALPHA BLACK = 0.2
ALPHA MA = 10.
ALPHA PP = 5.
BETA MA = 3.33
BETA XING = 2.
...
NORESTARTS = 1
NTRESTART = 8640
INTITLE = plume1A
OUTTITLE = plumeA
MAXWAITSECS = 3600
NOWAITSECS = 0
NRECUNIT = 4
NOSETSTSR = 4
NOSTATSTSR = 0
NOVARSTSR = 9
NOSETSAVR = 0
NOSTATSAVR = 0
NOVARSAVR = 0
NOSETSANAL = 1
NOFREQSANAL = 1
NOSTATSANAL = 0
NOVARSANAL = 7
MODFILES = inicon,1,1,U,R,plumeA.phsicsU,0,0,0,0,F,F,
MODFILES = modgrd,1,1,A,R,plumeA.modgrdA,0,0,0,0,F,F,
MODFILES = 2uvobc,1,1,U,R,plume1A.2uvobc1U,0,0,0,0,F,F,
MODFILES = 3uvobc,1,1,A,R,plume1A.3uvobc1A,0,0,0,0,F,F,
MODFILES = salobc,1,1,A,R,plume1A.salobc1A,0,0,0,0,F,F,
MODFILES = 2uvobc,2,1,U,R,plume1A.2uvobc2U,0,0,1,0,F,F,
MODFILES = 3uvobc,2,1,A,R,plume1A.3uvobc2A,0,0,1,0,F,F,
MODFILES = salobc,2,1,A,R,plume1A.salobc2A,0,0,1,0,F,F,
SURFACEGRIDS = 1,1,0,0,1000.,1000.,0.,0.
#
TSRVARS = 1,0,0,0,0,0.,C,width,Plume width,km,
TSRVARS = 2,0,0,0,0,0.,C,hfront,Plume length,km,
TSRVARS = 3,92,2,0,0,0.,C,umvel,X-component of depth-mean current,m/s,
Depth-mean current
TSRVARS = 4,101,2,0,0,0.,C,vmvel,Y-component of depth-mean current,m/s,
Depth-mean current
TSRVARS = 5,81,2,0,0,0.,C,zeta,Surface elevation,m,
TSRVARS = 6,93,3,0,0,0.,C,uvel,X-component of current,m/s,Current
TSRVARS = 7,102,3,0,0,0.,C,vvel,Y-component of current,m/s,Current
TSRVARS = 8,106,3,0,0,0.,C,wphys,Physical vertical velocity,m/s,
Physical current
TSRVARS = 9,111,3,0,0,0.,C,sal,Salinity,PSU,
IVARSTSR = 1,6,7,8,9
IVARSTSR = 4,1,2,3,4,5
TSR3D = 1,T,U,plumeA_1.tsout3U,T,,2
TSR0D = 4,T,A,plumeA_4.tsout0A,T,,2
TSRGPARS = 1,T,F,F,F,2003/01/03;00:00:00:000,3,0,0,1,120,1,1,40,1,20,20,1,0,
8640,360
TSRGPARS = 2,T,F,F,F,2003/01/03;00:00:00:000,3,0,0,30,30,1,1,40,1,1,20,1,0,
8640,360
TSRGPARS = 3,T,F,F,F,2003/01/03;00:00:00:000,3,0,0,1,120,1,5,5,1,1,20,1,0,
8640,360
TSRGPARS = 4,T,F,F,F,2003/01/03;00:00:00:000,2,0,0,30,30,1,1,1,1,1,1,1,0,
8640,12
#
7.5. FORCING FILES 295
#
INDEX ANAL = 46
NOFREQSHARM = 1
IFREQSHARM = 1,1
#
ANALVARS = 1,92,2,0,0,0.,C,umvel,X-component of depth-mean,current,m/s,
Depth-mean current
ANALVARS = 2,101,2,0,0,0.,C,vmvel,Y-component of depth-mean,current,m/s,
Depth-mean current
ANALVARS = 3,81,2,0,0,0.,C,zeta,Surface elevation,m,
ANALVARS = 4,93,3,0,0,0.,C,uvel,X-component of current,m/s,Current
ANALVARS = 5,102,3,0,0,0.,C,vvel,Y-component of current,m/s,Current
ANALVARS = 6,106,3,0,0,0.,C,wphys,Physical vertical velocity,m/s,
Physical current
ANALVARS = 7,111,3,0,0,0.,C,sal,Salinity,PSU,
IVARSANAL = 1,1,2,3,4,5,6,7
IVARSELL = 1,1,10
IVECELL2D = 1,1,2
IVECELL3D = 1,1,2
RES2D = 1,T,A,plumeA_1.resid2A,T,,2
RES3D = 1,T,A,plumeA_1.resid3A,T,,2
AMP2D = 1,1,T,A,plumeA_1.1amplt2A,T,,2
PHA2D = 1,1,T,A,plumeA_1.1phase2A,T,,2
ELL2D = 1,1,T,A,plumeA_1.1ellip2A,T,,2
ELL3D = 1,1,T,A,plumeA_1.1ellip3A,T,,2
ANALGPARS = 1,T,F,F,F,2003/01/03;06:00:00:000,3,0,0,1,120,1,1,40,1,1,20,1,0,
8640,1440
#
Example 7.7: (Parts) of the CIF produced for test case plumeA.
7.5 Forcing files

7.5.1 General aspects
The forcing files, used in the program code, can be divided into two cate-
gories:
1. Files, which have no time dependence, are called “initialisation” files
and may contain the following information:
• definitions of a domain decomposition
• model grid and bathymetry

• definitions of 2-D external grids
• locations of the open boundary points of a nested sub-grid
• specifiers for 2-D and 3-D open boundary conditions or 1-D water
column forcing
• specifiers for nesting
• definition of relaxation zones.
2. Time series files provide forcing data at one or more specific times,
given as a sequence of time record(s).
• initial conditions1
• open boundary data
• 1-D water column forcing data
• 2-D and 3-D open boundary data written for nested sub-grids
• data defined on a 2-D external (meteorological, SST) grid.
The standard structure of forcing files is composed of
• a metadata (header) section with global information about the file

(called “global attributes” in netCDF language) and information about
the data variables within the file (“variable attributes” in netCDF lan-
guage)
• a data section with the values of the data. The time coordinate (if
present) is considered as an additional data variable.
The general structure of the file is then2
[Names and values of dimensions]

Global attributes
...
[Attributes of the time coordinate]
Attributes of variable 1
...
...
1
Initial conditions can be given at one or more specific times.
2
The lines in [ ] are not always present. For example, metadata and data for the time
coordinate variable are only needed in case of a forcing file containing time series.
Attributes of variable n
[First data time]
Values of variables 1
...
Values of variables n
[Second data time
...]
Example 7.8: General layout of a forcing file.
The time coordinate and data time(s) need, obviously, only to be present
in case of time series files. Note that the data times must be stored in
chronological order, but may be given at non-regular time intervals. The
detailed formats of forcing files are discussed in the subsections below.
As mentioned in Section 6.1.4, the properties (or attributes) of data files
are stored into the derived type variable FileParams (see Example 6.7 for a
full list of file attributes). The attributes of the forcing files are stored into
the 3-D derived type array modfiles:
where
MaxIOTypes is the maximum number of file descriptors

MaxIOFiles is the maximum allowed number of files per file descriptor.
An element of the array modfiles can be generically written as

modfiles(iddesc,ifil,iotype) where
iddesc denotes the file descriptor key id. The program name of the key id has
the form io filedesc where filedesc is one of the descriptor strings given
in Section 7.2.4. For example, io 2uvobc is the key id for all forcing
files related to 2-D open boundary conditions.
ifil is the file number. In some cases, this number is always 1. For exam-
ple, the input data for defining the model grid are stored in one file
with key id io modgrd. On the other hand, if a main grid contains sev-
eral nested sub-grids, a data file has to be written for each requested
parameter and each sub-grid. The parameter is represented by its key
id, while the file number denotes the number of the sub-grid. A sim-
ilar approach is followed for open boundary data. For example, the
temperature profiles at open boundaries can be obtained from several
data files having the same key id io tmpobc.
iotype equals 1 for an input and 2 for an output file. All forcing files used by
the model are input files, except for the files written for sub-grid nest-
ing. However, the program provides the possibility to re-write the data
obtained from an input file to a separate output file in COHERENS
format. This is further discussed in Section 12.7.
In the current implementation, the global attributes of the files are defined
by components of the derived type variable modfiles and are given below. A
(∗ ) at the end of the description means that the attribute can be defined by
the user.
status∗ Status of the file
‘0’ : The file is not activated.
‘N’ : The file is activated but its contents are defined by the user
in a usrdef routine. The user needs to decide whether the
data are obtained from some external file or that the file only
exists virtually and the data are defined without making a
file connection. The option is only available for input files.
‘R’ : The file is activated and its contents are read from a data file
in COHERENS standard format. The option is only allowed
for input data (iotype=1).
‘W’: The data are written in COHERENS standard format. This
is always the case for nesting data. The option can be used
to re-write data, previously obtained in a user format. The
file can then be used in a subsequent simulation with the ‘R’
status. Since the file is created for output, the iotype index
must be 2.
form∗ Format of the data file.
‘A’: ASCII
‘U’: unformatted binary
‘N’: netCDF
filename∗ Name of the file. If the file status is ‘R’ or ‘W’ and the name of
the file is not defined by the user, a default name is given (see
Section 7.2). If the status is ‘N’, the name is either defined by
the user or unknown. In the latter case the file name is set to ‘N’
(unknown) which may mean that the data are not obtained from
a file.
info∗ An info (‘I’) file is produced with the metadata information only.
end type∗ Switch to decide what action needs to be taken when an end of file
condition occurs during a read. See Section 12.7.2 for details.
0: The program aborts with an error message

1: The program continues, no further attempt will be made to
read data.
2: The program continues, a next attempt to read the data will
be made after nowaitsecs seconds.
tlims(1:3)∗ Start/end/step time indices (i.e. times measured in units of the

2-D time step delt2d). The data will be updated after ABS(tlims(3))
×delt2d seconds. If tlims(3)>0, time interpolation will be per-
formed. If tlims(3)<0, the data values are set to the one obtained
from the latest data record earlier than the current time.
iunit File unit number. This parameter is set internally and cannot be
reset by the user.
iostat The I/O status of the file.
-1: An error occurred when the program attempted to open the

file.
0 : The file is not open.
1 : The file is open and the file pointer is located at the start or
before the end of the file.
2 : The file pointer is located at the end of the file (i.e. an end
of file condition will occur on a next read).
3 : An end of file condition did occur.
nocoords Number of coordinate arrays within the file, equal to 0 for an

initialisation file and 1 for a time series file.
novars Number of (non-coordinate) data variables within the file.
filedesc A string with a description of the file.
timeid netCDF variable id of the time coordinate.
The variable attributes are stored into a temporary derived type array
TYPE (VariableAtts), DIMENSION(nocoords+novars) :: varatts
where nocoords and novars are the global attributes stored in the modfiles
array. The following attributes are defined:
f90 name A string with the FORTRAN name of the variable as used in
the program. Maximum length is set by the system parameter
lenname.
long name A string with a description of the variable. Maximum length is
set by the system parameter lendesc.
vector name If the variable represents a vector component, a string with a
description of the vector. Its value must be the same for all
components of the same vector. Maximum length is set by the
system parameter lendesc.
units A string describing the variable’s unit. The string has a format
recognised by UNIDATA’s Udunits package (UDUNITS, 1997)
which can be considered as an internationally recognised stan-
dard. Maximum length is set by the system parameter lenunit.
data type The type of variable as given in the second column of Table 6.1
(e.g. real type for a REAL variable).
ivarid The variable’s key id.
nrank If the variable is an array, the rank of the array. Otherwise, the
variable is a scalar and the rank is zero.
shape If the variable is an array, a vector with the array size(s) in each
dimension. In case of a scalar the shape vector has one element
with the value 1.
7.5.2 Data contents of forcing files

Table 7.3 provides a general listing of the data contents for each type of
forcing file. Note that the exact number of data variables depends on how
the model has been set up. A detailed discussion is given in the Part IV.
The integer parameters used in the table for array dimensioning have the
following meaning:
nprocs number of processes in case the program is applied in parallel
mode
ncloc X-dimension of the local grid
nrloc Y-dimension of the local grid
nc X-dimension of the global (computational) grid
nr Y-dimension of the global (computational) grid
nz number of vertical layers
nhalo halo size (=2)
nconobc number of tidal constituents at open boundaries

nconastro number of astronomical constituents used for the tidal force
nobu number of open boundary points at U-nodes
nobv number of open boundary points at V-nodes
n1dat X-dimension of an external 2-D data grid
n2dat Y-dimension of an external 2-D data grid
nonestsets number of nested sub-grids
nhdat number of sub-grid open boundary locations in the horizontal used
for nesting of a sub-grid
nzdat number of vertical levels at sub-grid open boundary locations used
for nesting of a sub-grid
nonodes number of “nodal” grids used for interpolation in nesting proce-
dures (see Section 15.3.3)
novars number of data (meteorological, . . . ) variables in a data file
numprofs number of vertical profiles in a 3-D open boundary forcing file
nofiles number of data files (plus one) for open boundary or 1-D surface
forcing
norlxzones number of zones for application of the relaxation scheme near open
boundaries
Table 7.3: Data contents for each type of input forcing file. In the last column ‘R’,
‘I’, ‘C’, ‘D’ denote respectively real, integer, character and derived type data.
key id file number variable shape type

io mppmod 1 nc1procs nprocs I
nc2procs nprocs I
nr1procs nprocs I
nr2procs nprocs I
io inicon 1 udvel (1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo) R
vdvel (1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo) R
zeta (0:ncloc+1,0:nrloc+1) R
uvel (1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz) R
vvel (1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz) R
wvel (0:ncloc,0:nrloc,nz+1) R
temp (1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz) R
sal (1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz) R
(Continued)
tke (1-nhalo:ncloc+nhalo,
1-nhalo:nrloc+nhalo,nz+1) R
zlmix (1-nhalo:ncloc+nhalo,
dissip (1-nhalo:ncloc+nhalo,
bdragcoefatc (0:ncloc,0:nrloc) R
zroughatc (0:ncloc,0:nrloc) R
fnode obc nconobc R
phase obc nconobc R
fnode astro nconastro R
phase astro nconastro R
obcsalatu (0:nobu,nz,0:2) R
obcsalatv (0:nobv,nz,0:2) R
obctmpatu (0:nobu,nz,0:2) R
obctmpatv (0:nobv,nz,0:2) R
obc2uvatu (nobu,2) R
obc2uvatv (nobv,2) R
obc3uvatu (nobu,nz,2) R
obc3uvatv (nobv,nz,2) R
io modgrd 1 gxcoordglb (nc,nr) R
gycoordglb (nc,nr) R
gscoordglb (nc-1,nr-1,nz+1) R
depmeanglb (nc-1,nr-1) R
iobu nobu I
jobu nobu I
iobv nobv I
jobv nobv I
io metgrd 1 xcoord (n1dat,n2dat) R
ycoord (n1dat,n2dat) R
or surfgridglb (nc,nr) D
io sstgrd 1 xcoord (n1dat,n2dat) R
ycoord (n1dat,n2dat) R
or surfgridglb (nc,nr) D
io nstgrd 1:nonestsets xcoord nhdat R
ycoord nhdat R
or hnests (nhdat,nonodes) D
zcoord (nhdat,nzdat) R
(Continued)
io 1uvsur 1 gxslope amp nconobc R

gxslope pha nconobc R
gyslope amp nconobc R
gyslope pha nconobc R
zeta amp nconobc R
zeta pha nconobc R
2:nofiles ciodatetime – C
data1d novars R
io 2uvobc 1 ityp2dobu nobu I
iloczobu nobu I
itypintobu nobu I
ityp2dobv nobv I
iloczobv nobv I
itypintobv nobv I
no2dobc 2:nofiles I
iobc2dtype 2:nofiles I
index2dobc (nobu+nobv:2:nofiles) I
ud2obu amp (nobu,nconobc) R
zetobu amp (nobu,nconobc) R
ud2obu pha (nobu,nconobc) R
zetobu pha (nobu,nconobc) R
vd2obv amp (nobv,nconobc) R
zetobv amp (nobv,nconobc) R
vd2obv pha (nobv,nconobc) R
zetobv pha (nobv,nconobc) R
data2d (nodat,novars) R
io 3uvobc 1 itypobu nobu I
iprofobu nobu I
itypobv nobv I
iprofobv nobv I
noprofsd 2:nofiles I
indexprof (nobu+nobv,2:nofiles) I
iprofrlx norlxzones I
psiprofdat (nz,numprofs,1) R
io salobc 1 itypobu nobu I
iprofobu nobu I
(Continued)
itypobv nobv I
iprofobv nobv I
io tmpobc 1 itypobu nobu I
iprofobu nobu I
itypobv nobv I
iprofobv nobv I
io rlxobc 1 inodesrlx 2 I
idirrlx norlxzones I
ityprlx norlxzones I
iposrlx norlxzones I
jposrlx norlxzones I
ncrlx norlxzones I
nrrlx norlxzones I
io nstspc 1 nestcoords nonestsets I
nohnstglbc nonestsets I
nohnstglbu nonestsets I
nohnstglbv nonestsets I
novnst nonestsets I
inst2dtype nonestsets I
io metsur 1 ciodatetime – C
surdata (n1dat,n2dat,novars) R
io sstsur 1 ciodatetime – C
surdata (n1dat,n2dat,1) R
7.5.3 Standard format of forcing files

7.5.3.1 ASCII files
The ASCII format is illustrated with two examples. They are taken from a
case study for the North Sea (not discussed in the current version of the ma-
nual). Examples 7.9 and 7.10 show the contents of the files nsp89.2uvobc1A
and nsp89.metsurA. The line numbers have been added in the header section
for illustrative purposes only and do not appear in the actual file.
1 : 1
2 :V2.0
3 :2010/06/17;09:22:34
4 :Type of open boundary conditions for 2-D mode
5 : 0
6 : 17
7 : 620 3 1 29
8 :ityp2dobu
9 :Type of 2-D open boundary condition at U-nodes
10:-
11: 607 3 1 29
12:iloczobu
13:Position of elevation points with respect to U-open boundaries
14:-
15: 616 3 1 29
16:itypintobu
17:Switch to allow momentum advection near U-open boundaries
18:-
19: 621 3 1 111
20:ityp2dobv
21:Type of 2-D open boundary condition at V-nodes
22:-
23: 608 3 1 111
24:iloczobv
25:Position of elevation points with respect to V-open boundaries
26:-
27: 617 3 1 111
28:itypintobv
29:Switch to allow momentum advection near V-open boundaries
30:-
31: 624 3 1 2
32:no2dobc
33:Number of input data per input file

34:-
35: 612 3 1 2
36:iobc2dtype
37:Type 2-D open boundary data input
38:-
39: 611 3 2 140 2
40:index2dobc
41:Map of data points to open boundary locations
42:-
43: 637 5 2 29 9
44:ud2obu amp
45:Amplitude of X-component of depth-integrated current at U-open
boundaries
46:m^2/s
47: 648 5 2 29 9
48:zetobu amp
49:Amplitude of surface elevation at U-open boundaries
50:m
51: 638 5 2 29 9
52:ud2obu pha
53:Phase of X-component of depth-integrated current at U-open boundaries
54:radian
55: 649 5 2 29 9
56:zetobu pha
57:Phase of surface elevation at U-open boundaries
58:m
59: 640 5 2 111 9
60:vd2obv amp
61:Amplitude of Y-component of depth-integrated current at V-open
boundaries
62:m^2/s
63: 651 5 2 111 9
64:zetobv amp
65:Amplitude of surface elevation at V-open boundaries
66:m
67: 641 5 2 111 9
68:vd2obv pha
69:Phase of Y-component of depth-integrated current at V-open boundaries
70:radian
71: 652 5 2 111 9
72:zetobv pha
73:Phase of surface elevation at V-open boundaries
74:m
ityp2dobu
11 11 ...
iloczobu
1 1 ...
itypintobu
0 0 ...
ityp2dobv
11 11 ...
iloczobv
1 1 ...
itypintobv
0 0 ...
no2dobc
127 13
iobc2dtype
1 3
index2dobc
1 2 ...
ud2obu amp
0.4421976 0.5311887 ...
zetobu amp
0.3082999E-01 0.3055999E-01 ...
ud2obu pha
4.054574 4.223073 ...
zetobu pha
5.249485 5.269729 ...
vd2obv amp
0.5446934 0.7153571 ...
zetobv amp
0.4053500E-01 0.3966500E-01 ...
vd2obv pha
2.541209 2.624729 ...
zetobv pha
0.2956865 0.3112219 ...
Example 7.9: Contents of the file nsp89.2uvobc1A in standard ASCII
COHERENS format.
• Lines 1–6 give the values of the attributes:

header type the type of header which (in the current version) is
always 1 for a forcing file
coherens version the current program version number, which is the same
for all forcing files
creation date the exact date and time when the file was created
filedesc a description of the file
nocoords the number of coordinate variables (as defined in
modfiles)
novars the number of (non-coordinate) variables (as defined
in modfiles)
• In case of a time series file, the next four lines list the attributes of the
time coordinate (see Example 7.10).
• The remaining lines 7–74 show the attributes of the data variables.
• The attributes of each variable are given on four lines
– line 1: the attributes ivarid, data type, nrank, shape, giving 3+nrank
integer parameters on the input line
– line 2: the f90 name attribute
– line 3: the long name attribute
– line 4: the units attribute
• The total number of header lines is then given by 6+4*(nocoords+novars).
• The data section gives the values of the variables in the order in whichv
they have been defined in the header section.
– In case of an initialisation file, the name of the variable is written

on one line, followed by its values.
– In case of a time series file, the value of the time coordinate is
written first using the date/time string format (see Section 6.2.2),
the data values are written as in the previous case except that the
data values are preceded by an empty line (for illustration this line
is presented in the example by the variable’s name in [ ]). The
line next to the values of the last variable is the date/time of the
next time record, . . . .
The contents of an ASCII forcing file are to be read sequentially, i.e. line
by line.
• The lines in the header either contain a character string or integer pa-
rameters which makes it easier to read them using the character (‘A’)
format (strings) or free (∗ ) format (integers). The header information
does not provide additional information for the program, since the at-
tributes are already known internally, but are used for error checking
only. For users who like to read the data from some external program,
the metadata provides useful information (number, rank and shape of
the data variables).
• The data values (except the date/time string in time series files) are
either of type INTEGER or REAL and are read in FORTRAN array order,
e.g.
READ (iunit,IntegerFormat) itypintobu

READ (iunit,RealFormat) uwindatc
where the string format specifications IntegerFormat and RealFormat are

system parameters, defined in syspars.f90. Values are
IntegerFormat=’(50I11)’; RealFormat=’(50G16.7)’
It is advised not to change these values (except for the repeat specifi-
cation) since they allow to represent the data with the highest possible
precision.
1 : 1
2 :V2.0
3 :2010/06/17;09:22:34
4 :Meteo input surface data
5 : 1
6 : 7
7 : 952 1 2 23 -1
8 :time
9 :Time
10:date/time
11: 410 5 2 50 28
12:uwindatc
13:X-component of surface wind
14:m/s
15: 411 5 2 50 28
16:vwindatc
17:Y-component of surface wind

18:m/s
19: 402 5 2 50 28
20:atmpres
21:Atmospheric pressure
22:N/m^2
23: 401 5 2 50 28
24:airtemp
25:Air temperature
26:degC
27: 407 5 2 50 28
28:relhum
29:Relative humidity
30:-
31: 403 5 2 50 28
32:cloud cover
33:Cloud cover
34:-
35: 404 5 2 50 28
36:evapminprec
37:Evaporation minus precipitation rate
38:kg/m^2/s
1989/01/01;00:00:00,000
[uwindatc]
0.8044688E-06 -0.2852140 ...
[vwindatc]
9.202050 8.167472 ...
[atmpres]
102672.9 102768.9 ...
[airtemp]
13.85400 13.92300 ...
[relhum]
0.9958699 0.9328000 ...
[cloud cover]
0.6250000 0.6250000 ...
[evapminprec]
0.7811863E-05 0.7811863E-05 ...
1989/01/01;03:00:00,000
[uwindatc]
-0.3340597 -0.5992587 ...
[vwindatc]
9.566232 8.569798 ...

[atmpres]
102548.8 102661.5 ...
[airtemp]
13.95900 13.99600 ...
[relhum]
0.7983300 0.8664200 ...
[cloud cover]
0.6250000 0.6250000 ...
[evapminprec]
0.7811863E-05 0.7811863E-05 ...
1989/01/01;06:00:00,000
...
Example 7.10: Contents of the file nsp89.metsurA in standard ASCII
COHERENS format.
7.5.3.2 unformatted binary files

When the unformatted binary or ASCII format is selected, the same meta-
data and data are written in the forcing file. Differences are that in case of
a binary format:
• String attributes, numerical attributes and data values are written in
binary format. The form depends on the internal binary presentation
of each (character, integer, real) data type. Common types are known
as ‘NATIVE’, ‘LITTLE ENDIAN’, ‘BIG ENDIAN’, ‘IBM’.
• The file can be read only on machines which use the same binary pre-
sentation3 .
• Reading of the file or conversion to a readable format can only be
performed using some external (post-processing) program.
• The data are written sequentially as in the ASCII case but without a
format specification.
• Data values are no longer preceded by a blank line.
• Prime advantage of this format is that each numerical value (defined
in single precision) only uses (in most cases) only 4 bytes of disk space,
reducing the required storage space by a factor 3 to 4 compared to the
ASCII format.
3
Some compilers provide a CONVERT specifier in a FORTRAN OPEN call allowing to
make a conversion between two different binary formats.
The program provides an utility (using the info file attribute) to view the
metadata contents of a binary file without additional programming tools.
If the info attribute is set to .TRUE., the program will create an additional
“info” file with all metadata information in ASCII. An example is given below
for the rhone test case.
header type: 1
coherens version: V2.0
creation date: 2010/06/18;16:49:53
file description: Model grid
nocoords: 0
novars: 6
32 5 1 31
gsigcoord
Sigma coordinates on uniform grid
-
105 5 2 108 50
depmeanglb
Global mean water depth at C-nodes
m
43 3 1 65
iobu
Global X-index of U-open boundaries
-
51 3 1 65
jobu
Global Y-index of U-open boundaries
-
45 3 1 110
iobv
Global X-index of V-open boundaries
-
53 3 1 110
jobv
Global Y-index of V-open boundaries
-
Example 7.11: Contents of rhoneA.modgrdI info file, giving all metadata

information included in the rhone grid file.
7.5.3.3 netCDF files

The netCDF format is binary and non-sequential. The data are organised in
records which can be read by specifying the appropriate record number as
argument to a netCDF routine call. Moverover, the contents of the file, or
part of the contents (metadata only, values of one or more data variables) can
easily by converted to an ASCII format, which is the so-called CDL (network
Common Data form Language) format. For a full description of CDL, see
Russ et al. (2004).
• Data and metadata are stored, in a platform-independent way, as (non-

sequential) internal records.
• Reading and writing is performed by netCDF routine calls described

in the netCDF manual (Pincus & Rew, 2008). Specific routines are
available in the program to write metadata and data into a standard
COHERENS format, similar to the one used in the ASCII and unfor-
matted binary formats.
• An alias (starting with cf 90) is defined in the code for each netCDF
routine call (starting with NF90 ). The aim is a more efficient imple-
mentation of future netCDF versions.
• Although the file is in a compressed binary format, the contents or part

of the contents of a netCDF file can be converted to ASCII form with
the ncdump utility:
ncdump file.cdf
ncdump -h file.cdf
ncdump -v var file.cdf
The first form rewrites the file file.cdf to standard output in ASCII
format. The second rewrites the metadata section only, the third form
rewrites the metadata section and the values of the variable var.
.
Example 7.12 shows the metadata file in CDL format of the initial con-
dition file for the North Sea case study. Differences with the ASCII a binary
formats are:
• Variable dimensions must be defined with a given name.

• The f90 name, nrank and shape attributes are no longer explicitly de-
fined, but provided implicitly when a netCDF variable is defined with
the NF 90 def var library call.
• Global attributes are the same as before except for the cdfversion at-
tribute giving the current netCDF version used by the model and the
timerec attribute giving the number of time records in the file.
Reading and writing of netCDF metadata and data is performed using the
routines of the netCDF library. A detailed description is found in the netCDF
FORTRAN 90 manual (Pincus and Rew, 2008).
netcdf nsp89
dimensions:
tlendim = 23 ;
T = UNLIMITED ; // (2 currently)
X002 = 141 ;
Y002 = 128 ;
...
Z020 = 2 ;
variables:
char time(T, tlendim) ;
time:ivarid = 952 ;
time:long name = "Time" ;
time:units = "date/time" ;
float udvel(T, Y002, X002) ;
udvel:ivarid = 157 ;
udvel:long name = "X-component of depth-integrated current" ;
udvel:units = "m^2/s" ;
float vdvel(T, Y003, X003) ;
vdvel:ivarid = 166 ;
vdvel:long name = "Y-component of depth-integrated current" ;
vdvel:units = "m^2/s" ;
float zeta(T, Y004, X004) ;
zeta:ivarid = 113 ;
zeta:long name = "Surface elevation" ;
zeta:units = "m" ;
float uvel(T, Z005, Y005, X005) ;
uvel:ivarid = 162 ;
uvel:long name = "X-component of current" ;
uvel:units = "m/s" ;
float vvel(T, Z006, Y006, X006) ;
vvel:ivarid = 171 ;
vvel:long name = "Y-component of current" ;
vvel:units = "m/s" ;
float wvel(T, Z007, Y007, X007) ;
wvel:ivarid = 176 ;
wvel:long name = "Transformed vertical velocity" ;
wvel:units = "m/s" ;
float temp(T, Z008, Y008, X008) ;
temp:ivarid = 205 ;
temp:long name = "Temperature" ;
temp:units = "degC" ;
float sal(T, Z009, Y009, X009) ;
sal:ivarid = 204 ;
sal:long name = "Salinity" ;
sal:units = "PSU" ;
float tke(T, Z010, Y010, X010) ;
tke:ivarid = 304 ;
tke:long name = "Turbulent kinetic energy" ;
tke:units = "J/kg" ;
float fnode obc(T, X011) ;
fnode obc:ivarid = 353 ;
fnode obc:long name = "Nodal factors of tidal constituents at open boundaries" ;
fnode obc:units = "-" ;
float phase obc(T, X012) ;
phase obc:ivarid = 360 ;
phase obc:long name = "Astronomical phases at open boundaries" ;
phase obc:units = "radian" ;
float obcsalatu(T, Z013, Y013, X013) ;
obcsalatu:ivarid = 625 ;
obcsalatu:long name = "Storage array for salinity at U-open boundaries" ;
obcsalatu:units = "PSU" ;
float obcsalatv(T, Z014, Y014, X014) ;
obcsalatv:ivarid = 626 ;
obcsalatv:long name = "Storage array for salinity at V-open boundaries" ;
obcsalatv:units = "PSU" ;
float obctmpatu(T, Z015, Y015, X015) ;
obctmpatu:ivarid = 627 ;
obctmpatu:long name = "Storage_array_for_temperature_at_U-open_boundaries" ;
obctmpatu:units = "degC" ;
float obctmpatv(T, Z016, Y016, X016) ;
obctmpatv:ivarid = 628 ;
obctmpatv:long name = "Storage array for temperature at V-open boundaries" ;

obctmpatv:units = "degC" ;
float obc2uvatu(T, Y017, X017) ;
obc2uvatu:ivarid = 629 ;
obc2uvatu:long name = "Storage array for 2-D mode at U-open boundaries" ;
obc2uvatu:units = "-" ;
float obc2uvatv(T, Y018, X018) ;
obc2uvatv:ivarid = 630 ;
obc2uvatv:long name = "Storage array for 2-D mode at V-open boundaries" ;
obc2uvatv:units = "-" ;
float obc3uvatu(T, Z019, Y019, X019) ;
obc3uvatu:ivarid = 631 ;
obc3uvatu:long name = "Storage array for 3-D mode at U-open boundaries" ;
obc3uvatu:units = "m/s" ;
float obc3uvatv(T, Z020, Y020, X020) ;
obc3uvatv:ivarid = 632 ;
obc3uvatv:long name = "Storage array for 3-D mode at V-open boundaries" ;
obc3uvatv:units = "m/s" ;
// global attributes:
:header type = 1 ;
:coherens version = "V2.0" ;
:creation date = "2010/06/21;17:49:36" ;
:filedesc = "Physical initial conditions" ;
:cdfversion = "3̈.6.2¨ of" ;
:nocoords = 1 ;
:novars = 19 ;
:timerec = 2 ;
data:
time =
"1989/01/01;00:00:00,000",
"1989/12/25;00:00:00,000" ;
udvel =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, -0.08447912, 0.3973033, 0, ...
vdvel =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...
zeta =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1.607709, 1.618565, 1.631894, 0, ...
uvel =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, -0.006357468, 0.006396886, 0, ...
7.6. USER OUTPUT FILES 317
vvel =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...
wvel =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...
temp =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 10.34, 10.34, 10.34, 0, 0, 0, ...
sal =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 35.4, 35.4, 35.4, 0, 0, 0, 35.33, ...
tke =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1.114186e-05, 5.660635e-06, ...
fnode obc =
1.165938, 1.165991, 1.10667, 0.9655771, 0.9624547, 0.9655771, ...
phase obc =
5.17733, 2.496852, 0.2368603, 5.49324, 5.436536, 2.75393, 3.223492, ...
obcsalatu =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...
obcsalatv =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...
obctmpatu =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...
obctmpatv =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...
obc2uvatu =
-20.18008, -20.35524, -18.70897, -17.60509, -17.31932, -16.37582, ...
obc2uvatv =
-0.6839569, 2.442981, 1.570055, 0.996551, 1.981653, 2.819804, ...
obc3uvatu =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...
obc3uvatv =
0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...
Example 7.12: Metadata of the initial condition file for the North Sea test
case in netCDF CDL format.
7.6 User output files

7.6.1 General aspects
The procedures for defining user output are discussed at length in Chap-
ter 16. Only a summary, needed to understand the formatting of the data
file discussed in the next subsection, will be given here.
The following forms of user output can be defined
• Time series: output of model data at regular time intervals.
• Time averaged: output of model data averaged over a specific period

and repeated at regular time intervals.
• Harmonic: output of harmonically analysed model data over a specific

period and repeated at regular time intervals. Output data may consist
of residuals, amplitudes, phases and elliptic parameters.
User output is organised by defining so-called “output sets”. Each set

is characterised by a specific spatial and time resolution and a number of
selected variables. Each output set (except harmonic output) may contain 3
files at most:
• 0-D file: “globally” evaluated data (e.g. domain averaged temperature)

or data without a spatial dimension (e.g. width of a river plume)
• 2-D file: 2-D (horizontal) data without a vertical dimension (e.g. water
levels)
• 3-D file: 3-D data having both horizontal and vertical dimensions
For each file a derived type variable is defined of TYPE(FileParams). The

following attributes can be defined by the user:
defined Activates or disactivates the file if set to .TRUE. or .FALSE. res-

pectively.
form Format of the output file
‘A’: ASCII
‘N’: netCDF
info An info (‘I’) file is produced with the metadata information if
.TRUE.
header type No header (metadata) will be written if set to zero. The option
is not available for netCDF files.
The attributes iunit, iostat, nocoords, novars and timeid are defined internally
and have the same meaning as for forcing files (see Section 7.5.1).
The user is free to choose the output grid which may be the full model
grid, a subsection of the model grid or a completely irregular grid as is the
case for data at station locations. In case of a 2-D or 3-D grid, the horizontal
grid may be taken as one point so that the 2-D data reduce to one data value
and the 3-D data to one vertical profile per variable and time step.
The attributes of the output grid are stored in a derived type variable
of TYPE(OutGridParams). The definitions of its attributes are given in Sec-
tion 16.1.1.3, but repeated here for clarity.
gridded If .TRUE. (default), the output data are defined on a sub-grid of
the model grid (or the whole model grid). If .FALSE., the data
are taken at a number of irregularly spaced locations (“station”
data) defined by the user.
grid file If .TRUE., the coordinates of the output grid will be written on
a separate output file. Otherwise, they are written within the
data file itself (default).
land mask A land mask will be applied if .TRUE. and gridded=.TRUE.. This
means that the gridded data will be stored as a vector excluding
land points. Advantage may be a significant reduction in disk
space. Disadvantage is that the data need to be restored on the
original output grid by a postprocessing program. Default is
.FALSE.
time grid If .TRUE., the data grid is taken as time-dependent (since the
vertical positions in a σ-grid depend on time). Surface elevations
will be written as an additional coordinate variable at each time
step. Default is .FALSE., in which case the vertical positions are
referred to the mean water level. This option is only available
for time series output.
time format Format of the time coordinate.
0: date/time in string format (default value)
1: seconds
2: minutes
3: hours
4: days
5: months
6: years
7: date in years
Cases 1-6 are numerical formats. Cases 0 and 7 are absolute
times, while the others are times relative to the reference date/time
refdate.
refdate Reference date/time for calculating relative times. If not given,

refdate equals the first output date/time, rounded to the nearest
minute, hour, ... depending on the value of time format.
tlims Start/end/step time indices for data output. This means that
output will be written at intervals of delt2d*tlims(3) seconds.
nodim Dimension of the output grid (0/2/3). For example, the dimen-
sion must be set to 3 to enable 3-D output.
nostats Number of data stations in case of non-gridded (station) data.
xlims Start/end/step X-index in case of gridded data. This defines
the output sub-grid in the X-direction. (Option not available
for 0-D or station output).
ylims Start/end/step Y-index in case of gridded data. This defines
the output sub-grid in the Y-direction. (Option not available
for station or 0-D output).
zlims Start/end/step Z-index in case of gridded data. This defines the
output sub-grid in the Z-direction and applies for gridded and
non-gridded output. (Option only available for 3-D output).
Attributes of variables and coordinate arrays of the output grid are stored
in a derived type variable of TYPE(VariableAtts) (see Section 7.5.1). The
program makes distinction between two types of variables:
• Standard variables whose attributes are known to the program. In that

case the variable’s key id is supplied by the user and only a limited num-
ber of definitions need to be made. A number of operators (minimum,
maximum or mean value, value at a given vertical level or depth) can
be applied to the output data. The output values are automatically
generated by the program.
• User-defined variables in which case all attributes and output values

are to be defined by the user.
The procedures for defining time series output can be summarised as follows.
1. Define the three general parameters
nosetstsr number of sets

novarstsr total number of output variables
nostatstsr total number of output stations
2. Define the attributes of all variables used for time series output. At-
tributes can be automatically generated if the ivarid attribute is defined
by the user.
3. For each set
• Select which files are to be written (0-D, 2-D, 3-D) using the define
attribute.
• Define the file attributes form, filename, info, header type. Defaults
are available.
• Select the variables for each output file.
• Define the attributes of the output grid. Defaults are available.
The procedures for time averaged output are the same, except that an
averaging period needs to be defined instead of an output time interval.
For harmonic output additional parameters need to be defined. Assume
then that N frequencies are selected within one set. The following output
files may be defined within that set:
• 0-D: 1 residual, N amplitude and N phase files
• 2-D: 1 residual, N amplitude, N phase and N elliptic (tidal ellipse

parameters) files
• 3-D: 1 residual, N amplitude, N phase and N elliptic files
giving a maximum of 3+8N files per set.

In addition to the the procedures for time series output, harmonic output
requires to:
1. Define the total number of frequencies nofreqsanal.
2. Define all harmonic frequencies.
3. For each set
• select which of the 3+8N files are written

• select output frequencies
• select elliptic parameters (optional)
• select the period for analysis.
7.6.2 Structure of user output files

The general structure is similar to the one used for forcing files, except that
the file additionally contains the coordinates of the output grid.
[Names and values of dimensions]
Global attributes
...
Attributes of spatial coordinate 1
...
Attributes of spatial coordinate 2
...
Attributes of time coordinate
...
...
...
Attributes of variable n
...
Values of spatial coordinate 1
...
Values of spatial coordinate 2
...
First output time
[Surface elevation coordinate]
Values of variables 1
...
Values of variables n
Second output time
...
Example 7.13: General layout of a user output file.
In principle, the number of coordinate variables should be equal to or

lower than four (three spatial and one time variable). However, the model
uses a σ-grid which is fixed in time in the transformed coordinate system,
but not in physical space due to the up and down movements of the water
column. In most graphical applications these changes are negligible and the
total water depth is approximated by its mean value. However, time-varying
grids can be taken into account in the current version of COHERENS. The
output grid can then be defined through the following six coordinates (where
the spatial dimension is given in parentheses):
xout X-coordinate in m or fractional degrees longitude (2-D)

yout Y-coordinate in m or fractional degrees latitude (2-D)
zout Z-coordinate in m using mean water depths, i.e. between −h and 0
(3-D)
depout mean water depth in m (2-D)
zetout surface elevation in m (2-D)
time output time (0-D). Unit is specified by the time format attribute.
It is clear that
• In the case of a 0-D output only the time coordinate is included.
• In the case of a 2-D output only xout, yout, depout and time are in-
cluded.
• Elevation data are only included if the user selects a time varying 3-D
output grid using the time grid attribute.
The first four arrays have no associated time dimension. The last two are
stored within the file in chronological order at regular time intervals. In the
ASCII and unformatted binary format, storage is sequential. In the netCDF
format, data are stored with increasing record numbers at subsequent times.
7.6.3 Format of files with user-defined output

7.6.3.1 ASCII files
The ASCII format is illustrated with examples taken from the plume test
case. The first shows the contents of the output file plumeA 2.out3A. The
line numbers have been added in the header section for illustrative purposes
only and do not appear in the actual file.
1 : 2
2 :V2.0
3 :2010/06/23;12:19:42
4 :Time series data: plume1A
5 : 3
6 :F
7 : T F F
8 : 0 1 1
9 : 1 40 20 0 0 25
10: 10800.00
11:2003/01/03;00:00:00,000
12:2003/01/06;00:00:00,000
13:2003/01/03;00:00:00,000
14: 0
15: 5
16: 5
17: 4
18: 957 5 2 1 40
19:xout
20:X-coordinate
21: m
22: 962 5 2 1 40
23:yout
24:Y-coordinate
25: m
26: 968 5 3 1 40 20
27:zout
28:Z-coordinate
29: m
30: 951 5 2 1 40
31:depout
32:Mean water depth
33: m
34: 952 5 2 23 25
35:time
36:Time
37: date/time
38: 162 5 4 1 40 20 25
39:uvel
40:X-component of current
41:m/s
42:Current
43: 171 5 4 1 40 20 25
44:vvel
45:Y-component of current
46:m/s
47:Current
48: 175 5 4 1 40 20 25
49:wphys
50:Physical vertical velocity
51:m/s
52:Physical current
53: 204 5 4 1 40 20 25
54:sal
55:Salinity
56:PSU
57:
[xout]
29500.00 29500.00 ...
[yout]
500.0000 1500.000 ...
[zout]
-19.50000 -19.50000 ...
[depout]
20.00000 20.00000 ...
2003/01/03;00:00:00,000
[uvel]
-0.2228398 -0.2281678 ...
[vvel]
-0.8393249E-02 -0.1428325E-01 ...
[wphys]
0.000000 0.000000 ...
[sal]
33.00000 33.00000 ...
2003/01/03;03:00:00,000
...
Example 7.14: Contents of the output data file plumeA 2.tsout3A from the
plume test case.
• Line 1: the header type attribute. If set to 0, no further header infor-

mation will be given (except this line). Otherwise, its value is 2.
• Line 2: the coherens version attribute with the currently used COHERENS
version.
• Line 3: the creation date giving the exact date and time when the file
was created.
• Line 4: the filedesc attribute with a description of the simulation.
• Line 5: the nodim attribute giving the spatial dimension of the output
grid.
• Line 6: the grid file attribute. If .TRUE. (.FALSE.), grid data and
metadata are (are not) written to a separate data file.
• Line 7: the gridded, land mask and time grid attributes.
• Line 8: values of the switches of iopt grid sph, iopt grid htype and
iopt grid vtype which define the type of grid (see Section 12.4.1).
• Line 9: the attributes ncout, nrout, nzout, which define the size of the
output grid (gridded case), nowetout, giving the number of sea points in
the output grid (if the land mask attribute is .TRUE., zero otherwise),
nostats (the number of stations in the non-gridded case) and nstepout
(number of time records).
• Line 10: the output time step in seconds (deltout attribute).
• Line 11: date/time of first output (startdate attribute).
• Line 12: date/time of last output (enddate attribute).
• Line 13: reference date/time (refdate attribute). If the time coordinate

has a numerical format, the time is given as the time elapsed from this
date.
• Line 14: the time format attribute.
• Line 15: the nocoords attribute giving the number of grid coordinates.
• Line 16: the timeid attribute giving the variable id of the time coordi-
nate. This attribute is only used for reading the time coordinate in a
netCDF file.
• In case of a time varying grid (only), the zetaid attribute giving the vari-
able id of the zetout coordinate, used for reading the surface elevation
coordinate in a netCDF file.
• Line 17: the novars attribute giving the number of data variables.
• In case of station data, the labels and names of the stations are written
on subsequent lines with one line per station.
• Lines: 18-37: attributes of each coordinate variable using four lines per
variable.
– line 1: the attributes ivarid, data type, nrank, shape, represented

by 3+nrank integer parameters

• Lines 38–57: attributes of each data variable using five lines per variable
– line 1: the attributes ivarid, data type, nrank, shape, represented

by 3+nrank integer parameters
– line 5: the vector name attribute
• The total number of header lines in the current example is then given
by 17+4*nocoords+5*novars.
– If nostats>0, nostats lines have to be added.

– If time grid is .TRUE., there is 1 additional line for the zetaid at-
tribute. In that case nocoords is also increased by 1.
– If grid file is .TRUE., lines 7–16 and 18–37 are moved to the header
of the grid file. The total number of header lines is then decreased
by 10+4*nocoords.
• The remaining lines in the example form the data section, which is
composed of two parts:
– The first part lists (if the time grid attribute is .TRUE.) the values
of the time-independent coordinate arrays, preceded by an empty
line and written in the same order as defined in the header.
– The second lists (if the time grid attribute is .TRUE.) the values of
the time-dependent coordinate arrays (and data variables in the
following order:
∗ time coordinate
∗ zetout variable (if time grid is .TRUE. and preceded by an
empty line)
∗ values of each data variable in the same order as defined in
the header. Each variable list is preceded by an empty line.
∗ For clarity, the name of the variable is substituted in [ ] within
the example.
– The same procedure is followed for the next time records.
The contents of an ASCII forcing file are to be read sequentially, i.e. line
by line.
• The parameters listed on each line all have the same data type (except
for the station parameters) which makes it easy to read them using
the character (‘A’) format (strings) or in free (∗ ) format (integer, real,
logical data).
• The data values (except the date/time string if the time coordinate is
given in a non-numeric format) are all of type REAL, read in FORTRAN
array order. Format specifications are the same as for forcing files (see
Section 7.5.3.1), i.e. ‘(A)’ for the date/time string and RealFormat for
the other variables.
If grid file is set to .TRUE., all coordinate information and data are moved
to a separate grid file (i.e. lines 7–16, 18–37 and the values of the coordinate
arrays).
The next example is a 0-D output file from the test case fredyA.
2
V2.0
2010/06/24;14:07:32
Time series data: fredyA
0
F
T F F
0 1 1
0 0 0 0 0 865
600.0000
2003/01/01;00:00:00,000
2003/01/07;00:00:00,000
2003/01/01;00:00:00,000
0
1
1
8
952 5 2 23 865
time
Time
date/time
0 5 1 60
ekin
Kinetic energy
GJ
0 5 1 60
epot
Available potential energy
GJ
0 5 1 60
theta
Energy ratio
0 5 1 60
enstr
Enstrophy
m^3/s^2
0 5 1 60
a1pt
A1%
10^8 m^2
0 5 1 60
salmin
Minimum salinity
PSU
0 5 1 60
salmax
Maximum salinity
PSU
0 5 1 60
smean
Mean salinity deviation
PSU
2003/01/01;00:00:00,000
0.000000 9.042427 0.000000 0.000000

0.2500000 33.75000 34.85000 -0.3296069E-02
2003/01/01;00:10:00,000
0.2259467E-01 8.989937 0.2513329E-02 0.1228950E-04

0.3700000 33.75000 34.85001 -0.3295073E-02
...
2003/01/07;00:00:00,000
0.6530415 7.097948 0.9200427E-01 0.2413782

3.370000 34.27942 34.85036 -0.3307598E-02
Example 7.15: Contents of the output data file fredyA 2.tsout0A from the
fredyA test case.
• Since the data have no spatial dimension in a 0-D file, the time variable
is the only coordinate.
• Contrary to the general case, 0-D data are not stored indivually but as
a vector of size novars. They are read using
REAL, DIMENSION(novars) :: out0ddat
READ (iunit,’(A)’) ciodatetime

READ (iunit,RealFormat) out0ddat
ekin = out0ddat(1); ...; smean = out0ddat(novars)
• The ivarid attribute is zero for all data variables. This means that the
f90 name, long name and units attributes are non-standard and defined
by the user.
7.6.3.2 unformatted binary files

When the unformatted binary format is selected for a forcing file, the same
metadata and data are written as in the case of an ASCII format. The
differences are the same as described in Section 7.5.3.2 for forcing files.
7.6.3.3 netcdf files

The description of the netCDF format is similar to the one given in Sec-
tion 7.5.3.3 and will not repated here. Two examples are given below. The
first one lists the contents of the file plumeA 1.ellip3N, with harmonic output
from the test case plumeA.
netcdf plumeA 1
dimensions:
xdim = 120 ;
ydim = 40 ;
zdim = 20 ;
tlendim = 23 ;
tdim = UNLIMITED ; // (6 currently)
variables:
float xout(ydim, xdim) ;
xout:ivarid = 957 ;
xout:long name = "X-coordinate" ;
xout:units = "m" ;
float yout(ydim, xdim) ;
yout:ivarid = 962 ;
yout:long name = "Y-coordinate" ;
yout:units = "m" ;
float zout(zdim, ydim, xdim) ;
zout:ivarid = 968 ;
zout:long name = "Z-coordinate" ;
zout:units = "m" ;
float depout(ydim, xdim) ;
depout:ivarid = 951 ;
depout:long name = "Mean water depth" ;
depout:units = "m" ;
char time(tdim, tlendim) ;
time:ivarid = 952 ;
float ellmin3d(tdim, zdim, ydim, xdim) ;
ellmin3d:ivarid = 0 ;
ellmin3d:long name = "M2-Ellipticity" ;
ellmin3d:units = "-" ;
ellmin3d:vector name = "_" ;
:header type = 2 ;
:creation date = "2010/06/23;12:19:42" ;
:filedesc = "Elliptic parameters" ;
:iopt CDF fill = 0 ;
:grid dimension = 3 ;
:grid file = 0 ;
:gridded = 1 ;
:land mask = 0 ;
:time grid = 0 ;
:grid type = 0, 1, 1 ;
:dimensions = 120, 40, 20, 0, 0, 6 ;
:time step = 43200.f ;
:startdate = "2003/01/03;06:00:00,000" ;
:enddate = "2003/01/05;18:00:00,000" ;
:refdate = "2003/01/03;06:00:00,000" ;
:time format = 0 ;
:nocoords = 5 ;
:timeid = 5 ;
:novars = 1 ;
:timerec = 6 ;
data:
xout =
500, 1500, ...
yout =
500, 500, ...
zout =
-19.5, -19.5, ...
depout =
20, 20, ...
time =
"2003/01/03;06:00:00,000",
"2003/01/03;18:00:00,000",
"2003/01/04;06:00:00,000",
"2003/01/04;18:00:00,000",
"2003/01/05;06:00:00,000",
"2003/01/05;18:00:00,000" ;
ellmin3d =
0.03929285, 0.03556633, ...
-0.1459797, -0.1480648, -0.1499712, -0.1511258, -0.1511276, -0.1443668 ;
Example 7.16: Contents of the output data file plumeA 1.ellip3N from the
plumeA test case.
The attributes are similar to the ones listed in the ASCII format. Some are
defined with a different name (e.g. the dimensions attribute which combines
the values of the previous parameters ncout, nrout, nzout, nowetout, nostats,
nstepout into one vector). Other attributes are defined implicitly such as
f90 name, nrank and shape. The timerec giving the current number of (time)
records and cdfversion with the current version of netCDF, do not exist in the
ASCII and unformatted binary formats.
The second example is the same as Example 7.17 now given in CDL
format.
netcdf fredyA 2
dimensions:
tlendim = 23 ;
tdim = UNLIMITED ; // (865 currently)
variables:
char time(tdim, tlendim) ;
time:ivarid = 952 ;
float ekin(tdim) ;
ekin:ivarid = 0 ;
ekin:long name = "Kinetic energy" ;
ekin:units = "GJ" ;
ekin:vector name = "_" ;
float epot(tdim) ;
epot:ivarid = 0 ;
epot:long name = "Available potential energy" ;
epot:units = "GJ" ;
epot:vector name = "_" ;
float theta(tdim) ;
theta:ivarid = 0 ;
theta:long name = "Energy ratio" ;
theta:units = "_" ;
theta:vector name = "_" ;
float enstr(tdim) ;
enstr:ivarid = 0 ;
enstr:long name = "Enstrophy" ;
enstr:units = "m^3/s^2" ;
enstr:vector name = "_" ;
float a1pt(tdim) ;
a1pt:ivarid = 0 ;
a1pt:long name = "A1%" ;
a1pt:units = "10^8_m^2" ;
a1pt:vector name = "_" ;
float salmin(tdim) ;
salmin:ivarid = 0 ;
salmin:long name = "Minimum salinity" ;
salmin:units = "PSU" ;
salmin:vector name = "_" ;
float salmax(tdim) ;
salmax:ivarid = 0 ;
salmax:long name = "Maximum salinity" ;
salmax:units = "PSU" ;
salmax:vector name = "_" ;
float smean(tdim) ;
smean:ivarid = 0 ;
smean:long name = "Mean salinity deviation" ;
smean:units = "PSU" ;
smean:vector name = "_" ;
:header type = 2 ;
:creation date = "2010/06/24;09:55:22" ;
:filedesc = "Time series data: fredyA" ;
:iopt CDF fill = 0 ;
:grid dimension = 0 ;
:grid file = 0 ;
:gridded = 1 ;
:land mask = 0 ;
:time grid = 0 ;
:grid type = 0, 1, 1 ;
:dimensions = 0, 0, 0, 0, 0, 865 ;
:time step = 600.f ;
:startdate = "2003/01/01;00:00:00,000" ;
:enddate = "2003/01/07;00:00:00,000" ;
:refdate = "2003/01/01;00:00:00,000" ;
:time format = 0 ;
:nocoords = 1 ;
:timeid = 1 ;
:novars = 8 ;
:timerec = 865 ;
data:
time =
"2003/01/01;00:00:00,000",
...
"2003/01/07;00:00:00,000" ;
ekin = 0, 0.02259467, 0.08382063, ...
epot = 9.042427, 8.989937, ...
theta = 0, 0.002513329, ...
enstr = 0, 1.22895e-05, ...
a1pt = 0.25, 0.37, ...
salmin = 33.75, 33.75, ...
salmax = 34.85, 34.85001, ...
smean = -0.003296069, -0.003295073, ...
Example 7.17: Contents of fredyA 2.tsout0N output data file from the
fredyA test case in CDL format.
Contrary to the ASCII case, a separate netCDF call has to be made to read
each of the 0-D output data, i.e. the data are not stored in vector form but
as separate records in the netCDF file.
Chapter 8
Model grid and spatial

interpolation
8.1 Model grid arrays

8.1.1 Array shapes
The layout of the model grid and the grid indexing system have been pre-
sented in Section 5.2.1. The shape of a model array defined on the model
grid (further denoted as “model grid arrays”) depends on its nodal location.
If the model code would have been designed for serial (non-parallel) applica-
tions only, the shape of a model grid array could be obtained from Table 5.1.
For example, the shapes of a C-node, U-node or W-node array would be
(nc,nr,nz), (nc,nr,nz) or (nc,nr,nz+1), where it is recalled that nc, nr, nz are
the (computational) grid dimensions in the X-, Y- and Z-direction.
Since the model can be set up either in serial or in parallel mode, two
additional complexities arise:
1. The parallel code is based upon non-shared memory between the pro-
cesses. This means that model grid arrays are only defined locally. The
local array shape then depends on the dimensions of the local process
domains. The local dimensions in the X- and Y-direction are given by
the process-dependent parameters ncloc and nrloc, whereas the vertical
dimension is still given by nz.
2. The solution of the discretised equations on a parallel grid requires

that the domain on which an array is defined, must extend into the
neighbouring domains. This extended area, called the halo area, is
defined by adding extra rows and columns. The maximum size of the
337
338 CHAPTER 8. MODEL GRID AND SPATIAL INTERPOLATION
halo in each of the four directions (West/East/South/North) is given

by the parameter nhalo = 2. The actual size is array-dependent.
Examples of array shapes declarations are illustrated below.
REAL, DIMENSION(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz) :: sal
REAL, DIMENSION(0:ncloc+1,0:nrloc+1) :: zeta
REAL, DIMENSION(0:ncloc,0:nrloc) :: atmpres
REAL, DIMENSION(ncloc,nrloc,nz+1) :: vdifcoefscal
Example 8.1: examples of model grid array bounds.
The first array has a full size halo of two rows and columns in each direction,
the second a halo of one row and column in each direction, the third a one
column halo attached on its western boundary, whereas the last one is defined
without halo.
In Section 5.2.1 it was explained that the last array column at the eastern
boundary and the last row at the northern boundary of the computational
grid consist of dummy land points. Important to note that this is mostly
not the case for local array definitions, i.e. the horizontal grid points with
index (ncloc,j) and i,nrloc are physical points unless one of the edges of the
sub-domain extends into one of these two dummy boundary areas.
Local arrays usually have no global equivalent in the program. However,
in case that a global array has to be defined, then it must be declared, for
consistency, with the same halo sizes as its local equivalent. For example,
the arrays
gxcoord(0:ncloc+1,0:nrloc+1), gxcoordglb(0:nc+1,0:nr+1)
are the local and global representations of the same array.
A more detailed account of parallel grids is presented in Chapter 9.
8.1.2 Parameters and arrays related to the model grid
8.1.2.1 definition of the model grid

The following parameters and arrays are required for the definition of the
model grid:
• number of grid cells in the X-, Y- and vertical direction: parameters
nc, nr, nz
• horizontal coordinates of the model grid at the cell corners (solid circles
in Figure 5.1): arrays gxcoordglb(1:nc,1:nr), gycoordglb(1:nc,1:nr)
8.1. MODEL GRID ARRAYS 339
Table 8.1: Model grid parameters and arrays.

Local Global Local array bounds Purpose
name name
ncloc nc – number of grid cells in the X-
direction
nrloc nr – number of grid cells in the Y-
direction
nz nz – number of grid cells in the Z-
direction
gxcoord gxcoordglb (0:ncloc+1,0:nrloc+1) X-coordinates of the cell corners
(UV-nodes) in meters or degrees
longitude (between -1800 and 1800 )
gycoord gycoordglb (0:ncloc+1,0:nrloc+1) Y-coordinates of the cell corners
(UV-nodes) in meters or degrees lat-
itude (between -900 and 900 )
gscoord gscoordglb (0:ncloc+1,0:nrloc+1, σ-level coordinate at the W-nodes
nz+1) if iopt grid node=1 or UVW-nodes if
iopt grid node=2
• σ-coordinate grid at either the W- or UVW-nodes: array gscoordglb(1:nc-

1,1:nr-1,nz+1) in the former or gscoordglb(1:nc,1:nr,nz+1) in the latter
case
The information needs, in principle, to be supplied by the user. However,
• The 2-D horizontal coordinate arrays need to be provided only in case
of a non-rectangular (curvilinear) grid. In the case of a rectangular
grid, the user has to define:
– the coordinates of the lower left cell corner (i.e. UV-node with
grid indices (1,1)) and the grid spacings in either direction for a
uniform grid
– the X-coordinates of the first row gxcoordglb(1:nc,1) and the Y-
coordinates of the first column gycoordglb(1,1:nr) for a non-uniform
grid
• The 3-D array gscoordglb needs to supplied only in case of a general σ-
grid (non-uniform in the horizontal and vertical). In case of a uniform
σ-grid, the vertical grid is determined by the program whereas for a
non-uniform σ-grid in the vertical (only), a vertical vector of σ-values
needs to be given.
A list of all grid parameters and arrays is given in Table 8.1.

• Local (global) means that the parameter or array is defined on the local
sub-domain (global computational grid). In case of a serial application,
local and global definitions coincide (e.g. ncloc=nc)
• The bounds of the global array are obtained from the local one by
replacing (nc,nr) with (ncloc,nrloc).
8.1.2.2 definition of the open boundaries

The following information has to be given by the user
• the number of open sea (nosbu,nosbv) and river (nrvbu,nrvbv) bounda-
ries at U- and V-nodes
• the location of the open boundaries at U- and V-nodes: arrays iobu(nobu),

jobu(nobu), iobv(nobv), jobv(nobv) where nobu, nobv are the total (open
sea and river) boundaries at U- and V-nodes
The following remarks apply:
• At a U- or V-node open boundary one of the two adjacent cells must
be wet (sea) while the other one must be either a land cell or located
outside the physical domain. This allows to define linear as well as
“ragged” (stair-case) open boundaries.
• Open sea boundaries at U-nodes must be stored in iobu(1:nosbu), jobu(1:nosbu),

river boundaries in iobu(nosbu+1:nosbu+nrvbu), jobu(nosbu+1:nosbu+nrvbu).
A similar procedure is taken at V-nodes.
• Taking account of the previous restriction, the order of storage is ir-

relevant. However, the ordering is of importance for the definition of
the open boundary conditions (see Chapter 14) since it introduces an
indexing system, i.e. ii is (e.g.) the index of the U-open boundary
located at (iobu(ii), jobu(ii)).
Besides U- and V-open boundaries the program also uses internally the con-
cept of X- and Y-open boundaries which are defined as follows:
• A corner node is a X-open boundary if one of the adjacent U-nodes is an
open boundary and the other one a land/coastal or open sea boundary.
• A corner node is a Y-open boundary if one of the adjacent V-nodes is an

open boundary and the other one a land/coastal or open sea boundary.
Table 8.2: Open boundary parameters and arrays.

Local Global Local array bounds Purpose
name name
nosbuloc nosbu – number of West/East open sea boun-
daries at U-nodes
nrvbuloc nrvbu – number of West/East river open boun-
daries at U-nodes
nobuloc nobu – total number of West/East open boun-
daries at U-nodes (nobuloc = nosbu-
loc+nrvbuloc)
nosbvloc nosbv – number of South/North open sea
boundaries at V-nodes
nrvbvloc nrvbv – number of South/North river open
nobvloc nobv – total number of South/North open
boundaries at V-nodes (nobvloc = nos-
bvloc+nrvbvloc)
nobxloc nobx – number of X-open boundaries at cor-
ner nodes
nobyloc noby – number of Y-open boundaries at cor-
ner nodes
iobuloc iobu nobuloc X-indices of the West/East open boun-
daries at U-nodes
jobuloc jobu nobuloc Y-indices of the West/East open boun-
daries at U-nodes
iobvloc iobv nobvloc X-indices of the South/North open
jobvloc jobv nobvloc Y-indices of the South/North open
iobxloc iobx nobxloc X-indices of the open boundaries at X-
nodes
jobxloc jobx nobxloc Y-indices of the open boundaries at X-
nodes
iobyloc ioby nobyloc X-indices of the open boundaries at Y-
nodes
jobyloc joby nobyloc Y-indices of the open boundaries at Y-
nodes
The locations of the X- and Y-open boundaries are defined within the pro-
gram and do not need to be supplied by the user.
A list of all grid parameters and arrays is given in Table 8.2.
• Local (global) means that the parameter or array is defined on the local
sub-domain (global computational grid). In case of a serial application,
local and global definitions coincide (e.g. nosbuloc=nosbu).
• The bounds of the global array are obtained from the local one by
replacing the local dimension by the global one (e.g. nobuloc by nobu).
8.1.2.3 grid spacings

Grid spacings in the horizontal direction are calculated by the standard for-
mulae
q
∆Xijv = hv1;ij = (xi+1,j − xij )2 + (yi+1,j − yij )2
q
∆Yiju = hu2;ij = (xi,j+1 − xij )2 + (yi,j+1 − yij )2 (8.1)
or
s
1
∆Xijv = hv1;ij = R (λi+1,j − λij )2 + cos (φij + φi+1,j )(φi+1,j − φij )2
2
s
1
∆Yiju = hu2;ij = R (λi,j+1 − λij )2 + cos (φij + φi,j+1 )(φi,j+1 − φij )2
2
(8.2)
depending on whether Cartesian or spherical coordinates are used. Similar
expressions are used to evaluate the grid spacings at other nodes. Grid
spacings in the vertical are calculated using h3 = H∆σ where H is the total
water depth and ∆σ the σ-difference between two neighbouring levels.
The following grid spacing arrays are defined:
• grid spacing h1 in meters
delxatc, delxatu, delxatv, delxatuv
• grid spacing h2 in meters
delyatc, delyatu, delyatv, delyatuv
• σ-grid spacing ∆σ = h3 /H
delsatc, delsatu, delsatv, delsatw, delsatuw, delsatvw
The last letter(s) in the variable name denote(s) the grid node where the
array is defined.
8.1.2.4 pointer arrays

Pointer arrays denote the status of a grid node (dry, wet, open boundary).
A specific array is defined for each horizontal nodal type
nodeatc status at C-nodes

0: inactive cell which can either by a permanently land cell or a sea cell
temporarily set to dry by a mask criterium in case a flooding scheme
is applied (see Section 5.4.2)
1: active (wet) sea cell
nodeatu Pointers at U-node cell faces
0: dry (land) cell face
1: coastal boundary
2: interior wet U-node
3: open sea boundary
4: river open boundary
nodeatv Pointers at V-node cell faces
1: coastal boundary
2: interior wet V-node
nodeatuv Pointer at corner (UV) nodes
0: at least two surrrounding U-nodes or at least two surrrounding V-
nodes are dry
1: interior wet node, i.e. at most one surrounding U-node and at most
one surrounding V-node is dry and none of the four surrounding
velocity nodes are open boundaries
2: X-node open boundary, in which case at least one of the surrounding
U-nodes is an open boundary while the other one is either a closed
node or open boundary, but the node is not a Y-node open boundary
3: Y-node open boundary, in which case at least one of the surrounding
V-nodes is an open boundary while the other one is either a closed
node or open boundary, but the node is not an X-node open boundary
4: the node is both a X- and a Y-node open boundary
nodeatuw Pointer at UW-node cell faces
0: dry (land) cell face or bottom cell (1) or surface cell (nz+1)
1: coastal boundary
2: interior wet UW-node
nodeatvw Pointer at VW-node cell faces
0: dry (land) cell face or bottom cell (1) or surface cell (nz+1)
1: coastal boundary
2: interior wet VW-node
• The values of the pointer arrays are obtained from the bathymetry
(zero water depths at land, positive depths at sea) and the positions of
the open boundaries as given by the user.
• In the current implementation the arrays are fixed in time. Dynamic

masks are foreseen in future versions.
• Local bounds in the horizontal are given by (1-nhalo:ncloc+nhalo, 1-

nhalo:nrloc+nhalo).
• All arrays, except nodeatc, have a vertical dimension of nz at U-, V-

or UV-nodes and nz+1 at UW- or VW-nodes. The vertical dimension
has been added for the future implementation of structures.
• The bottom and surface values of nodeatuw, nodeatvw are, by definition,

always equal to 1.
• In the current implementation all arrays must be vertically uniform

(with exception of the previous restriction for UW- and VW-nodes).
8.2. INTERPOLATION OF MODEL ARRAYS AT A DIFFERENT NODE 345
8.2 Interpolation of model arrays at a diffe-

rent node
Since the model uses an Arakawa C-grid, arrays often have to be interpolated
from one grid node to another one. The simplest way is to consider uniform
interpolation between neighbouring points. The following issues need to be
taken into consideration:
• Uniform averaging is no longer applicable (or at least recommended)

in case of a curvilinear grid.
• Model grid arrays are undefined at land points. Land mask can be used
to eliminate these points from the interpolation.
These points will be addressed in the discussion below.
8.2.1 Interpolation without land flags

The general formula for interpolation a quantity X defined at node “a” to
node “b” is PN a
b n=1 wn X (xn , yn , zn )
X (x, y, z) = PN (8.3)
n=1 wn
where wn are grid-dependent weight factors. In case of a uniform interpola-
tion all wn = 1/N so that
N
1 X
Xb = X a (xn , yn , zn ) (8.4)
N n=1
The parameter N depends on the number of grid dimensions involved in the

interpolation:
• N=2: interpolation along a coordinate line (1 direction). In case of non-

uniform interpolation the weights factors have dimensions of lengths.
• N=4: interpolation within a coordinate surface (2 directions). In case of

non-uniform interpolation the weight factors have dimensions of areas.
• N=8: 3-D interpolation (3 directions). In case of non-uniform interpo-

lation the weight factors have dimensions of volumes.
General rules are
• Interpolations within a grid cell are always uniform.

• By default, interpolation involving values at neighbouring cells are uni-

form. This can be overruled with the switch iopt array interp or by call-
ing the interpolation routines with the optional hregular and vregular
argument set to .FALSE.. The second option always takes precedence
over the first.
• The interpolation routines in the program provide an option to exclude
land points or open sea boundaries from the interpolation.
1/2 1/2 wi−1,j wij
U(i,j) C(i,j) U(i+1,j) C(i−1,j) U(i,j) C(i,j)
U to C interpolation C to U interpolation
W(i−1,j,k+1) W(i,j,k+1)
Y Z
C(i−1,j) C(i,j) 1/2 1/2

u
W (i,j,k)
uv
C (i,j)
w i−1,j w ij
1/2 1/2
C(i−1,j−1) C(i,j−1)
W(i−1,j,k) W(i,j,k)
X X
C to UV interpolation W to U interpolation
Figure 8.1: Interpolation of model grid arrays at a different node.
Examples
1. interpolation from U- to C-node:
1
X c (i, j) = (X u (i, j) + X u (i + 1, j)) (8.5)
2
2. (non-uniform) interpolation from C- to U-node:
w(i, j)X c (i − 1, j) + w(i − 1, j)X c (i, j)
X u (i, j) =
w(i − 1, j) + w(i, j)
1 c
w(i, j) = h (i, j) (8.6)
2 1
8.2. INTERPOLATION OF MODEL ARRAYS AT A DIFFERENT NODE 347
3. (non-uniform) interpolation from C- to UV-node:

X uv (i, j) = w(i, j)X c (i − 1, j − 1) + w(i − 1, j)X c (i, j − 1)

+w(i, j − 1)X c (i − 1, j) + w(i − 1, j − 1)X c (i, j)
.
w(i, j) + w(i − 1, j) + w(i, j − 1) + w(i − 1, j − 1)
1 c
w(i, j) = h (i, j)hc2 (i, j) (8.7)
4 1
4. (non-uniform) interpolation from W- to U- node:

1
X u (i, j, k) = w(i, j)X w (i − 1, j, k) +
2
w(i − 1, j)X w (i, j, k) + w(i, j)X w (i − 1, j, k + 1)
.
+w(i − 1, j)X w (i, j, k + 1) w(i, j) + w(i − 1, j)
1 c
w(i, j) = h (i, j) (8.8)
2 1
What type of interpolation needs to be taken ?
• uniform Cartesian grids: uniform (allways)
• uniform spherical: uniform (recommended)
• non-uniform rectangular and curvilinear: user decision (depending on

the variation of grid size between neighbouring cells)
8.2.2 Interpolation with land flags

Land flags can be used to eliminate land areas or temporarily inactive cells
(in case a mask function is applied as decribed in Section 5.4.2) from the
interpolation. The general interpolation formula with land flags becomes
PN
b n=1 sn wn X a (xn , yn , zn )
X (x, y, z) = PN (8.9)
n=1 sn wn
where sn equals 0 for flagged and 1 for non-flagged grid points. The program
foresees the following options
0: No flags (sn =1 everywhere).
1: Land cells and cell faces at or near coastal boundaries (except open sea
boundaries) are flagged.
2: Land cells and cell faces at or near coastal boundaries (including open
boundaries) are flagged.
3: Only cell faces at open sea boundaries are flagged (allowing the inclu-
sion of coastal boundaries in the interpolation).
As an example the formula for array interpolation from C- to UV-nodes

becomes

X uv (i, j) = s(i − 1, j − 1)w(i, j)X c (i − 1, j − 1)
+s(i, j − 1)w(i − 1, j)X c (i, j − 1)
+s(i − 1, j)w(i, j − 1)X c (i − 1, j)
.
+s(i, j)w(i − 1, j − 1)X c (i, j)

s(i − 1, j − 1)w(i, j) + s(i, j − 1)w(i − 1, j)

+s(i − 1, j)w(i, j − 1) + s(i, j)w(i − 1, j − 1)
1 c
w(i, j) = h (i, j)hc2 (i, j) (8.10)
4 1
Note that the flags can be applied at the source node “a” (as given in the
equation above) as well as at the destination node “b”.
8.3 Curvilinear, index and relative coordina-

tes
Before proceeding to discuss the interpolation towards or from an exter-
nal data grid, some more detailed discussion is required how the model’s
curvilinear coordinates are related to the grix index system introduced in
Section 5.2.1.
Consider the grid layout as shown in Figure 8.2. The index (i,j) of a
UV-nodal grid point can be interpreted as the curvilinear coordinates (ξ1 ,
ξ2 ) with respect to axes in the X- and Y-direction and origin at corner index
(0,0). Within the same frame of reference, the corresponding curvilinear
coordinates of the C-point with index (i,j) are (i+1/2,j+1/2). For U- and
V-nodal points this becomes (i,j+1/2) and (i+1/2,j).
Instead of taking the origin at the corner point with index (0,0), the origin
can be moved to the C-point with index (0,0). In that case, the curvilinear
coordinates of a corner point at (i,j) are (i-1/2,j-1/2), while the curvilinear
coordinates of a C-grid point are the same as its indices. For U- and V-nodal
points this becomes (i-1/2,j) and (i,j-1/2). Similarly, if the origin is taken at
8.4. INTERPOLATION OF A 2-D EXTERNAL DATA GRID AT THE MODEL GRID 349
ξ2
(i,j)
(1,1)
(0,0) ξ1
Figure 8.2: Curvilinear versus index coordinates.
the U-node index point (0,0), the curvilinear coordinates of a C-point, U-

point, V-point and corner point are respectively (i+1/2,j), (i,j), (i+1/2,j-1/2)
and (i,j-1/2). Finally, taking the origin at the point with V-node index (0,0),
the curvilinear coordinates becomes (i,j+1/2) for a C-node, (i-1/2,j+1/2) for
a U-node,(i,j) for a V-node and (i-1/2,j) for a corner point.
Relative coordinates are a convenient way to perform interpolation from
one to an other. Let (ξ1 ,ξ2 ) be the (normalised) curvilinear coordinates of an
arbitrary point, the corresponding relative coordinates are then (i,j,x,y) where
(i,j) are the integer and (x,y) the decimal parts of (ξ1 ,ξ2 ). From the previous
discussion, the integer coordinates are taken with respect to a certain node
(C, U, V, UV). For example, if a corner index system is taken, the relative
coordinates of a C-point with index (i,j) with respect to this corner grid are
(i,j,1/2,1/2).
8.4 Interpolation of a 2-D external data grid

at the model grid
8.4.1 General description of the procedure
Assume that the model grid is embedded within an external 2-D data grid
as shown in Figure 8.3. The relative coordinates of the C-grid point X with
respect to the data grid at its cell corners are (i,j,x,y) where (x,y) are expressed
as normalised coordinates (i.e. between 0 and 1). The interpolated value of
data ‘d’ at X is given by
d(X) = (1 − x)(1 − y)d(i, j) + x(1 − y)d(i + 1, j)

+(1 − x)yd(i, j + 1) + xyd(i + 1, j + 1) (8.11)
(i,j+1) (i+1,j+1)
(i,j) (i+1,j)
x
Figure 8.3: Interpolation of external data to the model grid. The solid
(dashed) lines represent the external (model) grid.
where i, j are the indices defined on the data grid.
The following remarks apply
• The model points are principally taken at C-nodes, although the method
can be applied to other nodes as well.
• If the external grid is rectangular (uniform or non-uniform), the rel-

ative coordinates can be calculated by the program. No algorithm is
currently implemented for the determination of the relative coordinates
in case of a curvilinear or unstructured data grid.
• The weight factors in (8.11) only depend on the locations of the external
grid and do not take account of possible land points, which should be
excluded from the interpolation. The following options are available:
1. All land points are taken into account.

2. Interpolation is only performed if at least one of the surrounding
four points is located at sea.
3. Interpolation is only performed if all the four surrounding points
are at sea.
If the data grid represents meteorological data, no disctinction is made

between land and sea points.
8.4. INTERPOLATION OF A 2-D EXTERNAL DATA GRID AT THE MODEL GRID 351
8.4.2 Implementation
The method can currently be applied for interpolation of surface meteoro-
logical data or (satellite) surface temperature data. Future extensions are
planned for surface wave data.
As a first step the type of the 2-D external data grid is defined via the
following derived type definition:
TYPE :: GridParams
END TYPE GridParams
where
nhtype Type of the surface data grid.
0: single grid point
1: uniform rectangular grid
2: non-uniform rectangular grid
3: non-rectangular (curvilinear or non-structured) grid
4: the same as the model grid
n1dat number of grid cells in the X-direction
n2dat number of grid cells in the Y-direction
delxdat grid spacings in the X-direction (m or fractional degrees longitude)
when nhtype=1
delydat grid spacings in the Y-direction (m or fractional degrees latitude)
when nhtype=1
x0dat X-coordinate (Cartesian or longitude) of the lower left corner when
nhtype=1
y0dat Y-coordinate (Cartesian or latitude) of the lower left corner when
nhtype=1
Note that nhtype has to be supplied always if the value is different from its
default one (0). The n1dat, n2dat attributes have to be given if nhtype> 0.
All surface grid attributes are stored into the array surfacegrids
TYPE (GridParams), DIMENSION(MaxGridTypes,2) :: surfacegrids
where MaxGridTypes is the maximum number of external grids. A key id of
the form igrd * is used as index for the first dimension. The following values
are currently implemented
• igrd meteo: surface meteorological grid

• igrd sst: sea surface temperature (SST) grid
• igrd model: model grid
The last id seems to imply that the model grid itself is considered as an
external data grid which is obviously not the case. It has only been imple-
mented as an utility in case the user wants to define a rectangular uniform
model grid (see Section 12.6.1).
The second index can currently only take the value of 1 which means
interpolation to the model grid. The value 2 is intended for interpolation of
model data to the data grid which is currently not implemented.
The next step consists in determining the relative coordinates of all model
grid points located at sea. Use is made of the derived type definition
For example, in case of surface meteorological data, all relative coordinates
are stored in the array
TYPE (HRelativeCoords), DIMENSION(ncloc,nrloc) :: meteogrid
The relative coordinates itself can be determined by one of the following
procedures depending on the value of the nhtype attribute
0 : The external grid reduces to one data point. No interpolation is re-
quired.
1 : The external data grid is rectangular and uniform. The relative coordi-
nates are determined by the program.
2 : The external data grid is rectangular and non-uniform. The geographi-
cal (Cartesian or spherical) coordinates of the data grid are supplied by
the user. The relative coordinates are calculated by the program.
3 : The external data grid is curvilinear or unstructured. No algorithm is
provided by the program. The relative coordinates have to be supplied
by the user.
4 : The data grid coincides with the model grid. No interpolation is re-
quired.
The user procedure for defining the input of 2-D external forcing data, is
then the following:
8.5. INTERPOLATION OF MODEL DATA AT EXTERNAL LOCATIONS 353
1. The following parameters are defined by the user in usrdef mod params:
• Set the appropriate switch which is iopt meteo for meteo input or
iopt temp sbc for SST input.
• Define the attributes of the external grid(s) in surfacegrids.
• The attributes of the following files have or may be defined:
modfiles(io metgrd,1,1): grid locations of the meteorological grid
in case nhtype>1
modfiles(io sstgrd,1,1) : grid locations of the SST grid in case nhtype>1
modfiles(io metsur,1,1) : meteorological data file
modfiles(io sstsur,1,1) : SST data file
2. If nhtype>0, define the locations of the external grid. Two options are
available depending on the value of nhtype:
• The grid locations are obtained in absolute (geograhical) coor-

dinates by calling the user defined routines usrdef surface absgrd.
The program converts the absolute coordinates into relative ones.
• The grid locations are obtained in relative coordinates by calling
the user defined routines usrdef surface relgrd.
3. Define data input by calling the user-defined routines usrdef surface data.
Note that a usrdef * routine is not called if the corresponding status attribute
of the associated file is set to ‘R’ in which case a corrsponding read * routine
is called where the data are read from a file in standard COHERENS format.
Detailed descriptions of the procedures are given in Chapter 12 and Sec-
tion 15.2.
8.5 Interpolation of model data at external

locations
8.5.1 General description of the procedure
The procedure is similar to the one discussed in the previous section, except
that the roles of the external grid and model grid are interchanged. This
type of interpolation is currently only implemented for nesting procedures,
but may be used in future versions for the development of one- or two-way
coupling with meteorological and surface wave models.
Advantage now is that the external data points no longer need to be

located on some external (structured or unstructured ) “data” grid. The
only information needed by the program is the location, i.e. the relative
coordinates, of the external locations with respect to the model grid.
However, there are additional complexities which need to be taken into

account:
• Since the model uses a staggered C-grid, currents and scalar quantities
are calculated at different locations (nodes). This means that the rela-
tive coordinates need to be defined in general with respect to different
curvilinear coordinate origins (C(0,0),U(0,0),V(0,0)), whereby the type
of origin depends on the type of variable to be interpolated (C(0,0) for
C-node quantities and U(0,0), V(0,0) for vector quantitities).
• Model data located on land should be eliminated from the interpola-
tion.
• Interpolation of 3-D quantities requires that the relative coordinates
must contain a vertical dimension as well.
• The program allows to define multiple nested sub-grids within the same
main grid.
A horizontal layout of the main and sub-grid with the positions of all
points used in the interpolation on the two grids is displayed in Figure 8.4.
Interpolation can be performed on the 2-D variables U , V , ζ and the 3-D
variables δu, δv, T , S. The number and type of data depends on the type
of open boundary conditions used by the sub-grid and the dimensions (2-D
or 3-D) of the two grids. The only restriction, imposed by the program, is
that, although the model permits to use elevation data either at external
C-nodes (the solid circles in Figure 8.4 or at the velocity nodes on the open
boundaries itself (shown by the horizontal and vertical thick line segments
in the figure), only the latter form is allowed when the open boundary data
are derived from interpolation. The following five kinds of interpolation then
have to be considered in general.
1. Interpolation of U-node model values on the main grid to U-node open
boundary points on the sub-grid (U-to-U interpolation applied for U
and δu)
2. Interpolation of V-node model values on the main grid to V-node open
boundary points on the sub-grid (V-to-V interpolation applied for V
and δv)
main grid
subgrid
C−node main grid
U−node main grid
V−node main grid
C−node subgrid
U−node subgrid
V−node subgrid
Figure 8.4: Illustration of the nesting procedure in the horizontal plane. Solid
lines mark the main (coarser) grid, dashed lines the (finer) sub-grids. The
empty circles and (light colour) line segments mark the points on the main
grid used in the interpolation, the filled circles and (thick) line segments the
points on the sub-grid to which interpolation needs to be performed.
3. Interpolation of C-node model values on the main grid to U-node open

boundary points on the sub-grid (C-to-U interpolation applied for ζ
only )
4. Interpolation of C-node model values on the main grid to V-node open

boundary points on the sub-grid (C-to-V interpolation applied for ζ
only)
5. Interpolation of C-node model values on the main grid to C-node open

boundary points (C-to-C interpolation applied for T and S).
For each type of interpolation relative coordinates have to be defined with

different nodal type and origin.
In case of a 3-D quantity (δu, δv, T , S), the C-to-C, U-to-U and V-to-V
interpolation must extend to the vertical direction as well. this is achieved
by adding the vertical relative coordinates k, z to the four horizontal ones (i,
j, x, y) where k is the vertical index level of the W-, UW- or VW-node point
just below the data point at the which interpolation has to be performed
and z is (here) the normalised vertical distance (between 0 and 1) to the W-,
UW-, VW-node level. The definition is illustrated in Figure 8.5.
nz+1 surface
vertical relative coordinates
k: vertical cell index

z : normalised distance to cell bottom
Z
z
k
1 bottom
Figure 8.5: Definition of vertical relative coordinates.
The following remarks are to be given
• Interpolation does not take account of variations in water depth, i.e.

the vertical position at which interpolation is to performed, is assumed
to be independent in time.
• Vertical interpolation is performed prior to horizontal interpolation.

This means that the model data at the four surrounding main grid
points are firstly interpolated vertically at the same level as the des-
tination point. If a depth point is below or above the z-level of the
lowest or highest grid level, the interpolated value is set to the model
value at the lowest or highest level. The profile at the sub-grid location
is next obtained by horizontal interpolation of the four profiles using
(8.11).
The program provides the following derive type definition for storing vertical
relative coordinates
TYPE :: VRelativeCoords
INTEGER :: kcoord
REAL :: zcoord
END TYPE VRelativeCoords
Details of the code implementation are more complex than the ones in Sec-
tion 8.4.2. To simplify the discussion below, it is assumed that the program
is set up in serial mode.
1. The following parameters are defined by the user in usrdef mod params:
• The program switch iopt nests is set to 1.
• The parameter nonestsets is set to the number of nested sub-grids.
• The attributes of the following files have or may be defined:
modfiles(io nstspc,1,1) parameters to be defined in usrdef nstgrd spec
modfiles(io nstgrd,1:nonestsets,1) locations of the sub-grid open boun-
dary points in absolute or relative coordi-
nates for each sub-grid
modfiles(io 2uvnst,1:nonestsets,2) output data files with interpo-
lated values of U , V , ζ for each sub-grid
modfiles(io 3uvnst,1:nonestsets,2) output data files with interpo-
lated values of δu, δv
modfiles(io salnst,1:nonestsets,2) output data files with interpolated
values of S
modfiles(io tmpnst,1:nonestsets,2) output data files with interpo-
lated values of T
Note that output will be written only when the status attribute of
the respective output data file is set to ’W’.
2. The following arrays are defined in usrdef nstgrd spec
INTEGER, DIMENSION(nonestsets) :: nohnstglbc, nohnstglbu, &

& nohnstglbv, novnst
The first three arrays represent, for each sub-grid, the number of sub-
grid open boundary points at C-, U- and V-nodes. The last gives the
number of vertical levels for each sub-grid.
3. The locations of the open boundary locations are determined for each
sub-grid. The relative coordinates for each type of interpolation are
stored in the following derived type arrays
TYPE (HRelativeCoords), DIMENSION(numhnstc) :: hnstctoc

TYPE (HRelativeCoords), DIMENSION(numhnstu) :: hnstutou, hnstctou
TYPE (HRelativeCoords), DIMENSION(numhnstv) :: hnstvtov, hnstctov
TYPE (VRelativeCoords), DIMENSION(2,2,numhnstc,numvnst) :: vnstctoc
TYPE (VRelativeCoords), DIMENSION(2,2,numhnstu,numvnst) :: vnstutou
TYPE (VRelativeCoords), DIMENSION(2,2,numhnstv,numvnst) :: vnstvtov
where
numhnstc = SUM(nohnstglbc); numhnstu = SUM(nohnstglbu)

numhnstv = SUM(nohnstglbv); numvnst = MAXVAL(novnst)
These locations are to be defined in the user. Two options are available:
• The user supplies, within usrdef nstgrd abs, the horizontal posi-
tions in absolute (geographical) and the vertical positions, taken
as the positive distance from the mean sea level. The relative
coordinate arrays hnstctoc, . . . , vnstvtov are determined by the
program.
• The user supplies, within usrdef nstgrd rel, the horizontal positions
in relative coordinates and the vertical positions, taken as the po-
sitive distance from the mean sea level. The horizontal coordinates
are stored in hnstctoc, hnstctou, hnstctov, hnstutou, hnstvtov, the
vertical relative coordinates are calculated by the program and
stored in vnstctoc, vnstutou, vnstvtov.
4. The following “index mapping” arrays are defined by the program
INTEGER, DIMENSION(noprocs,numhnstc,nonestsets) :: indexnstc

INTEGER, DIMENSION(noprocs,numhnstu+numhnstv,nonestsets) :: indexnstuv
where
noprocs number of processes (1 in serial mode)

indexnstc projects the local index of a C-node data point onto a “global”
index over all sub-domains
indexnstuv projects the local index of a U-node or V-node data point

onto a “global” index over all sub-domains
5. Model data are interpolated and written to the appropriate output file.
Time resolution is determined by the tlims file attribute.
Note that a usrdef * routine is not called if the corresponding status attribute
of the associated file is set to ‘R’ in which case a corrsponding read * routine
is called where the data are read from a file in standard COHERENS format.
Detailed descriptions of the procedures are given in Chapter 12 and Sec-
tion 15.3.
Chapter 9
Aspects of parallellisation
9.1 Basic principles

9.1.1 Implementation of MPI
With the implementation of MPI the work load is divided among a given
number Np of processes. MPI uses non-shared memory, i.e. each process
does not share its own memory with the other processes. The global domain
is divided in Np horizontal sub-domains (no decomposition in the vertical).
To solve the discretised equations in the horizontal, communications need
to be set up between neighbouring domains. Communications are handled
by the routines of the MPI (Message Passing Interface) library (MPI, 1995).
Current implementation is Version 1.1.
Advantages are:
• The program runs faster.
• Internal memory is reduced when increasing Np .
• Land areas can be removed from the global domain by taking a suffi-
ciently large number of processes.
Disadvantages are:
• Increasing Np decreases the work load per process but increases the
number of communications and % of time spent in communications. A
maximum effficiency will be attained when Np = Nmax depending on
the application. The effect is illustrated in Figure 9.1.
361
362 CHAPTER 9. ASPECTS OF PARALLELLISATION
14
12
10
serial/parallel CPU time
8 OPTOS-CSM
OPTOS-NOS
OPTOS-BCZ
0
0 5 10 15 20
Number of processes
Figure 9.1: CPU efficiency, defined as the CPU time for a serial run di-
vided by the one obtained for the parallel run, as function of the number of
processes for the three optos test cases.
• Parallellisation is less efficient for 2-D (horizontally averaged) simu-

lations and the mode-splitting scheme (vertical profiles reduce to one
point, small time steps).
• Parallel code produces a slight overhead for serial applications.
MPI routine calls are only found in the file comms MPI.F90 1 . Each
MPI routine call (starting with MPI ) has a corresponding alias (starting
with comms ). This allows a more efficient implementation of future MPI
versions.
1
Sole exception is the MPI abort call in error routines.F90. Since MPI is based upon
FORTRAN 77, MPI parameters are declared and defined in an “include” file instead of a
module file. Instead of a USE a INCLUDE mpif.h statement has to be made inside the
code, contrary to the programming rules stated in Section 6.1.1. This will be removed in
future MPI implementations.
9.2. DOMAIN DECOMPOSITION 363
9.1.2 Principles of the parallel code

Variables (parameters and arrays) on a parallel grid can either be:
global defined on each sub-domain with the same value
local either defined on each sub-domain but with different values or defined
on one or more (but not all) sub-domains
A specific aspect of parallellisation is that different effects are or may be
procuced by the model code on different domains:
• A variable may be defined on one and non-defined on another domain.
• Arrays can be either allocated, deallocated or undefined on different

domains.
• Local arrays usually have different shapes (or may be of size 0) on

different domains.
• An IF statements may evaluate as .TRUE. on one or .FALSE. on an-

other sub-domain if the expression contains local variables.
The basic rule for an efficient parallel code is that the work load is (as
much as possible) equally spread among the processes. An important (but
unevitable) exception is that output operations (except for log and error
files) are restricted to one process, called the “master” process. On the other
hand, all processes are allowed to read from the same file, avoiding to copy
the input data from one particular “reader” process.
9.2 Domain decomposition

9.2.1 Definition
Process domains are arranged as a 2-D “parallel” grid with dimensions nprocsx
and nprocsy. Domains, solely composed of land points, can be excluded from
the grid so that nprocsx×nprocsy≥nprocs where nprocs is the number of “ef-
fective” processes. Each domain has a process id number, between 0 and
nprocs-1, which is assigned by MPI, and two domain grid indices (i,j) where
1≤i≤nprocsx and 1≤j≤nprocsy. Dummy (land) domains are defined with a
NULL process id (MPI proc null). Work load is as much as evenly partitioned
between the sub-domains (since the sub-domains are not of the same size).
Exception is the master process which is the only one with write access.
Reading is performed by all processes (except defined otherwise by the user).
4x3 domain layout with 12 processes
8, (3,1) 9, (3,2) 10, (3,3) 11, (3,4)

5x1 domain layout with 5 processes
4, (2,1) 5, (2,2) 6, (2,3) 7, (2,4) 0, (1,1) 1, (1,2) 2, (1,3) 3, (1,4) 4, (1,5)
0, (1,1) 1, (1,2) 2, (1,3) 3, (1,4)
not allowed !
Figure 9.2: Examples of allowed and non-allowed domain decompositions.

The first number is the process id, the two numbers in parentheses denote
the domain indices.
Some examples of simple domain decompositions are illustrated in Fi-

gure 9.2. Figure 9.3 shows an example of a decomposition where part of the
land areas have been removed.
9.2.2 Local grid indexing system

The grid indexing system for a local sub-domain, shown in Figure 9.4, is
practically the same as the one taken on the global grid (see Figure 5.1).
Main differences are:
• The local grid dimensions are now ncloc and nrloc, instead of nc and
nr.
• The most eastern column and most northern row are no longer com-
posed of dummy land points (except when they are located at the edges
of the global computational domain).
The local grid dimensions and indices are related to the global ones
through the following definitions:
9.2. DOMAIN DECOMPOSITION 365
Figure 9.3: Domain decomposition for the North Sea area with 128 processes
based on a 10×19 domain grid.
ncloc X-dimension of the local domain (local variant of nc)

nrloc Y-dimension of the local domain (local variant of nr)
nc1loc global X-index of the leftmost column (local)
nc2loc global X-index of the rightmost column (local)
nr1loc global Y-index of the lowest row (local)
nr2loc global Y-index of the highest row (local)
nc1procs(nprocs) array with the values of nc1loc for each domain (global)
nc2procs(nprocs) array with the values of nc2loc for each domain (global)
nr1procs(nprocs) array with the values of nr1loc for each domain (global)
nr2procs(nprocs) array with the values of nr2loc for each domain (global)
Global and local indices (at any node) are then related by
iglb = iloc + nc1loc - 1
jglb = jloc + nr1loc - 1
ξ2
nrloc
1
0 1
0 1
0 1
0 1
0 11
00 00
11 00
11 11
00 00
11
0
1 0
1 0
1 0
1 0
1
0 11
00
00 00
11
00 11
00
11 11
00
00 00
11
0
1 0
1 0
1 0
1 1 11 11 00 11 00
11
1
0 1
0 1
0 1
0 1
0
0 00
11
00 11
00
11 00
11
00 11
00
11 11
00
0
1 0
1 0
1 0
1 1 11 00 11 00 00
11
1
0 1
0 1
0 1
0 1
0
0 00
11
00 11
00
11 00
11
00 11
00
11 11
00
0
1 0
1 0
1 0
1 1 11 00 11 00 00
11
1
0 1
0 1
0 1
0 1
0
0 00
11
00 11
00
11 00
11
00 11
00
11 11
00
0
1 0
1 0
1 0
1 1 11 00 11 00 00
11
1
0 1
0 1
0 1
0 1
0
0 00
11
00 11
00
11 00
11
00 11
00
11 11
00
0
1 0
1 0
1 0
1 1 11 00 11 00 00
11
3
1
0 1
0 1
0 1
0 1
0
0 00
11
00 11
00
11 00
11
00 11
00
11 11
00
0
1 0
1 0
1 0
1 1 11 00 11 00 00
11
2
1
0 1
0 1
0 1
0 1
0
0 00
11
00 11
00
11 00
11
00 11
00
11 11
00
0
1 0
1 0
1 0
1 1 11 00 11 00 00
11
1
1
0 1
0 1
0 1
0 1
0
0 00
11
00 11
00
11 00
11
00 11
00
11 11
00
0
1 0
1 0
1 0
1 1 11 00 11 00 00
11
1 2 3 ncloc
ξ1
Figure 9.4: Horizontal layout of the computational grid on a local sub-

domain. Different nodes are indicated by the same symbols as in Figure 5.1.
Domain decomposition is uniquely defined by these last 4 “process” ar-

rays. Two options are available, depending on the value of the switch
iopt MPI partit:
1 Simple decomposition: the user specifies the values of two of the three
parameters nprocs, nprocsx, nprocsy. The arrays are defined internally
(see Section 12.3 for further details).
2 The arrays are defined externally by the user.

Other (global or local) parameters used in the model for parallel applica-
tion are:
parallel set user-defined parameter to switch on/off the parallel mode
(global)
idloc local process id (local)
iprocloc local process number = idloc+1 (local)
idmaster Process id of the master process (global). Its value can be
changed by the user. Default is 0.
idprocs(nprocs) vector of local process ids (global)
master .TRUE. if idloc equals idmaster, .FALSE. otherwise (local)
shared read user-defined parameter enabling reading by all processes if
.TRUE. (global)
9.3. HALOS 367
comm work MPI communicator composed of all “working” processes

(global)
iddomain(0:nprocsx+1,0:nprocsy+1) process id as function of domain grid in-
dices (global)
9.3 Halos
Numerical discretisations in the horizontal and horizontal averaging may re-
quire the availability of values of a model grid array located at grid points
within a neighbouring sub-domain. These values are calculated, not inside
the domain itself, but within its neighbours. They are obtained by estab-
lishing MPI communications between the domain and its neighbours. Each
of its neighbours sends an internal section of the array which is received and
stored by the domain in one of the local array’s halo sections (see Figure 9.5
and Figure 9.6).
Figure 9.5: Illustration of an halo for an array defined on a local sub-domain.

The halo of the sub-domain, located in the inner rectangle, is situated be-
tween the inner and outer rectangles.
A halo is created by adding extra columns and rows to the model array.
Most arrays have halo sizes which are all equal to the parameter nhalo = 2,
e.g.
uvel(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz)
Other arrays may have smaller halos or asymmetric halos, e.g.
(i−1,j+1) (i,j+1) (i+1,j+1)

NW N NE
(i−1,j) (i,j) (i+1,j)

W E
(i−1,j−1) (i,j−1) (i+1,j−1)

SW S SE
Figure 9.6: Partitioning of a sub-domain halo. Domain indices are given in

parentheses.
gxcoord(0:ncloc+1,0:nrloc+1), atmpres(0:ncloc,0:nrloc)
The West/East/South/North sizes are usually given by a 4-element vec-

tor. The halo sizes of the 3 arrays above are respectively
(nhalo,nhalo,nhalo,nhalo), (1,1,1,1), (1,0,1,0)
Halo sizes of a model array are the same on all sub-domains. The cor-
responding global arrays (i.e. defined over the whole domain) are declared
with the same halo sizes as their local counterparts. Halos of sub-domains
which are located at the edge of the (full) computational domain, extend to
the outside of the computational domain. These outside points are taken as
dummy land points belonging to a dummy outside sub-domain with NULL
process id.
9.4 Communications
9.4.1 Send and receive in MPI
A MPI communication consist of a send operation on one process (say A)
and a receive operation on another process (say B). COHERENS uses only
so-called “blocking” send and receive operations. The implementation in
COHERENS is based upon the following communication modes:
9.4. COMMUNICATIONS 369
1. Synchronous send.
• A sends a message with the data to B.

• B receives the message and the data, sends a message back to A
and completes next.
• A receives the message from B and completes.
This is the most robust mode.
2. Bufffered send.
• A sends a message to B, sends the data to a buffer, and completes

next.
• B receives the message, retrieves the data from the buffer and
completes next.
This mode is useful for transfering a large amount of data.
3. Standard send.
• The operation is performed either synchronously or in buffered

mode. The choice is made internally by MPI .
• Less robust than synchronous mode but usually more efficient.
Only the standard and synchronous mode are implemented in COHERENS.
1. Syntax of a standard send
SUBROUTINE MPI send(buf,count,datatype,dest,tag,comm,ierror)
<type>, INTENT(IN), DIMENSION(*) :: buf initial address of the send

buffer
INTEGER, INTENT(IN) :: count number of elements in the send buffer
INTEGER, INTENT(IN) :: datatype type of data in the send buffer (e.g.
MPI REAL for real data)
INTEGER, INTENT(IN) :: dest rank (process id) of the destination
process
INTEGER, INTENT(IN) :: tag message tag
INTEGER, INTENT(IN) :: comm communicator (usually comm work)
INTEGER, INTENT(OUT) :: ierror returned error code.
2. Syntax of a synchronous send
SUBROUTINE MPI ssend(buf,count,datatype,dest,tag,comm,ierror)
where the arguments have the same meaning as before.
3. Syntax of a receive operation
SUBROUTINE MPI recv(buf,count,datatype,source,tag,comm,&

& status,ierror)
<type>, INTENT(OUT), DIMENSION(*) :: buf initial address of the re-

ceive buffer
INTEGER, INTENT(IN) :: count number of elements in the receive
buffer
INTEGER, INTENT(IN) :: datatype type of the data in the receive buffer
(.e.g. MPI INT for integer data)
INTEGER, INTENT(IN) :: source rank (process id) of the source pro-
cess
INTEGER, INTENT(IN) :: tag message tag
INTEGER, INTENT(IN) :: comm communicator (usually comm work)
INTEGER, INTENT(OUT), STATUS(MPI STATUS SIZE) :: status return
status
INTEGER, INTENT(OUT) :: ierror returned error code.
In the COHERENS code, send and receive operations are performed using the
comms send * and comms recv * routines defined in comms MPI.F90.
9.4.2 Sort of communications

The following sort of communications are used in the program: copy, dis-
tribute, combine, combine all, exchange, collect.
1. Copy operations.
• Copies (the same) data from a root (usually the master) process
to all other processes.
• The operation involves Np −1 sends from the root and 1 receive at
each other process.
• This is called a “one-to-all” operation and therefore asymmetric.
• Used to copy data read by the root process from a data file (not
needed if shared read = .TRUE.).
2. Distribute operations.
• Copies (i.e. distributes) the local parts of a global model array

from the root process to all other sub-domains. Each local section
may or may not contain the array’s local halo parts.
• The operation involves Np −1 sends from the root and 1 receive at
each other process.
• This is called a “one-to-all” operation and therefore asymmetric.
• Used to set up initial conditions on each local domain or to dis-
tribute surface data in case the surface data grid coincides with
the model grid. Distribute operations are redundant if shared read
= .TRUE..
3. Combine operations.
• Copies (i.e. combines) a local array from each sub-domain to a

corresponding section of a global array on the root process. Halos
are not included.
• The operation involves Np −1 receives at the root and 1 send from
each other process.
• This is called a “all-to-one” operation and therefore asymmetric.
• Various versions are implemented:
- Combination of local “full” model arrays into a global “full”
array.
- Combination of local subsections of model arrays into a global
array.
- Combination of local irregular (station) data into a global
array.
- Combination of local open boundary arrays into a global boun-
dary array.
• Used for the construction of global arrays, obtained from local
model arrays, local regular or irregular sub-arrays. The global
arrays are mostly intended for output, the calculation of global
array sums, array maxima and minima.
4. Combine-all operations.
• The same as the combine operation except that the global data
are made available to all processes.
• The operation involves Np −1 sends and Np −1 receives on each
process.
• This is called a “all-to-all” operation and therefore symmetric.
Note that work load is (about) the same for each sub-domain so
that the CPU time for a combine-all is about the same as for a
corresponding combine operation.
5. Exchange operations.
• Send sub-sections of local model arrays to a corresponding section

within the halo of each neighbouring domain. Receives data from
each neighbouring domain and stores these data in one of its own
halo sections.
• Since each sub-domain has 8 neighbours (including dummy do-
mains outside the computational domain), the operation requires
in general 8 sends and 8 receives on each sub-domain. However,
this number can be reduced by specifying the halo sections for
which an exchange is needed or when component(s) of the halo
size vector is (are) zero.
• The operation is symmetric.
• Exchange operations are an essential part of the parallel code and
are mainly for implementation of numerical algorithms for hori-
zontal advection and diffusion, and for horizontal averaging.
6. Collect operations.
• Stores all local arrays into one global array with an extra dimen-
sion of size nprocs.
• The operation involves Np −1 sends and Np −1 receives on each
domain.
• This is a “all-to-all” operation and therefore symmetric.
• The operation is not frequently used.
Remarks:
• The root process is by default the master process.
• The communication routines are programmed using the MPI send and
MPI recv routines either in standard or synchronous mode.
• There are options to use MPI collective calls instead for some opera-
tions: MPI bcast for copy and MPI allgather for collect operations.
• For exchange operations there is an alternative option to use the

MPI sendrecv utility routine which combine a send and a receive oper-
ation into one call.
The main difficulty in programming MPI communications is to prevent so-
called dead locks, i.e. a send/receive operation cannot terminate because one
of the processes is engaged in another communication which cannot terminate
as well and so on. The problem does not arise for the asymmetric “one-to-all”
and “all-to-one” operations since each process is engaged in either a send or
a receive operation but not both. The problem is more severe for “all-to-all”
and exchange operations. Implementation of these two type of operations is
discussed below.
9.4.3.1 all-to-all operations

Firstly, an order of operations is defined for each process via a 2Np × Np
array. The elements are either -1, 0, 1, 2. Taking the example of Np =4, the
array is defined as follows (with easy extension for a general value of Np ):
 
0 2 2 2

 1 0 2 2 

1 1 0 2
 
 
 

 1 1 1 0 

−1 1 1 1
 
 
 

 2 −1 1 1 

2 2 −1 1
 
 
2 2 2 −1
where each column (except the first) is obtained by shifting the previous one
donwwards by 1 position. The first column represents the type and order of
the communications performed by process 0, the second by process 1 and so
on. The numbers present the kind of the operations to be performed:
-1: Dummy operation. Nothing is done.
0: The process “communicates” with itself, the local data are stored di-
rectly into the global array.
1: Send operation.
2: Receive operation.
Secondly, the source or destination of each communication needs to be

defined. The process ids are taken from the following vector (of size 2Np ):
(0, 1, 2, 3, 0, 1, 2, 3)T . Replacing the one and twos in the previous array by
respectively S and R, and inserting the process ids into each column of the
previous array, all communications can be symbolically presented by the
matrix  
0 R0 R0 R0
 S1 0 R1 R1 


 S2 S2 0 R2
 

 
 S3 S3 S3 0 
 
 −1 S0 S0 S0 
 
 
 R1 −1 S1 S1 
 
 R2 R2 −1 S2 
 
R3 R3 R3 −1
where the first column aplies to process 0, the second column to process 1
and so on. The numbers 0 and -1 have the same meaning as before, Si means
send to process i and Ri receive from process i. For example, process 2 (third
column) performs the following operations : receive from process 0, receive
from 1, internal storage, send to 3, send to 0, send to 1, nothing, receive
from 3. It can easily be shown that the order of communications, defined
in this way, can never produce a dead lock, since for each send/receive the
destination/source process will always be available to receive/send the data.
9.4.3.2 exchange operations

Consider as example a 4×4 decomposition which is arranged in a chessboard
pattern as shown in Figure 9.7.
Each domain has to communicate with its 8 neighbours. Dummy domains
(with process id MPI proc null) are added outside the computational domain
(not shown). Each communication has a specified direction (W, E, S, N,
SW, NE, NW, SE, as shown in Figure 9.6). The 8 sends and receives are
organised in 16 steps. The first four deal with W/E communications.
1: Black sends W, white receives E.
2: Black receives E, white sends W.
3: Black sends E, white receives W.

Figure 9.7: Communication pattern for exchange operations.
4: Black receives W, white sends E.
5-8: The same now for S/N directions.
9-12: The same now for SW/NE directions.
13-16: The same now for SE/NW directions.
The actual number of communications depends on the sizes of the halo. For
example, an array with halo size (0,2,2,2) has no western halo so that steps
3, 4, 11, 12, 13, 14 become unnecessary. There is also an option foreseen in
the exchange call to skip all corner communications (steps 9 to 16).
9.4.3.3 program routines for communications

The following generic communication routines have been implemented in the
code. For a discussion of the FORTRAN syntax see Section 23.17.
collect vars collect operations

combine mod combine operations on full model grid arrays
combine obc combine operations on open boundary arrays
combine stats combine operations on irregular (stations) arrays
combine submod combine operations on sub-sections of full model grid arrays
copy chars copy operation on character data
copy vars copy operation on numerical data
distribute mod distribute operation on model grid arrays
exchange mod exchange operation on model grid arrays.
9.5 Local versus global array indexing

Since the parallel decomposition uses non-shared memory, arrays exist only
on a local basis. In some cases, one needs to store all these local components
into some global array. The question is how to relate a local array element
with the corresponding element in the global array. The answer is so-called
index mapping, which maps local array indices into the corresponding global
ones.
For arrays defined on the model grid, this mapping has a simple form and
follows from the definition of the domain decomposition itself. Assume that
(iloc,jloc) are the local and (iglb,jglb) its corresponding global indices. They
are related by
iglb = iloc + nc1loc - 1
jglb = jloc + nr1loc - 1
The solution is less obvious for arrays not indexed by positions on the
model grid. Consider the example shown in Figure 9.8. The domain is
decomposed in 4 sub-domains.
1 2
1
3
2
3
1
4
2
2 5
3 1
Figure 9.8: Example of index mapping between global and local arrays.
There are 6 data points in total of which 3 are located in the domain
with process number 1, 2 in domain 2, 1 in domain 3 and none in domain
9.5. LOCAL VERSUS GLOBAL ARRAY INDEXING 377
4. The 3 elements of domain 1 map into elements (2,3,5) of the global array,
the 2 elements of domain 2 into (1,4), the element from domain 3 into global
element 6. No mapping is obviously needed for domain 4. The mapping can
be programmed as follows
INTEGER :: iproc, maxstats, nostatsglb, nostatsloc

INTEGER, DIMENSION(nprocs) :: nostatsprocs
INTEGER, DIMENSION(:,:) :: lstatsprocs
nostatsglb = 6
nostatsprocs = (/3,2,1,0/)
iproc 110: DO iproc = 1,nprocs
IF (idloc.EQ.idprocs(iproc)) THEN
nostatsloc = nostatsprocs(iproc)
ENDIF
ENDDO iproc 110
maxstats = MAXVAL(nostatsprocs)
ALLOCATE (lstatsprocs(nprocs,maxstats))
lstatsprocs(1,1:3) = (/2,3,5/)
lstatsprocs(2,1:2) = (/1,4/)
lstatsprocs(3,1) = 6
where nostatsloc, nostatsglb are the local and global number of data points,
nostatsprocs an array with the number of data points per process and lstat-
sprocs the array defining the index mapping. If, for example, the data points
represent stations used for output, the local data must be combined first into
the global array using the index mapping array. The situation is more com-
plex in practice since the number of points per domain are unknown initially.
Usually, these points have corresponding geographical positions which allows
to determine their distribution over the different sub-domains.
The second example is related to the indexing of open boundary locations.
The following definitions are made
nobu number of global U-open boundary points (global)
nobuloc number of local U-open boundary points (local)
westobu(nobu) .TRUE. (.FALSE.) for U-open boundary points
at western (eastern) boundaries (global)
iobuloc(nobuloc) local X-index of U-open boundary points on the
local grid (local)
jobuloc(nobuloc) local Y-index of U-open boundary points on the
local grid (local)
indexobu(nobuloc) global indexes of local U-boundary points (local)

indexobuprocs(nobu,nprocs) global indexes of local U-boundary points per do-
main (global)
The parameter nobuloc and the last 3 arrays are defined in routine
open boundary arrays (file Grid Arrays.F90). Consider the following code
iiloc 110: DO iiloc=1,nobuloc

i = iobuloc(iiloc); j = jobuloc(iiloc)
ii = indexobu(iiloc)
IF (westobu(ii)) THEN
....
ENDIF
ENDDO iiloc 110
The IF statement determines whether a local open boundary points is located

at a western or eastern boundary.
Index mapping is used in the program for local versus global indexing of:
• open boundary arrays
• output arrays of model data on an irregular grid
• the positions of the open boundary points belonging to nested sub-grids

Chapter 10
Structure of the model code
10.1 Source code files

The main code files, located in the source directory, can be classified into
distinct groups, using their file name.
• Files with suffix .f90 are FORTRAN source code files, files with .F90
are FORTRAN files containing C-language code (#ifdef) statements.
• Files whose name start with a lower case character and include no
underscore character, contain “declaration modules” with declarations
of variables and arrays as described in Section 6.1.5.
• Files whose name start with a lower case character and include an
underscore character, contain module routines, as described in Sec-
tion 6.1.5. The routines are often generic and of a general nature.
• Files whose name start with an upper case character (except Usrdef *
files) are external subprograms with “actual” code.
• Files whose name start with Usrdef , contain routines for user setup.
(The ones in the source directory are empty and intended for proper
compilation only, user-defined versions are defined elsewhere).
379
380 CHAPTER 10. STRUCTURE OF THE MODEL CODE
Table 10.1: List of declaration module files.
file name contents

currents.f90 (2-D and 3-D) current arrays
datatypes.f90 definitions of all derived types, used in the program
density.f90 density arrays
depths.f90 water depth and surface elevations arrays
diffusion.f90 horizontal and vertical diffusion coefficient arrays
fluxes.f90 arrays of surface and bottom fluxes, drag and exchange coeffi-
cients, roughness lengths
grid.f90 model grid arrays
gridpars.f90 model grid and related parameters
iopars.f90 parameters and arrays for all kind of I/O (including user-defined)
meteo.f90 surface meteorological arrays
modids.f90 key id definitions of all model variables
nestgrids.f90 parameters and arrays for sub-grid nesting applications
obconds.f90 arrays for 2-D and 3-D open boundary conditions, arrays for 1-D
surface forcing
optics.f90 optical arrays (including irradiance)
paralpars.f90 parameters and arrays needed for parallel applications
physpars.f90 physical model parameters
relaxation.f90 arrays for applying relaxation conditions
switches.f90 model switches
syspars.f90 “system” parameter constants
tide.f90 parameters and arrays for tidal applications
timepars.f90 date and time parameters
turbpars.f90 turbulence model constants
turbulence.f90 turbulence model arrays
10.1. SOURCE CODE FILES 381
Table 10.2: List of module routine files.
file name contents

array interp.f90 routines for interpolation on the model grid
cf90 routines.F90 library of netCDF routine calls
check model.f90 routines for checking of user-defined parameters and ar-
rays
cif routines.f90 utility routines used for reading and writing a CIF
comms MPI.F90 library of MPI routine calls
datatypes init.f90 initialisation of derived type scalar and array variables
default model.f90 default model settings
diagnostic routines.F90 utility routines calculating terms in the energy equation,
total energy, potential energy, enstrophy and vorticity
error routines.F90 routines performing error checking
fft library.f90 routines for performing fast Fourier transforms
grid interp.f90 routines for performing interpolation from and to external
grids and locations
grid routines. f90 utility routines performed on the model grid
inout paral.f90 routines for preparing input/output in parallel mode
inout routines.f90 routines for performing input/output in standard format
math library.f90 library of diverse mathematical routines (e.g. root finder)
modvars routines.f90 variable and file attributes
nla library.F90 linear algebra library
paral comms.f90 parallel communication library
paral utilities.f90 utility routines for parallel applications
reset model.F90 reset setup parameters and arrays defined by the user
rng library.f90 random generator library
time routines.f90 (calendar) date and time utility routines
turbulence routines.F90 routines used by the turbulence subprogram
utility routines.f90 various utility routines
Table 10.3: List of files with external procedures.
file name contents

Advection Terms.F90 advective terms in the transport equations
Allocate Arrays.f90 allocate/deallocate “global” variables
Bottom Fluxes.f90 bottom drag coefficient and shear stress
Coherens Program.f90 COHERENS main program
Corrector Terms.F90 corrector terms in the transport equations
Density Equations.F90 salinity and temperature equations,
optical module, equation of state, baroclinic pres-
sure gradient
Diffusion Coefficients.F90 horizontal and vertical diffusion coefficients
Diffusion Terms.F90 diffusion terms in the transport equations
Grid Arrays.F90 model grid parameters and arrays (grid spacings,
pointer arrays, open boundary locations, water
depths)
Harmonic Analysis.f90 harmonic analysis
Hydrodynamic Equations.F90 hydrodynamic equations (currents, 2-D mode, el-
evations)
Model Finalisation.f90 finalise model
Model Initialisation.F90 initialise model
Model Parameters.f90 read/write a CIF
Nested Grids.F90 sub-grid nesting
Open Boundary Conditions.f90 apply open boundary conditions
Open Boundary Data 2D.f90 define 2-D open boundary conditions and update
data
Open Boundary Data Prof.f90 define 3-D open boundary conditions and update
data
Parallel Initialisation.f90 initialise parallel mode (parameters, domain de-
composition, ...)
Relaxation Zones.f90 define and apply relaxation conditions
Surface Bounday Data 1D.f90 define and apply surface forcing conditions (slope
and elevation) for the water column mode
Surface Data.f90 update 2-D external forcing data
Surface Fluxes.F90 surface fluxes
Surface Grids.f90 define 2-D external grids
Tidal Forcing.F90 astronomical argument, nodal factors,
tidal force
Time Averages.f90 time-averaged output
Time Series.f90 time series output
(Continued)
10.2. STRUCTURE DIAGRAMS 383
Transport Equations.F90 solve transport equations

Turbulence Equations.F90 turbulence models
Table 10.4: List of user-defined routine files.
file name contents

Usrdef Harmonic Analysis.f90 parameters and data for harmonic analysis and
output
Usrdef Model.f90 “basic” model setup (model parameters,
bathymetry, domain decomposition, initial
conditions, open boundary conditions)
Usrdef Nested Grids.f90 setup of sub-grids for nesting
Usrdef Output.f90 output completely specified by the user
Usrdef Surface Data.f90 definition of external 2-D grids and update of 2-D
external data
Usrdef Time Averages.f90 parameters and data for time-averaged output
Usrdef Time Series.f90 parameters and arrays for time series output
10.2 Structure diagrams

10.2.1 General structure
The general structure of the program is given in Figure 10.1. The program
contains two major loops.
• The first (outer) loop is contained within the large (semi-)rectangle.

Each cycle corresponds to a new simulation, initiated by reading a next
input line from the file defruns. This is further discussed in Section 12.1.
• The second (inner) loop within the smaller rectangle denotes the time-
stepping.
Each simulation is composed of three parts: initialisation, time-stepping

(where the actual calculations are performed) and finalisation. Details are
given below. Initialisation and finalisation of MPI are the only procedures
initialise MPI
End of File
read title
Structure of the physical model
initialise model
meteorological
meteorological
data
data
surface elevation
wind stress heat fluxes
currents turbulence salinity temperature
optical module
density
bottom stress gradients
solar radiation
river and open river and open

boundary input boundary input
advection−diffusion
module
finalise model
finalise MPI
exit
Figure 10.1: General structure of COHERENS.
outside the outer loop. This means that, although multiple simulations can
be performed within one run, they must all be conducted either in serial or
in parallel mode.
The advection-diffusion module forms the central “core” part of the time-
loop section. The module is coded in a generic way and solves the advective-
diffusive transport equations of any scalar variable, 3-D and 2-D currents,
and turbulence tranport equations. The inputs for the routine are prepared
in separate routines for each variable (temperature, salinity, 3-D currents,
2-D currents, turbulent energy, . . . ) and are composed of source terms, open
boundary and surface forcing data. The boundary data are obtained via
general routine calls. For example, there is one program module (discussed
in Section 10.2.4 below) dealing with reading and updating of open boundary
profile data for any 3-D quantity.
10.2.2 Initialisation procedures

The initialisation procedures are schematically presented in Figure 10.2. Ex-
cept for user output, all initialisation routines are called from initialise model.
The first task to be performed by the program is the definition of all
parameters and arrays needed to setup the application. This is organised in
different sections.
1. Model parameters:
• model switches
• date and time parameters (start and end date, time steps)
• model grid (dimensions, resolution, number of open sea and river
boundaries)
• various parameters like number and type of tidal constituents,
number of nested sub-grids, ...
• parameters for setting up the model in parallel mode
• physical model parameters
• numerical model parameters
• parameters for the turbulence sub-module(s)
• attributes of external 2-D grids
• attributes of the forcing files
• parameters to define the type and form of monitoring
For details see Chapter 12.
2. Model grid and bathymetry:
• coordinates of the model grid
• bathymetry
• location of open boundaries
For details see Section 13.1.
3. Domain decomposition (parallel mode, see Section 12.9). Once the
model grid and domain decomposition have been defined, memory is
allocated to all model grid arrays and a series of additional arrays (grid
spacings, pointer arrays, . . . ) are defined.
4. Initial conditions (see Section 13.2).
5. Definition of the areas for application of the open boundary relaxation

scheme (Section 14.3).
6. Locations of nested sub-grid(s) (see Section 15.3).
7. Positions of external 2-D data grids (Section 15.2).
8. Type and form of open boundary conditions for the 2-D mode (Sec-
tion 14.1.1), baroclinic currents and 3-D scalars (Section 14.2.1).
9. Initialise surface and bottom fluxes.
10. Parameters for setting up user defined output (see Chapter 16).
Open boundary and surface forcing data are usually given as time series.
If the first data time coincides with the initial time, the data file is opened and
the first and (eventually second) time records are read from the file during the
initialisation phase of the program. This has the further advantage that error
checking can be performed (existence of the file, data formats, ...) before the
program enters the time loop.
Each section of the initialisation contains (or may contain) the following
sub-tasks:
1. Defaults values are given to several model parameters and arrays. In

many cases, these defaults are meaningfull and should be maintained.
In other case, they are not meaningfull and must be replaced by the
user. The advantage of such procedure is a more efficient error checking.
2. Values are (re)-defined. Two methods are available:
• The definitions are programmed by the user in a usrdef routine.

Options are foreseen in the program to write these definitions to
an external file in COHERENS standard format.
• All values are obtained as input from an external file in COHERENS
standard format.
3. Depending on the definitions given by the user, parameters are reset

from their default values.
4. The setup of the model (definitions of model parameters and arrays)

are checked for errors. If errors are detected, appropriate messages are
written to an errlog file and the program aborts.
10.2.3 Time loop

Figure 10.3 shows a diagram of the time loop. The order of routine calls is
in line with the solution procedure described in Section 5.8.
The routines where the 2-D mode, 3-D current, temperature and sali-
nity equations are solved, are schematically presented in Figures 10.4–10.6.
Each routines is composed of an initialisation section, a main part where the
variable(s) is (are) updated and a finalisation section.
initialisation Actions performed during the initialisation phase (time t=0):

allocation of local arrays, definition of open boundary conditions, open-
ing of data files and reading of first time records.
• The initialisation of the 2-D mode is actually perfomed in routines

update 2dobc data called from current 2d and define 2dobc spec
called from update 2dobc data.
• Open boundary conditions for 3-D currents are defined in current cor.
• If the temperature equation is forced with SST, the SST grid and
data are defined and initialised in temperature equation.
main section
• update open boundary data
• apply open boundary conditions
• apply surface and bottom boundary conditions (3-D variables only)
• calculate source terms
• solve the transport equations by calling the appropriate transport
routine
• exchange array sections with neighbouring sub-domains (parallel
mode only)
• write interpolated data for nested sub-grids (if requested)
finalisation Deallocate arrays at the current or final time step.
The following remarks are to be given:
• Surface elevations are updated in current 2d before the depth-integrated

transports.
• Open boundary conditions are applied in current 2d after solving the

2-D depth-integrated momentum equations.
• The 3-D current calculations are split over two routines called at diffe-
rent (predictor and corrector) time steps: surface and bottom boundary
conditions are applied, source terms calculated and transport equations
solved in current pred; open boundary conditions and corrector step are
applied, vertical currents calculated and nested output written in cur-
rent corr.
• Meteorological forcing data are defined by a separate call to meteo input
from the main program.
The update of a 2-D or 3-D quantity is performed by one of the trans-
port at * routines, which integrate the model equations in time. Exceptions
are surface elevation and vertical current which are obtained from the 2-D
and 3-D continuity equations. The procedures closely follow the numerical
descriptions given in Chapter 5 so that no diagrams need to be given here.
10.2.4 Open boundary and surface forcing data input

The procedure for applying open boundary conditions for the 2-D mode is
summarised in Figure 10.7:
1. The routine update 2dobc data is called from current 2d:
• At the initial time the routine define 2d obc spec is called where
– A series of arrays to be specified by the user, are allocated.
– The arrays are defined by calling either the user-defined rou-
tine usrdef 2dobc spec or as input from a standard COHERENS
file by calling read 2dobc spec. If requested, the arrays are
written to a standard file by calling write 2dobc spec.
– Error checking is performed.
• If there are external data files, it is checked first for each data
file, whether the data are still up to date, which means that the
last date and time for which data are available is later than the
current one. If this is not the case (such as at the initial time),
define 2d obc data is called where:
– New data are obtained by calling either the user-defined rou-
tine usrdef 2dobc data or as input from a standard COHERENS
file by calling read 2dobc data. If requested, the arrays are
written to a standard file by calling write 2dobc data.
– If an end of file condition occurs, further action is deter-
mined by the endfile attribute. This is further discussed in
Section 12.7.2.
• The new data (if any), representing the ψ0e term in equation (4.340),
are stored in the appropriate open boundary arrays and interpo-
lated in time (if requested).
• Harmonic tidal expansions are evaluated. If needed (which is
usually the case at the initial time), astronomical arguments and
nodal factors are calculated by calling astro params. The harmonic
terms are added to the data values.
2. The open boundary conditions are applied by calling open boundary conds 2d.
User-defined setup for 2-D open boundary conditions is further discussed in

Section 14.1.
The procedure for applying open boundary conditions for the 3-D mode
is given in Figure 10.8. The code is written in a generic form so that the
routines can be used for any 3-D quantity (currents, temperature, . . . ).
1. At the initial time the routine define profobc spec is called from the
“main” routine (current corr, temperature equation, . . . ):
• A series of arrays to be specified by the user, are allocated.

• The arrays are defined by calling either the user-defined routine
usrdef profobc spec or as input from a standard COHERENS file
by calling read profobc spec. If requested, the arrays are written
to a standard file by calling write profobc spec.
• Error checking is performed.
2. The routine update profobc data is called where:
• It is checked first for each data file, whether the data are still up
to date, which means that the last date and time for which data
are available is later than the current one. If this is not the case
(such as at the initial time), define profobc data is called where:
– New data are obtained by calling either the user-defined rou-
tine usrdef profobc data or as input from a standard COHERENS
file by calling read profobc data. If requested, the arrays are
written to a standard file by calling write profobc data.
– If an end of file condition occurs, further action is deter-
mined by the endfile attribute. This is further discussed in
Section 12.7.2.
• The new data (if any) are stored in the appropriate open boundary
profile arrays and interpolated in time (if requested).
• If any of the interpolating values has a flagged value, the inter-

polated open boundary profile data value will be flagged as well.
A flagged value at a certain vertical level within a vertical pro-
file means that a zero gradient condition will be applied at that
particular level.
3. The open boundary conditions are applied by calling open boundary conds 3d
for baroclinic currents or open boundary conds prof for scalars.
User-defined setup for baroclinic open boundary conditions is further dis-
cussed in Section 14.2.
The application of 2-D external data requires firstly the definition of the
data grid, which is implemented as follows (no diagram shown):
1. A derived type “grid” array is created by allocation in the “main”
routine (meteo input for the meteo or temperature equation for the SST
grid), for storing the relative coordinates of the data grid with respect
to the model grid (see Section 6.1.4).
2. The grid is defined by calling define surface input grid. Definition de-
pends on the value nhtype grid attribute (see Section 8.4.2):
0: No grid needs to be defined

1: The grid is uniform rectangular and is defined by calling
construct regular grid.
2: The grid is non-uniform rectangular. Coordinate arrays are obtained
by calling either the user-defined routine usrdef surface absgrd or as
input from a standard COHERENS file by calling read surface absgrd.
If requested, the coordinates are written to a standard file by calling
write surface absgrd. The relative coordinates are obtained by calling
model to data coords.
3: The grid is non-uniform and non-rectangular. The relative coordi-
nate arrays are directly obtained by calling either the user-defined
routine usrdef surface relgrd or as input from a standard COHERENS
file by calling read surface relgrd. If requested, the coordinates are
written to a standard file by calling write surface relgrd.
4: The grid coincides with the model grid and does not need to be
defined here.
Setup of 2-D data grids is discussed in Sections 15.2.1–15.2.2.

The procedure for the input of forcing data from a 2-D external data grid
is shown in Figure 10.9. The code is written in a generic form so that the
routines can be used for meteorological, SST, wave, . . . data. The routine
update surface data is called from the “main” routine (meteo input for the
meteo or temperature equation for the SST grid):
1. It is checked first for each data file, whether the data are still up to date,
which means that the last date and time for which data are available is
later than the current one. If this is not the case (such as at the initial
time), define surface data is called where:
• New data are obtained by calling either the user-defined routine

usrdef surface data or as input from a standard COHERENS file by
calling read surface data. If requested, the arrays are written to a
standard file by calling write surface data.
• If an end of file condition occurs, further action is determined by
the endfile attribute. This is further discussed in Section 12.7.2.
2. The data are interpolated in time.
3. If any of the interpolating values has a flagged value, the interpolated

open boundary profile data value will be flagged as well. In case of
SST data, the flagged value is replaced by the modelled temperature
at the highest level. There is currently no procedure foreseen for flagged
meteorological data values.
4. The data are interpolated in space by calling intpol data to model 2d if

0<nhtype<4.
10.2.5 Finalisation procedures

After termination of the time loop the simulation is finalised as follows:
• All files, which are still open with exception of monitoring files, are
closed.
• A timer report is written on request.
• Model arrays, which are still allocated, are deallocated.
• All monitoring files are closed.
• A new input line is read from the defruns file. If there is an end of
file condition, the program checks whether MPI was switched on at
the start, finalises MPI if needed and terminates. Otherwise, a new
simulation starts and all model parameters and arrays are reset to
their default values as part of the re-initialisation procedures discussed
in Section 10.2.2.
Model initialisation
define model parameters default read, usrdef, write reset check
define MPI communicator
define model grid default read, usrdef, write check
domain decomposition
communication parameters default read, usrdef, write check
allocate model arrays
grid arrays (grid spacings,

pointers, ...)
define initial conditions default read, usrdef, write reset check
initialise physical arrays
equation of state
astronomical tides
define relaxation conditions read, usrdef, write weight factors
nest locations read, usrdef, write relative coordinates
meteo grid read, usrdef, write relative coordinates
first meteo data read, usrdef, write
define default read, usrdef, write check

open boundary conditions
(2−D, currents, temperature, salinity)
first data read, usrdef, write check
initialise surface/bottom fluxes
first user output
first final conditions
Figure 10.2: Schematic diagram of all initialisation procedures.

time loop
nt = 0
nt = nt+1
update_time
meteo_input
nt−1 multiple of ic3d
predictor store_old_depths
step
mask_function
equation_of_state
vertical_diff_coefs
baroclinic_gradient
horizontal_diff_coefs
nt−1 multiple of ic3d current_pred

hydrodynamic_equations predictor
step
current_2d
nt multiple of ic3d current_corr

corrector
step
nt multiple of ic3d
corrector temperature_equation
step
salinity_equation
user output
final conditions
nt < nstep
Figure 10.3: Structure diagram of the time loop.

current_2d
initialise
update_2dobc_data open boundary data
surface_elevation solve continuity equation
atmospheric pressure
surface slope
baroclinic pressure
source terms astronomical tides
bottom stress
surface stress
coriolis (explicit)
transport_at_U_2d solve transport

transport_at_V_2d equations
coriolis (implicit)
exchange_mod exchange
open_boundary_conds_2d open boundary conditions
mean currents
update_nest_data_2d sub−grid data
finalise
exit
Figure 10.4: Diagram of routine current 2d which solves the 2-D mode equa-
tions.
current_pred current_corr
initialise yes
nt=0
atmospheric pressure
define open boundary define_profobc_spec
surface slope conditions
source terms tidal force first open boundary data update_profobc_data
no
baroclinic pressure sub−grid data update_nest_data_3d
coriolis (explicit) exit
update open boundary data update_profobc_data

transport_at_U_3d solve transport
transport_at_V_3d equations apply boundary conditions open_boundary_conds_3d
corrector scheme
coriolis (implicit)
relaxation_at_U
exchange_mod exchange relaxation scheme relaxation_at_V
finalise filtered currents
exit exchange exchange_mod
transf_vertical_current
vertical current transf_physical_current
exchange_mod
bottom/surface stress bottom_stress

surface_stress
sub−grid data update_nest_data_3d
finalise
exit
Figure 10.5: Diagrams of the routines current pred and current corr which
solve the 3-D momentum equation at the predictor and corrector step.
temperature_equation salinity_equation
yes yes
nt=0 nt=0
define open boundary define open boundary

conditions define_profobc_spec conditions define_profobc_spec
first open boundary data update_profobc_data first open boundary data update_profobc_data
no
sub−grid data update_nest_data_prof sub−grid data update_nest_data_prof

no
first sst data update_surface_data exit

exit
update open boundary data update_profobc_data update open boundary data update_profobc_data
apply boundary conditions open_boundary_conds_prof apply boundary conditions open_boundary_conds_prof
solar_irradiance surface boundary

source terms salinity_flux
conditions
heat_optics
surface boundary heat_flux solve transport

conditions equations transport_at_C_3d
update_surface_data
impose lower
solve transport limit
equations transport_at_C_3d
exchange exchange_mod
exchange exchange_mod
sub−grid data update_nest_data_prof
sub−grid data update_nest_data_prof
finalise
finalise
exit
exit
Figure 10.6: Diagrams of the routines temperature equation and

salinity equation which solve the temperature and salinity equations.
update_2dobc_data
define_2dobc_spec read_2dobc_spec, usrdef_2dobc_spec, write_2dobc_spec
yes define open boundary

nt=0 allocate read, usrdef, write check copy
conditions
allocate/initialise
no
exit read_2dobc_data, usrdef_2dobc_data, write_2dobc_data

define_2dobc_data
check update yes check latest yes define new data read, usrdef, write
time data time
no
no
time interpolation
phases and nodal factors astro_params
(add) harmonic series
finalise
exit
Figure 10.7: Diagrams of the routines used for defining and updating 2-D
open boundary conditions and data.
define_profobc_spec update_profobc_data read_profobc_data, usrdef_profobc_data, write_profobc_data
define_profobc_data
initialise
check update check latest define new data read, usrdef, write
time data time
define
read_profobc_spec usrdef_profobc_spec
time interpolation
write write_profobc_spec exit
reset
check
copy copy_vars
exit
Figure 10.8: Diagrams of the routines used for defining and updating 3-D
open boundary conditions and data.
update_surface_data
define_surface_data read_surface_data, usrdef_surface_data, write_surface_data
yes yes
check update check latest define new data read, usrdef, write
time data time
no
no
time interpolation
space interpolation
exit
Figure 10.9: Diagram of the routines used for defining and updating data
from an external 2-D grid.
Part IV
User manual
401
Chapter 11
Introduction
This part of the documentation explains how model setup is defined for a
user application. As explained in Section 2.6 a number of Usrdef files with
FORTRAN 90 code need to created by the user. These files provide the
following information to the program:
• values of an extensive series of model parameters (settings for monitor-
ing files, parallel setup, switches, time parameters, physical parameters,
definition of parameters for model forcing)
• model grid and bathymetry
• initial conditions
• open boundary conditions and input of open boundary data
• surface forcing grids and input of forcing data
• location of sub-grids for nesting
• definition of parameters and variables for creating time series and time-
averaged output
• definition of parameters and variables for performing harmonic analysis
and output of residuals, amplitudes, phases and elliptic parameters
• user-formatted output
All this information has to be defined within specific usrdef routines, located
in one of the Usrdef files. A complete listing of all usrdef routines is given
in Table 11.1.
Writing these usrdef routines from scratch may be a big task, especially
for a beginning user. The next alternative procedures can be followed.
403
404 CHAPTER 11. INTRODUCTION
1. Files with generic example code are found in the setups/examples

directory. Within these files, a specific value, assigned to a model pa-
rameter or array, indicates a default value. In many cases, the defaults
do not need to be changed or defined by the user. A “?” means that no
realistic default is available and the variable has to be defined. Some of
the assignment statements in the example code are within an IF block.
This means that the definition is conditional and depends on the out-
come of the IF test condition (usually the value of a model switch).
2. A second way for making a setup is to copy a Usrdef file from one of
the test cases defined in a setups directory and make the necessary
adaptations.
3. Use can be made of the CIF utility, in which case all parameters needed
for model setup (excluding forcing data) and user-defined output are
obtained from a central input file. An option is foreseen to create a
CIF by the program. For details see Sections 7.4 and 12.1.
4. Once a setup has been created, all forcing data (e.g. bathymetry, me-
teorological data,. . . ) can be written to a number of files in standard
COHERENS format. These files can be used in subsequent simulations
for model setup. This requires only to change a few options in the pro-
gram so that the usrdef routines are no longer called by the program.
A complete description of all model variables, which can possibly be used

for model setup, is given in the chapters below. Default values are in paren-
theses. As stated above and in the text below, some definitions are condi-
tional (usually depending on the value of a model switch). Physical units of
dimensional quantities are written between square brackets.
The program provides options, selected with the status attribute discussed
in Section 12.7, to read external data from a file in standard COHERENS for-
mat in which case the usrdef routine is not called, or to write the setups pa-
rameters and data, defined in a usrdef routine, to an external file in standard
COHERENS format. For many usrdef routines there exists a corresponding
read and write routine for reading and writing in standard format. They are
listed in Table 11.2
In summary, the following usrdef routines can be made redundant:
1. Model setup is provided through a CIF
usrdef init params, usrdef mod params, usrdef tsr params,

usrdef avr params, usrdef anal freqs, usrdef anal params
405
2. Forcing data are obtained from file(s) in standard COHERENS format
usrdef partition, usrdef phsics, usrdef 1dsur spec,

usrdef 2dobc spec, usrdef profobc spec, usrdef 1dsur data,
usrdef 2dobc data, usrdef profobc data, usrdef rlxobc spec,
usrdef surface absgrd, usrdef surface relgrd, usrdef surface data,
usrdef nstgrd spec, usrdef surface nstgrd abs,
usrdef surface nstgrd rel
3. Standard output variables are selected through their key id (see Chap-
ter 16)
usrdef tsr0d vals, usrdef tsr2d vals, usrdef tsr3d vals,

usrdef avr0d vals, usrdef avr2d vals, usrdef avr3d vals,
usrdef anal0d vals, usrdef anal2d vals, usrdef anal3d vals
Table 11.1: Overview of all Usrdef files and usrdef routines in the program.
file routine purpose

Usrdef Model.f90 usrdef init params setup and formats of monitor-
ing files
usrdef mod params model parameters and formats
for all model forcing
usrdef grid model grid and bathymetry
usrdef partition domain decomposition
usrdef phsics initial conditions
usrdef 1dsur spec surface forcing conditions (ele-
vations and surface slope) for
1-D (water column) applica-
tions
usrdef 2dobc spec open boundary conditions for
the 2-D mode
usrdef profobc spec open boundary conditions for
baroclinic currents, tempera-
ture, salinity
usrdef 1dsur data input of surface forcing data
for 1-D (water column) appli-
cations
usrdef 2dobc data input of 2-D open boundary
data
usrdef profobc data input of open boundary data
for 3-D baroclinic currents,
temperature and salinity
usrdef rlxobc spec setup of near-boundary areas
for application of the relaxation
scheme
Usrdef Surface Data.f90 usrdef surface absgrd definition of surface data grids
in absolute coordinates
usrdef surface relgrd definition of surface data grids
in relative coordinates
usrdef surface data input of (2-D) surface forcing
data
Usrdef Nested Grids.f90 usrdef nstgrd spec general specifications for nest-
ing (number of open boundary
points, type of coordinates)
(Continued)
407
usrdef nstgrd abs locations of sub-grid open

boundaries in absolute coordi-
nates
usrdef nstgrd rel locations of sub-grid open
boundaries in relative coordi-
nates
Usrdef Time Series.f90 usrdef tsr params definition of metadata and out-
put grid for time series output
usrdef tsr0d vals definition of 0-D time series
output data
output data
output data
Usrdef Time Averages.f90 usrdef avr params definition of metadata and out-
put grid for time averaged out-
put
usrdef avr0d vals definition of 0-D time averaged
output data
output data
output data
Usrdef Harmonic Analysis.f90 usrdef anal freqs definition of frequencies and
formats for harmonic analysis
usrdef anal params definition of metadata and out-
put grid for harmonic output
usrdef anal0d vals definition of 0-D data for har-
monic analysis
monic analysis
monic analysis
Usrdef Output.f90 usrdef output user-defined routine
Table 11.2: List of usrdef routines which have a related read and write
routine for reading from or writing to a file in standard COHERENS format.
user-defined standard read standard write

usrdef grid read grid write grid
usrdef partition read partition write partition
usrdef phsics read phsics write phsics
usrdef 1dsur spec read 1dsur spec write 1dsur spec
usrdef 2dobc spec read 2dobc spec write 2dobc spec
usrdef profobc spec read profobc spec write profobc spec
usrdef 1dsur data read 1dsur data write 1dsur data
usrdef 2dobc data read 2dobc data write 2dobc data
usrdef profobc data read profobc data write profobc data
usrdef rlxobc spec read rlxobc spec write rlxobc spec
usrdef surface absgrd read surface absgrd write surface absgrd
usrdef surface relgrd read surface relgrd write surface relgrd
usrdef surface data read surface data write surface data
usrdef nstgrd spec read nstgrd spec write nstgrd spec
usrdef nstgrd abs read nstgrd abs write nstgrd abs
usrdef nstgrd rel read nstgrd rel write nstgrd rel
Chapter 12
Control parameters
The parameters, discussed in this chapter (except the first section), are de-
fined in the following routines of the file Usrdef Model.f90:
• usrdef init params: setup of monitoring parameters (Section 12.2)
• usrdef mod params: switches, model parameters and attributes of for-

cing files (Sections 12.3-12.8)
• usrdef MPI partition: user-defined domain decomposition (Section 12.9)
12.1 File defruns

The program open this file at the start of the simulation(s) and is read line-
wise. Each line represents a separate run and contains the definitions of three
parameters defined separated by a ‘,’ The general systax is
runtitle,status,filename
where
runtitle the title of the simulation stored in the model parameter runtitle
status the status of the CIF
‘0’ The CIF utility is switched off (both for reading and writing).
‘R’ Model setup parameters are read from a CIF.
‘W’ Model setup parameters are written to a CIF.
filename Name of the CIF file. If not given, the default name TRIM(runtitle)//‘.cifmodA’
is taken. This parameter is obviously not used if status equals ‘0’
409
410 CHAPTER 12. CONTROL PARAMETERS
Defaults are taken (except for runtitle which must always be given) when the
value is an empty string, one blank or several blanks. All blanks are ignored
on the input line.
Consider the following example
conesA,,
conesA,R,
conesA,W,myciffile
In the example the first line initiates the run conesA without CIF, the second
one reads the setup from the file conesA.cifmodA, the third writes the CIF
data to the file myciffile.
Lines can be commented if the first character is a ‘!’. This replaces, for
compatibility with the CIF syntax below, the ‘#’ character used in previous
versions.
The procedure is used to combine multiple simulations within one run:
1. The program opens the file at the start.
2. The first line is read.
3. A simulation is started with the given title.
4. When the simulation ends, a next line is read giving a new title and a
next simulation initiates.
5. When there are no more lines to be read, the file is closed and the
program terminates.
12.2 Parameters for monitoring

This section describes the parameters used to set up the monitoring and a
few other general parameters. They are defined in usrdef init params. The
routine is called by all processes.
12.2.1 Cold start

LOGICAL :: cold start If .TRUE., the program executes model initialisation
and finalisation, but does not enter the time loop (.FALSE.).
If defruns contains multiple lines, a cold start is per-
formed for each simulation. The option is useful for
debugging.
12.2. PARAMETERS FOR MONITORING 411
12.2.2 Log files

INTEGER :: levprocs ini(npworld) Determines the level of tracing of the inilog
file for each process. Different levels can be defined for different
files. If 0 (default value), no log file will be written. The inilog file
only contains information about model initialisation and is closed
as soon as the program enters the time loop. In parallel mode,
the size (npworld) of the vector array equals the number of pro-
cesses, initially defined within MPI COMM WORLD or equals 1 in
the serial case.
INTEGER :: levprocs run(npworld) Determines the level of tracing of the runlog
file for each process. Different levels can be defined for different
files. If 0 (default value), no log file will be written. The runlog
file traces program execution during the time loop.
CHARACTER (LEN=leniofile) :: inilog file Name of the inilog file. Default is
TRIM(runtitle)//‘.inilogA’. In parallel mode, the name is appended
with the process id number.
CHARACTER (LEN=leniofile) :: runlog file Name of the runlog file. Default
is TRIM(runtitle)//‘.runlogA’. In parallel mode, the name is ap-
pended with the process id number.
LOGICAL :: exitlog Writes an exit statement of the form ‘num:R’, where ‘num’
is the program level in the “log”-file on exit of a routine call if
.TRUE. (.TRUE.).
INTEGER :: runlog count Sets the number of time steps after which the runlog
file is overwritten. Default is the total number of time steps (i.e.
information is written at all time steps and the file is never over-
written).
12.2.3 Error files

INTEGER :: maxerrors Maximum allowed number of error messages within
the errlog file. Default is MaxErrMsgs defined in syspars.f90.
INTEGER :: levprocs err(npworld) Level of error checking for each process
(0).
0 : error checking disabled (for a particular processor) and no file
is created
1 : error checking enabled during initialisation phase only
2 : error checking enabled throughout the whole program
CHARACTER (LEN=leniofile) :: errlog file Name of the errlog file. Default is

TRIM(runtitle)//‘.errlogA’. In parallel mode, the name is appended
with the process id number.
12.2.4 Warning file

LOGICAL :: warning Disables/enables writing of a warning file (.TRUE.).
CHARACTER (LEN=leniofile) :: warlog file Name of the warning file. Default
is TRIM(runtitle)//‘.warlogA’.
12.2.5 Timer file

INTEGER :: levtimer Determines the type of information in the timer report
(0).
0: No timer report is written.
1: Writes the total execution time only.
2: Writes time information (in % of total time) for all “timers”.
In case of a parallel run, the information is written as follows:
time on the master process, mean, minimum and maximum
time over all processes.
3: The same as previous, but in case of a parallel run, the in-
formation is additionally written for each individual process.
In the serial case, behaviour is as for case 2.
CHARACTER (LEN=leniofile) :: timing file Name of the timing file. Default
is TRIM(runtitle)//‘.timingA’.
INTEGER :: timer format Format for total execution time in the timer report
(1).
1: seconds
2: minutes
3: hours
4: days
12.3 Dimensions of the process domain grid

The parameters below are used to setup a domain decomposition and are de-
fined in usrdef mod params. The routine is called if ciffiles(icif model) %status
= ‘0’ or ‘W’
12.4. MODEL SWITCHES 413
nprocs the actual number of processes to be used (1)

nprocsx X-dimension of the decomposed domain (0)
nprocsy Y-dimension of the decomposed domain (0)
• nprocsx and nprocsy are needed by the program for making a “simple”
domain decomposition when the switch iopt MPI partit = 1. Otherwise,
if iopt MPI partit=2, these parameters are determined by the program.
• nprocs must be defined if the decomposition is obtained from a data

file or defined in usrdef partition. In that case its value must match the
size of the arrays nc1procs, nc2procs, nr1procs, nr2procs.
In case of a simple decomposition, each (but not all) of these three parameters
may be zero. However, their values must be between 0 and npworld which
is the number of processes in the MPI communicator MPI comm world or,
equivalently, the number of processes defined in the script launching the
program.
The program follows the following procedures
1. nprocsx and nprocsy are non-zero: nprocs is set to nprocsx×nprocsy
2. both nprocsx and nprocsy are zero: both values are set internally so
that nprocsx×nprocsy = nprocs and |nprocsx-nprocsy| is minimal
3. nprocsx is non-zero, while nprocsy is zero: nprocsy = nprocs/nprocsx
4. nprocsy is non-zero, while nprocsx is zero: nprocsx = nprocs/nprocsy
Remarks
• Cases 2–4: If nprocs is zero, its value is set to npworld.
• Case 3–4: If no integer division is possible, an error is issued.
12.4 Model switches

A total of 83 switches is implemented. They are defined in usrdef mod params.
12.4.1 Model grid

iopt grid sph Type of coordinates (0).
0 : Cartesian coordinates
1 : spherical coordinates
iopt grid htype Type of horizontal grid (1).
1 : uniform rectangular grid
2 : non-uniform rectangular grid
3 : curvilinear grid
iopt grid vtype Type of vertical grid (1).
1 : uniform σ-grid
2 : horizontally uniform and vertically non-uniform σ-grid
3 : horizontally and vertically non-uniform σ-grid
iopt grid nodim Grid dimension (3).
1 : 1-dimensional grid (water column model)
2 : 2-dimensional grid (depth-averaged model without ver-
tical structure)
3 : 3-dimensional grid
iopt grid node Grid location of input bathymetry and σ-coordinate grid (1).
1: at grid centers (‘C’-nodes)

2: at cell corners (‘UV’-nodes and ‘UVW’-nodes)
12.4.2 Interpolation
iopt arrint hreg Disables/enables (0/1) the use of non-uniform weighted aver-
ages for interpolation in the horizontal of arrays on the model
grid (0).
iopt arrint vreg Disables/enables (0/1) the use of non-uniform weighted av-
erages for interpolation in the vertical of arrays on the model
grid (0).
It is recommended to set these switches only for grids with highly irregular
grid spacings.
12.4.3 Hydrodynamics
iopt mode 2D Disables/enables (0/1) the 2-D hydrodynamical mode, i.e. up-
dates of transports and surface elevations (1).
iopt mode 3D Disables/enables (0/1) the 3-D hydrodynamical mode, i.e. up-
dates of 3-D currents (1).
It is recommended to keep these defaults except for very special tests like
the test cases cones and front.
12.4.4 Density
iopt dens Evaluation of the density and expansion coefficients (0).
0 : uniform density, zero expansion coefficients
1 : density from the linear equation of state (4.97), expan-
sion coefficients are uniform
2 : from the McDougall et al. (2003) general equation of
state (4.92)–(4.96) without pressure effects
3 : from the McDougall et al. (2003) general equation of
state (4.92)–(4.96) with pressure effects included
iopt dens grad Selects numerical algorithm for discretisation of the baroclinic
pressure gradient (1).
0 : gradient set to zero
1 : traditional σ-coordinate (second order) method
2 : z-level method
3 : method of Shchepetkin & McWilliams (2003)
iopt sal Salinity update (0).
0 : uniform (space and time) salinity field
1 : salinity field initialised but not updated in time
2 : salinity field initialised and updated in time
iopt sal sbc Type of surface boundary condition for salinity (0).
0 : zero surface flux
1 : surface flux given by (4.264)
iopt temp Temperature update (0).
0 : uniform (space and time) temperature field

1 : temperature field initialised but not updated in time
2 : temperature field initialised and updated in time
iopt temp optic Disables/enables (0/1) the optical module (1).
0 : all solar radiation is assumed to be absorbed at the sur-
face, i.e. the water column is considered as opaque
1 : solar radiation is absorbed within the water column using
specified values for the attenuation depths
iopt temp sbc Type of surface boundary condition for temperature (1).
1 : Neumann condition using the model’s surface heat flux
formulations
2 : Dirichlet using prescribed surface temperatures taken at
the first grid point below the surface
3 : Dirichlet using prescribed surface temperature taken at
the surface itself
12.4.5 Biology
iopt biolgy Disables/enables (0/1) the biological module (not available) (0).
Since no biological module is implemented in the current version,
this default cannot be changed.
12.4.6 Bottom boundary conditions

iopt bstres form Type of formulation for the bottom stress (2).
0 : bottom stress set to zero
1 : linear bottom stress law (4.326) or (4.327)
2 : quadratic bottom stress (4.328) or (4.327)
iopt bstres drag Formulation for the bottom drag coefficient Cdb (3).
0 : not used
1 : spatially uniform value
2 : spatially non-uniform obtained from a data file
3 : using a spatially uniform roughness length
4 : using a spatially non-uniform roughness length
iopt bstres nodim Type of currents in the (linear or quadratic) bottom stress
formulation (3).
2 : depth-mean currents
3 : 3-D current taken at the bottom grid cell
12.4.7 Advection
iopt adv scal Type of scheme for the advection of scalar quantities (3).
0 : advection disabled
1 : upwind scheme
2 : Lax-Wendroff (explicit) in the horizontal, central (semi-
implicit) in the vertical
3 : TVD scheme
iopt adv 2D Type of scheme for the advection of 2-D transports (1).
1 : upwind scheme
3 : TVD scheme
iopt adv 3D Type of scheme for the advection of 3-D currents (1).
1 : upwind scheme
3 : TVD scheme
iopt adv turb Type of scheme for the advection of turbulence quantities (0).
1 : upwind scheme
3 : TVD scheme
iopt adv tvd Type of limiting function for TVD scheme (1).
1 : superbee limiter
2 : monotone limiter
Comments
• The Lax-Wendroff/central scheme is non-monotone and should not be

selected. This is illustrated with the cases cones and front (see Sec-
tions 18.1 and 18.2).
• The TVD scheme has the ability to retain sharp gradients, but con-
sumes more CPU time compared to the upwind scheme.
• TVD is the recommended scheme for 3-D scalars. The advantage of

using a TVD scheme is less evident for the 2-D mode which uses a much
smaller time step than the 3-D mode. The faster upwind scheme can be
recommended for the 2-D mode in most cases. TVD is recommended
for resolving highly sheared 3-D currents, as occurring in e.g. frontal
zones.
• Advection of turbulence is considered of less importance than the pro-

duction and dissipation terms in the k, k−ε and kl transport equations.
It is recommended not to change the zero default value of iopt adv turb.
• The same limiting function applies for all transport equations solved
with the TVD scheme.
12.4.8 Diffusion coefficients

iopt hdif coef Type of scheme for horizontal diffusion coefficients (0).
0: not used
1: spatially uniform
2: Smagorinsky formulation (4.69) for momentum and (4.70)
for scalars
iopt hdif scal Disables/enables (0/1) horizontal diffusion in the scalar trans-
port equations (0).
iopt hdif 2D Disables/enables (0/1) horizontal diffusion in the 2-D trans-
port equations (0).
iopt hdif 3D Disables/enables (0/1) horizontal diffusion in the 3-D current
transport equations (0).
iopt hdif turb Disables/enables (0/1) horizontal diffusion in the turbulence

transport equations (0).
iopt vdif coef Selects the (general) type of vertical diffusion scheme (3).
0: vertical diffusion disabled
1: uniform diffusion coefficient
2: algebraic formulation as described in Section 4.4.2.2
3: second order turbulence closure as described in Section 4.4.3
• If horizontal diffusion is enabled, the Smagorinsky formulation, taken

from LES modelling, is a more robust scheme compared to a constant
diffusion coefficient.
• Horizontal diffusion of scalars may be potentially dangerous since it

introduces spurious diapycnal mixing.
• Horizontal diffusion of turbulence variables is only introduced for his-

torical reasons and compatibility with COHERENS V1, but has no real
physical basis.
12.4.9 Turbulence schemes

iopt turb alg Type of algebraic scheme if iopt vdif coef =2 (1).
1 : Pacanowski-Philander formulation (4.121)–(4.124)
2 : Munk-Anderson formulation (4.125)–(4.129)
3 : flow dependent formulation as described in Section 4.4.2.2
with α given by (4.137)
iopt turb dis bbc Type of bottom boundary condition for the dissipation
rate ε (2).
1 : Neumann condition (4.339)
2 : Dirichlet condition (4.337)
iopt turb dis sbc Type of surface boundary condition for the dissipation
rate ε (2).

iopt turb iwlim Type of background mixing scheme as described in
Section 4.4.3.6 (0).
0 : using uniform background coefficients
1 : using limiting conditions for turbulence parameters
2 : the Large et al. (1994) scheme given by (4.215)–
(4.216)
iopt turb lmix Mixing length formulation as described in
Section 4.4.3.5 (4).
1 : parabolic law (4.201)
2 : “modified” parabolic law (4.202)
3 : “Xing” formulation (4.203)
4 : “Blackadar” asymptotic formulation (4.204)
iopt turb ntrans Number of transport equations as described in
Section 4.4.3.4 (1).
0 : zero-equation model (equilibrium or Mellor-Yamada
level 2 method)
1 : turbulence energy equation with a mixing length se-
lected by iopt turb lmix
2 : k-ε of k-kl equation depending on the value of iopt turb param
iopt turb param Selects type of second turbulent variable (2).
1 : mixing length l (k-l scheme)
2 : dissipation rate ε (k-ε scheme)
iopt turb stab form Selects type of stability function (3).
1 : constant value (4.186)
2 : Munk-Anderson form (4.187)
3 : from RANS model as explained in Section 4.4.3.3
iopt turb stab lev Selects level for stability functions if
iopt turb stab form = 3 (1).
1 : quasi-equilibrium method (Section 4.4.3.3)
2 : non-equilibrium method (Section 4.4.3.3)
iopt turb stab mod Selects type of closure (RANS) model (4).
1 : MY82-model (Mellor & Yamada, 1982)

2 : KC94-model (Kantha & Clayson, 1994)
3 : BB95-model (Burchard & Baumert, 1995)
4 : HR82-model (Hossain & Rodi, 1982)
iopt turb stab tke Formulation for the turbulent diffusion coefficient νk (or
stability coefficient Sk ) of turbulent energy (2).
1 : constant value for Sk as given by equation (4.188)

2 : Sk is taken as proportional to momentum stability
function Su as given by (4.189)
3 : using the formulation of Daly & Harlow (1970) as
given by (4.173) or (4.179) depending on the value
of iopt turb stab lev
iopt turb tke bcc Type of bottom boundary condition for turbulence
energy (2).

iopt turb tke sbc Type of surface boundary condition for turbulence
energy (2).

12.4.10 Drying/wetting scheme

iopt fld Selects the type of drying/wetting scheme (0).
0 : Drying/wetting disabled
1 : Drying/wetting algorithm without dynamic masks
2 : Drying/wetting algorithm using dynamic masks
12.4.11 Time integration

iopt cor impl Time-integration of the Coriolis term (1).
0 : explicit
1 : semi-implicit
2 : implicit
iopt vadv impl Time-integration for vertical advection (1).
0 : explicit
1 : semi-implicit
2 : implicit
iopt vdif impl Time-integration for vertical diffusion (2).
0 : explicit
1 : semi-implicit
2 : implicit
12.4.12 Open boundary conditions

iopt obc advflux Type of open boundary condition for the cross-stream (2-D
and 3-D) advective fluxes (see Section 5.3.15.2)
1: zero gradient condition
2: quasi-upwind scheme
iopt obc advrlx Disables/enables (0/1) the relaxation scheme for horizontal
momentum advection (see Section 5.3.15.2)
0: relaxation scheme disabled (default)
1: relaxation scheme enabled. In that case the parameter
distrlx obc (representing the parameter dmax ) must be de-
fined by the user in usrdef mod params or in the CIF.
iopt obc 2D (General) type of open boundary conditions for the
2-D mode (0).
0: default conditions at all open boundaries
1: non-default conditions for at least one open boundary
point
iopt obc 3D (General) type of open boundary conditions for the
3-D currents (0).
0 : default conditions at all open boundaries

1 : non-default conditions for at least one open boundary
point
iopt obc sal (General) type of open boundary conditions for

salinity (0).

point
iopt obc temp (General) type of open boundary conditions for

temperature (0).

point
iopt obc bio (General) type of open boundary conditions for biological
variables (0). Currently not implemented.

point
iopt obc int Disables/enables (0/1) momentum advection adjacent to open

boundaries (0).
iopt obc invbar Disables/enables (0/1) inverse barometric effect at open boun-
daries (0).
iopt obc relax Disables/enables (0/1) open boundary relaxation as discussed
in Section 4.10.3 (0).
Note that the open boundary conditions automatically reduce to their de-
faults (see Section 4.10) and input of open boundary data is disabled if the
appropriate switch is not set.
12.4.13 Tides
iopt astro tide Disables/enables (0/1) the inclusion of the astronomical tidal
force in the momentum equations (0). This requires that the
model uses a spherical grid (iopt grid sph=1).
iopt astro pars Enbables or disables the inclusion of astronomical arguments

and nodal corrections in the harmonic expansions (4.218) and
(4.340) (0).
0 : astronomical argument set to zero, nodal factors set to 1,
nodal phases set to zero
1 : evaluate astronomical phases at a given time and refer-
ence longitude, nodal factors are set to 1, nodal phases
set to zero
2 : evaluate astronomical phases and nodal corrections at a
given time and reference longitude
iopt astro anal Disables/enables (0/1) the use of astronomical arguments for
harmonic analysis if iopt astro pars > 0 and iopt out anal = 1
(0).
12.4.14 1-D applications

iopt sur 1D Disables/enables surface forcing (surface slopes and elevations)
in case 1-D (iopt grid nodim=1) water column applications (0).
12.4.15 Meteorological forcing

iopt meteo Disables/enables (0/1) meteorological input and evaluation
of all surface fluxes (0).
iopt meteo stres Selects type of input data for the barotropic mode, i.e. sur-
face stress and pressure (0).
0 : no input
1 : components of wind speed (U10 ,V10 ) and (unless
iopt grid nodim=1) atmospheric pressure Pa
2 : components of surface stress (τsu ,τsv ) and (unless
iopt grid nodim=1) atmospheric pressure Pa
iopt meteo heat Selects type of input data for the heat fluxes (0).
0 : no input
1 : air temperature Ta , relative humidity RH, cloud cover
fc
2 : total (downward) non-solar surface heat flux, cloud
cover fc
3 : total (downward) non-solar surface heat flux, surface

solar radiance Qrad
4 : cloud cover fc
5 : surface solar radiance Qrad
iopt meteo salflx Selects type of input data for the salinity flux (0).
0 : no input
1 : evaporation minus precipitation rate Evap − Prc
2 : precipitation rate Prc
Note that all meteorological surface forcing is disabled if iopt meteo=0. This
means that all surface fluxes are automatically set to zero and the input of
any meteorological data is disabled.
12.4.16 Surface boundary conditions

iopt sflux cds Formulation for the neutral surface drag coefficient
Cds (0).
0 : constant value as given by the parameter cds cst (see
below)
2 : equation (4.275) from Smith & Banke (1975)
3 : equation (4.276) from Geernaert et al. (1986)
6 : equation (4.279) from Charnock (1955)
iopt sflux cehs Formulation for the neutral surface (heat) exchange coeffi-
cients Ce , Ch (0).
0 : constant value as given by the parameter ces cst or chs cst
(see below)
2 : equation (4.281) from Anderson & Smith (1981)
iopt sflux strat Selects dependence of surface drag and exchange coefficients
on atmospheric stratification effects (0).
0 : no dependence
1 : using the Kondo (1975) parameterisation (Section 4.8.2)
2 : using Monin-Obukhov similarity theory (Section 4.8.3)
12.4.17 Nesting
iopt nests Disables/enables (0/1) the writing of open boundary data for nested
sub-grids (0).
12.4.18 MPI mode

iopt MPI partit Selects the method for domain decomposition (1).
1 : “simple” partition based on the values of nprocsx
and nprocsy
2 : decomposition obtained from an external data file
or defined in usrdef partition
iopt MPI comm all Communication type for “all to all” operations (2).
1 : blocking, standard send
2 : blocking, synchronous send
3 : non-blocking, standard send
4 : non-blocking, synchronous send
iopt MPI comm exch Communication type for “exchange” operations (2).
5 : send-receive blocking calls
iopt MPI comm gath Communication type for “all to one” gather (combine)
operations (2).
iopt MPI comm scat Communication type for “one to all” scatter (distribute
and copy) operations (2).
iopt MPI comm coll Disables/enables (0/1) the use of MPI collective calls
(0).
iopt MPI abort 0: If an error is detected in a MPI routine, an error
message will be written, but the program will not
abort immediately.
1: If an error is detected in a MPI routine, an error
message will be written and the program will abort
immediately afterwards.
iopt MPI sync Disables/enables (0/1) synchronisation calls at the end
of a series of blocking or non-blocking operations (0).
Remarks
• The non-blocking options are not yet tested and should not be used in
the current version of COHERENS.
• Synchronisation of communication calls may lower the CPU perfor-
mance.
12.4.19 User output

iopt out tsers Disables/enables (0/1) time series output (1).
iopt out avrgd Disables/enables (0/1) time averaged output (0).
iopt out anal Disables/enables (0/1) harmonic output (0).
12.4.20 NetCDF
iopt CDF abort 0: If an error is detected in a netCDF routine, an error mes-
sage will be written, but the program will not abort im-
mediately.
1: If an error is detected in a netCDF routine, an error mes-
sage will be written and the program will abort immedi-
ately afterwards.
iopt CDF fill Disables/enables (0/1) the use of fill values (0).
iopt CDF format Selects the type netCDF file format (1).
1: classic format
2: 64-bit offset format
The different netCDF file formats are discussed in the netCDF User Manual.
12.5 Model parameters

All parameters in this section are defined in usrdef mod params.
12.5.1 Date and time parameters

CStartDateTime Start date in string format (‘yyyy/mm/dd;hh:mm:ss:mmm’)
of 23 characters. If the last 4 characters are omitted they
are set to ’:000‘ by default (?).
CEndDateTime End date in string format. If the last 4 characters are omit-
ted they are set to ’:000‘ by default (?).
delt2d 2-D time step [s] (?).
ic3d number of 2-D time steps within one 3-D time step (1).
icnodal Time step (measured in units of delt2d) for an update of the
nodal tidal factors and astronomical arguments if iopt astro pars
>0. If zero, nodal corrections (amplitudes and phases) are
evaluated at the initial time only (0).
time zone Time zone, i.e. the difference of the local time with respect
to GMT [hours]. Difference is positive (negative) eastwards
(westwards) from Greenwich (0).
Remarks
• If the 2-D time step is lower than 1000 seconds, its precision is 1 mil-
lisecond and decimal numbers from the fourth position after the decimal
point will be discarded. If the time step is larger than 1000 seconds,
its precision is 1 second and its decimal part is ignored. The 2-D time
step is limited by the CFL condition (5.4) for surface gravity waves.
The maximum allowed 2-D time step is written to the “log” file.
12.5. MODEL PARAMETERS 429
• The parameter time zone is of type REAL and must be between -

12.0 and 12.0 and is used to reset the start and end dates to GMT
where necessary. A time zone must be given for the calculation of solar
radiance and the astronomical Greenwich argument at the local time
when the start and end dates are not expressed in GMT.
• It is clear that ic3d only needs to be defined for 3-D applications

(iopt grid nodim=3). Note that the 3-D time step is limited by the
constraints (5.5), (5.6).
12.5.2 Grid parameters

nc number of grid cells in the X-direction (including an extra column
along the eastern edge) (?)
nr number of grid cells in the Y-direction (including an extra column
along the northern edge) (?)
nz number of grid cells in the vertical direction (?)
nosbu number of open sea boundaries at (West/East) U-nodes (0)
nosbv number of open sea boundaries at (South/North) V-nodes (0)
nrvbu number of river boundaries at (West/East) U-nodes (0)
nrvbv number of river boundaries at (South/North) V-nodes (0)
• nc and nr must be positive and are automatically (re)set to 3 for water

column applications (iopt grid nodim=1).
• nz must be positive and is automatically (re)set to 1 for 2-D applications

(iopt grid nodim=2).
• The last row and the last column of the computational domain rep-
resent dummy (land) points. The “phyical” (horizontal) dimension of
the domain is therefore (nc-1)×(nr-1).
12.5.3 Other integer model parameters

fld mask(nofldmasks) Enables (1) or disables (0) a specific mask criterium for
the drying/flooding algorithm as given by equations (5.323)–
(5.334). Default values are fld mask(1)=1,fld mask(2:)=0. The
number of available criteria given by nofldmask equals 11 in the
current implementation and cannot be changed by the user.
nconastro number of constituents for the astronomical tidal forcing used

when iopt astro tide=1 (0)
nconobc number of constituents for the open boundary tidal forcing if
iopt grid nodim>1 or for the surface forcing if iopt grid nodim=1
(0)
norlxzones number of relaxation zones used when iopt obc relax = 1 (0)
nonestsets number of nested sub-grids used when iopt nests = 1 (0)
nowaitsecs number of seconds to wait between two read attempts [s] (0)
maxwaitsecs maximum allowed time spent in wait calls [s] (3600)
norestarts number of restart times (1)
ntrestart(1:norestarts) Restart time indices for writing of initial conditions. If
a value equals int fill, it will be replaced by the total number of
2-D time steps (int fill).
ntobcrlx The relaxation period Tr , divided by the 2-D time step delt2d,
(optionally) used to define the relaxation factor αr (t), defined
by (4.342), for the 2-D mode at open boundaries. For details
see Section 4.10.1 (0).
idmaster Process id of the master process (0). Must be between 0 and
nprocs-1.
index obc(1:nconobc) Key ids of the tidal constituents used for the tidal for-
cing at open boundaries (?).
index astro(1:nconastro) Key ids of the tidal constituents for the astronomical
tidal forcing (?).
• nowaitsecs and maxwaitsecs are used in connection to the endfile at-

tribute discussed in Section 12.7.2.
• norestarts must not exceed the value of the system parameter MaxRestarts
defined in syspars.f90.
• Key ids for tidal constituents are defined in tide.f90.
12.5.4 Physical model parameters

The defaults of parameters marked with a “*” can be generally applied and
should, in priciple, not be changed.
atmpres ref* Reference atmospheric pressure Pref [Pa] (101325.0)

bdragcoef cst Constant bottom drag coefficient Cdb when iopt bstres drag=1
[-] (0.0).
bdraglin Bottom friction velocity klin used in the linear bottom fric-
tion law if iopt bstres form=1 [m/s] (0.0).
ccharno* Charnock’s constant a used in Charnock’s relation (4.279)
[-] (0.014).
cds cst Constant surface drag coefficient Cds when iopt sflux cds=0
[-] (0.0013).
ces cst Constant surface exchange coefficient Ce when iopt sflux cehs=0
[-] (0.0013).
chs cst Constant surface exchange coefficient Ch when iopt sflux cehs=0
[-] (0.0013).
ckar* von Karman’s constant κ [-] (0.4).
dcrit fld Critical water depth dcrit used in the drying/wetting algo-
rithm [m] (0.1).
depmean cst Constant water depth used to set up a default bathymetry
[m] (0.0).
distrlx obc Maximum distance dmax (from the open boundaries) used
in the relaxation factor (5.279) for momentum advection
dlat ref Reference latitude to be used for the Coriolis frequency in
the case of a Cartesian grid [decimal degrees] (0.0).
dlon ref Reference longitude to be used for solar irradiance in the
case of a Cartesian grid [decimal degrees] (0.0).
dlon ref anal If iopt astro pars>0, harmonically analysed phases are taken
with respect to the astronomical argument for this refer-
ence longitude at the central time [decimal degrees, positive
East] (0.0).
dlon ref obc If iopt astro pars > 0, phases at open boundaries are as-
sumed to be taken with respect to the astronomical argu-
ment at this reference value [decimal degrees]. If zero, the
reference longitude is taken at Greenwich (0.0).
dmin fld Minimum water depth dmin used in the drying/wetting al-
gorithm [m] (0.02).
dthd fld Threshold water depth dth used in the mask criteria for
drying and flooding (see Section 5.4.2) [m] (0.1).
gacc ref If different from real fill, the acceleration of gravity, taken as
horizontally uniform. Otherwise, g is evaluated as function

of latitude using (4.47) [m/s2 ] (real fill).
hdifmom cst Constant coefficient for horizontal momentum diffusion νH
when iopt hdif coef=1 [m2 /s] (0.0).
hdifscal cst Constant coefficient for horizontal scalar diffusion λH when
iopt hdif coef=1 [m2 /s] (0.0).
optattcoef1 cst Inverse optical attenuation depth (λ−1
1 ) for the absorption
of long-wave solar radiation as used in (4.48)[m−1 ] (10.0).
optattcoef2 cst Inverse optical attenuation depth (λ−1 2 ) for the absorption
of short-wave solar radiation as used in (4.48) [m−1 ] (0.067).
opt frac Long-wave fraction R of surface solar radiance as used in
(4.48) [-] (0.54).
Rearth* Mean radius of the Earth R [m] (6371000.0)
rho air* Air mass density ρa [kg/m3 ] (1.2)
sal ref Reference salinity Sref used if iopt sal=0 or in the linear
equation of state (4.97) or as default initial condition [PSU]
(33.0).
smag coef mom* Smagorinsky coefficient Cm for horizontal diffusion of mo-
mentum [-] (0.1).
smag coef scal* Smagorinsky coefficient Cs for horizontal diffusion of scalars
[-] (0.1).
specheat* Specific heat of seawater cp at constant pressure [J/kg/degC]
(3987.5).
temp min Minimum temperature. If set to real fill, the minimum is
taken as the freezing point of sea water (see equation (4.38)
which is a function of salinity [deg C] (0.0).
temp ref Reference temperature Tref used if iopt temp=0 or in the
linear equation of state (4.97) or as default initial condition
[deg C] (12.0).
theta cor* Implicity factor θc for the Coriolis term [between 0.0 and
1.0] (0.5).
theta vadv* Implicity factor θa for vertical advection [between 0.0 and
1.0] (0.501).
theta vdif* Implicity factor θd for vertical diffusion [between 0.0 and
1.0] (1.0).
vdifmom cst Constant coefficient for vertical diffusion of momentum used

if iopt vdif coef=1 or as background value if iopt turb iwlim=0
[m2 /s] (10−6 ).
vdifscal cst Constant coefficient for vertical diffusion of scalars used if
iopt vdif coef=1 or as background value if iopt turb iwlim=0
[m2 /s] (10−6 ).
zrough cst Constant bottom roughness length z0 when iopt bstres drag=3
[m] (0.0).
12.5.5 Turbulence model parameters

Parameters marked with a * have been calibrated from experimental data or
obtained from turbulence theory. Their values should not be changed, unless
the user has sufficient experience in turbulence modelling.
alpha Black constant α1 in the Blackadar (1962) mixing length formulation

(4.205) [0.2]
alpha ma parameter αm in the Munk & Anderson (1948) scheme (4.125)–
(4.128) [10.0]
alpha pp parameter αp in the Pacanowski & Philander (1981) scheme
(4.121)–(4.123) [5.0]
beta ma parameter βm in the Munk & Anderson (1948) scheme (4.125)–
(4.128) [3.33]
beta Xing attenuation factor β1 in the Xing & Davies (1996) mixing
length formulation (4.203) [2.0]
cnu ad parameter Cν in equation (4.140) [2.0]
c1 eps* constant c1ε in the shear production term of the ε-equation
(4.193) [1.44]
c2 eps* constant c2ε in the dissipation term of the ε-equation (4.193)
[1.92]
c31 eps* constant c3ε in the buoyancy sink term of the ε-equation (4.193)
in case of stable stratification (N 2 > 0) [0.2]
c32 eps* constant c3ε in the buoyancy source term of the ε-equation
(4.193) in case of unstable stratification (N 2 < 0) [1.0]
c sk* Daly-Harlow parameter csk in (4.165) [0.15]
delta1 ad parameter δ1 in equation (4.132) [0.0]
delta2 ad parameter δ2 in equation (4.132) [0.0]
dissipmin* numerical lower limit εmin for ε [10−12 W/kg]

expmom ma parameter n1 in the Munk & Anderson (1948) scheme (4.125)–
(4.128) [0.5]
expmom pp parameter np in the Pacanowski & Philander (1981) scheme
(4.121)–(4.123) [2.0]
expscal ma parameter n2 in the Munk & Anderson (1948) scheme (4.125)–
(4.128) [1.5]
e1 my* constant E1 in the shear production term of the kl-equation
(4.197) [1.8]
e2 my* constant E2 in the wall proximity term (4.198) of the kl-
equation (4.197) [1.33]
e3 my* constant E3 in the buocancy source/sink term of the kl-equation
(4.197) [1.0]
k1 ad parameter K1 in equations (4.137) and (4.139) [0.0025]
k2 ad parameter K2 in equation (4.138) [2×10−5 ]
lambda ad parameter λ⋆ in equation (4.135) [0.0 m]
omega1 ad parameter ω1 in equation (4.140) [ 10−4 s−1 ]
riccrit iw critical Richardson number Ri0 in the Large et al. (1994) back-
ground mixing scheme (4.215) [0.7]
r1 ad parameter r1 in equation (4.132) [1.0]
r2 ad parameter r2 in equation (4.132) [1.0]
sigma k* parameter σk used to define Sk in (4.189) [1.0]
skeps* neutral value Sk0 of the stability coefficient Sk in the k-ε model
(see equation (4.188)) [0.09]
sq my* parameter Sq used to determine Sk0 in the Mellor-Yamada
model (see equation (4.190)) [0.2]
tkelim* background limit klim for k (see equation (4.214)) [10−6 J/kg]
tkemin* numerical lower limit kmin for k [10−14 J/kg]
vbmom pp parameter νbp in the Pacanowski & Philander (1981) scheme
(4.121)–(4.123) [10−4 m2 /s]
vbscal pp parameter λbp in the Pacanowski & Philander (1981) scheme
(4.121)–(4.123) [10−5 m2 /s]
vdifmom iw internal wave breaking diffusion coefficient νT 0 for momentum
in the Large et al. (1994) background mixing scheme (4.215)
[10−4 m2 /s]
12.6. PARAMETERS FOR SURFACE DATA GRIDS 435
vdifscal iw internal wave breaking diffusion coefficient λT 0 for scalars in

[5×10−5 m2 /s]
vdifshear iw maximum mixing due to unresolved vertical shear ν0s in the
Large et al. (1994) background mixing scheme (4.215) [0.005
m2 /s]
vmaxmom ma parameter νmax in the Munk & Anderson (1948) scheme (4.125)–
(4.128) [3.0]
vmaxscal ma parameter λmax in the Munk & Anderson (1948) scheme (4.125)–
(4.128) [4.0]
vmax pp parameter νmax in the Pacanowski & Philander (1981) scheme
(4.121)–(4.123) [3.0]
v0dif ma parameter ν0m in the Munk & Anderson (1948) scheme (4.125)–
(4.128) [0.06 m2 /s]
v0dif pp parameter ν0p in the Pacanowski & Philander (1981) scheme
(4.121)–(4.123) [0.01 m2 /s]
wfltke surface wave factor cw used in the surface flux condition (4.271)
for turbulent energy [0.0]
zlmixmin* numerical lower limit lmin for l [1.7×10−10 m]
zrough bot bottom roughness length z0b in the mixing length formulation
(4.200) [0.0 m]
zrough sur surface roughness length z0s in the mixing length formulation
(4.200) [0.0 m]
12.6 Parameters for surface data grids

Surface data grids are external grids where (e.g. meteorological) data are
defined for the surface forcing. The parameters characterising a surface grid
are stored into the 2-D array surfacegrids of DERIVED TYPE GridParams,
defined by
TYPE :: GridParams
END TYPE GridParams
TYPE (GridParams), DIMENSION(MaxGridTypes,2) :: surfacegrids
An element of the array surfacegrids can be generically represented as sur-
facegrids(igrd,ifil) where igrd is a key id, called the “grid descriptor” and ifil
the “file number”. The file number can take the value of 1 for external data
intended for input and 2 for data written by the model to the external grid.
The latter is intended for future applications and currently not implemented.
All parameters of this section are defined in usrfdef mod params.
12.6.1 Grid descriptors

The grid descriptor may take (in the current version) the following values:
igrd model model grid

igrd meteo meteorological external grid
igrd sst sea surface temperature external grid
Identifying the model grid as an external grid seems rather strange at first
sight. The intention is to provide the possibility to define a uniform rectan-
gular grid using the parameters below.
12.6.2 Grid parameters

nhtype Type of the surface data grid.
0: single grid point
3: non-rectangular (curvilinear or non-structured)
4: the same as the model grid
n1dat X-dimension of the surface grid
n2dat Y-dimension of the surface grid
delxdat grid spacings in the X-direction (meters or degrees longitude) when
nhtype=1
delydat grid spacings in the Y-direction (meters or degrees latitude) when
nhtype=1
x0dat X-coordinate (meters or degrees longitude) of the lower left corner
when nhtype=1
y0dat Y-coordinate (meters or degrees latitude) of the lower left corner
when nhtype=1
• If nhtype=1, all parameters need to be defined.

12.7. ATTRIBUTES OF FORCING FILES 437
• If nhtype=2,3, only n1dat and n2dat need to be defined.
• If nhtype=4, then n1dat=nc and n2dat=nr, and no further definitions

need to be made.
• In case of the model grid (grid type igrd=igrd model) the value of nhtype
equals the value of the switch iopt grid htype.
• The corner coordinates x0dat, y0dat and the grid spacings delxdat,
delydat are given in meters or degrees longitude and latitude depending
on whether iopt grid sph equals 0 or 1.
12.7 Attributes of forcing files

Model forcing requires the definition of pamameters and input data. They
can be directly defined by the user in one of the usrdef routines below or by
reading them for some external file. Before these data can be obtained, a
series of “file attributes” needs to be set by the user to inform the program
which parameters/data are needed and how they are accessed. These at-
tributes are stored in the 3-D array modfiles of DERIVED TYPE FileParams,
defined by
TYPE :: FileParams
INTEGER :: endfile, header type, iostat, iunit,lenrec, &
& maxrecs, nocoords, nodim, novars,timeid, &
& timerec, tskips, varid, zetaid
END TYPE FileParams
TYPE (FileParams), DIMENSION(MaxIOTypes,MaxIOFiles,2) :: &
& modfiles
Only the underlined parameters can be defined by the user, the others
are used internally in the program (e.g. iunit giving the FORTRAN file unit
number).
An element of the array modfiles can be generically represented as mod-
files(idesc,ifil,iotype) where idesc is the “file descriptor”, ifil the “file number”
and iotype represents input (output) data if 1 (2).
The meaning of the third index iotype is as follows. Almost all forcing data
(except nesting) are input data, i.e. represented by an element of modfiles
with iotype=1. By defining a corresponding output file with iotype=2 one has
the possibility to re-write the same input data now in a COHERENS standard
format. This file can be used as input within a subsequent run. The user
then needs to change only the status atrtribute from ‘N’ to ‘R’ (see below).
In case of nested output, iotype must take the value of 2.
Input data can be spread over multiple files for a given descriptor by
specifying different file numbers. This is further discussed below. The ma-
ximum value of ifil is given by the system parameter MaxIOFiles defined in
syspars.f90.
12.7.1 File descriptors

The following key ids are available as file descriptors.
io mppmod parallel decomposition (ifil=1)

io inicon initial conditions (ifil=1)
io modgrd model grid (ifil=1)
io metgrd surface meteorological grid (ifil=1)
io sstgrd sea surface temperature grid (ifil=1)
io nstgrd nested sub-grids (one file per sub-grid)
io 1uvsur specifiers for 1-D surface forcing if ifil=1, forcing data if ifil=2
io 2uvobc specifiers for 2-D mode open boundary forcing if ifil=1, open
boundary data if ifil>1
io 3uvobc specifiers for 3-D mode (baroclinic currents) open boundary for-
cing if ifil=1, open boundary data if ifil>1
io salobc specifiers for salinity open boundary forcing if ifil=1, open boun-
dary data if ifil>1
io tmpobc specifiers for temperature open boundary forcing if ifil=1, open
io bioobc specifiers for biological open boundary forcing if ifil=1, open
io rlxobc definitions of relaxation zones (ifil=1)
io nstspc specifiers for sub-grid nesting (ifil=1)
io 2uvnst 2-D open boundary data for nested sub-grids (one file per sub-
grid)
12.7. ATTRIBUTES OF FORCING FILES 439
io 3uvnst 3-D (baroclinic current) open boundary data for nested sub-grids
(one file per sub-grid)
io salnst salinity open boundary data for nested sub-grids (one file per
sub-grid)
io tmpnst temperature open boundary data for nested sub-grids (one file
per sub-grid)
io bionst biological open boundary data for nested sub-grids (one file per
sub-grid). Currently not implemented.
io metsur meteorological data (ifil=1)
io sstsur SST data (ifil=1)
12.7.2 File parameters for input forcing (iotype=1)

status Status of the data file (‘0’).
‘0’ (zero): not defined
‘N’: user-defined
‘R’: COHERENS standard file
form File format.
‘A’: ASCII (portable, sequential)
‘U’: unformatted binary (non-portable, sequential)
‘N’: netCDF format (portable, non-sequential)
filename File name (including file path if needed).
tlims Start/end/step time indices (i.e. times measured in units of delt2d).
These parameters are not directly used for reading the data, but
to make updates after tlims(3)×delt2d seconds. If tlims(3)>0, time
interpolation will be performed (see below).
info An “info” file with all header information will be created if .TRUE.
(.FALSE.).
endfile Switch to decide what action needs to be taken when an end of
file conditions occurs (0).
0: The program aborts with an error message
1: The program continues, no further attempt will be made to
read data.
2: The program continues, a next attempt to read the data will
be made after nowaitsecs seconds.
• Important to note that the status attribute equals ‘0’ by default which
means that the corresponding usrdef routine is not called by the pro-
gram.
• The meaning of tlims is illustrated as follows for the case of meteorolog-

ical forcing data. These data are used to evaluate the surface fluxes of
momentum, heat and salinity and for the atmospheric pressure gradient
in the momentum equations. All these quantities will be updated from
time tlims(1) upto time tlims(2) at time intervals given by tlims(3). The
data are read into the program with a date/time stamp which is saved.
If tlims(3)>0, which is usally shorter than the time interval between
two input dates, the meteo data are first linearly interpolated in time
between their values at the most recent date, earlier than the current
program time, and the earliest date, later than the current time. Since
these dates are stored in memory, the program knows automatically
when new data need to be read. If tlims(3)<0, the method is the same
but without time interpolation, i.e. the data at the current program
time are set to their values at the most recent date earlier than or equal
to the program time. Although it is not absolutely necessary, it is rec-
ommended that tlims(3) is smaller than the time interval between two
consecutive inputs. Note that if an element of the vector tlims is set
to the undefined value int fill, this value will be automatically replaced
by the total number of 2-D time steps in the simulation nstep, which
means that the corresponding time is set to the end date of the run.
• If endfile equals 2 and an “end of file condition” occurs during a read,

the program waits for nowaitsecs seconds before make a next attempt.
The total waiting time is given by maxwaitsecs after which the program
aborts with an error message. The procedure is intended for making
simulations in interactive mode. For example, assume that a main grid
writes the open boundary data for a nested sub-grid. If the main and
sub-grid are launched together and the former runs slower than the
latter, the nested grid will wait for input from the main grid.
12.7.3 File parameters for output forcing (iotype=2)

status Status of the data file (‘0’).
‘0’: not defined
‘W’: a COHERENS standard file will be created
form File format.
12.8. PARAMETERS FOR USER-DEFINED OUTPUT 441
‘A’: ASCII (sequential)

‘U’: unformatted binary (machine-dependent, sequential)
‘N’: netCDF format (portable, non-sequential)
filename File name (including file path if needed).
12.7.4 Other forcing attributes

Other relevant parameter components, not defined in usrdef mod params but
used internally, are:
iunit File unit. This parameter is set internally and cannot be defined by
the user.
iostat File I/O status
-1: open error occurred
0 : file not opened
1 : file is open and file pointer is located at the start or before the
end of the file
2 : file pointer is located at the end of the file (i.e. an EOF condition
will occur on a next read)
3 : an end of file condition did occur
12.8 Parameters for user-defined output

A few general parameters need to be specified in usrdef mod params for user-
defined output. They need to be defined in usrdef mod params. All other
specifiers for user-defined output are to be defined in other Usrdef files. For
more details about the meaning of the parameters below, see Section 7.6.
nosetstsr number of time series file sets if iopt out tsers=1 (0)
nostatstsr number of time series output stations if iopt out tsers=1 (0)
novarstsr number of time series variables if iopt out tsers=1 (0)
nosetsavr number of time averaged file sets if iopt out avrgd=1 (0)
nostatsavr number of time averaged output stations if iopt out avrgd=1 (0)
novarsavr number of time averaged variables if iopt out avrgd=1 (0)
nosetsanal number of harmonic file sets if iopt out anal=1 (0)
nofreqsanal number of harmonic frequencies if iopt out anal=1 (0)
nostatsanal number of harmonic output stations if iopt out anal=1 (0)

novarsanal number of harmonic variables if iopt out anal=1 (0)
intitle title used to create names of model forcing files
outtitle title used to create names of user output files
12.9 Domain decomposition

The domain decomposition is defined in usrdef partition. This routine is
called in parallel mode by reader processes if iopt MPI partit=2 and mod-
files(io mppmod,1,1)%status=‘N’.
nc1procs(nprocs) global X-index of lower left cell of the process domains

nc2procs(nprocs) global X-index of lower right cell of the process domains
nr1procs(nprocs) global Y-index of lower left cell of the process domains
nr2procs(nprocs) global Y-index of lower right cell of the process domains
Chapter 13
Model grid and initial

conditions
The chapter explains the setup of model grid, bathymetry and physical initial
conditions, defined in the Usrdef Model.f90 routines:
• usrdef grid: model grid and bathymetry
• usrdef phsics: initial conditions
13.1 Model grid and bathymetry

This section describes the arrays defined in the routine usrdef grid. The
routine is called by reader processes if modfiles(io modgrd,1,1)%status=’N’. If
the status attribute equals ‘R’, the program calls the routines read grid where
the grid and bathymetric arrays are read in standard format.
The list below specifies all arrays which could be defined here.
gxcoordglb(1:nc,1:nr) X-coordinates (Cartesian or spherical) at the UV-nodes
(corner points) [m or fractional degrees]. Definition depends on
the value of iopt grid htype:
1 : No definition is needed. The coordinates are generated by
the program using the attributes of surfacegrid(igrd model,1)
defined in usrdef mod params.
2 : Define only gxcoordglb(1:nc,1), the other rows are automat-
ically generated by the program.
3 : The grid is curvilinear and the full array has to be defined
here.
443
444 CHAPTER 13. MODEL GRID AND INITIAL CONDITIONS
gycoordglb(1:nc,1:nr) Y-coordinates (Cartesian or spherical) at the UV-nodes

(corner points) [m or fractional degrees]. Definition depends on
the value of iopt grid htype:
1 : No definition is needed. The coordinates are generated by
the program using the attributes of surfacegrid(igrd model,1)
defined in usrdef mod params.
2 : Define only gycoordglb(1,1:nr), the other columns are auto-
matically generated by the program.
3 : The grid is curvilinear and the full array has to be defined
here.
gsigcoord(nz+1) σ-coordinates in case of an horizontally uniform and verti-
cally non-uniform σ-grid. Define only when iopt grid vtype=2.
gscoordglb(1:nc-1,1:nr-1,nz+1) σ-coordinates in case of non-uniform σ-grid
in both the vertical and horizontal directions. Define only when
iopt grid vtype=3.
depmeanglb(1:nc-1,1:nr-1) mean water depths (bathymetry) [m]
iobu(nobu) (Global) X-index of the (West/East) open boundary points at
U-nodes
jobu(nobv) (Global) Y-index of the (West/East) open boundary points at
U-nodes
iobv(nobv) (Global) X-index of the (South/North) open boundary points at
V-nodes
jobv(nobv) (Global) Y-index of the (South/North) open boundary points at
V-nodes
Remarks
• In case of a parallel application, all arrays are defined on the “global”
grid.
• Coordinate units in the horizontal are m or fractional degrees depending
on whether iopt grid sph equals 0 or 1.
• In case of a uniform vertical σ-grid (iopt grid vtype=1), the σ-levels
are uniformly distributed over the vertical. This is automatically per-
formed by the program.
• In case that a uniform water depth is taken, no bathymetry needs to be
defined here. Before calling usrdef grid the program sets, by default, all
water depths to the value of depmean cst defined in usrdef mod params.
13.2. INITIAL PHYSICAL CONDITIONS 445
• nobu and nobv are the total (open sea and river) number of open boun-
dary points at U- and V-nodes. They are obtained from the values of
nosbu, nrvbu, nosbv, nrvbv defined in usrdef mod params.
• An open boundary must be located either at a velocity node on the

edge of the “physical” domain or a velocity node separating a land
and a sea cell. Note that open boundaries cannot be located near cells
where a drying process can take place.
• If the model is applied to simulate the inundation of land areas (iopt fld=2),
the bathymetry should include the land topography of the areas which
can potentially be flooded. For details see Section 5.4.2.
• Negative values of depmeanglb are not allowed. Zero values indicate

grid cells which are permanently dry and cannot be inundated.
13.2 Initial physical conditions

Routine usrdef phsics defines the initial conditions for the physical module.
The routine is called by all processes if modfiles(io phsics,1,1)%status=‘N’.
If the status attribute equals ‘R’, the program calls the routine read phsics
where the initial conditions are obtained in standard format.
The initialisation of some variables depends on the values of switches.
Some arrays are defined “locally”. In that case, the arrays must be given
with a different shape, depending on whether the model is applied in parallel
or serial mode (see below). Note that the shapes may be different from the
ones used in the program itself.
2-D mode
udvel Depth-integrated current in the X-direction [m2 /s]. Shape is

(nc,nr) in serial and (ncloc,nrloc) in parallel mode.
vdvel Depth-integrated current in the Y-direction [m2 /s]. Shape is
(nc,nr) in serial and (ncloc,nrloc) in parallel mode.
zeta Surface elevation [m]. Shape is (nc-1,nr-1) in serial and (ncloc,nrloc)
in parallel mode.
3-D currents
uvel Current in the X-direction [m/s]. Shape is (nc,nr,nz) in serial and

(ncloc,nrloc,nz) in parallel mode. Define only for 1-D and 3-D
applications.
vvel Current in the Y-direction [m/s]. Shape is (nc,nr,nz) in serial and

(ncloc,nrloc,nz) in parallel mode. Define only for 1-D and 3-D
applications.
wvel Transformed vertical current [m/s]. Shape is (nc-1,nr-1,nz+1) in
serial and (ncloc,nrloc,nz+1) in parallel mode. Define only for 3-D
applications.
density arrays
temp Temperature [deg C]. Define only when iopt temp>0.

sal Salinity [PSU]. Define only when iopt sal>0.
The shape of both arrays is (nc-1,nr-1,nz) in serial and (ncloc,nrloc,nz)

in parallel mode.
turbulence arrays
Turbulence arrays can be defined if a RANS model (see Section 4.4.3)
is selected (iopt vdif coef=3).
tke Turbulent kinetic energy [J/kg].
zlmix Mixing length [m]. Define only for a two-equation k − l model
(iopt turb ntrans=2 and iopt turb param=1).
dissip Dissipation of turbulent energy [W/kg]. Define only for a two-
equation k−ε model (iopt turb ntrans=2 and iopt turb param=2).
The shapes of the arrays are (nc-1,nr-1,2:nz) in serial and (ncloc,nrloc,2:nz)

in parallel mode.
arrays for bottom stres
bdragcoefatc Bottom drag coefficient [-]. Define only when iopt bstres drag=2.
zroughatc Bottom roughness length [m]. Define only when iopt bstres drag=4.
The shapes of the arrays are (nc-1,nr-1) in serial and (ncloc,nrloc) in

parallel mode.
tidal arrays
fnode obc(nconobc) nodal factors of tidal constituents at open boun-

daries [-]
phase obc(nconobc) Greenwich arguments of tidal constituents at
open boundaries [rad]
fnode astro(nconastro) nodal factors of tidal constituents used for as-

tronomical forcing [-]
phase astro(nconastro) Greenwich arguments of tidal constituents used
for astronomical forcing [rad]
The phases need to be defined if iopt astro pars=0, the nodal factors
if iopt astro pars=0,1. Otherwise, the phases and nodal factors will be
automatically initialised by the program itself.
open boundary arrays

The arrays below represent “storage” arrays used in case the open boun-
dary conditions at specific nodes require the solution of a differential
equation in time. The following arrays are used for the 2-D mode
obc2uvatu(nobu,2) 2-D mode at U-open boundaries (iopt obc 2D=1)

obc2uvatv(nobv,2) 2-D mode at V-open boundaries (iopt obc 2D=1)
The meaning of the last index in the open boundary arrays depends on
the type of open boundary condition1, 2 .
6 : Orlanski
1: U or V at the interior point nearest to the open boundary
2: U or V at the interior point second nearest to the open boundary
7 : Camerlengo-O’Brien
2: U or V at the interior point second nearest to the open boundary
9 : Flather with specified elevation
2: U L or V L at the previous time step
10: Flather
1: ζ L at the previous time step
2: U L or V L at the previous time step
11: Røed and Smedstad
1: outgoing characteristic
12: characteristic method with specified elevation
1
The number in the main list below refers to the value of ityp2dobu or ityp2dobv defined
in Section 14.1.1.1 or to the description list in Section 4.10.1.
2
The number in the list refers to the index in the last dimension of the array.
13: characteristic method using zero normal gradient

2: incoming characteristic
The following additional arrays are used for application of the open
boundary conditions of scalar quantitities (baroclinic currents, T , S),
denoted by ψ below
obc3uvatu(nobu,nz,2) 3-D baroclinic current at U-open boundaries

(iopt obc 3D=1)
obc3uvatv(nobv,nz,2) 3-D baroclinic current at V-open boundaries
(iopt obc 3D=1)
obctmpatu(nobu,nz,0:2) temperature at U-open boundaries (iopt obc temp=1)
obctmpatv(nobv,nz,0:2) temperature at V-open boundaries (iopt obc temp=1)
obcsalatu(nobu,nz,0:2) salinity at U-open boundaries (iopt obc sal=1)
obcsalatv(nobv,nz,0:2) salinity at V-open boundaries (iopt obc sal=1)
The index of the last dimension in the array has the following meaning
0: open boundary value of ψ at the open boundary (scalars only)

1: value of ψ at the interior point nearest to the open boundary
2: value of ψ at the interior point second nearest to the open boundary
The open boundary arrays are usually not created by the user but
obtained from a previous run in which case the data are read from an
external file.
remarks
• Initial condition arrays can be obtained from an external data file.

This may create an extra overhead if the program runs in parallel
mode, since the data arrays are usually defined on a global grid.
This mean that, after reading the global arrays, they must be
distributed onto the local grids. Details are found in the example
code of usrdef phsics in the file examples/Usrdef.f90.
• In case an inundation scheme is applied, a negative surface ele-
vation can be supplied in land areas, which are taken intially as
dry, but may be inundated at a later time. See Section 5.4.2 for
details.
defaults If a variable is not defined, the following defaults are assumed (see
Section 4.11):
• transports, currents, elevations: 0

• temperature: uniform value given by temp ref, defined in usrdef mod params
• salinity: uniform value given by sal ref, defined in usrdef mod params
• turbulence: see Section 4.11
• bottom stress arrays: 0
• astronomical phases: 0
• nodal factors: 1
• open boundary arrays: 0
Chapter 14
Open boundary conditions
This chapter deals with the setup of the open boundary conditions for the
2-D and 3-D mode. The following routines, located in Usrdef Model.90, are
discussed in the next four sections:
• usrdef 2dobc spec: specifies the type of conditions for the 2-D mode
• usrdef 2dobc data: defines the input of open boundary data for the 2-D
mode
• usrdef profobc spec: specifies the type of conditions for the 3-D mode
• usrdef profobc data: defines the input of open boundary data for the
3-D currents and scalars
• usrdef rlxobc spec: setup for applying the relaxation open boundary
scheme
14.1 2-D mode

14.1.1 Open boundary specifiers for the 2-D mode
The routine usrdef 2dobc spec is called if iopt obc 2D=1 and
modfiles(io 2uvobc,1,1)%status=‘N’. Important to note is that the file index
for open boundary specifiers is 1. The open boundary data itself are defined
in files whose attributes are stored in modfiles(io 2uvobc,ifil,1) where ifil takes
values of 2 upto nofiles. The number of associated data files is therefore given
by nofiles-1.
External (specified) values for U , V or ζ are written in the general form
(4.340). The first part ψ0e must be defined in usrdef 2dobc data, usually as
451
452 CHAPTER 14. OPEN BOUNDARY CONDITIONS
time series input from a data file. The amplitudes An and phases ϕn are
time-independent and must be defined in usrdef 2dobc spec together with
the arrays discussed below.
14.1.1.1 general specifiers

ityp2dobu(nobu) Type of open boundary condition at U-nodes. See Sec-
tion 4.10.1 for details (0).
0 : clamped
1 : zero slope
2 : zero volume flux
3 : specified elevation
4 : specified transport
5 : radiation condition using shallow water speed
6 : Orlanski (1976) condition
7 : Camerlengo & O’Brien (1980)
8 : Flather (1976) with specified elevation and transport
10: Røed & Smedstad (1984)
11: characteristic method with specified elevation and trans-
port
13: characteristic method using a zero normal gradient con-
dition
ityp2dobv(nobv) Type of open boundary condition at V-nodes. Meaning is
the same as above with U replaced by V and West/East by
South/North (0).
iloczobu(nobu) If the elevation has to be specified at the open boundary,
the array selects the position of the specified elevation with
respect to the open boundary.
0: not required
1: at the open boundary U-node
2: at the “nearest” C-node outside the domain
iloczobv(nobv) As previous now for V-node open boundary points.
14.1. 2-D MODE 453
itypintobu(nobu) Disables/enables advection of momentum next to U-open

boundaries if iopt obc int=1 (0/1).
itypintobv(nobv) Disables/enables advection of momentum next to V-open
boundaries if iopt obc int=1 (0/1).
14.1.1.2 specifiers for the data files

no2dobc(2:nofiles) number of data locations within each data file
iobc2dtype(2:nofiles) identifies the variables within the data file
1: depth-integrated currents and elevations

2: elevations only
3: depth-integrated currents only
index2dobc(nobu+nobv,2:nofiles) Each data file contains a sub-set of open

boundary data points. The element index2dobc(idat,ifil)
maps, for file ifil, the local data point idat into a corres-
ponding global open boundary index (between 1:nobu
for U- and nobu+1:nobu+nobv for V-open boundaries).
The physical size of the first dimension for file ifil equals
no2dobc(ifil).
The procedure is illustrated in Figure 14.1. The filled circles represent open
boundary points. The data are spread over 4 data files. The number in
parentheses denotes the number of the data file (between 2 and 5), the second
number to the right the open boundary index ranging from 1 to nobu at U-
nodes and nobu+1 to nobu+nobv at V-nodes. In the example, nobu=11 and
nobv=8. Each file contains data for the following points:
• ifil=2: data at (U-)o.b. points 1 to 8
• ifil=3: data at (U-)o.b. points 9 to 11
• ifil=4: data at (V-)o.b. points 12 to 14
• ifil=5: data at (V-)o.b. points 15 to 18
• ifil=6: data at (V-)o.b. point 19
The definitions in FORTRAN code are:

(5) 15 (5) 16 (5) 17 (5) 18
(2) 8
(2) 7
(2) 6 (3) 11
(2) 5 (3) 10
(2) 4 (3) 9
(2) 3
(2) 2 (6) 19
(2) 1
(4) 12 (4) 13 (4) 14
nobu = 11, nobv = 8
Figure 14.1: Example showing how to define the arrays no2dobc and in-
dex2dobc.
nofiles = 6
no2dobc = (/8,3,3,4,1/)
index2dobc(1:8,2) = (/1,2,3,4,5,6,7,8/)
index2dobc(1:3,3) = (/9,10,11/)
index2dobc(1:3,4) = (/12,13,14/)
index2dobc(1:4,5) = (/15,16,17,18/)
index2dobc(1,6) = 19
If iobc2dtype(ifil)=1, each data location in file ifil contains two data values
(one for the depth-integrated current and one for the surface elevation).
Otherwise, only one data is defined (either depth-integrated current of el-
evation).
14.1. 2-D MODE 455
14.1.1.3 amplitudes and phases

ud2obu amp(nobu,nconobc) amplitudes of the depth-integrated current U at
U-open boundaries [m2 /s]
vd2obv amp(nobv,nconobc) amplitudes of the depth-integrated current V at
V-open boundaries [m2 /s]
zetobu amp(nobu,nconobc) amplitudes of the surface elevation ζ at U-open
boundaries [m]
zetobv amp(nobv,nconobc) amplitudes of the surface elevation ζ at V-open
boundaries [m]
ud2obu pha(nobu,nconobc) phases of the depth-integrated current U at U-
vd2obv pha(nobv,nconobc) phases of the depth-integrated current V at V-
zetobu pha(nobu,nconobc) phases of the surface elevation ζ at U-open boun-
daries [rad]
zetobv pha(nobv,nconobc) phases of the surface elevation ζ at V-open boun-
daries [rad]
By default, the program uses zero values for amplitudes and phases. In
that case, the program will (obviously) not make an harmonic expansion of
harmonic constituents, even when the tidal frequencies index obc are defined
in usrdef mod params.
14.1.2 Open boundary data for the 2-D mode

The data for 2-D mode open boundary conditions are defined in usrdef 2dobc data
which is called if iopt obc 2D=1 and modfiles(io 2uvobc,ifil,1)%status=‘N’ where
ifil is the file index of the data file. The routine is declared in the program
as follows:
SUBROUTINE usrdef 2dobc data(ifil,ciodatetime,data2d,nodat,novars)

CHARACTER (LEN=lentime), INTENT(INOUT) :: ciodatetime
INTEGER, INTENT(IN) :: ifil, nodat, novars
REAL, INTENT(INOUT), DIMENSION(nodat,novars) :: data2d
where
ifil file number index of the data file (>1)

nodat the number of data points given by no2dobc(ifil)
novars the number of data variables depending on the value of

iobc2dtype(ifil)
1: novars equals 2 since both depth integrated current and surface
elevation data are required.
2: novars equals 1 since only surface elevation data are required.
3: novars equals 1 since only depth integrated current data are re-
quired.
The arguments of INTENT(INOUT) and INTENT(OUT) need to be de-

fined here. They have the following meaning:
ciodatetime date/time of the input data in string format1

data2d values of the open boundary data
14.2 3-D mode

14.2.1 Open boundary specifiers for the 3-D mode
The specifier arrays for open boundary conditions in the 3-D case are defined
in usrdef profobc spec. The routine is called by the program for 3-D baroclinic
currents and all 3-D scalar quantities for which a transport equations needs to
be solved (currently T and S). No conditions are to be defined for turbulence
variables, which are solved with the default zero gradient condition at the
open boundaries. The routine is declared with several arguments:
SUBROUTINE usrdef profobc spec(iddesc,itypobu,itypobv,iprofobu,&

& iprofobv,iprofrlx,noprofsd,&
& indexprof,indexvar,novars,nofiles)
INTEGER, INTENT(IN) :: iddesc, nofiles, novars
INTEGER, INTENT(INOUT), DIMENSION(2:nofiles) :: noprofsd
INTEGER, INTENT(OUT), DIMENSION(nobu) :: itypobu
INTEGER, INTENT(OUT), DIMENSION(nobv) :: itypobv
INTEGER, INTENT(INOUT), DIMENSION(nobu,novars) :: iprofobu
INTEGER, INTENT(INOUT), DIMENSION(nobv,novars) :: iprofobv
INTEGER, INTENT(INOUT), DIMENSION(novars*(nobu+nobv),2:nofiles) :: indexprof
INTEGER, INTENT(INOUT), DIMENSION(novars*(nobu+nobv),2:nofiles) :: indexvar
INTEGER, INTENT(INOUT), DIMENSION(norlxzones) :: iprofrlx
1
If the parameter time zone is defined with a non-zero value, the time of the input data
must be given in local time.
14.2. 3-D MODE 457
The INTENT(IN) arguments have the following meaning:
iddesc The file descriptor key id of the 3-D quantity which may take the
following values
io 3uvobc baroclinic currents
io salobc salinity
io tmpobc temperature
io bioobc biological variables (currently not implemented)
nofiles the number of data files plus 1 (the file index for data files ranges
from 2 to nofiles)
novars the number of variables for which open boundary conditions are de-
fined. Value in the current implementation is 1.
The routine is called if the appropriate switch (iopt obc 3D, iopt obc sal,
iopt obc temp) is set to 1 and modfiles(iddesc,1,1)%status=‘N’.
14.2.1.1 general specifiers

itypobu type of open boundary condition at U-nodes. In case of baroclinic
currents
0: External data profile or first order zero gradient (default) condi-
tion
1: Second order zero gradient condition
2: Local solution
3: Radiation condition using internal wave speed
4: Orlanski type of radiation condition
In case of C-node scalar(s)
0: default, i.e. zero gradient condition or specified external profile
1: radiation condition using the internal wave speed
2: Orlanski condition
itypobv type of open boundary condition at V-nodes. Definitions are the
same as above for itypobu.
iprofobu profile number used at U-open boundaries (0 is none)
iprofobv profile number used at V-open boundaries (0 is none)
iprofrlx Disables/enables the application of the open boundary relaxation

scheme within the zones defined in usrdef rlxobc spec (0/1). See
Section 14.3 below. Default is 0.
Remarks
• If, at an U-open boundary point with index ii, itypobu(ii)=0 then a

zero gradient condition applies for variable ivar if iprofobu(ii,ivar)=0,
whereas a positive value of iprofobu(ii,ivar) designates the external pro-
file number used at this point. Negative values are not allowed. The
procedure is obviously the same for the arrays itypobv and iprofobv at
V-open boundaries
• The method allows to use the same profile at different open boundary
points.
• The data profiles itself are defined as time series in usrdef profobc data.
• By default, itypobu, itypobv, iprofobu, iprofobv are set to zero.
14.2.1.2 specifiers for the data files

noprofsd number of profiles per data file
indexprof Each data file contains a sub-set of open boundary profiles. The el-
ement indexprof(iprof,ifil) maps, for file ifil, the local profile number
iprof into a corresponding “global” index as defined by iprofobu and
iprofobv. The physical size of the first dimension for file ifil equals
noprofsd(ifil). If not defined and nofiles=2, the program sets index-
prof(1:noprofsd(2),2) = (/(1,2,...,noprofsd(2))/). The procedure is
illustrated with an example below.
indexvar Defines the variable number of the data profiles (for current ver-
sions where novars>1). The array is not used in the current imple-
mentation and does not need to be defined.
The procedure is illustrated in Figure 14.2. The filled circles represent

open boundary points. The data are spread over 4 data files. The number
in parentheses denotes the number of the data file (between 2 and 5), the
second number to the right the number of the profile applied at the open
boundary location. In the example a zero gradient condition is applied at
the eastern boundary. The data files contain the following profiles
• ifil=2: profiles 1 and 2

14.2. 3-D MODE 459
• ifil=3: profile 3
In FORTRAN code, the definitions become
nobu = 11; nobv = 8

itypobu = 0; itypobv = 0
iprofobu = (/1,1,1,1,2,2,2,2,0,0,0/)
iprofobv = (/3,3,3,4,4,4,4,5/)
nofiles = 5; noprofsd(2:5) = (/2,1,1,1/)
indexprof(1:2,2) = (/1,2/)
indexprof(1,3) = 3
indexprof(1,4) = 4
indexprof(1,5) = 5
If novars>1 (only for future versions), the profiles of different variables

can be spread over more than one file. The following additional definitions
can be made in future versions
novarsd number of variables per data file. If there is only one data file (nofiles
= 2), the program sets novarsd(2) to novars by default.
iobctype Mapping array for variable indices.
In the current version of COHERENS, novars=1, novarsd=1 and iobctype=1.

These defaults are, currently, not to be changed.
14.2.2 Open boundary data for the 3-D mode

The data for 3-D mode open boundary conditions are defined in usrdef profobc data
which is called if the appropriate switch (iopt obc 3D, iopt obc sal, iopt obc temp)
equals 1 and modfiles(iddesc,ifil,1)%status=‘N’ where iddesc if the file descrip-
tor id and ifil the file index of the data file. The routine is declared in the
program as follows:
SUBROUTINE usrdef profobc data(iddesc,ifil,ciodatetime,psiprofdat,numprofs)

INTEGER, INTENT(IN) :: iddesc, ifil, numprofs
REAL, INTENT(INOUT), DIMENSION(numprofs,nz) :: psiprofdat

profiles at open boundaries
(4) 4 (4) 4 (4) 4 (4) 4
(2) 2
(2) 2
(2) 2 0
(2) 2 0
(2) 1 0
(2) 1
(2) 1 (5) 5
(2) 1
(3) 3 (3) 3 (3) 3
Figure 14.2: Example how to define the open boundary specifier arrays.
14.3. SPECIFIERS FOR RELAXATION OPEN BOUNDARY CONDITIONS 461
iddesc The file descriptor key id of the 3-D quantity which may take the
following values:
io salobc salinity
ifil file number index of the data file (>1)
numprofs The number of profiles which must be equal to noprofsd(ifil).
The following INTENT(OUT) variables must be defined here
ciodatetime date/time of the profile data in string format1

psiprofdat values of the profile data
Values in the data array which are lower than or equal to the flag value
real min are considered as flagged. In that case the open boundary condition
at that specific vertical location (only) is changed from an external data pro-
file to a zero gradient condition. This may be used e.g. to prevent unrealistic
data input below a pycnocline depth. Note that the vertical profile data of
baroclinic currents must be either all flagged or all non-flagged.
14.3 Specifiers for relaxation open boundary

conditions
Open boundary relaxation is discussed in Section 4.10.3. The following ar-
rays need to be defined in routine usrdef rlxobc spec if iopt obc relax=1 and
modfiles(io rlxobc,1,1)%status=‘N’:
inodesrlx(2) Disables/enables relaxation at different nodes (0/1)

1: C-nodes
2: U- and V-nodes
idirrlx(norlxzones) Determines position of each zone
1: West
2: East
3: South
4: North
ityprlx(norlxzones) Type of interpolation scheme

1: linear
2: quadratic
3: hyperbolic
iposrlx(norlxzones) (global) X-index of the lower left corner of each zone
jposrlx(norlxzones) (global) Y-index of the lower left corner of each zone
ncrlx(norlxzones) size of the zones (number of grid points) in the X-direction
nrrlx(norlxzones) size of the zones (number of grid points) in th Y-direction.
An illustrative case is shown in Figure 14.3 showing a case with four boundary
zones.The FORTRAN definitions become
norlxzones = 4
idirrlx = (/1,3,2,4/)
iposrlx = (/1,1,nc-2,5/)
jposrlx = (/9,1,1,nr-1/)
ncrlx = (/2,15,2,10/)
nrrlx = (/9,3,nr-1,1/)
The following general remarks have to be given
• A relaxation zone can have only one relaxation direction. For exam-
ple, zone 2 in the example has two adjacent open boundaries but the
scheme is only applied in the Y-direction along the southern boundary
(idirrlx(2)=3) since the area is defined as “southern”. In the same way
no relaxation is applied towards the southern and northern boundaries
within zone 3 since idirrlx(3)=2.
• The zones are defined as rectangles. This means that the scheme can
only be used at straight and not at ragged (“stair-case”) open bounda-
ries.
• No relaxation is applied at a center or velocity node grid point, if the
line segment, normal to the open boundary, which joins this point and
the corresponding open boundary location crosses a dry cell or a solid
velocity interface.
• The scheme can be activated for 3-D baroclinic currents, temperature
and salinity by setting iopt obc relax to 1 and the appropiate elements
of the vector iprofrlx to 1 for each specific variable. Note that relaxation
of 2-D transports is not available in the current implementation.
14.3. SPECIFIERS FOR RELAXATION OPEN BOUNDARY CONDITIONS 463
Figure 14.3: Example definitions of open boundary zones for application of

the relaxation scheme.
Chapter 15
Surface forcing and nesting
This chapter discusses the setup of the surface forcing needed for the applica-
tion of surface boundary conditions and the procedures for defining nesting.
The following routines are described in the next sections:
• usrdef 1dsur spec: specifies the setup of boundary forcing for water col-
umn applications (1-D mode)
• usrdef 1dsur data: defines the input of surface forcing data for water
column applications
• usrdef surface absgrd: defines a surface data grid using absolute coordi-
nates
• usrdef surface relgrd: defines a surface data grid using relative coordi-
nates
• usrdef surface data: defines the input of surface data for a specific data
grid
• usrdef nstgrd spec: general definitions for nesting (e.g. number of sub-
grid data points)
• usrdef nstgrd abs: geographical (absolute) positions of the sub-grid (nested)

data points
• usrdef nstgrd rel: relative coordinates of the sub-grid (nested) data

points with respect to the model grid
The first two routines are contained in Usrdef Model.f90, the next three in
Usrdef Surface Data.f90 and the last three in Usrdef Nested Grids.f90 (see
Table 11.1).
465
466 CHAPTER 15. SURFACE FORCING AND NESTING
15.1 Water column surface forcing

The routines below are only used for 1-D applications (iopt grid nodim=1).
15.1.1 Surface forcing specifiers for the 1-D mode

Contrary to the 2-D and 3-D case, the surface elevation and the horizontal
pressure gradient are in the case of a water column application (iopt grid nodim=
1) not calculated by the model but are considered as an external forcing
at the surface instead. The subroutine usrdef 1dsur spec describes specifier
arrays for this water column surface forcing and is called if iopt sur 1D=1
and modfiles(io 1uvsur,1,1)%status =‘N’. The following arrays can be defined
here:
gxslope amp(nconobc) amplitudes of the X-component of the pressure gradi-
ent divided by ρ0 [m2 /s]
gxslope pha(nconobc) phases of the X-component of the pressure gradient
[rad]
gyslope amp(nconobc) amplitudes of the Y-component of the pressure gradi-
ent divided by ρ0 [m2 /s]
gyslope pha(nconobc) phases of the Y-component of the pressure gradient
[rad]
zetadat amp(nconobc) amplitudes of the surface elevation [m]
zetadat pha(nconobc) phases of the surface elevation [rad]
isur1dtype selects the type of variables if they are supplied from
an external data file, i.e. when (modfiles(io 1uvsur,2,1)%status
= ‘N’ or ‘R’)
1: components of the pressure gradient and elevation
2: surface elevation
3: components of the pressure gradient
The size nconobc of the arrays denotes, in this case, the number of tidal con-
stituents. Note also that the pressure gradient is normalised by the reference
density ρ0 .
15.1.2 Surface forcing data for the 1-D mode

The data for the water column forcing are defined in the routine usrdef 1dsur data.
The routine is called if iopt sur 1D=1 and modfiles(io 1uvsur,2,1)%status=‘N’.
The routine is declared as follows:
15.2. 2-D SURFACE FORCING 467
SUBROUTINE usrdef 1dsur data(ciodatetime,data1d,novars)

INTEGER, INTENT(IN) :: novars
REAL, INTENT(INOUT), DIMENSION(novars) :: data1d
where
novars the number of data variables depending on the value of

isur1dtype
1: three data values (X- and Y-component of the pressure gradient
and elevation)
2: one data value (elevation)
3: two data values (X- and Y-component of the pressure gradient)
The following information has to be obtained:
ciodatetime date/time in string format1

data1d forcing data. The array elements are:
1: X-component of the pressure gradient if isur1dtype=1 or 3,
surface elevation if isur1dtype=2
2: Y-component of the pressure gradient if isur1dtype=1 or 3
3: surface elevation if isur1dtype=1
15.2 2-D surface forcing

15.2.1 Surface grid in absolute coordinates
The subroutine usrdef surface absgrd defines a surface data grid in “absolute”
(geographical) coordinates. The X- and Y-coordinates are Cartesian or sphe-
rical depending on the value of the switch iopt grid sph. The routine is called
when
• the grid is rectangular and non-uniform: surfacegrids(idgrd,ifil)%nhtype=2

where idgrd is the grid key id (see below)
• modfiles(iddesc,ifil,1)%status=‘N’ where iddesc is the file descriptor and

ifil the file index (see below)
1
If the parameter time zone is defined with a non-zero value, the time of the input data
must be given in local time.
• the switch iopt meteo is set to 1 in the case of a meteorological grid
• the switch iopt temp sbc equals 2 or 3 in the case of a SST (sea surface
temperature) grid
SUBROUTINE usrdef surface absgrd(iddesc,ifil,n1dat,n2dat,xcoord,ycoord)

INTEGER, INTENT(IN) :: iddesc, ifil, n1dat, n2dat
REAL, INTENT(INOUT), DIMENSION(n1dat,n2dat) :: xcoord, ycoord
iddesc The file descriptor of the corresponding data file. The key id in paren-
theses below is the associated grid key id (idgrd).
io metgrd surface meteo grid (igrd meteo)
io sstgrd surface grid for sea surface temperature (SST, igrd sst)
ifil file index. In the current version its value is 1.
n1dat X-dimension of the data grid equal to surfacegrids(idgrd,ifil)%n1dat
n2dat Y-dimension of the data grid equal to surfacegrids(idgrd,ifil)%n2dat
The following arrays need to be given here:
xcoord(n1dat,n2dat) X-coordinates [m or degrees longitude]

ycoord(n1dat,n2dat) Y-coordinates [m or degrees latitude]
15.2.2 Surface grid in relative coordinates

The subroutine usrdef surface relgrd defines a surface data grid in “relative”
coordinates. Currently, the routine is only used to obtain the coordinates of
the model C-grid points relative to a data grid.
The routine is called when
• The grid is non-rectangular: surfacegrids(idgrd,ifil)%nhtype=3 where id-

grd is the grid key id (see below)

ifil the file index (see below)
• The switch iopt meteo is set to 1 in the case of a meteorological grid
• The switch iopt temp sbc equals 2 or 3 in the case of a SST grid
15.2. 2-D SURFACE FORCING 469
The relative coordinates are stored in a DERIVED TYPE array of type HRel-
ativeCoords:
where icoord, jcoord are the indices in the X- and Y-direction of the grid
cell containing the data point and xcoord, ycoord the normalised Cartesian
coordinates (between 0 and 1) with respect to axes along the cell faces and
origin at the lower left corner.
The routine is declared as
SUBROUTINE usrdef surface relgrd(iddesc,ifil,surfgridglb,nx,ny,&

& nonodes)
INTEGER, INTENT(IN) :: iddesc, ifil, nonodes, nx, ny
TYPE (HRelativeCoords), INTENT(INOUT), DIMENSION(nx,ny,nonodes)&
& :: surfgridglb
where
iddesc The file descriptor of the corresponding data file. The key id in
parentheses below is the associated grid key id (idgrd).

io sstgrd surface grid for SST (igrd sst)
ifil file index. In the current version its value is 1.

nx Currenly equal to the global X-dimension nc of the model grid.
ny Currenly equal to the global Y-dimension nr of the model grid.
nonodes Number of nodes. In the current implementation its value equals 1.
The relative coordinates, defined in this routine, must be stored in the

array:
surfgridglb relative coordinates of the model C-node grid with respect to a

data grid represented by iddesc
15.2.3 Surface forcing data

The surface forcing data are defined in usrdef surface data. The routine is
called if

ifil the file index (see below).
• The switch iopt meteo is set to 1 in the case of a meteorological grid.
• The switch iopt temp sbc equals 2 or 3 in the case of a SST (sea surface
temperature) grid.
The routine is declared as
SUBROUTINE usrdef surface data(iddesc,ifil,ciodatetime,&

& surdata,n1dat,n2dat,novars)
INTEGER, INTENT(IN) :: iddesc, ifil, novars, n1dat, n2dat
REAL, INTENT(INOUT), DIMENSION(n1dat,n2dat,novars) :: surdata
where
iddesc The file descriptor of the corresponding data file:

io metsur surface meteo data
io sstsur surface SST data
ifil The file index. In the current version its value is 1.
novars Number of data variables. In case of meteorological data its value
ranges from 2 to 7, in case of SST data its value is 1.
The number and type of meteorological data depends on the values of the
switches iopt meteo stres, iopt meteo heat and iopt meteo salflx (see Section
12.4.15).
The data, to be defined, are:
ciodatetime date/time in string format1

surdata surface forcing data as defined on the surface data grid
15.3. NESTING 471
15.3 Nesting
The objective of nesting is to interpolate values of specific model arrays to
external data points, which constitute the open boundaries of one or more
sub-grids nested within the model grid. The interpolated data are written
to output files in standard COHERENS format. A different file is used for
each type of variable and each subgrid. Writing of a file is enabled by setting
modfiles(iddesc,iset,2)%status=‘W’ in usrdef mod params where
iddesc the file descriptor which can take the following values:
io 2uvnst 2-D mode variables (transport and surface elevation)
io 3uvnst 3-D baroclinic current
io salnst salinity
io tmpnst temperature
io bionst biological state variables (currently not implemented)
iset number of the nested sub-grid (between 1 and nonestsets)
It is assumed that the variables on the subdomain are defined on a C-
grid like the main grid. The following five types of horizontal interpolation
(depending on the type of variable) need to be considered:
• from model C-nodes to sub-grid C-nodes: 3-D scalars
• from model C-nodes to sub-grid U- or V-nodes: elevations
• from model U-nodes to sub-grid U-nodes: X-components of transports
and currents
• from model V-nodes to sub-grid V-nodes: Y-components of transports
and currents
To summarise, the nesting procedure is defined as follows:
1. Set iopt nests to 1.
2. Define nonestsets as the number of nested sub-grids.
3. Define the number of data points in usrdef nstgrd spec.
4. Define the positions of the data points in usrdef nstgrd abs and/or
usrdef nstgrd rel.
5. Enable the interpolation and writing of specific model variables by
setting modfiles(iddesc,iset,2)%status=‘W’.
15.3.1 Sub-grid specifications

This section describes routine usrdef nstgrd spec where general parameters
such as the number of data points and the type of coordinates are defined
for each sub-grid. The routine is called if:
• the switch iopt nests is set to 1.
• modfiles(io nstspc,1,1)%status=‘N’
SUBROUTINE usrdef nstgrd spec

INTEGER, DIMENSION(nonestsets) :: nestcoords, nohnstglbc, &
& nohnstglbu,nohnstglbv, novnst, inst2dtype
The argument arrays need to be defined for each sub-grid separately:

nestcoords Type of coordinates used to define the positions of the sub-grid
open boundary points
1: absolute coordinates
2: relative coordinates
nohnstglbc number of C-node sub-grid points in the horizontal
nohnstglbu number of U-node sub-grid points in the horizontal
nohnstglbv number of V-node sub-grid points in the horizontal
novnst vertical dimension of the sub-grid
inst2dtype selects the type of data for 2-D nesting
1: transports and elevations
2: elevations
3: transports
15.3.2 Sub-grid locations in absolute coordinates

The positions of the data points for a sub-grid with index iset in absolute
coordinates are obtained in usrdef nstgrd abs. The routine is called when
• iopt nests is set to 1.
• modfiles(io nstgrd,iset,1)%status=‘N’
• nestcoords(iset)=1
• nhdat>0 (see below)

15.3. NESTING 473
The routine has the following arguments:
SUBROUTINE usrdef nstgrd abs(iset,nhdat,nzdat,xcoord,ycoord,zcoord,cnode)

CHARACTER (LEN=1), INTENT(IN) :: cnode
INTEGER, INTENT(IN) :: iset, nhdat, nzdat
REAL, INTENT(OUT), DIMENSION(nhdat) :: xcoord, ycoord
REAL, INTENT(OUT), DIMENSION(nhdat,nzdat) :: zcoord
where
iset the index number of the sub-grid

cnode grid node of the sub-grid data points which may take the values ‘C’,
‘U’, ‘V’
nhdat number of sub-grid points in the horizontal, equal to the value of either
nohnstglbc(iset), nohnstglbu(iset) or nohnstglbv(iset) depending on the
value of cnode
nzdat number of data points in the vertical equal to novnst(iset)
Provided that the conditions above are fullfilled, the routine is called for each
sub-grid at most 3 times with respectively cnode=‘C’,‘U’,‘V’.
The following coordinate arrays are to be defined:
xcoord X-coordinates of the sub-grid data points [meters or longitude]

ycoord Y-coordinates of the sub-grid data points [meters or latitude]
zcoord Z-coordinates of the sub-grid locations, defined as the negative dis-
tance to the mean surface level (only when nzdat>0) [m]
15.3.3 Sub-grid locations in relative coordinates

The positions of the data points for sub-grid with index iset in relative coor-
dinates are obtained in usrdef nstgrd rel. The routine is called when
• iopt nests is set to 1.
• modfiles(io nstgrd,iset,1)%status=‘N’
• nestcoords(iset)=2
• nhdat>0 (see below)
As for the case of a surface data grid, the horizontal relative coordinates are
stored in a DERIVED TYPE array of type HRelativeCoords:
where icoord, jcoord are the indices in the X- and Y-direction of the grid
cell containing the data point and xcoord, ycoord the normalised Cartesian
coordinates (between 0 and 1) with respect to axes along the cell faces and
origin at the lower left corner.
The routine is declared as follows:
SUBROUTINE usrdef nstgrd rel(iset,nhdat,nzdat,nonodes,hnests,&

& zcoord,cnode)
INTEGER, INTENT(IN) :: iset, nhdat, nonodes, nzdat
TYPE (HRelativeCoords), INTENT(OUT), DIMENSION(nhdat,nonodes) :: hnests
The INTENT(IN) arguments have the following meaning
iset the index number of the sub-grid

cnode grid node of the sub-grid data points which may take the values ‘C’,
‘U’, ‘V’
nhdat number of sub-grid points in the horizontal, equal to the value of ei-
ther nohnstglbc(iset), nohnstglbu(iset) or nohnstglbv(iset) depending
on the value of cnode
nzdat number of data points in the vertical equal to novnst(iset)
nonodes the number of nodes for which relative coordinates need to be pro-
vided. Its value equals 1 or 2 depending on the value of cnode. This
is further discussed below.
The positions are stored into the arrays
hnests relative coordinates of the sub-grid (‘C’, ‘U’, ‘V’) locations with re-
spect to either the C-, U- or V-node model grid
zcoord Z-coordinates of the sub-grid locations, taken as the negative distance
to the mean surface level (only when nzdat>0) [m].
Provided that nhdat> 0 and the other conditions above apply, the routine
is called successively with cnode=‘C’,‘U’,‘V’. The value of nonodes and the
meaning of hnests depends on cnode:
15.3. NESTING 475
‘C’: One series of coordinates needs to be given (nonodes=1), representing

interpolation from the C-node model grid to the C-node sub-grid loca-
tions.
‘U’: Two series of coordinates need to be given (nonodes=2)
1: interpolation from the U-node model grid to the U-node sub-grid lo-
cations
2: interpolation from the C-node model grid to the U-node sub-grid lo-
cations
‘V’: Two series of coordinates need to be given (nonodes=2)
1: interpolation from the V-node model grid to the V-node sub-grid lo-
cations
2: interpolation from the C-node model grid to the V-node sub-grid lo-
cations
Chapter 16
User output
There exist 4 types of user output:
1. The source file Usrdef Time Series.f90 defines setup parameters and
data for time series output. Time series output is enabled when
iopt out tsers=1 (default value).
2. The source file Usrdef Time Averages.f90 defines setup parameters and
data for time averaged output. Time averaged output is enabled when
iopt out avrgd=1.
3. The source file Usrdef Harmonic Analysis.f90 defines setup parameters

and data for harmonic analysis and output. Harmonic analysis and
output is enabled when iopt out anal=1.
4. User formatted output can be defined in Usrdef Output.f90.
The usrdef routines for each type are discussed in Sections 16.1-16.4. The
output files not only contain the model data and metadata but also the coor-
dinates of the output grid. In this way each output file can be considered
as self-consistent and used by independent postprocessing programs for dis-
play and analysis. Coordinates of the output data grid are the subject of
Section 16.5.
16.1 Time series output

The file Usrdef Time Series.f90 contains the routines:
• usrdef tsr params: defines the output variables, file attributes, the space-
time resolution of the output grid and other metadata
477
478 CHAPTER 16. USER OUTPUT
• usrdef tsr0d vals: values of the 0-D output variables
16.1.1 Specifiers for time series output

The following integer and derived type arrays can or must be defined here:
TYPE (VariableAtts), DIMENSION(novarstsr) :: tsrvars

INTEGER, DIMENSION(nosetstsr,novarstsr) :: ivarstsr
TYPE (FileParams), DIMENSION(nosetstsr) :: tsr0d, tsr2d, &
& tsr3d, tsrgrd
TYPE (OutGridParams), DIMENSION(nosetstsr) :: tsrgpars
INTEGER, DIMENSION(nosetstsr,nostatstsr) :: lstatstsr
TYPE (StationLocs), DIMENSION(nostatstsr) :: tsrstatlocs
The array dimensions are previously defined in usrdef mod params and have
the following meaning
nosetstsr number of output “sets” as defined in usrdef mod params

novarstsr total number of output variables as defined in usrdef mod params
nostatstsr total number of stations as defined in usrdef mod params
The general meaning of the setup arrays is
tsrvars attributes of the output variables

ivarstsr variable indices
tsr0d attributes of the 0-D output files
tsrgrd attributes of the grid file (if needed)
tsrgpars attributes of the output data grid
lstatstsr stations labels
tsrstatlocs station attributes
A more detailed discussion is given below.

16.1. TIME SERIES OUTPUT 479
16.1.1.1 variable attributes

Attributes of the output variables are stored in a DERIVED TYPE array of
type VariableAtts1
INTEGER :: ivarid, klev, nrank, oopt
REAL :: dep
Output variables and their attributes are then selected with the following
arrays:

ivarid Variable key id of the output variable (as defined in modids.f90).

If zero, the variable is considered as user-defined. Otherwise, the
key id should be supplied using its FORTRAN name (standard
variable). The syntax is iarr * where * is the variables’s FOR-
TRAN name (e.g. iarr temp). A list of available key ids is given
in Appendix E. Variables need to be defined in the following
order: 0-D (if any), 2-D (if any), 3-D (if any).
f90 name FORTRAN name of the variable (e.g. ‘temp’) (user-defined va-
riables only)
long name long description of the variable, e.g. ‘temperature’ (user-defined
variables only)
vector name If the variable is the component of a vector, the name of the
vector, e.g. ‘current’ (user-defined variables only)
units unit of the variable, e.g. ‘m/s’ (user-defined variables only)
nrank variable rank (0, 2 or 3). Its value must be non-decreasing with
the array index. The variables are ordened in the same sequence
as ivarid. This means that the variables in the array tsrvars must
be defined in the following order: first 0-D (if any), next 2-D (if
any) and finally the 3-D variables (if any).
1
The string lengths lenname, lendesc, lenunit, lennode are defined in syspars.f90.
ivarstsr Each file set contains a sub-set of the variables defined in tsrvars.
The element ivarstsr(iset,ivar) maps, for set iset, the local variable
index ivar into the corresponding array index in tsrvars.
In case of a standard variable (non-zero ivarid attribute), the following
attributes may optionally be defined:
oopt If the rank of the result is different from the one implemented by
the variable’s rank, the rank attribute must be set to the rank of
the result. For example, the domain average of a 3-D variable
has a rank of 0. The attribute has one of the following values
oopt null No operator is applied (default).
oopt mean Result depends on the rank of the model variable
and the rank of the output data.
- If the rank of the result is 0, the output value
is the domain average in case of a 3-D or the
surface average in case of a 2-D variable. Land
areas are excluded in the averaging.
- If the rank of the output value is 2, the result is
the depth averaged value.
oopt int Result depends on the rank of the model variable
is the domain integrated value in case of a 3-
D or the surface integrated value in case of a
2-D variable. Land areas are excluded in the
integration.
the depth integrated value.
oopt max Result depends on the rank of the model variable
- If the rank of the result is 0, the output value is
the domain maximum in case of a 3-D or the sur-
face maximum in case of a 2-D variable. Land
areas are excluded.
the maximum over the water depth.
oopt min Result depends on the rank of the model variable

is the domain minimum in case of a 3-D or the
surface minimum in case of a 2-D variable. Land
areas are excluded.
the minimum over the water depth.
klev Produces the value of a 3-D variable at the vertical
level given by the attribute klev. Rank of the result
is 2.
oopt dep Produces the value of a 3-D variable using vertical
interpolation at a specified depth given by the at-
tribute dep. Rank of the result is 2.
oopt klev Defines the output vertical level in case oopt equals oopt klev.
dep Defines the output water depth (measured positively from the
surface) in case oopt equals oopt dep. Result is 0, if dep is larger
than the total water depth at the output location.
node Used for 3-D variables defined at W-nodes on the model grid. If
node is set to ‘C’ (default), the vertical profile of the variable is
first interpolated at the C-node before the operator is applied.
If set to ‘W’, the output variable must be defined at the W-node
and no interpolation is performed. It is remarked that quantities
defined at U- or V-nodes are always interpolated at the C-nodes
before the operator is applied.
16.1.1.2 file attributes

File attributes are stored in a DERIVED TYPE array of type FileParams,
defined in Section 12.7:
TYPE (FileParams), DIMENSION(nosetstsr) :: tsr0d, tsr2d, tsr3d, tsrgrd
The following file attributes can be defined:

defined The output file will be created only if this parameter is set to
.TRUE.. Default is .FALSE..
form Format of the data file.
‘A’: ASCII
‘N’: netCDF
filename File name. If not defined, a default will be constructed by the

program.
info An “info” file (ending with ‘I’) will be created if .TRUE. (default
value).
header type No heading information will be written if set to 0. Default is 2.
This option is not available for netCDF (‘N’) files.
The arrays tsr0d, tsr2d, tsr3d are used for output of respectively 0-D, 2-D,
3-D output. They will contain metadata output if header type is set to its
default value or in case of a netCDF file. By default, the data file will contain
the coordinates of the output grid and the times of output. The coordinate
and time data can also be written to a separate “grid” file whose attributes
are stored in tsrgrd. A selection can be made with the grid file attribute
described below.
16.1.1.3 output data grid

The output grid (in space and time) and its attributes are defined using the
following DERIVED TYPE array.
TYPE :: OutGridParams
LOGICAL :: gridded, grid file, land mask, time grid
CHARACTER (LEN=lentime) :: refdate
INTEGER :: nodim, nostats, time format
INTEGER, DIMENSION(3) :: tlims, xlims, ylims, zlims
END TYPE OutGridParams
gridded If .TRUE. (default), output data are defined on a sub-grid of

data) defined below.
a separate output file (defined by tsrgrd). Otherwise, they are
written within the data file itself. Default is .FALSE.
space. Default is .FALSE..
time grid If .TRUE., the data grid is taken as time-dependent (since the
vertical positions in a σ-grid depend on time). Surface elevations
will be written as an additional coordinate variable at each time
step. Default if .FALSE., in which case the vertical positions are
referred to the mean water level.
time format Format of the time coordinate (0).
0: date/time in string fromat

1: seconds
2: minutes
3: hours
4: days
5: months
6: years
7: date in years
Cases 1–6 are numerical formats. Cases 0 and 7 are absolute

times, the other ones relative to the reference date/time.
tlims Start/end/step time indices for data output. This means that
output will be written at intervals of delt2d*tlims(3) seconds.
for 0-D or station output). Default values are (1,nc-1,1).
for station or 0-D output). Default values are (1,nr-1,1).
Default values are (1,nz,1).
16.1.1.4 station attributes

Station atrributes are defined by
TYPE :: StationLocs
INTEGER :: ipos, jpos
CHARACTER (LEN=lenname) :: name
END TYPE StationLocs
ipos (global) X-index of the output stations

jpos (global) Y-index of the output stations
name descriptive names of the stations. Default is ‘Station X’ where ‘X’
is the station’s array index.
lstatstsr Station labels. Each file set may contain a sub-set of stations. The
element lstatstsr(iset,istat) maps, for set iset, the local station index
istat into the corresponding global array index in tsrstatlocs.
16.1.2 Time series output data

The usrdef routines below are only called to define the values of user-defined
variables. Output data for standard variables are automatically generated by
the program and evaluated at the C-nodes (except when the node attribute
is set to ‘W’). Interpolation is performed when necessary.
Important to note is that the program assumes that all (including user-
defined) 2-D and 3-D output data are given at the C-nodes (unless the node
attribute is set to ‘W’). This means that variables, defined at other nodes,
such as velocity components, need to be interpolated first at the C-nodes.
Interpolation routines are provided by the program (see Section 23.1).
16.1.2.1 values of 0-D time series data

The subroutine usrdef tsr0d vals defines the 0-D (space-independent) data for
time series output.
SUBROUTINE usrdef tsr0d vals(out0ddat,n0vars)

INTEGER, INTENT(IN) :: n0vars
REAL, INTENT(OUT), DIMENSION(n0vars) :: out0ddat
where
n0vars number of 0-D output variables

out0ddat 0-D output data. The variables are given in the same order as they
are defined in the array tsrvars with the index 1 referring to the first
0-D variable and the index n0vars to the last variable in tsrvars.

The subroutine usrdef tsr2d vals defines the 2-D (horizontally dependent)
data for time series output.
SUBROUTINE usrdef tsr2d vals(out2ddat,i,j,n2vars)

INTEGER, INTENT(IN) :: i, j, n2vars
where

i X-index of the data location on the local model grid
j Y-index of the data location on the local model grid

The subroutine usrdef tsr3d vals defines the 3-D (spatially dependent) data
for time series output.
SUBROUTINE usrdef tsr3d vals(out3ddat,i,j,k,n3vars)

INTEGER, INTENT(IN) :: i, j, k, n3vars
where

k vertical index of the data location on the model grid
16.2 Time averaged output

The file Usrdef Time Averages.f90 contains the routines:
• usrdef avr params: defines the output variables, file attributes, the space-
time resolution of the output grid and other metadata
• usrdef avr0d vals: values of the 0-D output variables
Time averaged output is defined in almost the exact way as time series out-
put. Only differences are
• In all variable and routine names ‘tsr’ is replaced by ‘avr‘.
• The third element of the vector attribute tlims(3) is now used also to
determine the averaging period.
• The output grid is always time independent.
For completeness all definitions are fully discussed below.
16.2.1 Specifiers for time averaged output

The following integer and derived type arrays can or must be defined here:
TYPE (VariableAtts), DIMENSION(novarsavr) :: avrvars

INTEGER, DIMENSION(nosetsavr,novarsavr) :: ivarsavr
TYPE (FileParams), DIMENSION(nosetsavr) :: avr0d, avr2d, &
& avr3d, avrgrd
TYPE (OutGridParams), DIMENSION(nosetsavr) :: avrgpars
INTEGER, DIMENSION(nosetsavr,nostatsavr) :: lstatsavr
TYPE (StationLocs), DIMENSION(nostatsavr) :: avrstatlocs
The array dimensions are previously defined in usrdef mod params and have
the following meaning
nosetsavr number of output “sets” as defined in usrdef mod params

novarsavr total number of output variables as defined in usrdef mod params
nostatsavr total number of stations as defined in usrdef mod params
The general meaning of the setup arrays is

16.2. TIME AVERAGED OUTPUT 487
avrvars attributes of the output variables

ivarsavr variable indices
avr0d attributes of the 0-D output files
avrgrd attributes of the grid file (if needed)
avrgpars attributes of the output data grid
lstatsavr stations labels
avrstatlocs station attributes

Output variables and their attributes are selected with the following arrays:

The array components and elements provide the following information

f90 name FORTRAN name of the variable, e.g. ‘temp’) (user-defined vari-
ables only)
long name long description of the variable (e.g. ‘temperature’), user-defined
variables only
vector, e.g. ‘current’ (user-defined variables only). Otherwise, it
is left undefined.
as ivarid. This means that the variables in the array avrvars must
be defined in the following order: first 0-D (if any), next 2-D (if
any) and finally the 3-D variables (if any).
ivarsavr Each file set contains a sub-set of the variables defined in avr-
vars. The element ivarsavr(iset,ivar) maps, for set iset, the local
variable index ivar into the corresponding array index in avrvars.

integration.
areas are excluded.

areas are excluded.
oopt klev Produces the value of a 3-D variable at the vertical
is 2.
klev Defines the output vertical level in case oopt equals oopt klev.
and no interpolation is performed. It is remarked that quantities
before the operator is applied..

TYPE (FileParams), DIMENSION(nosetsavr) :: avr0d, avr2d, avr3d, avrgrd
defined The output file will be written only if this parameter is set to

‘A’: ASCII
‘N’: netCDF
program.
value).
The arrays avr0d, avr2d, avr3d are used for output of respectively 0-D, 2-D,
3-D output. They will contain metadata output if header type is set to its
default value or in case of a netCDF file. By default, the data file will contain
the coordinates of the output grid and the times of output. The coordinate
and time data can also be written to a separate “grid” file whose attributes
are stored in avrgrd. A selection can be made with the grid file attribute
described below.

following DERIVED TYPE array:

a separate output file (defined by avrgrd). Otherwise, they are

1: seconds
2: minutes
3: hours
4: days
5: months
6: years
7: date in years
tlims The first two elements of this vector are the start and end time
indices for data output and determine the start and end output
date/times. The averaging period is defined by tlims(3). This
means in practice that output will be written at regular inter-
vals of delt2d*tlims(3) seconds which is the same as the period
of averaging. Output times are defined in the middle of each
averaging period.
for 0-D or station output). Default values are (1,nc-1,1).
for 0-D or station output). Default values are (1,nr-1,1).


Arrays and array components represent the following

lstatsavr Station labels. Each file set may contain a sub-set of stations. The
element lstatsavr(iset,istat) maps, for set iset, the local station index
istat into the corresponding global array index in avrstatlocs.
16.2.2 Time averaged output data

16.2.2.1 values of 0-D time averaged data

The subroutine usrdef avr0d vals defines the 0-D (space-independent) data
for time averaged output.
SUBROUTINE usrdef avr0d vals(out0ddat,n0vars)

where

are defined in the array avrvars with the index 1 referring to the first
0-D variable and the index n0vars to the last variable in avrvars.

The subroutine usrdef avr2d vals defines the 2-D (horizontally dependent)
data for time averaged output.
SUBROUTINE usrdef avr2d vals(out2ddat,i,j,n2vars)

where


The subroutine usrdef avr3d vals defines the 3-D (spatially dependent) data
for time averaged output.
SUBROUTINE usrdef avr3d vals(out3ddat,i,j,k,n3vars)

where

16.3 Harmonic analysis

The file Usrdef Harmonic Analysis.f90 contains the routines:
• usrdef anal freqs: defines the frequencies for harmonic analysis and their
attributes
• usrdef anal params: defines the output variables, file attributes, the
space-time resolution of the output grid and other metadata
• usrdef anal0d vals: values of the 0-D output variables

The definitions for harmonic output are similar to the ones for time series
output. Main difference is that the output grid is time independent and
additional information has to be given about the analysis itself and that the
output files can be produced for residual data, amplitudes, phases and elliptic
parameters.
16.3.1 Harmonic frequencies

The following arrays are defined here:
CHARACTER (LEN=7), DIMENSION(nofreqsanal) :: harm freq names

CHARACTER (LEN=lentime), DIMENSION(nosetsanal) :: cdate time ref
INTEGER, DIMENSION(nosetsanal) :: nofreqsharm
INTEGER, DIMENSION(nofreqsanal) :: index anal
INTEGER, DIMENSION(nosetsanal,nofreqsanal) :: ifreqsharm
REAL, DIMENSION(nofreqsanal) :: harm freq
The array sizes are defined in usrdef mod params and have the following
meaning:
nosetsanal number of output “sets” as defined in usrdef mod params
nofreqsanal total number of frequencies as defined in usrdef mod params
The arrays provide the following information
index anal Key ids of the constituents used in harmonic analysis (as de-
fined in tide.f90). If positive, harm freq names and harm freq
do not need to be defined. Default is 0.
nofreqsharm number of frequencies per set
harm freq values of the frequencies [rad/s]
harm freq names names of the frequencies names (e.g. ‘M2’)
ifreqsharm Each set contains a sub-set of frequencies defined by index anal.

The element ifreqsharm(iset,ifreq) maps, for set iset, the lo-
cal frequency ifreq into the corresponding “global” array
index as defined in the global array index anal.
cdate time ref If set by the user, all harmonic phases are calculated with
respect to this reference date. Otherwise, the reference
date/time is taken with respect to the central time or to the
astronomical phase at Greenwich depending on the value of
iopt astro anal.
16.3.2 Specifiers for harmonic output

The following integer and derived type arrays can be defined here:
TYPE (VariableAtts), DIMENSION(novarsanal) :: analvars

INTEGER, DIMENSION(nosetsanal,novarsanal) :: ivarsanal
TYPE (FileParams), DIMENSION(nosetsanal) :: res0d, res2d, res3d, &
& analgrd
TYPE (FileParams), DIMENSION(nosetsanal,nofreqsanal) :: &
& amp0d, amp2d, amp3d, pha0d, pha2d, pha3d, ell2d, ell3d
TYPE (OutGridParams), DIMENSION(nosetsanal) :: analgpars
INTEGER, DIMENSION(nosetsanal,nostatsanal) :: lstatsanal
TYPE (StationLocs), DIMENSION(nostatsanal) :: analstatlocs
INTEGER, DIMENSION(nosetsanal,14) :: ivarsell
INTEGER, DIMENSION(nosetsanal,2) :: ivecell2d, ivecell3d
where the arrays sizes are defined in usrdef mod params:
nosetsanal are the number of output “sets” as defined in usrdef mod params
novarsanal are the total number of output variables as defined in usrdef mod params
nostatsanal are the total number of stations as defined in usrdef mod params
Output parameters are defined by the following arrays
analvars attributes of the output variables

ivarsanal variable indices
res0d attributes of the 0-D residual file(s)
amp0d attributes of the 0-D amplitudes file(s)
pha0d attributes of the 0-D phase file(s)

ell2d attributes of 2-D elliptical file(s)
ell3d attributes of 3-D elliptical file(s)
analgrd attributes of the grid file (if needed)
analgpars attributes of the output data grid
lstatsanal stations labels
analstatlocs station attributes
ivarsell variable indices for elliptic parameters
ivecell2d array indices (taken from analvars) for the X- and Y-component
of 2-D elliptic vectors
ivecell3d array indices (taken from analvars) for the X- and Y-component
of 3-D elliptic vectors

Output variables and their attributes are selected with the following arrays:

Arrays and array components have the following meaning

f90 name FORTRAN name of the variable, e.g. ‘temp’ (user-defined vari-
ables only)
long name long description of the variable, e.g. ‘temperature’ (user-defined

variables only)
vector, e.g. ‘current’ (user-defined variables only). Otherwise, it
is left undefined.
as ivarid. This means that the variables in the array analvars
must be defined in the following order: first 0-D (if any), next
2-D (if any) and finally the 3-D variables (if any).
ivarsanal Each file set contains a sub-set of the variables defined in anal-
vars. The element ivarsanal(iset,ivar) maps, for set iset, the local
variable index ivar into the corresponding array index in anal-
vars.
ivarsell Has the same meaning as ivarsanal now for elliptic parameters
(i.e. defines which elliptic parameters are written to output).
ivecell2d The array elements ivecell2d(iset,1) and ivecell2d(iset,2) are the
array indices in analvars of the X- and Y-component of the vector
used to describe the harmonic ellipses for 2-D output.
ivecell3d Array elements ivecell3d(iset,1) and ivecell3d(iset,2) are the array
indices in analvars of the X- and Y-component of the vector used
to describe the harmonic ellipses for 3-D output.


integration.
areas are excluded.
areas are excluded.
oopt klev Produces the value of a 3-D variable at the vertical
is 2.
klev Defines the output vertical level in case oopt equals oopt klev.
and no interpolation is performed.It is remarked that quantities
before the operator is applied.
The elliptic parameters, available for output are: major axis and minor
axis of the tidal ellipse, ellipticity, inclination of the ellipse, elliptic phase and
magnitude of the cyclonic and anticyclonic current. The values of the elliptic
parameters do not need to be specified by the user, but are automatically
determined by the program using the variables’s key id. A list of all key ids
for elliptic variables is given in Table 16.1, including the dimension of the
corresponding “current” vector, which may in principle be any kind of vector
and whose components are known to the program through the arrays ivecell2d
and ivecell3d. Since they can be defined both in 2-D and 3-D mode, there
are 14 key ids available. This explains why the second dimension of ivarsell
equals 14. Note that the f90 name, long name, units of elliptic parameters are
pre-defined by the program and cannot be reset by the user in the current
implementation.

TYPE (FileParams), DIMENSION(nosetsanal) :: res0d, res2d, res3d, &

& analgrd
& amp0d, amp2d, amp3d, pha0d, pha2d, pha3d, ell2d, ell3d
defined The output file will be written only if this parameter is set to
‘A’: ASCII
‘N’: netCDF
Table 16.1: List of available elliptic parameters (corresponding variable key

id, description of the parameter and the dimension of the vector which de-
termines the ellipse).
Key id Description Dimension

iarr ellmaj2d Major axis 2
iarr ellmin2d Minor axis 2
iarr ellip2d Ellipticity 2
iarr ellinc2d Inclination 2
iarr ellpha2d Elliptic phase 2
iarr ellcc2d Cyclonic component 2
iarr ellac2d Anticyclonic component 2
iarr ellmaj3d Major axis 3
iarr ellmin3d Minor axis 3
iarr ellip3d Ellipticity 3
iarr ellinc3d Inclination 3
iarr ellpha3d Elliptic phase 3
iarr ellcc3d Cyclonic component 3
iarr ellac3d Anticyclonic component 3

program.
value).
The arrays ⋆0d, ⋆2d, ⋆3d are used for output of respectively 0-D, 2-D, 3-D
output. They will contain metadata output if header type is set to its default
value or in case of a netCDF file. By default, the data file will contain the
coordinates of the output grid and the times of output. The coordinate and
time data can also be written to a separate “grid” file whose attributes are
stored in analgrd. A selection can be made with the grid file attribute defined
below.

following DERIVED TYPE array:

a separate output file (defined by analgrd). Otherwise, they are
1: seconds
2: minutes
3: hours
4: days
5: months
6: years
7: date in years
tlims The first two elements of this vector are the start and end time
indices for data output and determine the start and end output
date/times. The period of the harmonic analysis is defined by
tlims(3). This means in practice that output will be written
atregular intervals of delt2d*tlims(3) seconds which is the same
as the period of the analysis. Output times are defined in the
middle of each period (central time) of analysis.
for 0-D output). Default values are (1,nc-1,1).
for 0-D output). Default values are (1,nr-1,1).


Arrays and array components have the following meaning


lstatsanal Station labels. Each file set may contain a sub-set of stations.
The element lstatsanal(iset,istat) maps, for set iset, the local station
index istat into the corresponding global array index in analstatlocs.
16.3.3 Harmonic output data

16.3.3.1 values of 0-D harmonic data

The subroutine usrdef anal0d vals defines the 0-D (space-independent) data
for harmonic output.
SUBROUTINE usrdef anal0d vals(out0ddat,n0vars)

where
n0vars number of 0-D harmonic variables

out0ddat 0-D output data. The variables are given in the same order as
they are defined in the array analvars with the index 1 referring to
the first 0-D variable and the index n0vars to the last variable in
analvars.

The subroutine usrdef anal2d vals defines the 2-D (horizontally dependent)
data for harmonic output.
SUBROUTINE usrdef anal2d vals(out2ddat,i,j,n2vars)

where
analvars.

The subroutine usrdef anal3d vals defines the 3-D (spatially dependent) data
for harmonic output.
SUBROUTINE usrdef anal3d vals(out3ddat,i,j,k,n3vars)
where
analvars.
16.4 User-defined output

The routine usrdef output is intended for users who like to define output in
their own format. The routine has to be programmed by the user at his/hers
responsibility. Their are no general rules, except that the routine is called
at each 2-D time step. Examples are defined for most test cases and can be
found in the subdirectories of setups.
16.5. OUTPUT GRID COORDINATES 505
16.5 Output grid coordinates

Besides data of model variables, the program writes also the coordinates of
the output data grid. They are written, either to the data file itself or to a
separate file. The selection is made with the grid attribute grid file discussed
above. In this way, a postprogramming program can read data as well as
their locations (on a geographic spherical or an arbitrary Cartesian grid). If
the file is written in netCDF format, there is a further advantage since sev-
eral graphical software programs (MATLAB, FERRET, ncview, ...) accept
netCDF data without a need for an intermediate postprocessing program.
The following coordinate arrays are written, depending on the values of
the grid attributes nodim and time grid:
1. xout: X-coordinates of the data grid in meters or (fractional) degrees

longitude depending on the value of iopt grid sph. Only when nodim>0.
2. yout: Y-coordinates of the data grid in meters or (fractional) degrees

latitude depending on the value of iopt grid sph. Only when nodim>0.
3. zout: Z-coordinates (z) in meters of the output grid based on the

mean water depth. They are calculated using the formula (see equa-
tion (4.8)).
z = h(σ − 1) (16.1)
Only when nodim=3.
4. depout: Mean water depth h (bathymetry) in meters. Land points are

set to zero. Only when nodim>0.
5. time: Output times written at each output time. Units are absolute
(in string format) or numerical depending on the value of the attribute
time format (see above).
6. zetout: Water elevation ζ in meters. This array is written at all times

when nodim=3 and time grid=.TRUE..
The arrays depout and zetout are included for the following reasons:
• If output is written with land mask=.TRUE., the data are not written
in gridded format, but as a vector array excluding land points. The
output grid can be recovered by a postprocessing program knowing the
positions of the land areas where depout>0.
• If the output grid is taken as time-dependent, the exact vertical posi-

tions of the data are then obtained using
z = z(1 + ζ/h) + ζ (16.2)
where z, h and ζ are obtained from the data file. An easier alternative
would be to write z at all times, but this would require the output of a
3-D array at each time, while in the present formulation only one 2-D
array (ζ) is needed, giving a saving of disk space.
It may be remarked that in future releases of COHERENS different coordinate

data may be implemented to comply with international data standards.
Recommendations for
programming
The model setup requires that FORTRAN 90 program code is inserted in

several Usrdef files. Below are a few recommendations and hints.
declaration of variables All variables used within a routine must be de-
clared. For local variables this is easily done within the routine. Al-
though not required explicitly, the COHERENS code is entirely pro-
grammed without “implicit typing rules”. This means that the local
variable declaration part should start with the line
IMPLICIT NONE
Most variables within a usrdef routine have a non-local scope and are
already declared in a MODULE file. They are made accessible in the
usrdef routine via a USE X statement at the head of the routine where
X is the name of the module. The name of a module always appears
on the first line of the a module file. These are the files in the source
directory whose names start with a lower case character and contain
no “ ” (underscore) character. The file names have a close relation
with their contents (like currents.f90 which contains the modules with
all declarations concerning currents). A description of all program va-
riables is given in Chapter 25. Module routines used within a usrdef
routine need to be declared with a
USE X, ONLY: Y
statement where X is the name of the module and Y the name of the
module routine. Module routine file names start with a lower case
letter and have an “ ” character in their name. The routine name can
be found within the routine. A full description of modules and module
routines is found in Chapters 25 and 23. The following is an example
of USE statements
507
USE currents
USE inout routines, ONLY: close file, open file
file operations Important to know is that files cannot be opened or closed

with the standard FORTRAN OPEN and CLOSE statements. There are
two alternatives, based upon routines declared in inout routines.f90:
1. Use open filepars to open and close filepars to close files. The
first argument of these routines is a derived type variable of type
FileParams. Besides opening and closing, the routines set or reset
a number of file attributes.
2. Use open file and close file. The routines are similar to the classical
OPEN and CLOSE FORTRAN routines.
The syntax of these routines is explained in Chapter 23.
time series data A special procedure needs to be followed within a

usrdef routine which reads time series data (i.e. the routines having
ciodatetime as an argument).
1. On first call, the file is opened and the iostat attribute is reset
from 0 to 1. No data are read.
2. A second call is made, immediately after the first one (i.e. at
the same model time step) to read the date/time and first series
of data. These calls are repeated until the date/time of the last
input is later than the actual model time.
3. When during program execution, the model date equals or be-
comes later than the one obtained from the last input, the usrdef
routine is called again, until the date/time in the file becomes later
than the actual model time.
4. If an end of file condition occurs or the user knows that this will
occur on a next read, the user must set the iostat number to 2. The
program will no longer call the routine. Further action (decided
by the program) now depends on the value of the endfile attribute
(see Section 12.7.2).
5. At the end of the simulation the program automatically closes all
open files whose attributes are stored in an element of the array
modfiles. Otherwise, the user has to close the file when the last
data record has been read.
The first point can be programmed as

16.5. OUTPUT GRID COORDINATES 509
IF (modfiles(iddesc,ifil,1)%iostat.EQ.0) THEN
CALL open filepars(modfiles(iddesc,ifil,1))
RETURN
ENDIF
...
if the file exists, or
IF (modfiles(iddesc,ifil,1)%iostat.EQ.0) THEN
modfiles(iddesc,ifil,1)%iostat = 1
RETURN
ENDIF
...
if the file does not exist and the data are defined without reading from
an external data file. The third point could be implemented as follows
iunit = modfiles(iddesc,ifil,1)%iunit
READ (iunit,..,END=99)
...
99 modfiles(iddesc,ifil,1)%iostat= 2
...
Part V
Test cases
511
Chapter 17
Introduction
A total of 12 test cases has been implemented. The first eight are adapted
versions of the ones made available with the release of the COHERENS V1
source code and discussed in the COHERENS V1 manual. The files, used for
the setup (including the Usrdef * files), are located in subdirectories of the
setups folder. The main objectives for implementing the test cases are to
• check the installation of the model code by the user
• perform simulations without any programming effort by the user
• demonstrate the various options, available in the program (e.g. selec-

tion of a particular scheme by setting the appropriate switches) and, in
particular, to show how model results are affected by different choices
of model switches or parameters
• test the portability of the program
• verify model results against exact or analytical solutions
• provide a debugging tool for further developments of the model code.
The following test cases have been implemented:
1. Test cases for advection.
cones
advection in a closed basin of an initially coned-shaped contami-
nant distribution rotating around the basin’s centre. Four exper-
iments are defined using different values of the model switch for
scalar advection.
513
front
advection (on a σ-grid) of a front by a tidal current over a sloping
bottom in an open channel without “physical” diffusion (James,
1996). Four experiments are defined using different values of the
model switch for scalar advection.
seich
adjustment to equilibrium of an initial horizontal density gradient
in a closed channel, through the propagation of internal waves.
The numerical results are compared with an analytical solution.
Five experiments are defined using different values of the model
switches for scalar and momentum advection.
fredy
development of 3-D baroclinic eddies in a closed basin. This test
case was previously considered in the NOMADS project (Proctor,
1997). Four experiments are defined using different values of the
model switches for scalar and momentum advection. Results are
compared with those described in Tartinville et al. (1998).
2. Test cases for turbulence and heat formulations
pycno
a 1-D test describing the evolution of a wind-driven surface layer
without rotation. An initial linear stratification is assumed and
advection is neglected. The results are compared with analytical
theory (Kundu, 1981; Luyten et al., 1996). Seven experiments are
defined using different values of the turbulent switches.
csnsp
a 1-D simulation of the seasonal evolution of thermal stratifica-
tion at station CS in the North Sea. Nine experiments are defined
using different values of the turbulence switches, different param-
eterisations for the surface exchange coefficients, or disabling the
attenuation of light.
3. Density fronts and river plumes
river
evolution of an estuarine salinity front advected by a tidal cur-
rent and the corresponding estuarine circulation in an open non-
rotating channel. Four experiments are defined using different
values of the switches for turbulence and momentum advection.
515
plume
formation and evolution of a tidally modulated river plume front.
Some comparison is made with the theory of tidal plumes pre-
sented in Visser et al. (1994). Seven experiments are defined test-
ing the role and form of horizontal diffusion, the scheme for mo-
mentum advection, the type of open boundary condition and the
effects of the tide.
rhone
simulation of the Rhone plume in the Gulf of Lions (Mediterranean
Sea) with a real bathymetry. Seven experiments are defined with
different river discharges, turbulence schemes and directions of the
wind forcing.
4. Flooding and drying experiments
flood2d
simulation of flooding and subsequent drying in a 2DV channnel.
Four experiments are defined using two different bathymetries and
two different drying/wetting formulations.
flood3d
simulation of flooding and drying in a 3-D rectangular basin. Four
experiments are defined using different bathymetries.
5. Shelf sea modelling
bohai
simulation of the tides in the Bohai Sea (northern part of the
Yellow Sea). Six experiments are defined using different types of
open boundary conditions either in 2-D (depth-averaged) and 3-D
mode.
The instructions for installing and running a test case are already ex-
plained Section 2.3. A simulation is performed using the Run script with an
argument in the form of a capital letter. The argument informs the program
which experiment is simulated (see Table 2.1).
Further information about the setup of a test case can be obtained by
inspecting the FORTRAN source files in the corresponding /setups subdi-
rectory. A series of output parameters, which are described in the chapters
below, are defined for each test case. If no run-time error occurred during the
execution of an experiment, a file is produced at the end of the simulation.
Its name is composed of 10 characters:
• characters 1–5: name of the test case (as given in the first column of
Table 2.1)
• character 6: name of the experiment presented by one of the capital

letters A to I
• character 7–10: “.tst”
Simulations were performed for all test cases on different machines and
compilers. The corresponding .tst-files for different compilers are found in
the different subdirectories of the /setups/ptests folder. These files are
a useful tool to test the portability of the model code. The test cases are
described in Chapters 18–22. The values of the test parameters, given in
tabular form within the text, and the figures in the text were obtained from
simulations, performed on a LINUX machine with a gfortran compiler.
Calculation times for all test case experiments are listed in Table 17.1.
The simulations are permormed on a LINUX PC in serial mode and a parallel
cluster at ECMWF (European Center for Medium Range Weather Forecast-
ing, UK) using different number of processors.
517
Table 17.1: Calculation times (in seconds) for test case experiments on a LINUX
serial PC using gfortran and a parallel cluster using XL Fortran at ECMWF. The
number after the ’-’ sign denotes the number of processes.
Name Experiment LINUX-0 ECMWF-1 ECMWF-4 ECMWF-16 ECMWF-32

cones A 3.7 4.6 3.7
B 3.7 2.5 3.8
C 3.6 7.3 4.7
D 5.4 5.3 2.7
front A 2.9 1.1 2.2
B 2.9 1.1 3.7
C 1.8 4.0 2.3
D 3.8 4.0 2.2
seich A 1.3 3.9 3.4
B 3.5 3.8 4.9
C 3.7 2.1 3.1
D 2.4 4.8 4.2
E 4.7 3.1 6.4
fredy A 293 378 140 107
B 575 768 270 158
C 381 512 205 124
D 662 975 335 165
pycno A 8.5 12.4
B 11.0 10.5
C 11.0 12.7
D 8.2 11.8
E 10.3 9.7
F 8.8 10.1
G 9.0 12.2
csnsp A 47.9 64.3
B 45.7 60.8
C 48.2 70.6
D 43.7 60.1
E 47.5 63.3
F 45.5 66.6
G 46.1 72.6
H 47.4 65.9
I 42.8 61.5
river A 35.3 29.6 39.8
B 30.2 27.5 36.4
(Continued)
C 32.1 28.2 37.8

D 58.7 41.8 53.0
plume A 971 1069 339 171 156
B 601 634 188 121 144
C 683 750 272 132 136
D 664 697 267 126 130
E 641 696 218 127 149
F 641 692 202 127 154
G 945 1064 306 171 160
rhone A 2261 2522 1076 362 385
B 2270 2525 1024 359 438
C 2190 2438 1027 353 452
D 2264 2520 926 360 448
E 2264 2520 1024 359 406
F 2269 2515 894 366 432
G 2265 2515 947 486 431
flood2d A 53.0 56.4 84.4
B 53.8 59.1 90.1
C 201.9 195.8 176.7
D 219.1 216.3 206.3
flood3d A 1163 1534 589 373 569
B 1685 2219 793 438 563
C 5828 7537 2426 966 1073
D 418 626 287 290 582
bohai A 1000 764 348 285
B 958 760 351 282
C 949 760 373 289
D 2668 2776 1272 506
E 2658 2780 1314 506
F 2658 2772 1311 537
Chapter 18
Advection schemes
18.1 Test case cones

18.1.1 Description of the problem and model setup
The cones problem is a well known problem for the testing of advection
schemes (e.g. Takacs (1985); Ruddick (1995)). A squared-shaped basin is
considered bounded by solid walls. The width of the basin is taken as 40 m
and the mesh size of the grid is 1 m. A current field is imposed in the form
of a solid body rotation with angular velocity Ω around the point (x0 ,y0 )
located near the centre of the basin
u = −Ω(y − y0 ) , v = Ω(x − x0 ) , w = 0 (18.1)

where (x,y) are the horizontal Cartesian coordinates, (u,v) the horizontal
components of the current, w the vertical velocity, Ω = 1/1200 s−1 and (x0 ,y0 )
= (19.5,19.5). An initial contaminant distribution, represented in the setup
by a salinity field, has a cone shaped form with radius R and centered at
(xc ,yc ):
q
(x − xc )2 + (y − yc )2
" #
C = max 1 − ,0 (18.2)
R
where R = 5, (xc ,yc ) = (10.5,20.5) and C is the contaminant concen-
tration1 in arbitrary units. The initial current and contaminant field dis-
tributions are plotted in Figure 18.1. The program only needs to solve one
transport equation. This takes the following simple form in the absence of
diffusion, vertical currents, surface elevation and variations in bottom depth
1
Since there is no contaminant module implemented in the current version, the conta-
minant distribution is represented here by salinity.
519
520 CHAPTER 18. ADVECTION SCHEMES
∂C ∂ ∂
+ (Cu) + (Cv) = 0 (18.3)
∂t ∂x ∂y
Figure 18.1: The initial configuration of the cones test case.
18.1.2 Experiments and output parameters

The cones test intercompares the four scalar advection schemes implemented
in the program. The following experiments have been set up:
A : upwind scheme
B : Lax-Wendroff scheme
C : TVD scheme using the superbee limiting function
D : TVD scheme using the monotonic limiting function
In each experiment the program is run for two rotation periods. The conta-
minant distributions at the end of the simulation are given in Figures 18.2
for the four schemes. Figures 18.3 display the surface distributions after two
periods of revolution along two transects through the cone centre parallel to
respectively the X- and Y-axis.
18.1. TEST CASE CONES 521
A series of parameters are defined in the program and written to the .tst
output files at t = 0.5T , T , 1.5T , 2T where T is the rotation period.
xmin The cone radius measured in the negative X-direction (m). This is
taken as the distance between the cone centre and the point to the left
where C becomes less than 0.01 along a line parallel to the X-axis2 .
xplus The cone radius measured in the positive X-direction (m). This is taken
as the distance between the cone centre and the point to the right where
C becomes less than 0.01 along a line parallel to the X-axis2 .
ymin The cone radius measured in the negative Y-direction (m). This is
taken as the distance between the cone centre and the point below
where C becomes less than 0.01 along a line parallel to the Y-axis2 .
yplus The cone radius measured in the positive Y-direction (m). This is taken
as the distance between the cone centre and the point above where C
becomes less than 0.01 along a line parallel to the Y-axis2 .
cmin Minimum value of the concentration over the entire domain.
cmax Maximum value of the concentration over the entire domain.
Exact values are 5 for the four radii, 0 for cmin and 1 for cmax.
18.1.3 Results
• It is clear that scheme C which is also the default scheme of the pro-
gram, gives the best performance both in preserving the original shape
as in maintaining the gradient of the contaminant concentration.
• Scheme D produces a more diffusive and asymmetric distribution and

less sharp gradients.
• The upwind scheme A is only first order accurate and therefore highly
diffusive. This is clearly observed in Figure 18.2a where the original
distribution has been smeared out over the entire basin.
• Although scheme B can preserve sharp gradients, the original shape is

highly distorted. A further problem is the non-preservation of extremal
values yielding even negative concentrations.
2
If the radius is larger than the distance of the cone centre to the corresponding basin
boundary, its value is set to -999.9.
Figure 18.2: Test case cones. Surface concentrations after two periods of
revolution for scheme A (a), B (b), C (c), D (d).
18.1. TEST CASE CONES 523
Figure 18.3: Test case cones. Surface concentrations at the end of the
simulation along a transect through the cone centre parallel to the X-axis (a)
and the Y-axis (b) for the exact case (solid) schemes A (dots), B (dashes),
C (dash-dots) and D (dash plus 3 dots).
18.2 Test case front

This test case has been designed to verify the horizontal schemes for the
advection of scalar quantities. The initial configuration consists of a non-
rotating channel with open boundaries at the two ends. The water depth is
determined by a piecewise linear profile of the form
H = 50 for 0 < x < 25

H = 150 − 4x for 25 ≤ x ≤ 30 (18.4)
H = 30 for x > 30
where H is the water depth in m and x1 the along-channel distance in km.

An initial two-layer distribution is specified by
C = 2 if zs < 20 , 0 < x < 25

C = 1 if x ≥ 25 (18.5)
C = 0 if zs ≥ 20 , 0 < x < 25
where zs is the distance to the surface in m and C the contaminant concen-

tration in arbitrary units. During the simulation the lateral and horizontal
front are advected by an imposed tidal current with a semi-diurnal period:
u = ua (x, zs ) cos(2πt/T ) (18.6)
where T = 12 h. The amplitude ua in m/s is prescribed by
ua = 2 if zs + ∆z/2 < 30
ua = 0 if zs − ∆z/2 > 30 (18.7)
ua = 2(30 − zs + ∆z/2)/∆z otherwise
where ∆z is the vertical grid spacing. The model uses a σ-coordinate system
with 20 vertical levels so that the vertical grid spacing ∆z, following (18.4)
varies horizontally 2.5 m in the deepest part to 1.5 m in the shallowest part
of the domain.
The program only solves two equations: the transport equation for the
contaminant concentration without diffusion and the continuity equation for
the vertical velocity. The latter is non-zero only along the slope where the
prescribed velocity field has a non-zero horizontal gradient. The channel
length is set to 50 km. All cross-channel variations are neglected.
18.2. TEST CASE FRONT 525

In analogy with the cones test case the front case is an idealised problem
enabling to intercompare the different advection schemes implemented in the
program using simple forcing and initial conditions. The same four tests have
been set up:
A : upwind scheme
B : Lax-Wendroff scheme
C : TVD scheme using the superbee limiting function
D : TVD scheme using the monotonic limiting function
The simulations are performed for 36 hours, i.e. 3 semi-diurnal tidal cycles.
The contaminant distributions and current field are displayed in Figures 18.4
at the initial time and at 3 h intervals during the last cycle for scheme C
which is also the default scheme of the program. The distributions after 27
hours are compared for the four experiments in Figures 18.5. The concentra-
tions at 5 m below the surface and a vertical profile at 30 km from the left
boundary are shown in Figures 18.6 after 27 hours of simulation.
The following output test parameters are defined
gradh The maximum horizontal gradient (km−1 ) along an horizontal transect

taken at 5 m depth below the surface.
gradv The maximum vertical gradient (m−1 ) along a moving vertical transect
taken at the left edge of the lateral front.
hleng The width of the lateral front measured in km at 5 m below the surface.
This is defined as the horizontal width of the area where the horizontal
gradient is larger than 0.01 km−1 .
cmin Minimum concentration along the moving vertical transect.
cmax Maximum concentration along the moving vertical transect.
Values for the exact case are 1 (gradh, hleng), 0.8 (gradv), 0 (cmin), 2 (cmax).
18.2.3 Results
• After an initial broadening due to numerical diffusion, the shape of
the fronts remains unchanged after a tidal cycle as can be seen by
comparing Figures 18.4b and f.
Figure 18.4: Test case front. Contaminant distribution and current field for
experiment C at t = 0 h (a), t = 24 h (b), t = 27 h (c), t = 30 h (d), t = 33
h (e), t = 36 h (f).
18.2. TEST CASE FRONT 527
Figure 18.5: Test case front. Contaminant concentration after 27 hours for
scheme A (a), B (b), C (c), D (d). Contour lines are at 0.2 intervals.
Figure 18.6: Test case front. Contaminant concentration after 27 hours for
scheme A (solid), B (dots), C (dashes) and D (dash-dots): horizontal profile
at 5 m below the surface (a), vertical profile at 30 km from the left boundary
(b).
18.3. TEST CASE SEICH 529
• Comparing the test results for the different experiments shows that the
default scheme C not only produces the sharpest (lateral) front (para-
meter gradh) but also the smallest frontal width (parameter hleng).
• The importance of the type of advection scheme for the simulation

of frontal systems can be further observed in Figures 18.5. The up-
wind scheme, which is only first order accurate, is the most diffusive.
Schemes C and D are similar although the latter is somewhat more
diffusive. A sharp horizontal front is also produced by the second order
Lax-Wendroff scheme. A clear disadvantage is that this scheme does
not preserve monotonicity resulting in spurious over- and undershoot-
ing along the lateral front. The same features can also be inferred from
Figures 18.6a–b. The results are clearly in agreement with the previous
cones test.
18.3 Test case seich

The previous two problems served to test the advection schemes for scalar
quantities. They are idealistic in the sense that the velocity is not updated
by the program but prescribed externally. A more realistic test case is the
seich problem where a two-dimensional circulation along a vertical plane is
generated through an horizontal pressure gradient. The main aim is to verify
the advection schemes for momentum and scalars and to test the circulation
module.
A non-rotating channel, 30 km long, with a uniform depth of 20 m is
considered bounded by a solid lateral wall at the two ends. All cross-channel
variations are neglected. The initial surface elevation is set to zero. A salinity
stratification is specified initially in a two-layer form with a fresh water value
of S1 = 25 PSU in the upper and a sea water value of S2 = 35 PSU in the
lower layer. The interface is located at a depth of 7.5 m in the left and 12.5 m
in the right portion of the channel. In the middle of the channel the interface
decreases with a uniform slope of 0.0025 m−1 . The upper layer density is
related to salinity via a linear equation of state of the form
ρ1 = ρ2 (1 + βS (S1 − S2 )) (18.8)
where ρ1 , ρ2 are the densities in the upper, respectively lower layer and βS
is the uniform salinity expansion coefficient. The initial state is shown in Fi-
gure 18.7. The resulting horizontal (baroclinic) pressure gradient creates, in
the absence of vertical and horizontal diffusion, an horizontal motion through

a balance with the inertial force in the momentum equation and a vertical
current via the continuity equation. The program solves all momentum (2-D
and 3-D) equations, the equation of continuity (2-D and 3-D) and the trans-
port equation for salinity. Spatial resolution is 500 m in the horizontal and
1 m in the vertical.
18.3.2 Analytical solution

The problem can be solved analytically provided that all non-linear terms
are neglected in the momentum and continuity equation. This assumption
is validated by the numerical solutions presented below. The general solu-
tion consists of a combination of four modes: two internal (baroclinic) modes
propagating in opposite along-channel directions with a wave speed ci = 2.2
km/h and two external (barotropic) modes propagating in the same oppo-
site directions with a larger speed ce = 50 km/h. Since the initial surface
elevation is set to zero, the latter modes only have a negligible impact. As a
consequence the slope front in the middle of the channel splits in two equal
parts. The upper (lower) part moves with speed −ci to the left (right).
Vertical motions are generated above and below the slope front which are
downwards directed along the leftward moving front and upward along the
rightward moving front. The circulation is closed between the two fronts by
an horizontal current towards the left in the upper and towards the right in
the lower layer. This evolution is illustrated in Figures 18.8a–c showing the
circulation and the front after 1, 3, and 6 hours. The frontal system reaches
the boundaries of the domain after nearly 7 hours.

To test firstly the influence of the advection of momentum and secondly the
type of advection scheme the following four experiments have been defined:
A : advection of momentum switched off, TVD scheme for salinity
B : upwind scheme for momentum and salinity
C : upwind scheme for momentum, TVD scheme for salinity
D : TVD scheme for momentum, upwind scheme for salinity
E : TVD scheme for momentum and salinity

Experiment C uses the default scheme implemented in the program. The

simulations are performed for a period of 7 hours. The results obtained with
scheme C are compared with the analytical solution in Figures 18.8a–f. The
five experiments are compared in Figures 18.9 showing the distributions after
4 hours.
The following output parameters are defined
hleft The distance (km) of the leftward moving front with respect to the
centre of the channel. The position of the front is taken at the
location where the vertical current in the upper layer attains its
largest negative value.
hright The distance (km) of the rightward moving front with respect to
the centre of the channel. The position of the front is taken at
the location where the vertical current in the lower layer attains its
largest positive value.
v2up The value of the horizontal current (m/s) in the upper layer averaged
between the two fronts.
v2lo The value of the horizontal current (m/s) in the lower layer averaged
between the two fronts.
wmaxup Maximum value of the vertical current (mm/s) in the upper layer.
wmaxlo Maximum value of the vertical current (mm/s) in the lower layer.
wminup Minimum value of the vertical current (mm/s) in the upper layer.
wminlo Minimum value of the vertical current (mm/s) in the lower layer.
sdev The relative difference between the volume averaged salinity and its
initial value, defined by
sdev = 107 (hS(t)i − hS(0)i)/hS(0)i (18.9)
where a h i denotes the averaged value over the whole width and
depth of the channel. Since the salinity fluxes are zero at the surface,
the bottom and along the solid side walls, the exact value of SDEV
is zero. Since the numerical schemes for the advection of salinity are
conservative, non-zero values are only produced by rounding errors.
This parameter is therefore useful to test the machine accuracy.
In the definition of the above parameters the upper and lower layer are conve-
niently taken at respectively 5.5 below the surface and 4.5 above the bottom.
Values for the analytical solution are given in Table 18.1.
Table 18.1: Output values for the analytical solution of test case seich.
time (h) 1 2 3 4 5 6
hleft 2.750 5.250 7.250 9.750 11.75 13.75
hright 2.750 5.250 7.250 9.750 11.75 13.75
v2up -0.1188 -0.1273 -0.1358 -0.1355 -0.1392 -0.1417
v2lo 0.1316 0.1401 0.1486 0.1483 0.1520 0.1545
wmaxup 0.4180 0.4180 0.4180 0.4179 0.4180 0.4180
wmaxlo 0.3432 0.3433 0.3432 0.3433 0.3433 0.3432
wminup -0.4185 -0.4185 -0.4185 -0.4186 -0.4185 -0.4185
wminlo -0.3431 -0.3431 -0.3431 -0.3431 -0.3431 -0.3431
sdev 0 0 0 0 0 0
Figure 18.7: The initial configuration of the seich test case.

Figure 18.8: Evolution of the current field, salinity and the frontal system
for the seich test case after 1, 3, and 6 hours according to the analytical
theory (a, b, c) and experiment C (d, e, f).
Figure 18.9: Current field and salinity distribution for the seich test case
after 4 hours using scheme A (a), B (b), C (c), D (d) and E (e).
18.3.4 Results
• It should be remarked first that contrary to the numerical setup the an-
alytical derivation assumes that the channel has open ends allowing the
perturbation to propagate towards infinity. This explains the (barely
visible) small perturbation in the current field outside the fronts caused
by the barotropic mode which already attains the edges of the channel
after 17 min and bounces off the solid walls. The model appears in
good agreement with the analytical theory. A notable difference is the
initial occurrence of spurious oscillations of the current field gradually
attenuating in time. Note also that the interface which separates the
upper and lower layer between the two fronts is spread over 3–4 m (or
grid cells). The interface thickness remains however uniform in time.
• The numerical oscillations of the current field are more clearly observed
in the case of scheme A which does not advect momentum, whereas
they are almost absent in the other runs due to numerical diffusion by
the advection scheme. Note also the larger thickness of the interface
when the salinity is advected by the upwind scheme (experiments B
and D).
• Comparing the values of the parameters hleft and hright for the ana-
lytical case and the four experiments it is seen that the fronts advance
more slowly to the left and the right in the model results. This indi-
cates that the internal wave speed ci is somewhat underestimated by
the model. Best agreement is found for experiments C and E using the
TVD scheme for salinity.
• The magnitude of the horizontal current is underestimated by the

model in the upper and lower layers. However, the horizontal kinetic
energy has the tendency to increase in all cases. This occurs at the ex-
pense of potential energy which decreases while the fronts are moving.
• The vertical velocity is non-zero only above and below the points where
the interface has a non-zero gradient. The maximum and minimum
values within the upper and lower layer are time-independent in the
analytical solution which is not the case in the model results where
the magnitude of the vertical current decreases with time both in the
upper and the lower layer. This may be due to numerical diffusion.
Best agreement is for experiment E.
• All scalar advection schemes are discretised in a conservative form

within the program. This means that sdev should be zero in the absence
of rounding errors. The magnitude of this parameter has a maximum

value mostly below 4×10−7 which may considered as sufficiently accu-
rate.
18.4 Test case fredy

The test case fredy is a 3-D problem intended to compare the advection
schemes of momentum and scalars and was used previously in the MAST-
NOMADS project (Proctor, 1997) as an intercomparison study for shelf sea
models. The results of the exercise are described in Tartinville et al. (1998).
The initial setup of the problem is based upon an earlier numerical study
of James (1996). An analogous series of laboratory experiments has been
conducted by Griffiths & Linden (1981) whereby a bottomless cylinder of
fresh water is immersed into a rotating tank containing a fluid of higher den-
sity. After removal of the cylinder the fresh water spreads radially outwards
until a geostrophic quasi-equilibrium state is reached. During the next stage
non-axisymmetric instabilities develop in the form of growing vortices at the
edge of the cylindrical area. The number of vortices is determined by the
growth rate of the most unstable mode which depends on the initial para-
meters of the experiment. The laboratory results bear resemblance to those
obtained by Madec et al. (1991) who investigated numerically the process of
deep water formation in the Mediterranean Sea and found similar eddy-like
structures.
The setup used in test case fredy is almost the same as in Tartinville
et al. (1998). A 20 m deep squared basin is considered. The domain is closed
by four solid boundaries and the basin has a width of 60 km to minimise
the influence of the side walls. The grid resolution is 1 km in the horizontal
and 1 m in the vertical3 . The initial salinity distribution in PSU, shown in
Figures 18.10 is given by
S = 1.1(D/3)8 + 33.75 if D ≤ 3 and d ≤ 10

= 34.85 otherwise (18.10)
where D is the distance in km to the axis of the cylinder, located at (29.5,29.5)

in Figure 18.10 (left) and d denotes the depth in m. The density is determined
with the aid of the equation of state
ρ = ρ0 (1 + βS (S − S0 )) (18.11)
3
For convenience, the outer 15 km of the basin are not displayed in Figures 18.10–18.13.
18.4. TEST CASE FREDY 537
The simulated area is located at 520 3′ N with a corresponding Coriolis fre-

quency of 1.15×10−4 s−1 .
The initial current and surface elevation are set to zero. The problem
is further simplified by neglecting all diffusion terms and setting the surface
and bottom stress equal to zero. The simulation is performed for a period
of 6 days. The program solves the following equations: the 2-D and 3-D
momentum and continuity equations, and the salinity equation.

The results, presented in Tartinville et al. (1998), clearly show that the type
of advection scheme, used for momentum and salinity, has an important
influence on the development and structure of the baroclinic eddies. Only
the upwind and TVD scheme with the superbee limiter are considered in the
present study. The following four experiments are defined:
A : upwind scheme for momentum and salinity
B : TVD scheme for momentum, upwind for salinity
C : upwind scheme for momentum, TVD for salinity (default schemes of the
program)
D : TVD scheme for momentum and salinity
A series of figures is produced showing the state at the end of the simulation
for the four experiments: surface distributions of current and salinity (Figure
18.11), surface distributions of the vertical vorticity (Figure 18.12), current
and salinity along a lateral transect parallel to the X-axis and through the
axis of the cylinder (Figure 18.13).
In analogy with Tartinville et al. (1998) the volume-integrated kinetic
energy, available potential energy and enstrophy are defined by
1 Z
Ekin = ρ0 (u2 + v 2 ) dV (18.12)
2 V (t)
Z Z
Epot = ρgx3 dV − ρ0 gx3 dV0
V (t) V0
1 Z
2
Z
= gρ0 ζ dS − ρ0 bx3 dV (18.13)
2 S(t) V (t)
Z ∂v ∂u 2
Estr = − dV (18.14)
V (t) ∂x1 ∂x2
where V (t) is the volume of the basin, V0 its initial value, S(t) the surface,
ζ the surface elevation and b = −g(ρ − ρ0 )/ρ0 the buoyancy. A fourth quan-
tity a1% is defined as the surface area bounded by the contour line where
the salinity is 0.01 PSU less than the ambient value of 34.85 PSU. This is
determined by the number of surface grid cells where the salinity is less than
34.839 PSU multiplied by the area of a surface grid cell. Time series of these
four quantities are plotted in Figures 18.14.
The following output parameters are defined for this test case:
ekin Volume integrated kinetic energy (109 J) as defined by (18.12).
epot Volume integrated available potential energy (109 J) as defined by
(18.13).
enstr Volume integrated vorticity (m3 /s2 ) as defined by (18.14).
a1pt Value of a1% (108 m2 ).
salmin The minimum salinity value (PSU) inside the domain.
salmax The maximum salinity value (PSU) inside the domain.
sdev In analogy with the test case seich this parameter represents the
relative difference between the volume averaged salinity and its initial
value and is, defined by
sdev = 106 (hS(t)i − hS(0)i)/hS(0)i (18.15)
where a h i represents an averaged value over the entire domain. This

parameter is useful for testing the machine accuracy.
theta The value of the ratio Ekin /Epot averaged over an inertial period,
determined by applying an harmonic analysis for the last 3 days (4.7
inertial periods).
18.4.3 Results
The following conclusions are made:
• A four-lobed structure is obtained. This is clearly observed in Figu-
res 18.11d and 18.12d for scheme D and in a much weaker form for the
other experiments.
• In analogy with the experimental results of Griffiths & Linden (1981)
four cyclonic vortex rings develop at the points where the unstable
displacements are directed inwards. The vortices are separated by ar-
eas with a weaker anticyclonic vorticity. The phenomenon is again
most clearly observed for scheme D. This shows the ability of the TVD
scheme to simulate highly sheared density fronts.
• The main circulation pattern consists of an outward (inward) displace-

ment of the central area above (below) the interface, upwelling inside
and below the fresh water patch with a maximum at the edge of core
region and downwelling motions a few km outside the front. Note also
the different depths of the fresh water layer in the four experiments. In
the case of schemes C and D the interface depth decreases from 10 to
5–6 m giving a much shallower surface layer compared to A and B.
• During the first hours of the simulation the kinetic energy increases at
the expense of potential energy representing the outward expansion of
the core region. As soon as a quasi-geostrophic balance is achieved and
the eddies start to grow, both Ekin and Epot oscillate with the inertial
period and opposite phases. This quasi-equilibrium state is most clearly
attained for experiment D, whereas Ekin and Epot gradually increase in
the case of experiments A and B. Note also that the vorticity, measured
by the parameter Estr , is stronger in experiments B and D which use
the TVD scheme for the advection of momentum. On the other hand,
the surface area of the patch increases more rapidly for schemes A and
B. This is due to the larger numerical diffusion produced by the upwind
scheme for salinity.
• According to Tartinville et al. (1998) the form and growth of the eddies
is related to the ratio Θ of the kinetic to the available potential energy
(represented here by the output parameter theta). Firstly, the number
of baroclinic eddies given by the wavenumber n scales as n ∼ Θ−1/2 .
Simulations using the PPM advection scheme both for salinity and cur-
rents (James, 1996) yield a value of Θ of ∼0.5 and a 2-lobed instability.
This is comparable to the value obtained with scheme D in which case,
however, a 4-lobed instability is found. Secondly, the growth rate of
the instability increases with Θ1/2 . This is, at least qualitatively, in
agreement with the present results, as can be seen by comparing the
development of the eddies in Figures 18.11 and 18.12 for experiments
A, C, B and D which corresponds to increasing values of Θ.
Figure 18.10: Initial salinity distribution for the fredy test case along the
surface (a) and along a transect parallel to the X-axis and through the patch
(b).
Figure 18.11: Test case fredy. Surface current and salinity after 6 days for
experiment A (a), B (b), C (c), D (d).
Figure 18.12: Test case fredy. Surface vorticity normalised by the Coriolis
frequency for experiment A (a), B (b), C (c), D (d).
Figure 18.13: Test case fredy. Current and salinity along a transect parallel
to the X-axis and through the centre of the patch after 6 days for experiment
A (a), B (b), C (c), D (d).
Figure 18.14: Test case fredy. Time series of the kinetic energy Ekin in 109 J
(a), the available potential energy Epot in 109 J (b), the enstrophy Estr in
m3 /s2 (c) and the fresh water area A1% in units of 108 m2 (d) for experiment
A (solid), B (dots), C (dashes), D (dash-dots).
Chapter 19
Turbulence and heat flux

formulations
19.1 Test case pycno

19.1.1 Theory
This test case is a 1-D problem describing the evolution of a wind-driven
surface mixed layer in the absence of rotation. Although simple in form
the problem is of considerable oceanographic interest. Moreover it allows to
intercompare in a simple way the different turbulence formulations imple-
mented in the program. The initial state consists of a water column at rest
with a stable stratification in the vertical using a constant density gradient.
A surface stress is applied initially remaining uniform in space and time. A
surface mixed layer develops which grows in time. The deepening is governed
by the entrainment of denser water at the base of the mixed layer. As will
be shown below the process critically depends on some parameters of the
turbulence formulation while others are of less importance.
The basic equations in the absence of advection and horizontal diffusion
are given by
∂u ∂ ∂u
= νT (19.1)
∂t ∂z ∂z
∂ρ ∂ ∂ρ
= λT (19.2)
∂t ∂z ∂z
where z is the vertical coordinate (increasing upwards and zero at the sur-
face), u the current, ρ the density and νT , λT the vertical eddy coefficients1 .
1
The eddy coefficients reduce to their molecular values in the absence of turbulence.
545
546CHAPTER 19. TURBULENCE AND HEAT FLUX FORMULATIONS
The initial and boundary conditions are given by

g ∂ρ
u=0, − = N02 at t = 0 (19.3)
ρ ∂z
∂u ∂ρ
νT = u2∗s , λT = 0 at z = 0 (19.4)
∂z ∂z
where N0 is the uniform initial buoyancy frequency and ρ0 a reference density.
Kundu (1981) explored the possibility to cast the solutions of (19.1) and
(19.2) into a self-similar form
u(z, t) = Û (t)F (ξ) (19.5)
ρ(z, t) = ρh (t) + (ρ̂(t) − ρh (t))G(ξ) (19.6)
where ξ = −z/h(t), h(t) is the depth of the turbulent layer2 , ρh the density
at the base of the layer and Û , ρ̂ the values of respectively the current and
density averaged over the turbulent layer. He showed that (19.5)–(19.6)
are acceptable forms provided that the following additional assumptions are
made:
• u = 0 and Ri = −ρ0 (∂u/∂z)2 /(g(∂ρ/∂z)) = Ric at z = −h where Ric
is a constant critical Richardson number
• the eddy coefficients can be cast into the form
νT = fν (ξ)h2 /t , λT = fλ (ξ)h2 /t (19.7)
The solutions of (19.1)–(19.2) can then be written as

u∗s
u(z, t) = F (ξ)(tN0 )1/2 (19.8)
(2Ri)1/4
∆ρ(z, t) = ρ(z, t) − ρ(z, 0)

ρ0 N02
= (2 − 2ξ − G(ξ))h(t) (19.9)
2g
and
h(t) = (2Ri)1/4 u∗s (t/N0 )1/2 (19.10)
The bulk Richardson number Ri is defined by
N02 h2 (t) F ′2 (1)
Ri = =− ′ Ric = constant (19.11)
2Û 2 (t) G (1)
where a ′ denotes a derivative with respect to ξ. For a more profound theo-
retical discussion of this idealised mixed layer problem the reader is referred
to the papers by e.g. Kundu (1981); Kranenburg (1983); Luyten et al. (1996).
2
This definition of h should not be confused with the one for the mean water depth.
19.1. TEST CASE PYCNO 547
19.1.2 Model setup

Equations (19.1)–(19.4) are solved numerically with the following parameters
u∗s = 0.01m/s , N0 = 0.01s−1 (19.12)
for a simulated period of 1 day. The total water depth is set to 100 m which
is more than 2 times larger than the simulated mixed layer depths. The
density equation (19.2) is transformed into an equivalent salinity equation
using a linear equation of state. The initial salinity field is given by
N02
S = S0 − (z + H) (19.13)
gβS
where S0 is a reference salinity and H the water depth.

Seven numerical experiments have been defined by setting a number of tur-
bulence switches. The following schemes are used in the experiments:
A : zero-equation k − l model using the Mellor-Yamada expressions for

the stability functions and the “Blackadar” mixing length formulation
(4.204)–(4.205)
B : one-equation model using the Munk-Anderson formulation (4.187) for

the stability functions and the “Blackadar” mixing length (4.204)–
(4.205) without limiting conditions
C : as scheme B now including the limiting conditions (4.213)–(4.214)
D : one-equation model using the k − ε and Hossain-Rodi formulation for

the stability functions, and the parabolic mixing length (4.201) with
limiting conditions enabled
E : as scheme D now using Blackadar’s (4.204)–(4.205) mixing length for-

mulation
F : two-equation k − l model using the Mellor-Yamada formulation for the

stability functions and with limiting conditions enabled
G : two-equation k − ε model using the Hossain-Rodi formulation for the

stability functions and with limiting conditions enabled.
Table 19.1: Settings of the turbulence switches for the pycno experiments.
A “-” means that the value of the switch is irrelevant.
switch A B C D E F G
iopt turb ntrans 0 1 1 1 1 2 2
iopt turb param 1 1 1 2 2 1 2
iopt turb stab form 3 2 2 3 3 3 3
iopt turb lmix 4 4 4 1 4 - -
iopt turb stab mod 1 - 1 4 4 1 4
iopt turb iwlim 0 0 1 1 1 1 1
Values of the corresponding turbulence switches are listed in Table 19.1. Note
that experiment E corresponds to the default scheme of the program (except
for the inclusion of limiting conditions). All schemes, except B and C, yield
a critical Richardson number so that the first criterion for self-similarity is
satisfied. It can be demonstrated that none of the schemes complies with the
second criterion. As shown by Luyten et al. (1996) the latter condition is of
minor importance.
Time series of the mixed layer depth h(t), the surface current u(0, t)
and the surface density difference ∆ρ(0, t) are shown in Figures 19.1a–f. The
mixed layer depth is determined as the surface distance of the first grid point
below the surface where the current is lower than 1% of its surface value.
Vertical profiles of the current u, the density ρ minus the initial surface value
ρ(0, 0) and the Richardson number at the end of the simulation period are
plotted in Figure 19.2.
A number of output parameters are defined. Their intention is primarily
to compare the results with the self-similarity theory. Equations (19.8)–
(19.11) for the surface current, the surface value of ∆ρ, h(t) and Ri are then
written in the form
ln h = αh + βh ln(tN0 ) (19.14)
ln u(0, t) = αu + βu ln(tN0 ) (19.15)
ln ∆ρ(0, t) = αd + βd ln(tN0 ) (19.16)
ln Ri = αr + βr ln(tN0 ) (19.17)
where, according to the self-similarity theory,
βh = βu = βd = 1/2 , βr = 0 (19.18)
and
1 u
⋆s
αh = ln(2Ri) + ln (19.19)
4 N0
The eight coefficients (αh ,αu ,αd ,αr ), (βh ,βu ,βd ,βr ) in (19.14)–(19.17) are de-
termined from the model results by applying a linear regression analysis. To
remove the influence of initial conditions and adjustments the analysis is re-
stricted to the last 14 hours. A description of all output parameters is given
below.
rvmean The value of Ri defined by (19.11) and averaged over the last 14
hours.
brv The coefficient βr in the linear relation (19.17) for Ri.
corrv The squared correlation coefficient r2 for the linear relation (19.17).
A zero value indicates that Ri is uncorrelated with time.
rvmean2 The value of Ri as determined from (19.19).
bh The coefficient βh in the linear relation (19.14) for h(t) (log(m)).
corrh The squared correlation coefficient r2 for the linear relation (19.14).
bu2 The coefficient βu in the linear relation (19.15) for u(0, t) (log(m/s)).
corru2 The squared correlation coefficient r2 for the linear relation (19.15).
bdr0 The coefficient βd in the linear relation (19.16) for ∆ρ(0, t) (log(kg/m3 )).
corrdr0 The squared correlation coefficient r2 for the linear relation (19.16).
vedmax The maximum value of the eddy viscosity coefficient νT over the
whole water depth (m2 /s) at the end of the simulation.
difmax The maximum value of the eddy diffusion coefficient λT over the
whole water depth (m2 /s ) at the end of the simulation.
tkemax The maximum value of the turbulence energy k over the whole water
depth (J/kg) at the end of the simulation .
tmld The value of h at the end of the simulation (m).
usur The value of the surface velocity at the end of the simulation (m/s).
drosur The value of the surface density difference ∆ρ at the end of the
simulation (kg/m3 ).
sdev The relative difference between the depth-averaged salinity and its
initial value, defined by
sdev = 105 (S(t) − S(0))/S(0) (19.20)
where an overbar denotes a depth-averaged value. Since there are no
bottom and surface salinity fluxes, the exact value of sdev is zero. A
conservative scheme is applied in the model for the vertical diffusion
of salinity so that non-zero values are only due to rounding errors.
This parameter is therefore useful to test the machine accuracy.
Values for all experiments are given in Table 19.2.
Table 19.2: Output values for the parameters of test case pycno.
parameter A B C D E F G
rvmean 0.3318 4.028 1.014 0.6097 0.5974 0.6002 0.4777

brv 0.0592 0.3793 0.0503 0.0357 0.0176 0.0361 -0.0529
corrv 0.2223 0.9702 0.3253 0.1602 0.0568 0.2012 0.0036
rvmean2 0.2275 0.3559 0.7355 0.4852 0.5341 0.4766 0.4942
bh 0.5147 0.5948 0.5126 0.5089 0.5044 0.5090 0.4987
corrh 0.9971 0.9992 0.9987 0.9984 0.9987 0.9987 0.9980
bu2 0.5019 0.3515 0.4106 0.4294 0.4267 0.4159 0.4214
corru2 0.9999 0.9997 1.000 1.000 1.000 1.000 0.9999
bdro 0.4897 0.5653 0.5356 0.5254 0.5303 0.5329 0.5374
corrdro 0.9999 1.000 1.000 1.000 1.000 1.000 1.000
vedmax 10.19 1.247 1.187 1.890 1.252 1.506 1.350
difmax 12.79 1.422 1.385 2.587 1.825 2.166 1.663
tkemax 226.2 3.254 3.254 3.036 3.036 3.036 4.362
tmld 26.75 51.25 35.25 30.75 30.75 30.75 29.25
usur 0.6497 0.4002 0.4377 0.4415 0.4634 0.4518 0.4789
drosur 0.0987 0.1530 0.1418 0.1348 0.1333 0.1340 0.1244
sdev -2.337 -4.297 -13.01 -0.1192 -0.0596 -0.0954 -0.9775
Figure 19.1: Test case pycno. Time series of the mixed layer depth (a–b),
the surface current (c–d) and the surface density difference ∆ρ(0, t) (e–f).
Test runs A, B, C, are represented in Figures a, c, e by the solid, dotted
and dashed curves respectively. Test runs D, E, F, G are shown in Figures
b, d, f by the solid, dotted, dashed and dash-dotted curves respectively.
Figure 19.2: Test case pycno. Vertical profiles of the current (a–b), the den-
sity minus its initial surface value, ρ(z, t) − ρ(0, 0) (c–d) and the Richardson
number (e–f) after one day. Experiments A, B, C are represented in (a),
(c), (e) by the solid, dotted and dashed-dotted curves respectively. Experi-
ments D, E, F, G are shown in (b), (d), (f) by the solid, dotted, dashed
and dash-dotted curves respectively.
Figure 19.3: Test case pycno. Vertical profile of the vertical diffusion coef-
ficient λT after one day (a) and time series of λT at 10 m depth during the
last hour of the simulation (b) for experiment A.
19.1.4 Results
The results can be summarised as follows:
• The time-averaged bulk Richardson number Ri (parameter rvmean) is
much higher for the schemes B and C which use the Munk-Anderson
formulation for the stability functions compared to the other schemes
using a RANS model.
• The general time dependence of Ri (not shown) consists of an oscilla-
tion around a mean value which increases in time. The amplitude of the
oscillations and the growth rate of the mean value of Ri remain small
in all cases except B. This explains why brv is larger for B compared
to the other experiments.
• The parameter rvmean2 is mostly lower than rvmean. The former is
obtained from the linear regression analysis and (19.19) whereas the
latter is evaluated using its definition (19.11). The difference is larger
for the schemes A–C indicating that the self-similarity hypothesis is
less valid for this type of schemes. The laboratory data of Kato &
Phillips (1969) calibrated by Price (1979) yield a value of Ri close to 0.6
which agrees more with the values predicted by the RANS schemes D,
E, F, G than the ones obtained from the Munk-Anderson formulations
B, C.
• The parameters βh and βd are close to 0.5 in agreement with the value
predicted by the self-similarity theory whereas βu ≃ 0.4 (except for
case A) which is lower than the theoretical value of 0.5.
• For larger values of Ri (parameter rvmean) the surface current tends to
decrease whereas the surface density and the mixed layer depth tend
to increase in agreement with equations (19.8)–(19.10).
• The schemes D to G produce larger shears near the surface and much
shallower mixed layer depths compared to the B and C schemes. Note
the remarked difference between the zero-equation and two-equation
models A and F which are physically nearly the same. The discrepancy
is most clearly observed in the profiles of the current (Figures 19.2a–b
and the density (Figures 19.2c–d).
• From Figures 19.2e–f one observes that the Richardson number ap-
proaches its critical value in the stratified zone just below the surface
mixed layer (except in the runs A and B). Note that Ri ≃ Ric at the
base of the turbulent layer for the schemes C–G which use a limiting
19.2. TEST CASE CSNSP 555
condition (iopt turb iwlim=1). The highly oscillating curve for run A
is due to a numerical instability (see below).
• It is clear that the results obtained with the zero-equation model A

should not be considered as realistic. This type of schemes becomes
numerically unstable either when the time step ∆t is too large or the
vertical grid spacing ∆z is too small. The problem is illustrated in
Figures 19.3 showing the vertical profile of λT at the end of the sim-
ulation and a time series of λT for the last hour of the run at 10 m
depth. An unrealistic “jittering” is observed oscillating over 2 vertical
grid spacings. The problem can be remedied by increasing the vertical
resolution. A more elaborate discussion can be found in Frey (1991);
Luyten et al. (1996). Since there exists no clear criterion for the stabil-
ity of the level 2 schemes, it is recommended to avoid the zero-equation
scheme in a realistic model application.
19.2 Test case csnsp

The intention of the previous test case is to verify the different turbulence
schemes implemented in the program against analytical solutions. The setup
of these applications is however far from the realistic conditions prevailing
in coastal and shelf seas. A more realistic study should take account of
the effects of e.g. wind, tides and seasonal stratification. Test case csnsp
has been constructed for this purpose. This simulates the annual cycle of
thermal stratification at station CS (55◦ 30′ N, 0◦ 55′ E) located in the deeper
parts of the North Sea where a thermocline forms during the summer. The
model is forced using realistic meteorological and tidal data. To limit CPU
time the simulation is performed with the 1-D (water column) version of
the program so that advective effects are ignored. The results can validated
with the observed data sets of the UK North Sea Project (Charnock et al.,
1994). This test case allows to compare the influence of different formulations
available in the program (turbulence, boundary conditions, optics, equation
of state).
Using the notations of Section 19.1.1 the basic equations in Cartesian
coordinates (x,y,z) are:
∂u ∂ζ ∂ ∂u
− f v = −g + νT (19.21)
∂t ∂x ∂z ∂z
∂v ∂ζ ∂ ∂v
+ f u = −g + νT (19.22)
∂t ∂y ∂z ∂z
∂T 1 ∂I ∂ ∂T
= + λT (19.23)
∂t ρ0 cp ∂z ∂z ∂z
where f = 2Ω sin φ is the Coriolis frequency, φ the latitude, ζ the surface
elevation, T the temperature, cp the specific heat of seawater at constant
pressure and I(z, t) solar irradiance. Neglecting the baroclinic component of
the pressure gradient the surface slope terms are written as
∂ζ ∂ζ
g = F cos(ω2 t − ϕx ) , g = G cos(ω2 t − ϕy ) (19.24)
∂x ∂y
where ω2 is the frequency of the dominant M2 -tide and F , G the specified
amplitudes of the surface slope term.
The boundary conditions are
∂u ∂v ∂T
ρ0 ν T , = (τs1 , τs2 ) , ρ0 cp λT = −Qnsol (19.25)
∂z ∂z ∂z
at the surface, and
∂u ∂v ∂T
ρ0 ν T , = ρ0 Cdb (u2b + vb2 )1/2 (ub , vb ) , ρ0 cp λT
=0 (19.26)
∂z ∂z ∂z
at the bottom where (ub ,vb ) are the velocities at the grid point nearest to the
bottom. Different formulations are used for the surface stress and non-solar
heat flux Qnsol (see below). The bottom drag coefficient Cdb is expressed as
a function of the roughness length z0 . The solar irradiance in the tempera-
ture equation is decomposed into a near-infrared part absorbed in a shallow
surface layer, and a non-infrared part which attenuates exponentially within
a larger surface layer.
The simulation is performed from the beginning of January until the end
of October 1989. As initial temperature the observed vertical profile from
the North Sea Project is taken. The meteorological data are obtained from
the UK Met Office.

Nine experiments are defined. The first four (A, B, C, D) are intended
to examine the role of the turbulence scheme, the next four (E, F, G, H)
analyse the influence of different heat flux parameterisations at the surface.
Light attenuation is disabled in the last experiment I. The general equation
of state (4.92)–(4.96) is used in all experiments (iopt dens=2). Unless stated
otherwise all experiments use the setup of reference experiment A.
Table 19.3: Settings of the model switches for the csnsp experiments. A “-”
means that the value of the switch is irrelevant.
switch A B C D E F G H I
iopt vdif coef 3 3 3 2 3 3 3 3 3
iopt turb alg - - - 2 - - - - -
iopt turb stab form 3 3 2 - 3 3 3 3 3
iopt turb iwlim 1 0 0 - 1 1 1 1 1
iopt temp optic 1 1 1 1 1 1 1 1 0
iopt sflux cds 6 6 6 6 4 6 5 0 6
iopt sflux cehs 0 0 0 0 3 0 4 0 0
iopt sflux strat 2 2 2 2 1 0 2 0 2
A : Uses the Charnock formulation (4.279) for Cds including Monin-Obukhov

stratification (Section 4.8.3). The default turbulence scheme (one equa-
tion, k − ε, Blackadar mixing length, Hossain-Rodi RANS model) is
taken with limiting condition enabled.
B : The limiting conditions for the mixing length and turbulence energy are
disabled.
C : The formulation (4.187) by Munk-Anderson instead of the RANS for-
mulation (Section 4.4.3.3) is implemented for the stability functions
and limiting conditions are disabled.
D : The turbulence scheme is replaced by the simpler empirical relations
(4.125)–(4.129) of Munk and Anderson.
E : The surface exchange coefficients CE and CH are calculated using the
Kondo (1975) formulation (see Section 4.8.2).
F : The surface drag coefficient Cds is determined from the Charnock (1955)
relation (4.279). CE and CH are taken as constants.
G : The formulation by Wu (1980) is used with effects of stratification.
H : Both surface and heat exchange coefficients are taken as constants.
I : The optical mode is disabled, all solar radiation is assumed to be absorbed
at the surface.
The values of the model switches, used for setting up each experiment are
given in Table 19.3.
The following output parameters are defined:
tsur Surface temperature (◦ C) measured one-half grid distance below the

surface.
tbot Bottom temperature (◦ C) measured one-half grid distance above the
bottom.
tmean Depth-averaged temperature (◦ C).
tdep The thermocline depth (m) measured as the distance to the surface
where the temperature is 1◦ C higher than the bottom temperature.
tgrad Maximum value of the vertical temperature gradient (◦ C/m).
twidth This parameter measures the sharpness of the thermocline and is de-
fined as the vertical distance (m) between the two points where the
temperature is equal to respectively 8.5 ◦ C and 12 ◦ C.
19.2.3 Results
turbulence schemes Time series of surface and bottom temperature, and
mixed layer depth for experiments A, B, C, D are compared in Figu-
res 19.4a, 19.5a. Vertical profiles on August 4 are shown in Figure 19.6a.
• Surface, bottom and mean temperature are not much different
between experiments A and B. The schemes are almost identical
except that the former uses a background mixing scheme based on
limiting conditions for turbulence parameters (see Section 4.4.3.6)
which results in a deeper thermocline and a less sharper tempera-
ture gradient in the thermocline.
• Comparing schemes A, C and D it is observed that the first (last
two) produce(s) larger (lower) surface temperatures, lower (larger)
bottom temperature and larger (lower) temperature gradients in
the thermocline. This shows that A is the least diffusive scheme.
This can be explained by the absence of a critical Richardson
number for the turbulence schemes used in C and D.
• The more diffusive scheme D produces an almost vertically mixed
water column at the end of October whereas a significant surface-
bottom temperature difference remains in the latter experiments.
This is clearly observed in Figure 19.4a.
• Less differences are observed for the depth-mean temperature, al-
though there seems to be a tendency for a higher mean tempera-
ture in case of tests C, D compared to A.
• An additional difference between schemes A, B and C, D is that
the mixed layer increases smoothly for the former cases whereas
an abrupt increase in mixed layer depth occurs for the latter cases
each time the surface temperature drops after a wind event during
summer.
drag and exchange coefficients Time series of surface and bottom tem-
perature, mixed layer depth, (upward) non-solar surface heat flux and
the exchange coefficient CE for experiments H, A, E, F, G are com-
pared in Figures 19.4b, 19.5b and 19.7a–b. Vertical profiles on August
4 are shown in Figure 19.6b.
• The differences between the five experiments are most easily seen
in the time series of the surface exchange coefficient. Compared
to the reference case H with constant values and the formulation
F, which does not include a dependence on air-sea temperature
difference, the CE coefficient increases by 50% in experiments A,
G and even by 100% (and occasionally 400%) in test E.
• Contrary to what one may expect intuitively, the differences are
inversely correlated with the behaviour seen in the evolution of the
heat fluxes. For example, experiment G which shows the lowest
time variability for CE , produces the largest maxima and lowest
minima for the heat fluxes. This is explained by a kind of relax-
ation effect. When CE increases, the heat flux will first increase
as well, so that the air-sea temperature difference is reduced. This
occurs quite rapidly and is not seen in the figures showing 3-day
averaged values. Once the difference is reduced the heat flux re-
laxes towards a lower value and CE rapidly decreases again. If
the initial increase of CE is lower, the time of relaxation becomes
longer. This behaviour can be deduced by a close inspection of
Figures 19.7.
• Despite the relaxation mechanism, the use of a stratification de-
pendent scheme for the exchange coefficients has an important
impact on the evolution of surface temperature in summer by de-
creasing its value by 20 C.
• Since all schemes use the same turbulence formulation, the impact
on diffusion, thermocline depth and stratification is less.
light attenuation When all solar light is absorbed at the surface itself and
no longer within the water column, a strong stratification is produced
in a shallow surface layer during periods of strong solar heating and
low winds. The result is a damping of turbulence and less downard
diffusion, yielding significantly larger surface temperatures (upto 50 C)
and shallower thermocline as seen in Figures 19.4 and 19.5. The ef-
fect on surface temperature is only temporary since the extra surface
stratification is removed once the wind increases again.
Results of 1-D numerical simulations at station CS are discussed in Luyten

(1996); Warrach (1998).
Figure 19.4: Test case csnsp. Time series (3-days average) of surface and
bottom temperatures: (a) experiment A (solid), B (dots), C (dashes), D
(dash-dots), I (dash and 3 dots); (b) experiment H (solid), A (dots), E
(dashes), F (dash-dots), G (dash and 3 dots).
Figure 19.5: Test case csnsp. Time series (3-days average) of mixed layer
depth. Legend is as in Figure 19.4.
Figure 19.6: Test case csnsp. Temperature profile on August 4. Legend is

as in Figure 19.4.
Figure 19.7: Test case csnsp. Time series (3-days average) of (upward) non-
solar heat flux (a) and surface exchange coefficient CE (b) for experiment H
(solid), A (dots), E (dashes), F (dash-dots), G (dash and 3 dots).
Chapter 20
Density fronts and river plumes
20.1 Test case river

Salinity fronts due to the fresh water input by river discharges are frequently
occurring features in coastal areas and estuaries. The cross-frontal density
gradients create the well-known estuarine circulation (see e.g. Heaps, 1972;
Garvine, 1974; Officer, 1976) consisting of a surface outflow, a bottom inflow
and downwelling motions at the front. The aim of test case river is to
simulate the circulation and the evolution of a tidally modulated estuarine
front and to analyse the influence of different schemes implemented in the
program.
The problem is simplified by considering a non-rotating channel of uni-
form depth with open ends. Lateral effects are ignored. The channel length
and depth are taken as 140 km and 20 m respectively. The initial posi-
tion of the front is represented through the following distribution shown in
Figure 20.1a:
S = 30 if x ≤ 25
S = 14 (x − 25) + 30 if 25 < x < 45 (20.1)
S = 35 if x ≥ 45
where S is the salinity in PSU and x the distance from the left boundary of
the channel in km.
A tidal forcing is imposed by specifying the elevations and normal trans-
ports at the left boundary in harmonic form:
ζ = A cos(ωt + π/2) , U = cζ (20.2)
√
where c = gH is the barotropic wave speed, H the water depth, U the
depth-integrated current, ω = π/6 rad/h the S2 semi-diurnal frequency and
565
566 CHAPTER 20. DENSITY FRONTS AND RIVER PLUMES
Table 20.1: Settings of the model switches for the river experiments. A “-”
means that the value of the switch is irrelevant.
switch A B C D
iopt adv 2D 1 1 1 3
iopt adv 3D 1 1 1 3
iopt vdif coef 3 2 2 3
iopt turb alg - 1 3 -
A the forcing amplitude taken as 0.8 m. At the right boundary, the nor-
mal gradient of the incoming Riemann variable R− is assumed to vanish, i.e.
∂R− /∂x = 0. This allows the tidal wave to propagate freely from left to
right. Since salinity remains vertically and horizontally homogeneous near
the channel ends during the entire simulation, a zero normal gradient condi-
tion is selected for salinity at the two open boundaries.
The tidal current field within the simulated domain is initialised by split-
ting the simulation in two phases. During a first spin-up phase of 2 days the
model is run without salinity. The salinity front is introduced at the start of
the second run which takes 3 days.

Four experiments have been setup. The first three show the influence of
the turbulence scheme while the fourth is intended to test the role of the
advection scheme for momentum.
A : upwind scheme for momentum advection, default scheme for turbulence
B : Paconowski-Philander algebraic scheme for turbulence, upwind scheme

for momentum advection
C : a flow-dependent algebraic scheme for turbulence, upwind scheme for

advection of momentum
D : default scheme for turbulence, TVD scheme for the advection of mo-
mentum.
In all experiments the TVD scheme is applied for salinity. The values of the
model switches, used for setting up each experiment are given in Table 20.1.
The final run is performed for 6 tidal cycles. The evolution of the front
and the current field is shown in Figures 20.1b–f for the last cycle and the
scheme A at intervals of 3 hours. Use is made of the program’s utility for
20.1. TEST CASE RIVER 567
making an harmonic analysis. Residuals, amplitudes and phases of the cur-

rent and salinity are calculated by the program using a daily period. The
distributions of the residual fields, obtained with scheme A, are plotted in
Figures 20.2a–c at daily intervals. The results for the last day are compared
with those obtained for the other three experiments in Figures 20.2d–f. The
non-analysed distributions of current and salinity at the end of the simula-
tion are compared for the four experiments in Figures 20.3a–d. Note that
the lowest 8 meters have been omitted in Figures 20.1 and 20.3. The time
evolution of the position of the surface front, measured by the parameter
hfront (see below), is displayed in Figure 20.4 for the four experiments.
hfront The location of the point where the front outcrops the surface, mea-
sured by the distance in km of the 34 PSU contour line (taken at the
first grid cell below the surface) to the left boundary.
pdep The depth of the halocline measured 5 km to the left of the surface
front. This is determined as the depth in m of the point where the
salinity first equals 34.5 PSU.
hgrad This parameter measures the strength of the horizontal salinity gra-
dient below the surface layer and is defined as the maximum value of
|dS/dx| in PSU/km along a layer halfway between the surface and the
bottom. Note that the initial value, according to (20.1), is given by
0.25 PSU/km.
vgrad This parameter measures the sharpness of the halocline and is defined
as the maximum value of |dS/dz| in PSU/m along a vertical profile
at 5 km to the left of the surface front.
The following harmonic parameters are defined at a location in the mid of

the channel:
sures Residual value of the surface current in m/s.

suamp Amplitude of the surface current in m/s.
supha Phase of the surface current in degrees.
bures Mid-depth value of the residual current in m/s.
buamp Mid-depth amplitude of the current in m/s.
bupha Mid-depth phase of the current in degrees.
Figure 20.1: Test case river. Initial position of the salinity front (a). Evolu-
tion of the current and salinity fields during the last tidal cycle for experiment
A at intervals of 3 hours (b–f).
Figure 20.2: Test case river. Residual salinity and current field for experi-
ment A analysed for day 1 (a), 2 (b), 3 (c). The same now for day 3 and
experiment B (d), C (e), D (f).
Figure 20.3: Test case river. Distributions of current and salinity at the end
of the simulation for experiment A (a), B (b), C (c), D (d).
Figure 20.4: Test case river. Time series of the distance to the left boundary
of the point where the front outcrops the surface for experiment A (solid),
B (dots), C (dashes), D (dash-dots).
20.1.3 Results
The evolution of the frontal system for experiment A can be described as fol-
lows. The initial configuration represents a non-equilibrium state. Although
the model setup is different from the seich problem, where turbulent dif-
fusion is absent, there is some similarity. A circulation is generated with
a surface flow to the right, a bottom flow to the left, downwelling at the
right edge and upwelling at the left edge of the front. Contrary to the seich
test, the current is generated by a balance between the baroclinic pressure
gradient and the vertical diffusion term, induced by tidal friction (Officer,
1976). The initial evolution therefore consists of a slight displacement of the
surface front to the right and the bottom front to the left. The circulation
pattern is modulated by the tide so that at the end of the cycle the front al-
most returns to its original position. The turbulent diffusion term, however,
varies with the tide. This means that turbulence is suppressed during the
phases where the current reverses sign and the shear is low. At that time
the balance in the momentum equation is now mainly between the baroclinic
pressure and inertia terms as in the seich problem giving a net displace-
ment of the surface layer to the right. The surface and bottom layer are
separated by a halocline of increasing strength. The vertical stratification
reduces the turbulence even further and enhances the motion of the surface
layer to the right. Figure 20.4 shows that the front moves with an almost
uniform mean speed on which tidal modulations are superimposed. As the
front moves further out downwelling at the front due to frontal convergence,
first increases and then decreases. The main aspects of the physical analysis
can be observed in Figures 20.1b–f and Figure 20.4.
The results for the other three experiments can be summarised as follows:
• Experiment B uses the Paconowski-Philander scheme. Contrary to the
default scheme, turbulence is less reduced in the case of a strong stable
stratification. The result is a more diffusive halocline and a slower
outward expansion of the front.
• The flow-dependent scheme of experiment C is much more diffusive.

The front returns to its initial position after each cycle so that no
halocline forms and the front does not expand outwards. The test
clearly shows the importance of the turbulence scheme in the simulation
of estuarine fronts.
• Experiment D uses the same turbulence model as scheme A but advects

the current with the less diffusive TVD scheme. The results are an
increase of the inertial force and horizontal density gradient and a larger
expansion speed of the surface front.
• In experiment D, the upwelling and downwelling motions are mod-

ulated by the tide which generates in combination with the vertical
density gradient, an internal tide. The wavelength of the tide is ∼ 5
km. Only the TVD scheme is capable of representing this internal tide.
This indicates again the importance of adequate schemes for advection
and turbulence to model frontal processes.
20.2 Test case plume

In the test case river, the evolution of a salinity front was simulated within
a narrow non-rotating channel. When a river discharges fresh water into
the open sea, rotational effects become important and the problem becomes
three-dimensional. The formation and evolution of river plumes has been ex-
amined numerically by e.g. Chao & Boicourt (1986); Chao (1988); Kourafalou
et al. (1996) in the absence of tides and by Ruddick et al. (1995) who simu-
lated the tidally modulated plume of the river Rhine. The general picture,
20.2. TEST CASE PLUME 573
emerging from these studies, is that the fresh water released at the river
mouth, first expands seawards and then turns anticyclonically (i.e. to the
right looking seawards in the northern hemisphere). Before reaching the
coast again, the plume water deflects in the cyclonic sense forming a buoy-
ancy driven coastal jet. The general form of the plume then consists of an
anticyclonic bulge with a coastal plume to the right (in the northern hemi-
sphere). The width of the plume is of the order of the baroclinic Rossby
radius (∼5–10 km).
The aim of the test case plume is to simulate the evolution of a tidally
modulated river plume using the idealised conditions of a uniform water
depth and no wind forcing. The computational domain has the form of a
rectangle enclosed by a coastal (solid) boundary and three open sea bounda-
ries. For convenience, the former will be denoted by the southern boundary,
the latter by the western, eastern cross-shore boundaries and the northern
alongshore boundary. The basin has a length of 120 km, a width of 40 km
and a depth of 20 m. The horizontal resolution is 1 km and 20 levels are used
in the vertical. The area is filled initially with seawater having a uniform sali-
nity of 33 PSU. The simulations are performed in Cartesian coordinates with
the x-axis taken alongshore and the y-axis across-shore (see Figure 20.5).
Tidal forcing is imposed in the form of a frictionless Kelvin wave entering
at the western boundary and propagating along the coast (Ruddick et al.,
1995). The incoming Riemann variable, specified at the western boundary,
then takes the form
ζ = Ae−y/c cos(ωt) , U = cζ (20.3)
where the Coriolis frequency is evaluated at a latitude of 52◦ , ω is the M2
tidal frequency, A = 0.8 m and U , c, ζ are as before the depth-integrated
alongshore current, the barotropic wave speed and the surface elevation. The
amplitude of the wave decreases exponentially with distance to the coast with
a decay scale given by the barotropic Rossby radius c/f ≃ 120 km.
The characteristic method with a zero normal gradient condition for the
incoming characteristic is selected at the eastern and northern boundaries.
The condition is justified by the fact that the width of the basin is much
smaller than the external Rossby radius c/f .
In a first phase the model is run for a period of two days (almost four tidal
cycles) without any stratification to initialise the current field and the sea
surface elevation. At the start of the the final run fresh water of 10 PSU is
released through an inlet at the southern boundary located 25.5 km from the
western boundary. The evolution of the plume is then simulated for a period
of three days. The procedures are the same as outlined in Section 20.1.1 for
the river test case.
Figure 20.5: The computational domain for the test case plume. The solid
line(s) indicate the coastal (southern) boundary, the dashed lines the open sea
boundaries and the dotted lines the two cross-shore transects AA′ (x = 30),
BB ′ (x = 50) and the two alongshore transects CC ′ (y = 2) and DD′ (y = 5).
The inlet is located at O. Points P and Q are used for the evaluation of a
number of output parameters (see text).
Since the value of ζ is unknown at the river mouth, the open boundary
condition at the inlet is no longer defined in terms of the incoming Riemann
variable but by specifying the cross-shore component of the depth-integrated
current. This is given as the sum of a residual value, representing the river
discharge, and a tidal component
V = Qd /W + Ar H cos(ωt − ϕr ) (20.4)
where Qd = 1500 m3 /s is the river discharge, W = 1 km the width of the
inlet and Ar = 0.6 m/s the amplitude of the tidal current at the mouth of
the river. The phase ϕr is determined by
ϕr = ωDr /c − π/2 (20.5)
where Dr = 25.5 km so that Dr /c represents the time travelled by the Kelvin
wave from the western boundary to the river mouth. Observations in the
Rhine plume show that the alongshore and cross-shore component are in
anti-phase which explains the use of the factor π/2.
In addition to the previous conditions for the 2-D mode, open boundary
conditions have to be imposed during the final run for the horizontal baro-
clinic currents (δu, δv)1 and the salinity S. At the open sea boundaries a
zero normal gradient (default) condition is taken for all quantities. In the
case of salinity this procedure is a reasonable approximation since the plume
never intersects the western and northern boundary while the cross-boundary
gradient in the non-tidal case (experiment G below) is much smaller than
the along-boundary gradient at the eastern boundary.
The default conditions are no longer applicable at the river mouth where
δv and S are specified in the form of a two-layer stratification
S = 10 , δv = 0.6 if z > −δ
(20.6)
δv = −0.2 if −H ≤ z ≤ −δ
where δ = 5 m is the specified depth of the plume layer at the mouth. In this
way fresh water is released through the surface layer whereas saltier seawater
flows into the estuary through the bottom layer. A zero gradient condition
is applied for salinity in the bottom layer.

Although the plume problem is a valuable test to examine the role of diffe-
rent physical forcing mechanisms (bathymetry, tides, wind, . . . ) on the plume
structure, the intention here is to test some of the schemes implemented in
the program2 . Seven experiments are defined testing the role of the different
formulations for horizontal diffusion and different boundary conditions.
A : Uses default values and model setup.
B : As experiment A now using the upwind scheme for the advection of

momentum.
C : As experiment B now with horizontal diffusion enabled using the Smagorin-

sky formulation.
D : As experiment B now with horizontal diffusion enabled and using the

uniform values νH = λH = 100 m2 /s for the horizontal diffusion coef-
ficients.
1
The velocity deviations are defined as the current minus its depth-averaged value.
2
The influence of winds on plume evolution are considered in test case rhone discussed
in the next section.
E : As experiment D but the boundary condition (20.3) is replaced by a

condition for the surface elevation only:
ζ = Ae−f y/c cos ω2 t (20.7)
F : As experiment D but the boundary condition (20.3) is replaced by a

condition for the depth-integrated current only:
U = cAe−f y/c cos ω2 t (20.8)
G : As experiment A but without tidal forcing which means that condition

(20.3) is replaced by a zero gradient condition at the western boundary
and Ar is set to zero in the condition (20.4) at the inlet.
A series of figures have been prepared for this test case. The intention
is not only to examine the structure and the evolution of the river plume
and to compare the different experiments, but also to illustrate how har-
monic analysis can be applied to model results. The time evolution of the
surface plume for experiment A is shown in Figures 20.6 during the third
cycle at intervals of 3 hours. The residual salinity and current field obtained
for the last 12 hours of the simulation are compared in Figures 20.7 for all
experiments (except F which is similar to E). The residual fields plotted in
Figures 20.8a–b and 20.8c–d for experiments A and G are taken respectively
along the transects AA′ perpendicular and DD′ parallel to the coast (see
Figure 20.5 for a location of the transects). The time evolutions of plume
width and length are compared in Figures 20.9 for several experiments. The
first figure shows the plume width taken as the cross-shore distance of the 32
PSU contour line from the mouth, the second the length of the plume mea-
sured by the alongshore distance between the inlet and the point to the right
along transect CC ′ where the salinity reaches a value of 32 PSU. Harmon-
ically analysed values and current ellipse parameters for experiment A are
displayed in Figures 20.10 (surface and bottom ellipticity), 20.11a–c (major
axis of the tidal ellipse for the depth-averaged current and experiments A,
E, F) and 20.11d–f (amplitude of the surface elevation for the same experi-
ments).
A series of output parameters are defined. The first four are evaluated
at intervals of 6 hours. For a location of the transects and points see Fi-
gure 20.5.
hbulge The width of the plume bulge. This is measured by the maximum
distance in km of the 32 PSU surface contour line from the coast.
hwidth The width of the coastal plume measured by the distance from the
coast in km of the point where the 32 PSU surface contour line in-
tersects the transect BB ′ .
pdep Depth of the surface plume at point P measured by the distance to
the surface in m of the 30 PSU contour line.
hfront The length of the plume measured by the alongshore distance in km
between the river mouth and the point where the 32 PSU surface
contour line intersects the transect CC ′ .
A second series of parameters represent harmonically analysed values of the

current and surface elevation and tidal ellipse parameters at the two points P
and Q. The analysis is performed for the last 12 hours of the simulation.
sures
Surface value of the residual u-current at P (m/s).
svres
Surface value of the residual v-current at P (m/s).
selmaj
Surface value of the tidal ellipse’s major axis at P (m/s).
sellip
Ellipticity of the surface ellipse at P .
bures
Value of the residual u-current at P and 10 m depth (m/s).
bvres
Value of the residual v-current at P and 10 m depth (m/s).
belmaj
Value of the tidal ellipse’s major axis at P and 10 m depth (m/s).
bellip
Ellipticity of the tidal ellipse at P and 10 m depth.
dures
Residual value of the depth-averaged u-current at Q (m/s).
duamp
Amplitude of the depth-averaged u-current at Q (m/s).
dupha
Phase of the depth-averaged u-current at Q (degrees).
zetres
Residual surface elevation at Q (m).
zetamp
Amplitude of the sea surface elevation at Q (m).
zetpha
Phase of the sea surface elevation at Q (degrees).
The residual values for experiment G are obtained by taking averaged values
over the last 12 hours.
20.2.3 Results
• Figures 20.6 clearly show how the plume evolves during a tidal cycle.
At the time when the alongshore current reverses sign and the outflow
reaches its maximum, a new blob of fresh water enters the basin, moving
seawards. As the eastward directed tidal wave becomes stronger, the
fresh water patch is deflected to the right. During this phase of the
tide both the bulge and the coastal plume expand seawards. When
the tidal current reverses sign again and turns to the west, the current
inside the plume is first southeastwards pushing the bulge towards the
coast and finally southwestwards reducing the extent of the bulge and
the coastal plume. Since the tidal current enforces the anticyclonic
motion inside the bulge, the results are similar to the ones obtained for
non-tidal plumes. The main difference here is that the bulge and the
coastal plume oscillate with the tide.
• After a few tidal cycles (Figures 20.7) the structure of tidal and non-
tidal plumes are manifestly different. While in the latter case the tran-
sition between the bulge and the coastal plume is clearly observed, no
clear distinction can be made in the former case. This effect is due to
increased turbulent diffusivity which reduces the anticyclonic vorticity
inside the bulge and the strength of the coastal current. The effect be-
comes more pronounced when more horizontal diffusion is introduced
in the simulation either by using the upwind scheme for momentum
advection or by adding horizontal diffusion terms in the momentum
and salinity equations.
• The residual fields along the two transects AA′ and DD′ (Figures 20.8)
show the presence of an estuarine-type circulation. In the cross-shore
transect upwelling takes place at the coast while downwelling occurs
at the edge of the plume by the convergence of the surface outflow
current. A similar phenomenon is seen in the coastal jet where down-
welling motions are created by the convergence of the coastal jet. In the
case of a non-tidal plume the plume layer is shallower and the frontal
Figure 20.6: Test case plume. Surface distributions of currents and salinity
for experiment A at 24 h (a), 27 h (b), 30 h (c) 33 h (d), 36 h (e).
Figure 20.7: Test case plume. Residual surface distributions of currents and
salinity for the last tidal cycle and experiment A (a), B (b), C (c), D (d),
E (e), G (f).
Figure 20.8: Test case plume. Residual distributions of currents and salinity
for the last tidal cycle along the cross-shore transect AA′ for experiment A
(a), G (b), and at the alongshore transect DD′ for experiment A (c), G (d).
Figure 20.9: Test case plume. Time series of the plume width taken as the
cross-shore distance of the 32 PSU contour line from the mouth (a) and of
the plume length at the transect CC ′ (b) for experiments A (solid), B (dots),
D (dashes), E (dash-dots) and G (dash and 2 dots).
Figure 20.10: Test case plume. Ellipticity of the tidal ellipses for experiment
A: surface (a) and bottom (b) distributions. Negative and positive values
are drawn by dashed, respectively solid lines. The analysis is performed for
the last tidal cycle.
gradients are stronger compared to the tidal case where turbulent dif-
fusion increases the depth of the surface layer and reduces the vertical
stratification.
• The oscillations of the plume shape induced by the tide are clearly ob-
served in Figures 20.9. In the absence of tides the width of the bulge
first grows in time levelling off after 10–12 hours which is comparable
to the inertial period of ∼ 15 h. A somewhat similar behaviour can
be deduced for the tidal case where the mean growth curve is strongly
modulated by the tide. The length of the plume increases linearly in the
non-tidal case. In the presence of tides the growth is strongly reduced
as found previously and seems to decrease asymptotically. The exper-
iments with horizontal diffusion show a slower growth of the coastal
plume.
• The presence of a stratified surface layer has an important impact on

the form of the tidal current. Outside the plume the current is rectilin-
ear (zero ellipticity) while inside the plume the current rotates anticy-
clonically (negative ellipticity) in the surface and cyclonically (positive
ellipticity) in the bottom layer. This is confirmed by observational data
in the Rhine plume and the physical theory discussed in Visser et al.
(1994).
• The amplitude of the depth-averaged tidal current measured by the

Figure 20.11: Test case plume. Distributions of the major axis (m/s) of the
tidal ellipse for the depth-averaged current and A (a), E (b), F (c) and of
the M2 surface elevation amplitude and A (d), E (e), F (f).
major axis of the tidal current is clearly stronger inside the plume due
to the reduction of the turbulence and the bottom shear stress. No
significant change is found for the amplitude of the surface elevation.
• Figures 20.11 compare the three different formulations for the tidal for-
cing at the western boundary, represented by experiments A, E and
F. Although the results are qualitatively the same, there are important
quantitative differences. On the other hand, the results shown in Figu-
res 20.10, 20.11a and 20.11d are practically the same for experiments
A, B, C and D suggesting that horizontal diffusion has no significant
influence on the tidal currents (at least for this idealised test case).
20.3 Test case rhone

The outflow of the Rhone river is located in the Gulf of Lions situated between
420 − 430 30′ N and 30 − 60 E. The bottom topography in most areas along
the French coast, including the Rhone plume area, is characterised by a
steep slope with depths increasing rapidly up to values of 1000 m at 20–
50 km from the coast. Observations (Albérola et al., 1995) and numerical
simulations (Tsimplis et al., 1995) indicate that tides are insignificant in
most parts of the Western Mediterranean. This is even more the case in the
Gulf of Lions where tidal amplitudes have values of only a few cm and tidal
currents are extremely low (less than 0.1 cm/s). The rhone test case can
therefore be considered as complementary to the plume case discussed in the
previous section. The discharge of the Rhone river provides a major input
of fresh water, nutrients, sediments and suspended material in the Gulf of
Lions and even the Western Mediterranean. The drainage area is of the order
of ∼105 km2 . The mean river discharge is 1700 m3 /s with strong seasonal
variations between ∼500 and ∼8000 m3 /s. The lowest and highest values
occur in October and March–April.
The Rhone plume can be observed by infrared satellite images in the
summer (winter) when the plume water is warmer (colder) than the ambient
seawater of the Gulf of Lions. Demarcq & Wald (1984) used remote sensing
to study the influence of the wind on the shape of the plume. In the absence
of wind the plume is confined to the coast. The response of the plume to
the wind is rapid and consists in a deflection of the plume to the right of the
wind direction with an average angle of deflection of ∼500 . Northwesterly
winds, which are typical for the winter regime, cause the plume to expand
seawards with a tendency to detach from the coast. A southeasterly wind
20.3. TEST CASE RHONE 585
on the other hand confines the plume even more to the coast while the fresh
water spreads in eastward direction and may attain the Gulf of Fos.
The frontal boundary of a river plume is not only characterised by strong
gradients of salinity but also by front convergence, i.e. a strong negative
gradient of the current towards to the front. Forget et al. (1990) used a
VHF radar technique to determine the plume boundary by measuring the
current in the direction of the radar beam. The frontal boundary can easily
be identified by a jump (∼20 cm/s) in the current field. Inside the plume
values of 50 cm/s were measured.
The river plume can be identified in the salinity field by two frontal
regimes.When the low salinity water (10–15 PSU) of the Rhone river dis-
charges into the the Gulf of Lions (∼ 38 PSU), the fresh water spreads out-
wards in the form of a highly stratified (∼10 PSU/m) surface layer with low
turbulence and a thickness of a few meters, floating above a mixed bottom
layer. Flow convergence occurs at the edge of the plume. This area, often
visible by foam, has a width of only a few hundred meters and acts as a
source for the accumulation of dissolved material, sediments and nutrients.
At the lateral frontal boundary the horizontal gradient is of the order of 7
PSU/km. Salinity measurements in the Rhone plume are reported by e.g.
Sournia et al. (1990); Naudin et al. (1992).
The domain of the simulations, covers the area between 430 05′ – 430 30′ N
and 40 07′ – 50 28′ E. The X- and Y-axis are directed respectively along the
West-East and South -North directions. The horizontal resolutions are given
by ∆φ = 30′′ in latitude and ∆λ = 45′′ in longitude which corresponds
approximatively to a 1×1 km grid.
The bathymetry of the area is displayed in Figure 20.12. The estuary
of the Rhone river is approximated by a straight channel having a width of
1 km and a length of 6.5 km (7 grid cells). Fresh water (salinity of 10 PSU)
is discharged at the head of the channel. The bathymetry in front of the
river mouth is characterised by a strong seaward bottom slope with a water
depth increasing from 10 m at the mouth upto 100 m at distance of ∼10 km
from the coast. The strongest gradient occurs within a distance of only 1 km
from the mouth. To represent this effect in the model a seaward bottom
slope is introduced inside the channel allowing the water depth to increase
from 5 m at the head of the channel to 20 m at the mouth. Other areas of
interest for the plume study are the Gulf of Fos, located at the East of the
river mouth which is a shallow area with depths between 5 and 20 m, and
the Camargue coast to the West where the water depth increases less rapidly
with the distance to the coast.
The following setup is used:

Figure 20.12: Bathymetry of the Rhone plume area.
• The TVD scheme is applied for all transport equations.
• The baroclinic pressure gradient is evaluated using the z-level scheme

(iopt dens grad=2).
• Time steps are 10 s for the 2-D and 180 s for the 3-D mode and the
simulations are performed for a period of 4 days.
• The simulations start with zero initial currents and a uniform salinity
of 38.1 PSU.
• A zero normal gradient for the incoming Riemann characteristic is im-

posed at all open sea boundaries.
• The river discharge at the river mouth is taken as uniform in time and
over the vertical which means that the baroclinic current at the mouth
is set to zero. The salinity of the fresh water release is set to 10 PSU.

Seven experiments are defined. Except for C the aim is not to test numerical
algorithms and schemes but to analyse the role of physical forcing parameters
like discharge rate and wind.
A : Standard run without wind and a discharge rate Q=1500 m3 /s.
B : As experiment A now using Q=6000 m3 /s.
C : As experiment A now using the Pacanowski-Philander algebraic turbu-

lence scheme as defined in Section 4.4.2.1.
D : As experiment A with a wind speed of 6 m/s and a wind direction of 0

degrees (westerly wind).
E : As experiment D but now with a wind direction of 90 degrees (southerly

wind).
F : As experiment D but now with a wind direction of 180 degrees (easterly

wind).
G : As experiment D but now with a wind direction of 270 degrees (northerly

wind) .
In all wind experiments the wind is set to zero during the first two days.
The following output parameters are defined
area34 Area (in km2 ) where salinity is lower than 34 PSU.

area22 Area (in km2 ) where salinity is lower than 22 PSU.
ekin Volume integrated kinetic energy (109 J).
epot Volume integrated potential and internal energy (109 J).
etot Volume integrated total energy (109 J).
bdissip Volume integrated energy dissipation (106 W).
enstr Volume integrated vorticity (m3 /s2 ) as defined by (18.14).
curmax Maximum value of the horizontal current magnitude (cm/s).
wmax Maximum value of the transformed vertical current (mm/s).
wmin Minimum value of the transformed vertical current (mm/s).
d34max Maximum distance (km) of the 34 PSU contour line from the coast.
Figure 20.13: Test case rhone. Surface distributions for salinity and currents
for experiment A (a), B (b), C (c). The arrows on the southern boundary
locate the positions of the South-North transects shown in Figures 20.14 and
20.15.
20.3.3 Results
The following series of figures are produced for all experiments at the end
of simulation. Surface plume and currents are shown for all epxeriments in
Figures 20.13 and 20.16, salinity and current distributions are displayed along
different vertical transects in Figures 20.14, 20.15 and 20.17. Time series of
the plume area, as defined by the test parameter area34 are displayed in
Figures 20.18.
1. No wind experiments.
• Experiment A shows the “traditional” evolution of a non-tidal

plume at non-tropical latitudes (Figure 20.13a). The plume spreads
outwards in offshore direction over a few kilometers, then turns
Figure 20.14: Test case rhone. Distribution of currents and salinity along a
vertical transect at 4.850 E through the river mouth for experiment A (a), B
(b), C (c).
vertical transect at 4.450 E for experiment A (a), B (b), C (c).
Figure 20.16: Test case rhone. Surface distributions for salinity and cur-
rents for experiment D (a), E (b), F (c), G (d). The arrow on the southern
boundary locates the position of the South-North transects shown in Figu-
res 20.17.
vertical transect for experiment D at 4.850 E (a), E at 50 E (b), F at 4.70 (c)
and G at 4.70 E (d).
Figure 20.18: Test case rhone. Plume area as defined as the area between
the coast and the 34 PSU contour line: (a) experiment A (solid), B dots),
C (dashes); (b) experiment D (solid), E (dots), F (dashes), G (dash-dots).
anti-cyclonically around a central bulge until the fresh water reaches

the coast where it turns cyclonically to form a narrow coastal jet
current. The transect through the river mouth (Figure 20.14a)
shows a vertically uniform outflow, also due to the imposed zero
baroclinic current at the river boundary. The region in front of
the mouth is characterised by a strong horizontal salinity front
and the formation of a shallow halocline of ∼2 m due to upwelling
motions at the mouth. In the coastal plume the transport is on-
shore while no halocline is seen due to vertical mixing and the
shallowness of the area (Figure 20.15).
• In experiment B the discharge rate is increased by a factor four.
The results are qualitatively similar to the previous case, but the
dimensions of the plume (extent of the bulge and width of the
coastal plume) and the magnitude of the currents are now larger.
The total plume area is 2 to 4 (depending on the criterion) times
larger than the one in the previous (reference) case.
• Experiment C uses the Pacanowski-Philander turbulence model,
which is more diffusive than the default RANS model taken in
all other experiments. Currents and salinity fronts are almost the
same near the mouth and the dimensions of the bulge are similar
to the reference case. Vorticity is weaker within the two eddies.
The jet current, plume fronts and onshore transports within the
coastal plume are now much weaker. However, the total size of the
plume remains the same (Figure 20.18a) since the slower advance
of the coastal front, seen in Figure 20.13c, is compensated by a
larger width of the plume (measured by the parameter d34max).
2. Wind experiments.
Outside the surface plume, the direction of the surface flow is deter-
mined by surface and bottom friction. In the shallow parts where the
surface current “feels” the bottom friction, the current flows predom-
inantly in the direction of the wind. In the deeper parts the surface
current turns to the right by Ekman drift. Within the plume the wind-
and plume-driven currents interact in a more complex way. As can be
seen in Figures 20.16 and is known from satellite images, the wind has
a large impact on size and direction of the plume. Each experiment is
further discussed below.
• A westerly wind is imposed in experiment D. Since the coast is

located to the left of the wind direction, this case is known as
an upwelling favourable wind whereby the wind-driven circula-

tion consists of an offshore (onshore) flow in the surface (bottom)
layer and upwelling at the coast. Since wind- and plume-driven
circulations act in the same sense at the mouth, the result, seen
in Figure 20.17a, is a (slight) enforcement of the current magni-
tude. Main effect is that no bulge is formed and most fresh water
is transported southwards with only a small Ekman deflection in
the deeper areas near the southern boundary. This is the only
experiment where fresh water is directly transported beyond the
shelf and into the Gulf of Lions.
• A southerly onshore wind is taken in experiment E. The results
are manifestly different from the reference and previous cases. The
onshore flow strongly inhibits the outflow of fresh water so that an
even stronger lateral density front is formed close to the mouth.
The bulge is still visible, but strongly deflected to the right at
its southern edge where water depths are larger. The result is
a coastal plume to the East of the mouth, extending into the
Gulf of Fos, while a smaller plume remains to the West. The
lateral density fronts within these plumes are less intense due to
wind-induced turbulence and diffusion. This is also observed in
Figure 20.17b .
• Experiment F represents the case of an easterly, downwelling
favourable wind. The coast is now on the right of the wind di-
rection giving an onshore (offshore) flow in the surface (bottom)
layer and downwelling at the coast. The onshore surface transport
limits the outward expansion of the plume and bulge. Since the
alongshore wind-driven current is towards the West, the coastal
jet current is strengthened. The coastal plume is driven towards
the coast (as can be seen by inspecting the values of d34max) with
stronger frontal gradients.
• When the wind arrives from the North (experiment G), the wind-
driven surface current is southwards near the coast and has a
westward component in the deeper offshore areas. In analogy with
the case of a northward wind in experiment E, the bulge is now
deflected to the West. Main difference with the no-wind case is
the absence of a return flow towards the coast at the West of the
bulge so that the plume becomes more and more detached from the
coast. A consequence is the complete absence of a coastal plume.
Within the detached plume, vertical stratification is reduced by
wind mixing giving a deeper fresh water layer with a thickness of
∼5 m (Figure 20.17d).
Chapter 21
Inundation schemes
21.1 Test case flood2d

The 2DV test case flood2d simulates the flooding and drying by an oscillat-
ing current inside a straight channel using two different bathymetries, shown
in Figures 21.1. The solid line represents the bathymetry, the dotted line the
initial water level. The area at the upper level to the right is initially taken
as dry. All simulations start at ebb tide. In the first case, the water rises
along an upsloping bottom while the second case represents the flooding over
a barrier.
The channel, directed in the X-direction, has a length of 6810 m and
is discretised using 100 cells in the horizontal and 20 vertical levels. Tidal
forcing is imposed by using the local solution method (4.346) and specifying
the surface elevation at the western boundary in harmonic form
ζ = ζa cos(ωt − π) (21.1)
where ζa = 2 m and ω = π/6 rad/h is the semi-diurnal S2 frequency. The

time steps are limited by the 2-D and 3-D CFL stability criteria (5.4) and
(5.6). Values are ∆τ = 3 s and ∆t = 15 s for the first bathymetry. The same
2-D and 3-D time step of 3 s has to be taken for the second bathymetry. At
the initial time the water level ζ(0), outside the dry area (see Figure 21.1),
is set to a constant value (-2 m in the first and -3 m in the second case) so
that the total water depth is below the reference level used in the definition
of the bathymetry.
597
598 CHAPTER 21. INUNDATION SCHEMES
Figure 21.1: Test case flood2d. Bathymetry (solid) and initial water level
(dots) for configuration 1 (a) and 2 (b) used in flood2d. Also shown are the
three areas used for the definition of test case parameters.
21.1. TEST CASE FLOOD2D 599

The following experiments have been defined:
A : First bathymetry using the drying/wetting scheme without mask criteria
B : First bathymetry using the drying/wetting scheme with the default mask
criterium
C : Second bathymetry using the drying/wetting scheme without mask cri-
teria
D : Second bathymetry using the drying/wetting scheme with the default
mask criterium
The simulations are performed for 24 h or two tidal cycles. The flooding
and subsequent drying of the land areas during the first tidal cycle are shown
in Figures 21.2 and 21.3 for respectively experiments B and D. Time series
of the dry area fraction, and the maximum and mean depth error ∆he , as
defined in Section 5.4.1, are given in Figures 21.4, respectively 21.5.
volerr Volume error in %, which results from adding or removing water
to the domain, normalised by the total domain volume. In the
case of a mass conserving numerical scheme, the change of the
total volume V in time should equal the net amount of water
entering or leaving the domain at the open boundaries, which is
obtained by integrating the continuity equation over the whole
domain
∂V Z
= − Un dl (21.2)
∂t B
where the integral at the right hand side is taken over the open
boundary B and Un the outward directed normal component of
the transport. If mass is not conserved, the amount of volume
δV added or removed from the area satisfies the equation
∂ ∂V Z
δV = + Un dl (21.3)
∂t ∂t B
For the present setup, the discretised form of (21.3) is given by
δV m+1 = δV m + ∆2 m+1 m
X
(Hi1 − Hi1 ) − Ub W δτ (21.4)
i
where ∆ is the uniform horizontal grid spacing, W the width

of the (western) open boundary and Ub the X-component of the
transport at the open boundary. Since W = ∆, the normalised

volume error is given by
m+1
δV m+1 δV m ∆ − Hi1
i (Hi1
m
) − Ub ∆τ
P
= m+1 + m+1 (21.5)
V V ∆ i Hi1
P
The parameter volerr is defined as the term on the right hand

side of (21.5) multiplied by 100.
depmeanerr Horizontally averaged depth error in cm.
depmaxerr Maximum depth error in cm.
dryarea % of the area which is (temporarily) dry. A cell is considered as
dry if the total water depth equals dmin (iopt fld=1) or the cell
is inactive (iopt fld=2).
volume1 % of water volume residing in area I (see Figure 21.1).
volume2 % of water volume residing in area II.
volume3 % of water volume residing in area III.
uvelmax Maximum value of the horizontal current (cm/s).
uvelmin Minimum value of the horizontal current (cm/s).
wphysmax Maximum value of the physical vertical current (mm/s).
wphysmin Minimum value of the physical vertical current (mm/s).
21.1.3 Results
• Comparison of the test case parameters and time series of the currents
and elevations (not shown for tests A and C) reveal that the differences
between the two drying/wetting algorithms are small. Only noticeable
difference is that the dry area is slightly larger for the second scheme.
The main difference is mass conservation, further discussed below.
• In the sloping bottom experiment, the flow of the rising water retards
when the water mass reaches the edge of the shelf at 1.4 m depth.
Flow divergence, followed by convergence, is observed when the tidal
wave moves over the shallower area in the middle of the channel. This
shallowing effect is reduced with the approach of the flood tide. The
reverse effect occurs when the water recedes from the coast. As the
water depth over the outer shelf approaches its minimal value, the flow
retards by bottom friction. This explains why water is still falling from
the edge into the deeper basin at the ebb tide even when the water
level in the deeper part is already 0.6 m below the shelf.
• The second experiment with the large obstacle in the middle of the
channel, is a similar, but more extreme case. As the water mass moves
past the obstacle, the water forms a thin layer and falls abruptly into
the coastal basin (Figure 21.3a). The wave, generated by the falling
water masses downhill of the slope, reflects at the coast1 . The re-
flected wave opposes the tidal current (Figure 21.3b) and even creates
a temporarily flow reserval. At the approach of the maximum flood,
the wave decreases in amplitude and the tidal current reappears (Fi-
gure 21.3c). Some similar wave behaviour is observed at ebb tide when
the layer above the obstacle thins and water falls downhill into the west-
ern deeper part of the channel. The wave does not propagate entirely
through the open boundary which could explain the vertical oscillations
at ebb tide (Figure 21.3f). The oscillation gradually damps out at the
start of the next tidal cycle and disappears about one hour after the
onset of the flood tide (not shown).
• Mass conservation can be verified by checking the values of the pa-

rameters depmaxerr, depmeanerr and volerr in the .tst files and from
Figure 21.5. As explained in Section 5.4.1, virtual water is added to
the water column when the water depth drops below hmin which occurs
during the drying (ebb) phase of the tidal cycle.
– The results, in case of the first configuration, are now manifestly

different for the two schemes. For the first one (without mask
function) the maximum error, occurring close to the coast, in-
creases by more than 1 cm at each cycle and the volume error at
the end of the simulation becomes 0.4%. Using the second scheme
(with mask function) these values become 0.008 cm and 0.005%,
which may be considered at or below noise level.
– For the second configuration, drying only occurs when the water
shallows above the obstacle. Values for the maximum depth and
volume error remain sufficiently small for both schemes, implying
that mass is reasonable well conserved.
1
It is remarked that the hydrostatic assumption may no longer be valid in this case.
Figure 21.2: Test case flood2d. Time series of currents and surface elevations
during the first tidal cycle and experiment flood2dB.
Figure 21.3: Test case flood2d. Time series of currents and surface elevations
during the first tidal cycle and experiment flood2dD.
Figure 21.4: Test case flood2d. Time series of the dry area fraction and
experiment A (solid), B (dots), C (dashes) and D (dash-dots).
Figure 21.5: Test case flood2d. Time series of the maximum water depth
error for experiment A (solid), B (dots), and the mean depth error for ex-
periment A (dashes) and B (dash-dots).
21.2 Test case flood3d

Test case flood3d consists of a series of experiments simulating flooding and
drying by an oscillating tidal current in a rectangular basin. The experiments
are conducted for three different bathymetries shown in Figure 21.6.
The basin has a size of 6810 m. The model grid uses 100 cells in each
horizontal direction and 20 vertical levels. A tidal current enters the basin
through the western boundary. All other lateral boundaries are closed. The
tide is imposed by using the local solution method (4.346) and specifying the
surface elevation at the western boundary using the harmonic form (21.1)
with ζa = 2 m and the semi-diurnal S2 frequency.
The time step is ∆τ = 3 s for the 2-D mode. The 3-D time step is respec-
tively 30, 15 and 3 s for respectively the first, second and third bathymetry.
At the initial time the water level ζ(0), outside the inital dry area (see Fi-
gure 21.6), is set to a constant value -2 m so that total water depth is below
the reference level used in the definition the bathymetry.

The following experiments have been defined:
A : Flow over a temporarily inundated mountain in the center of the domain

(first bathymetry).
B : Flow over a gently sloped “crater” rim in the center of the domain
(second bathymetry).
C : Flow over a strongly sloped “crater” rim (third bathymetry).
D : As experiment C now using a 2-D (depth-averaged) grid.
All experiment use the same drying/wetting scheme with the default mask
function.
Time series of currents and water levels for the first tidal cycle are shown
in Figures 21.7, 21.9, 21.11 for respectively experiments A,B,C. Depth mean
currents and total water depths are displayed as time series for the first cycle
in Figures 21.8, 21.10, 21.12, 21.13 for respectively experiments A, B, C,
D. Time series of the dry area fraction, and the maximum depth error ∆he ,
as defined in Section 5.4.1, are given in Figures 21.14, respectively 21.15.
Figure 21.6: Test case flood3d. Bathymetry (solid) and initial water level
(dots) along a transect normal to the open boundary and through the center
of the basin for the three different configurations used in flood3d (left). Top
view of the bathymetry (right).
volerr Volume error in %,which results from adding or removing wa-

ter to the domain, normalised by the total domain volume. In
analogy with (21.5) this is given by
n+1
δV n ∆2 i,j (Hij − Hijn ) − W Ub ∆τ
P
δV n+1
= n+1 + (21.6)
V V ∆2 ij Hijn+1
P
multiplied by a factor 100.

depmeanerr Horizontally averaged depth error in cm.
depmaxerr Maximum depth error in cm.
dryarea % of the area which is (temporarily) dry (inactive).
ekin Volume integrated kinetic energy (109 J).
epot Volume integrated potential energy (109 J).
etot Volume integrated total energy (109 J).
edissip Domain integrated (negative) energy dissipation (104 W).
uvelmax Maximum value of the u-current (cm/s).
uvelmin Minimum value of the u-current (cm/s).
vvelmax Maximum value of the v-current (cm/s).
vvelmin Minimum value of the v-current (cm/s).
wphysmax Maximum value of the physical vertical current (mm/s).
wphysmin Minimum value of the physical vertical current (mm/s).
21.2.3 Results
• It is readily observed that all solutions are symmetric with respect to
the vertical transect in the X-direction passing through the center of
the basin.
• In the case of an isolated hill (experiment A), the flooding and drying
process proceeds smoothly. During the rising tide, the incoming east-
ward flow in the central part deflects in the along-hill direction when
it approaches the hill boundary. In the more southern (northern) parts
the water flows unimpeded until it reaches the solid eastern boundary
where it deflects to the left (right). The result is a cyclonic (anticy-
clonic) circulation below (above) the center line during the rising tide.
The circulation reverses with the onset of the ebb tide. At first, the
top of the hill is still inundated and the flow is mainly westward. As
soon as the drying starts on the top of the hill, the water masses close
to the dry area start to flow both along and away from the hill.
Figure 21.7: Test case flood3d. Time series of currents and elevations during
the first tidal cycle and along a transect normal to the open boundary and
through the center of the basin for experiment flood3dA.
Figure 21.8: Test case flood3d. Time series of horizontal depth mean cur-
rents and water depths during the first tidal cycle and experiment flood3dA.
Figure 21.9: Test case flood3d. Time series of currents and elevations during
the first tidal cycle and along a transect normal to the open boundary and
through the center of the basin for experiment flood3dB.
rents and water depths during the first tidal cycle and experiment flood3dB.
Figure 21.11: Test case flood3d. Time series of currents and elevations
during the first tidal cycle and along a transect normal to the open boundary
and through the center of the basin for experiment flood3dC.
rents and water depths during the first tidal cycle and experiment flood3dC.
rents and water depths during the first tidal cycle and experiment flood3dD.
Figure 21.14: Test case flood3d. Time series of the dry area fraction and
experiment A (solid), B (dots), C (dashes) and D (dash-dots).
Figure 21.15: Test case flood3d. Time series of the maximum water depth
error for experiment A (solid), B (dots), C (dashes) and D (dash-dots).
• Experiment B is similar to the previous one, until the water reaches

the rim of the crater, when the flow retards upslope and accelerates
downslope towards the center of the (inner) basin. Comparison of Fi-
gures 21.8 and Figures 21.10 shows that the general circulation patterns
are similar for A and B.
• The bathymetry of experiment C is similar to the previous one, except

that the slopes on the outer and inner side of the crater are much steeper
in the latter case. When the water flows over the rim in experiment C,
it falls rapidly towards the center2 . Contrary to the analogous 2DV case
test case flood2dD, the water comes from all directions. The infall is,
moreover, not radially symmetric. Once the infalling water reaches the
center, an outgoing non-symmetric radial wave is created, opposing the
masses still falling in the crater, The result, as seen in Figure 21.11b,
is that water starts to move out along the western rim and to move in
with higher speed from the eastern side. The rim currents slow down
at the approach of high tide and the flow at the western side becomes
inwards again. The drying process during the ebb proceeds in a much
smoother way, since the crater is already filled with water.
• Although test D uses the same bathymetry as experiment C, the re-

sults at high water, observed in Figures 21.13, are manifestly different.
The reason is that the momentum equations are solved without taking
account of velocity shear in the former case and it is evident from Fi-
gures 21.12 that vertical shear cannot be neglected when water flows
over the rim.
• The maximum depth error, which occurs at the top of the mountain
(experiment A) or at the crater rim (B, C), is of the order of 1 cm per
cycle. Note that error in case of the 2-D test D is negligible small, which
may be related to the observation in Figure 21.14 that no “effective
drying” (as defined by the mask criterium) seems to occur.
2
It is remarked that the hydrostatic assumption may no longer be valid in this case.
Chapter 22
Shelf sea modelling
22.1 Test case bohai
The aim of this test case is to illustrate the use of COHERENS for tidal
prediction studies, to show how an harmonic analysis can be performed and
how an analysis can be made of the distribution, propagation and dissipation
of tidal energy. The Bohai Sea is situated in the northern part of the Yellow
Sea between the Northeast coast of China and the Korean peninsula. The
simulated area is between 1170 5′ E–1250 35′ E and 370 –410 5′ N. Water depths,
shown in Figure 22.1, are lower than 50 m in the western and between 60–
85 m in the central eastern part.
The tides enter the domain through the southern boundary. Two tidal
constituents (M2 and S2 ) are imposed in harmonic form, as given by equa-
tion (4.340) without the first (residual) term. The grid has an horizontal
resolution of 5′ in longitude and latitude. The time step for the barotropic
(2-D) mode is 30 s. The simulations are performed either in depth-averaged
mode or using a full 3-D grid. In the former case, the bottom stress is cal-
culated using the 2-D quadratic law (4.329) and a constant bottom drag
coefficient Cdb =0.00237. In the latter case, the 3-D quadratic law (4.328)
is taken, the bottom drag coefficient is calculated from (4.330) using a con-
stant roughness length z0 =0.0035 m, the baroclinic time step is set to 5 min
and 20 uniform σ-levels are taken in the vertical. The simulated period is 16
days, covering a full spring-neap cycle. Results are harmonically analysed for
the two tidal constituents. Analysed output consists of the amplitudes and
phases of water levels and currents, parameters of tidal ellipses and energy
parameters (kinetic and potential energy, energy dissipation and fluxes).
619
620 CHAPTER 22. SHELF SEA MODELLING
Figure 22.1: Bathymetry of the Bohai Sea. The diamond symbols locate the
position of the 4 four stations used in the definition of the output parameters.

Six experiments are defined in the bohai test case. The aim is to compare
three different types of open boundary conditions either in 2-D and 3-D mode.
A : A 2-dimensional grid is taken. At the open boundaries the characteristic

method with specified elevation is applied.
B : As experiment A now using the Flather condition (4.353) at open boun-

daries.
C : As experiment A now using the local solution (4.346) at open bounda-

ries.
D : As A now using a 3-D grid.
E : As B now using a 3-D grid.
F : As C now using a 3-D grid.

22.1. TEST CASE BOHAI 621
A series of output parameters are defined. The first five are global resid-
uals obtained from the harmonic analysis.
ekin The domain integrated kinetic energy hE k i (in 1015 J) with E k defined
by (D.8) in the 2-D and (D.11) in the 2-D case.
epot The domain integrated potential energy hEp i (in 1015 J) with Ep de-
fined by (D.3).
etot The domain integrated total energy (in 1015 J) given as the sum of
ekin and epot.
bdissip The domain integrated negative energy dissipation -hDi with D de-
fined by (D.13) in the 2-D or (D.10) in the 3-D case.
The next series of parameters gives the location of the four amphidromic
points (two for the M2 and two for the S2 tide) which are determined as
local minima of ζ.
zetmin Value of the local minimum for ζ (m).

xpos Longitude of the amphidromic point (decimal degrees East)
xpos Latitude of the amphidromic point (decimal degrees North)
The last series of parameters are the amplitudes and phases of the surface
elevation, and the elliptic parameters obtained from harmonic analysis for
the two tidal constituents at 4 stations.
M2-zetamp M2 amplitude of the sea level heigth (cm)

M2-zetpha M2 phase of the sea level heigth (cm)
M2-ellmaj major axis of the M2 tidal ellipse (cm)
M2-ellipt ellipticity of the M2 tidal ellipse
M2-ellinc inclination of the M2 tidal ellipse (degrees)
M2-ellpha elliptic phase of the M2 tidal ellipse (degrees)
S2-zetamp S2 amplitude of the sea level heigth (cm)
S2-zetpha S2 phase of the sea level heigth (cm)
S2-ellmaj major axis of the S2 tidal ellipse (cm)
S2-ellipt ellipticity of the S2 tidal ellipse
S2-ellinc inclination of the S2 tidal ellipse (degrees)
S2-ellpha elliptic phase of the M2 tidal ellipse (degrees)
For a definition of the tidal ellipse parameters see Section 4.12.2.

22.1.2 Results
The following figures are produced for experiment A.
• Amplitudes and phases of the sea surface elevation, major axis and
ellipticity of the tidal ellipse are shown in Figures 22.2 for the M2 and
22.3 for the S2 tide.
• Figure 22.4 displays time series of the domain averaged kinetic, poten-
tail, total energy and energy dissipation.
• Spatial distributions of the residual depth-mean tidal energy, energy
dissipation and tidal energy flux, as defined by equations (D.11), (D.13)
and (D.12) are given in Figure 22.5.
The results can be summarised as follows
• Both the M2 and S2 tide show the same two amphidromic points located
respectively in the Southwest and Southeast parts of the domain. The
positions are the same for all experiments.
• From figures 22.2 and 22.3 one infers that the M2 amplitudes for ele-
vation and currents are 2 to 2.5 times higher than the ones obtained
from the S2 tide. The tides themselves show a strong variability over
the domain with much larger amplitudes for elevations and currents
(up to a factor 5) in the eastern compared to the western parts. From
the distributions of tidal ellipticity one observes rapid changes from
nearly circular to rectilinear ellipses and from cyclonic to anticyclonic
motions.
• There is no difference between the tests using the open boundary condi-
tion with the local solution and the one with the characteristic method
and a very small difference with the test using the Flather condition,
both for the 2-D as for the 3-D case. Larger differences are seen be-
tween the 2-D and 3-D runs. Although these can be still be considered
as small for the amplitudes, a phase difference of a few degrees can
be observed. Since the tidal flow is mainly barotropic with no shear,
except at the bottom (not shown), this can only be explained by the
different formulation for the bottom stress.
• The residual and domain-averaged kinetic and potential are nearly the
same, in analogy with linear surface waves. The time series of the non-
analysed energy parameters exhibits a strong spring-neap cycle since
the amplitude ratio equals the square of the ones obtained for elevations
and currents.
Figure 22.2: Amplitudes in cm (a), phases in degrees (b) of the surface

elevation, major axis in m (c) and ellipticity (d) for the M2 tide and experi-
ment bohaiA.
• As expected from the previously discussed tidal distributions, tidal en-

ergy is mainly concentrated in the eastern parts. The propagation of
tidal energy is mainly concentrated along the slopes of the bathymetry
(Figure 22.5c). Energy dissipation only occurs within well-defined
coastal areas in the eastern parts.
Figure 22.3: Amplitudes in cm (a), phases in degrees (b) of the surface

elevation, major axis in m (c) and ellipticity (d) for the S2 tide and experi-
ment bohaiA.
Figure 22.4: Time series of (a) the domain-integrated kinetic energy (1015 J),
(b) potential energy (1015 J), (c) total energy (1015 J) and (d) energy dissipa-
tion (109 W) for experiment bohaiA.
Figure 22.5: Distribution of the depth-integrated residual tidal energy (a),

depth-integrated energy dissipation (b) and energy flux (c) for experiment
bohaiA. Units are 106 J/m2 (a), W/m2 (b), 106 W/m (c).
Appendix A
Transformed model equations
A.1 Horizontal transformation

The continuity, momentum and scalar transport equations can be rewritten
from Cartesian to orthogonal curvilinear coordinates (ξ1 ,ξ2 ) with the aid of
the general tranfsormation rules (e.g. Batchelor, 1979):
!
1 ∂ 1 ∂
∇h = , (A.1)
h1 ∂ξ1 h2 ∂ξ2
" #
1 ∂ ∂
∇h · Fh = (h2 F1 ) + (h1 F2 ) (A.2)
h1 h2 ∂ξ1 ∂ξ2
!
F2 ∂h1 ∂h2

Fh · ∇h Fh = Fh · ∇F1 + F1 − F2 ,
h1 h2 ∂ξ2 ∂ξ1
!
F1 ∂h2 ∂h1
Fh · ∇F2 + F2 − F1 (A.3)
h1 h2 ∂ξ1 ∂ξ2
where the subscript h denotes the horizontal component of the associated
vector or operator and h1 , h2 are the metric coefficients defined by (4.7).
Substituting the above relations into (4.32)–(4.34) and (4.36) or (4.37) one
obtains " #
1 ∂ ∂ ∂w
(h2 u) + (h1 v) + =0 (A.4)
h1 h2 ∂ξ1 ∂ξ2 ∂z
!
∂u u ∂u v ∂u ∂u v ∂h1 ∂h2
+ + +w + u −v − 2Ωv sin φ
∂t h1 ∂ξ1 h2 ∂ξ2 ∂z h1 h2 ∂ξ2 ∂ξ1
!
g ∂ζ 1 ∂Pa 1 ∂q t ∂ ∂u
=− − − + F1 + νT
h1 ∂ξ1 ρo h1 ∂ξ1 h1 ∂ξ1 ∂z ∂z
627
628 APPENDIX A. TRANSFORMED MODEL EQUATIONS
∗ ∗
+Dmh1 (τ11 ) + Dmh2 (τ12 )
(A.5)
!
∂v u ∂v v ∂v ∂v u ∂h2 ∂h1
+ + +w + v −u + 2Ωu sin φ
∂t h1 ∂ξ1 h2 ∂ξ2 ∂z h1 h2 ∂ξ1 ∂ξ2
!
g ∂ζ 1 ∂Pa 1 ∂q t ∂ ∂v
=− − − + F2 + νT
h1 ∂ξ2 ρo h2 ∂ξ2 h2 ∂ξ2 ∂z ∂z
∗ ∗
+Dmh1 (τ21 ) + Dmh2 (τ22 )
(A.6)
!
∂ψ u ∂ψ v ∂ψ ∂ψ ∂ ∂ψ
+ + +w = S(ψ) + λT
∂t h1 ∂ξ1 h2 ∂ξ2 ∂z ∂z ∂z
" ! !#
1 ∂ h2 ∂ψ ∂ h1 ∂ψ
+ λH + λH (A.7)
h1 h2 ∂ξ1 h1 ∂ξ1 ∂ξ2 h2 ∂ξ2
The horizontal diffusion operators for momentum are defined by (Pacanowski

& Griffies, 2000)
1 ∂
∗
Dmh1 (F ) = (h2 F ) (A.8)
h1 h22 ∂ξ1 2
1 ∂
∗
Dmh2 (F ) = 2 (h21 F ) (A.9)
h1 h2 ∂ξ2
A.2 Vertical transformation

A general vertical coordinate is defined through the transformation
(ξ1 , ξ2 , z, t) −→ (ξ˜1 , ξ˜2 , s, t̃) (A.10)
with ξ˜i = ξi , t̃ = t and s = f (ξ1 , ξ2 , z, t) where, as stated in Section 4.1.3.3,

the transformed vertical coordinate s is defined by normalising the σ-coordinate,
using (4.29) such that (A.13) is valid. Spatial and time derivatives are trans-
formed by applying the chain rule
∂ ∂ ∂s ∂
= + (A.11)
∂t ∂ t̃ ∂t ∂s
∂ ∂ ∂s ∂
= + (A.12)
∂ξi ˜
∂ ξi ∂ξi ∂s
∂ 1 ∂
= (A.13)
∂z h3 ∂s
A.2. VERTICAL TRANSFORMATION 629
where the derivatives on the left hand side in the first two relations are taken
along constant z-surfaces and the first ones on the right side along constant
s-surfaces. The following useful relations can be derived from (A.11)–(A.13)
∂s 1 ∂z
= , = h3 (A.14)
∂z h3 ∂s
∂z ∂s
+ h3 =0 (A.15)
∂ ξ˜i ∂ξi
∂h3 ∂s ∂h3
+ =0 (A.16)
∂ t̃ ∂t ∂s
! ! !
∂h3 ∂ ∂z ∂ ∂z ∂ ∂s
= = =− h3 (A.17)
∂ ξ˜i ∂ ξ˜i ∂s ∂s ∂ ξ˜i ∂s ∂ξi
∂z ∂s ∂z ∂s
=− = −h3 (A.18)
∂ t̃ ∂t ∂s ∂t
A new vertical velocity is defined by
ds
ω = h3
dt !
∂s u ∂s v ∂s ∂s
= h3 + + +w
∂t h1 ∂ξ1 h2 ∂ξ2 ∂z
!
∂s u ∂s v ∂s
= h3 + + +w (A.19)
∂t h1 ∂ξ1 h2 ∂ξ2
from which (4.61) is obtained.
The continuity equation (A.4) is rewritten in the transformed coordinate
system with the aid of the previous relations
" #
1 ∂ ∂ ∂w
0 = (h2 u) + (h1 v) +
h1 h2 ∂ξ1 ∂ξ2 ∂z
" #
1 ∂ ∂ ∂s ∂ ∂s ∂ 1 ∂w
= (h2 u) + (h1 v) + (uh2 ) + (vh1 ) +
h1 h2 ∂ ξ˜1 ∂ ξ˜2 ∂ξ1 ∂s ∂ξ2 ∂s h3 ∂s
1 ∂ ∂ ∂s ∂ ∂h3

= (h2 h3 u) + (h1 h3 v) + h3 (uh2 ) − uh2
h1 h2 h3 ∂ ξ˜1 ∂ ξ˜2 ∂ξ1 ∂s ∂ ξ˜1
∂s ∂ ∂h3 1 ∂w

+ h3 (vh1 ) − vh1 +
∂ξ2 ∂s ∂ ξ˜2 h3 ∂s
!
1 ∂ ∂ ∂s ∂ ∂ ∂s

= (h2 h3 u) + (h1 h3 v) + h3 (uh2 ) + uh2 h3
h1 h2 h3 ∂ ξ˜1 ∂ ξ˜2 ∂ξ1 ∂s ∂s ∂ξ1
!
∂s ∂ ∂ ∂s 1 ∂w
+ h3 (vh1 ) + vh1 h3 +
∂ξ2 ∂s ∂s ∂ξ2 h3 ∂s
" !#
1 ∂ ∂ ∂ ∂s ∂s 1 ∂w
= (h2 h3 u) + (h1 h3 v) + h2 h3 u + h1 h3 v +
˜
h 1 h 2 h 3 ∂ ξ1 ˜
∂ ξ2 ∂s ∂ξ1 ∂ξ2 h3 ∂s
" # " #
1 ∂ ∂ 1 ∂ h3 ∂s h3 ∂s
= (h2 h3 u) + (h1 h3 v) + w+ u + v
h1 h2 h3 ∂ ξ˜1 ∂ ξ˜2 h3 ∂s h1 ∂ξ1 h2 ∂ξ2
" # !
1 ∂ ∂ 1 ∂ ∂s
= (h2 h3 u) + (h1 h3 v) + ω − h3
h1 h2 h3 ∂ ξ˜1 ∂ ξ˜2 h3 ∂s ∂t
" # !
1 ∂ ∂ 1 ∂ω 1 ∂h3 ∂s ∂ ∂s
= (h2 h3 u) + (h1 h3 v) + − −
h1 h2 h3 ∂ ξ˜1 ∂ ξ˜2 h3 ∂s h3 ∂s ∂t ∂s ∂t
" #
1 ∂h3 1 ∂ ∂ 1 ∂ω
= + (h2 h3 u) + (h1 h3 v) + (A.20)
h3 ∂ t̃ ˜
h 1 h 2 h 3 ∂ ξ1 ˜
∂ ξ2 h3 ∂s
which becomes identical to (4.49) by letting ξ˜i = ξi and t̃ = t.

The physical vertical current is given by
dz ∂z u ∂z v ∂z ω ∂z
w = = + + +
dt ∂ t̃ h1 ∂ ξ˜1 h2 ∂ ξ˜2 h3 ∂s
∂z u ∂z v ∂z
= + + +ω (A.21)
∂ t̃ h1 ∂ ξ˜1 h2 ∂ ξ˜2
Equation (4.62) is recovered by adding (A.21) and z times (A.20)
∂z u ∂z v ∂z
w = + + +ω
∂ t̃ h1 ∂ ξ˜1 h2 ∂ ξ˜2
zh 1 ∂ ∂ ∂ω ∂h3 i

+ (h2 h3 u) + (h1 h3 v) + +
h3 h1 h2 ∂ ξ˜1 ∂ ξ˜2 ∂s ∂ t̃
1 ∂z ∂ω ∂z ∂h3 uh3 ∂z z ∂

= ω +z + h3 +z + + (h2 h3 u)
h3 ∂s ∂s ∂ t̃ ∂ t̃ h1 ∂ ξ˜1 h1 h2 ∂ ξ˜1
vh3 ∂z z ∂

+ + (h1 h3 v)
h2 ∂ ξ˜2 h1 h2 ∂ ξ˜2
" #
1 ∂ 1 ∂ 1 ∂ ∂
= (h3 z) + (h2 h3 uz) + (h1 h3 vz) + (ωz)
h3 ∂ t̃ ˜
h 1 h 2 ∂ ξ1 ˜
h 1 h 2 ∂ ξ2 ∂s
(A.22)
The total derivative of a quantity ψ (velocity component or scalar) transforms

according to
dψ ∂ψ u ∂ψ v ∂ψ ∂ψ
= + + +w
dt ∂t h1 ∂ξ1 h2 ∂ξ2 ∂z
!
∂ψ u ∂ψ v ∂ψ ∂ψ ∂s u ∂s v ∂s w
= + + + + + +
∂ t̃ h1 ∂ ξ˜1 h2 ∂ ξ˜2 ∂s ∂t h1 ∂ξ1 h2 ∂ξ2 h3
A.2. VERTICAL TRANSFORMATION 631
∂ψ u ∂ψ v ∂ψ ω ∂ψ
= + + +
∂ t̃ h1 ∂ ξ˜1 h2 ∂ ξ˜2 h3 ∂s
" #
1 ∂ 1 ∂ ∂ 1 ∂
= (h3 ψ) + (h2 h3 uψ) + (h1 h3 vψ) + (ψω)
h3 ∂ t̃ h1 h2 h3 ∂ξ1 ∂ξ2 h3 ∂s
" #
ψ ∂h3 ψ ∂ ∂ ψ ∂ω
− − (h2 h3 u) + (h1 h3 v) −
h3 ∂ t̃ h1 h2 h3 ∂ξ1 ∂ξ2 h3 ∂s
" #
1 ∂ 1 ∂ ∂ 1 ∂
= (h3 ψ) + (h2 h3 uψ) + (h1 h3 vψ) + (ψω)
h3 ∂ t̃ h1 h2 h3 ∂ξ1 ∂ξ2 h3 ∂s
(A.23)
by virtue of (A.20).
The horizontal gradient of a vertically independent quantity obviously
does not change. For a 3-D quantity one has
" #
1 ∂ψ 1 ∂ψ ∂s ∂ψ
= +
hi ∂ξi hi ∂ ξ˜i ∂ξi ∂s
" #
1 1 ∂ ψ ∂h3 ∂s ∂ψ
= (h3 ψ) − +
hi h3 ∂ ξ˜i h3 ∂ ξ˜i ∂ξi ∂s
" ! #
1 1 ∂ ψ ∂ ∂s ∂s ∂ψ
= (h3 ψ) + h3 +
hi h3 ∂ ξ˜i h3 ∂s ∂ξi ∂ξi ∂s
" !#
1 1 ∂ 1 ∂ ∂s
= (h3 ψ) + h3 ψ
hi h3 ∂ ξ˜i h3 ∂s ∂ξi
" !#
1 ∂ ∂ ∂z
= (h3 ψ) − ψ (A.24)
˜
h i h 3 ∂ ξi ∂s ∂ ξ˜i
from which (4.63) is obtained with ψ = q.

Applying the previous rule for the horizontal diffusion terms in the mo-
mentum and scalar transport equations one recovers the definitions (4.56),
(4.57), (4.66) and (4.67) by making the assumption that diffusion takes place
along constant s-surfaces.
Appendix B
Solutions of the RANS

equations
B.1 Non-equilibrium method

Using the definitions (4.167) and (4.169), the RANS equations (4.166) can be
reduced to two linear equations for the stability functions Su and Sb . Firstly,
the following auxiliary parameters are defined
3
α1 = 1 − c21 − c23 + c22
2
2
α2 = (1 − c21 ) + c23 (4 − 4c21 + c23 )
α3 = 3 − c21 + 2c23 − 2c3
α4 = c23 (3 − 2c21 + c23 − c3 )
α2
α5 = α1 −
c1
α6 = (1 − c21 )(3 − c21 + 2c23 − 2c3 ) + α4
Rβ⋆ = Rβ (1 − c3β ) (B.1)
The stability functions are then obtained as solution of

h 2 i
c21 c1β + c1β α2 αM + c1 (1 − c3 )αN Su
3
h2 i 2
+ (1 − c3 ) c1β (2 − 2c21 + c23 ) + c1 (1 − c21β ) αN Sb = c1 c1β α1
3 3
(B.2)
h2 i h
c1β (1 − c21 + 2c23 ) − c22β c1 αM Su + c1 c21β − c1 c22β (1 − c21β )αM
3
633
634 APPENDIX B. SOLUTIONS OF THE RANS EQUATIONS
2 i 2
+ 2c1β c1 Rβ⋆ + (1 − c3 ) αN Sb = c1 c1β
3 3
(B.3)
The solution can be written in the form, given by (4.170). The coefficients
Ca1 –Ca11 take the following values
2α1
Ca1 =
3c1
2α1 (1 − c21β )c22β
Ca2 = −
3c1 c21β
2 h 2(c − c ) 1 − c21β
23 22
i
Ca3 = − (1 − c3 ) + − 2Rβ⋆ α1
3c1 c1β c1 c1β
2
Ca4 =
3c1β
2 h 2 c22β i
Ca5 = α2 − α1 (1 − c21 + 2c23 ) + α1
3c1 c1β 3c1 c1β
2(1 − c3 )
Ca6 =
3c1 c21β
2α2 c22β (1 − c21β )
Ca7 = −
3c21 c21β
" #
1 7(1 − c3 )
Ca8 = + 2Rβ⋆
c1β 3c1
2c22β (1 − c21β )α2
Ca9 = −
3c21 c21β
2 n h 2c
23
Ca10 = 2
(1 − c 3 ) (1 − c21 )
3c1 c1β c1
1 i o
+ c22β (2 − 2c21 + c23 ) − (1 − c21β )(1 − c21 + 2c23 ) + 2Rβ⋆ α2
c1β
" #
2(1 − c3 ) 2(1 − c3 )
Ca11 = + Rβ⋆
c1 c21β 3c1
(B.4)
B.2 Quasi-equilibrium method

The governing equations for the algebraic RANS model are given by (4.174)
supplemented by the last 7 equations of (4.166). In analogy with the previous
B.2. QUASI-EQUILIBRIUM METHOD 635
case they can be reduced to the following equations for Su and Sb .

h2 i
c1 [c1 c1β + (1 − c3 )αN ]Su + c1β α6 + c1 (1 − c3 )(1 − c21β ) αN Sb
3
2
= c1 c1β α5 (B.5)
3
h 2 i
c1 c21β − c1 (1 − c21β )c22β αM + (2c1 c1β Rβ⋆ + c1β α3 − c1 c22β )αN Sb
3
2
= c1β (c1 − 1 + c21 − 2c23 ) + c1 c22β (B.6)
3
If c22β = 0, the solutions can be cast in the form (4.175) where
2α5
Cb1 =
3c1
2 h 2 2α6
Cb2 = (α3 α5 − α6 ) + 2 (1 − c21 + 2c23 )
3c1 c1β 3c1 3c1
(1 − c3 )(1 − c21β ) 1 i
− 1 − (1 − c21 + 2c23 ) + 2α5 Rβ⋆
c1β c1
2 α3
Cb3 = Rβ⋆ +
c1β 3c1
1 − c3
Cb4 =
c1 c1β
2 1

Cb5 = 1 − (1 − c21 + 2c23 ) (B.7)
3c1β c1
If c22β 6= 0 the solutions are given by (4.176)–(4.177) with
2α5
Cc1 =
3c1
" #
1 2α6 (1 − c3 )(1 − c21β )
Cc2 = − +
c1 3c1 c1β
1 − c3
Cc3 =
c1 c1β
!
h 2α
6 1 − c21β c22β 1 − c3 i
Cc4 = − + +
3c21 c1β c1β c1
!
2 h α6 2α3 c22β (1 − c3 )(1 − c21β ) α3 i

⋆ ⋆
Cc5 = − 2Rβ + − + 3Rβ +
3c1 c1β c1 3c1 c1β c1β c1
2α5 (1 − c21β )c22β
Cc6 = −
3c1 c21β
636 APPENDIX B. SOLUTIONS OF THE RANS EQUATIONS
2 h 2 α3 α5 + α6 α6 (1 − c21 + 2c23 )
Cc7 = −
3c1 c1β 3 c1 c21
(1 − c3 )(1 − c21β ) 1 − c21 + 2c23 c22β α6 i
+ 1− − (α5 − ) + 2α5 Rβ⋆
c1β c1 c1β c1
2α5 2 2 c22β
Cc8 = − − (1 − c21 + 2c23 ) + (B.8)
3c1 c1β 3 3c1 c1β
B.3 Equilibrium method

The coefficients in the quadratic equation (4.183) for κ2 are obtained from
equations (B.5)–(B.6) and the equilibrium relation Su αM − Sb αN = 1. One
has
2α5 (1 − c21β )c22β
Cd1 = − −
3c1 c21β
1 2 7
Cd2 = + (1 − c3 ) + 2Rβ⋆
c1β 3 3c1
2(1 − c21β )c22β α5
Cd3 =
3c1 c21β
2 h 2 (1 − c21 + 2c23 )α6
Cd4 = α6 − α3 α5 −
3c1 c1β 3c1 c1
(1 − c3 )(1 − c21β ) 1 − c21 + 2c23 c22β 1
+ 1− + α1 + (1 − c3 )(2 − 2c21 + c23 )
c1β c1 c1β c1
i
− 2α5 Rβ⋆
1 − c3 2 4(1 − c3 ) ⋆

Cd5 = + + 2R β (B.9)
c1 c21β 3 3c1
Appendix C
Discretisation of the Coriolis

force
The Coriolis terms in the 2-D and 3-D momentum equations are discretised
in time using a “quasi”-implicit formulation. The time discretised equations
are written as
un+1 − un
− f θc v n+1 + (1 − θc )v n = F1 (C.1)
∆t
v n+1 − v n
+ f θc un+1 + (1 − θc )un = F2 (C.2)
∆t
where Fi represent all other (explicit and implicit) terms (pressure gradient,
advection, diffusion, tidal force). The solution proceeds in two steps
1. Equations (C.1–(C.2) are solved explicitly for the Coriolis force (θc =
0). This gives
u∗ = un + ∆t(F1 + f v n ) (C.3)
v ∗ = v n + ∆t(F2 − f un ) (C.4)
2. Substituting (C.3)–(C.4) into (C.1)–(C.2) one has

un+1 − f θc ∆tv n+1 = u∗ − f θc ∆tv n (C.5)
v n+1 + f θc ∆tun+1 = v ∗ + f θc ∆tun (C.6)
or
f θc ∆t(∆v − f θc ∆t∆u)
un+1 = u∗ + (C.7)
1 + (f θc ∆t)2
f θc ∆t(∆u + f θc ∆t∆v)
v n+1 = v ∗ − (C.8)
1 + (f θc ∆t)2
637
638 APPENDIX C. DISCRETISATION OF THE CORIOLIS FORCE
where
∆u = u∗ − un , ∆v = v ∗ − v n (C.9)
The following remarks apply
• The forcing terms Fi on the right hand side of (C.1)–(C.2) contain both
explicit and implicit terms. A simplification has been made since the
latter one are taken at level ∗ and not at the new time tn+1 .
• In the 3-D case the new time level tn+1 is replaced by the predictor step
tp .
• A four-point spatial interpolation is needed for the evaluation of the

currents in the Coriolis terms. Since the open boundary conditions are
applied only after solving the momentum equations at all interior nodes,
open boundary values are excluded from the interpolation procedure.
Appendix D
Energy balance equation
The energy balance equation is derived by multiplying equations (4.50),

(4.51), (4.49) by respectively ρ0 u, ρ0 v, ρ0 gζ and adding. For simplicity the
baroclinic and atmospheric pressure gradients, the tidal force and horizontal
diffusion are neglected. After a straightforward calculation one obtains
1 ∂ 1 ∂Ep 1 h ∂ ∂ i
(h3 Ek ) + + (h2 h3 F1 ) + (h1 h3 F2 ) = D (D.1)
h3 ∂t H ∂t h1 h2 h3 ∂ξ1 ∂ξ2
where
1
Ek = ρ0 (u2 + v 2 ) (D.2)
2
is the kinetic energy,
1
Ep = ρ0 gζ 2 (D.3)
2
the potential energy,
1
(F1 , F2 ) = ρ0 (u2 + v 2 ) + ρ0 gζ (u, v, ω) (D.4)
2
the energy flux vector and
u ∂D v ∂D2
1
D = ρ0 + (D.5)
h3 ∂s h3 ∂s
the dissipation of energy by turbulent diffusion. The diffusion fluxes are given
by
ν ∂u ν ∂v
T T
(D1 , D2 )= , inside the water column
h3 ∂s h3 ∂s
= (τs1 , τs2 ) at the surface (D.6)
= (τb1 , τb2 ) at the bottom
639
640 APPENDIX D. ENERGY BALANCE EQUATION
The vertically integrated form of (D.1) becomes
∂ 1 h ∂ ∂ i
(E k + Ep ) + (h2 F 1 ) + (h1 F 2 ) = D (D.7)
∂t h1 h2 ∂ξ1 ∂ξ2
where
1 Z Nz
E k = ρ0 h3 (u2 + v 2 ) ds (D.8)
2 0
Z Nz h
1 i
(F1 , F 2 ) = h3 ρ0 (u2 + v 2 ) + ρ0 gζ (u, v) ds (D.9)
0 2
Z Nz
νT h ∂u 2 ∂v 2 i
D = ρ0 (us τs1 + vs τs2 − ub τb1 − vb τb2 ) − ρ0 + ds (D.10)
0 h3 ∂s ∂s
where (us ,vs ) and (ub ,vb ) are the velocities at respectively the surface and
the bottom.
In case of a pure 2-D application, u ≃ u and v ≃ v in which case (D.7)–
(D.10) reduce to
1
E k = ρ0 H(u2 + v 2 ) (D.11)
2
h1 i
(F1 , F 2 ) = H ρ0 (u2 + v 2 ) + ρ0 gζ (u, v) (D.12)
2
D = ρ0 (us τs1 + vs τs2 − ub τb1 − vb τb2 ) (D.13)
Finally, the domain integrated forms are obtained by integrating (D.7)
over the 2-D horizontal domain. This gives
∂ Z
hE k i + hEp i + (F 1 n1 + F 2 n2 ) dℓ = hDi (D.14)
∂t
with Z Nx Z Ny
h· · ·i = (· · ·)h1 h2 dξ1 dξ2 (D.15)
0 0
The second integral is taken along the 2-D boundary of the domain where
(n1 ,n2 ) is the outwards pointing unit normal along the boundary.
Appendix E
List of standard output

variables
Table E.1: Key ids of the variables which can be used for defining standard output
variables. The variables denoted by a ∗ are W-node variables for which the node
variable attribute can be reset to ‘W’.
key id description unit

0-D variables
iarr edens0d domain integrated baroclinic energy J
iarr dissip0d domain integrated energy dissipation W
iarr ekin0d domain integrated kinetic energy J
iarr epot0d domain integrated potential energy J
iarr etot0d domain integrated total energy J
2-D variables
0
iarr airtemp air temperature Ta C
iarr atmpres atmospheric pressure Pa N/m2
iarr bdragcoefatc bottom drag coefficient Cdb –
iarr bfricatc bottom friction velocity u∗b m/s
iarr bstresatc bottom stress τb N/m2
iarr cds surface drag coefficient Cds –
iarr ces surface exchange coefficient Ce for the latent heat flux –
iarr chs surface exchange coefficient Ch for the sensible heat flux –
iarr cloud cover cloud cover fc –
iarr depmeanatc mean water depth h m
iarr deptotatc total water depth H m
iarr deptotatc err total water depth error δe H m
iarr edens2d vertically integrated baroclinic energy J/m2
(Continued)
641
642 APPENDIX E. LIST OF STANDARD OUTPUT VARIABLES
Table E.1: Continued
iarr edissip2d vertically integrated energy dissipation W/m2

iarr eflux2du X-component of the depth-integrated energy flux J/s/m
iarr eflux2dv Y-component of the depth-integrated energy flux J/s/m
iarr ekin2d vertically integrated kinetic energy J/m2
iarr epot2d vertically integrated potential energy J/m2
iarr etot2d vertically integrated total energy J/m2
iarr evapminprec evaporation minus precipitation rate kg/m2 /s
iarr hdifcoef2datc depth mean horizontal diffusion coefficient m2 /s
iarr precipitation precipitation rate Rpr kg/m2 /s
iarr qlatent latent heat flux Qla W/m2
iarr qlwave long wave heat flux Qlw W/m2
iarr qnonsol non-solar heat flux Qnsol W/m2
iarr qrad surface solar irradiance Qs W/m2
iarr qsensible sensible heat flux Qse W/m2
iarr qtot total downward surface heat flux W/m2
iarr relhum relative humidity RH –
iarr ssalflux surface salinity flux PSU m/s
iarr sstresatc surface stress τs N/m2
iarr udvel X-component of the depth-integrated current U m2 /s
iarr umvel X-component of the depth-mean current u m/s
iarr uwindatc X-component of the surface wind U10 m/s
iarr vdvel Y-component of the depth-integrated current V m2 /s
iarr vmvel Y-component of the depth-mean current v m/s
iarr vortic2d vertically integrated vorticity m/s
iarr vwindatc Y-component of the surface wind V10 m/s
iarr zeta surface elevation ζ m
iarr zroughatc bottom roughness z0 m
3-D variables
iarr beta sal salinity expansion coefficient βS PSU−1
0 −1
iarr beta temp temperature expansion coefficient βT C
iarr buofreq2∗ squared buoyancy frequency N 2 s −2
iarr dens mass density ρ kg/m3

iarr dissip∗ dissipation of turbulent kinetic energy ε W/kg
iarr edens3d baroclinic energy J/m3
iarr eddisip3d energy dissipation W/m3
iarr eflux3du X-component of the energy flux W/m3
iarr eflux3dv Y-component of the energy flux W/m3
iarr eflux3dw vertical component of the energy flux W/m3
(Continued)
643
Table E.1: Continued
iarr ekin3d kinetic energy J/m3

iarr etot3d total energy J/m3
iarr hdifcoef3datc horizontal diffusion coefficient νH m2 /s
iarr radiance solar irradiance I W/m2
iarr ricnum∗ Richardson number Ri –
iarr sal salinity S PSU
iarr shearfreq2∗ squared shear frequency M 2 s−2
0
iarr temp temperature T C
iarr tke∗ turbulent kinetic energy k J/kg
iarr uvel X-component of the current u m/s
iarr vdifcoefmom∗ eddy viscosity νT m2 /s
iarr vdifcoefscal∗ eddy diffusivity λT m2 /s
iarr vdifcoeftke∗ vertical diffusion coefficient for turbulence energy νk m2 /s
iarr vortic3d vertical vorticity s−1
iarr vvel Y-component of the current v m/s
iarr wphys physical vertical current w m/s
iarr wvel∗ transformed vertical current ω m/s
iarr zlmix∗ mixing length l m
644 APPENDIX E. LIST OF STANDARD OUTPUT VARIABLES
Bibliography
Albérola, C., Rousseau, S., Millot, C., Astraldi, M., Font, J., Garcia-
Lafuente, J.M., Gasparin, G.P., Send, U., & Vangriesheim, A. 1995. Tidal
currents in the western Mediterranean Sea. Oceanologica Acta, 18, 273–
284.
Anderson, R.J., & Smith, S.D. 1981. Evaporation coefficient for the sea
surface from eddy flux measurements. Journal of Geophysical Research,
86, 449–456.
Beckmann, A., & Haidvogel, D.B. 1993. Numerical simulation of flow around
a tall isolated seamount. Part I: Problem formulation and model accuracy.
Journal of Physical Oceanography, 23, 1736–1753.
Blackadar, A.K. 1962. The vertical distribution of wind and turbulent ex-
change in a neutral atmosphere. Journal of Geophysical Research, 67,
3095–3102.
Blanc, T.V. 1985. Variation of bulk-derived surface flux, stability, and rough-
ness results due to the use of different transfer coefficient schemes. Journal
of Physical Oceanography, 15, 650–669.
Blumberg, A.F., & Mellor, G.L. 1987. A description of a three-dimensional

coastal ocean circulation model. Pages 1–16 of: Heaps, N.S. (ed), Three-
dimensional Coastal Ocean Models. Coastal and Estuarine Sciences. Wash-
ington D.C.: Americal Geophysical Union.
Boris, J.P., & Book, D.L. 1979. Flux corrected transport: I.SHASTA, a fluid
transport algorithm that works. Journal of Computational Physics, 11,
38–69.
Bowden, K.F., Fairbairn, L.A., & Hughes, P. 1959. The distribution of

shearing stresses in a tidal current. Geophysical Journal of the Royal As-
tronomical Society, 2, 288–305.
645
646 BIBLIOGRAPHY
Burchard, H. 2001. Simulating the wave-enhanced layer under breaking sur-

face waves with two-equation turbulence models. Journal of Physical Ocea-
nography, 31, 3133–3145.
Burchard, H. 2002. Applied Turbulence Modelling in Marine Waters. Lecture

Notes in Earth Sciences, no. 100. Berlin: Springer-Verlag.
Burchard, H., & Baumert, H. 1995. On the performance of a mixed-layer

model based on the k − ε turbulence closure. Journal of Geophysical Re-
search, 100, 8523–8540.
Burchard, H., & Bolding, K. 2002. GETM – A General Estuarine Transport

Model. Scientific Documentation. Tech. rept. Institute for Environment
and Sustainability, Joint Research Centre, Ispra, Italy.
Burchard, H., & Petersen, O. 1999. Models of turbulence in the marine

environment – a comparative study of two-equation turbulence models.
Journal of Marine Systems, 21, 29–53.
Burchard, H., Deleersnijder, E., & Meister, E. 2003. A high-order Patankar-

type discretisation for stiff systems of production-destruction equations.
Applied Numerical Mathematics, 47, 1–30.
Businger, J.A., Wyngaard, J.C., Izumi, Y., & Bradley, E.F. 1971. Flux-profile
relationships in the atmospheric surface layer. Journal of the Atmospheric
Sciences, 28, 181–189.
Camerlengo, A.L., & O’Brien, J.J. 1980. Open boundary conditions in ro-
tating fluids. Journal of Computational Physics, 35, 12–35.
Canuto, V.M., Howard, A., Cheng, Y., & Dubovikov, M.S. 2001. Ocean
turbulence. Part I: One-point closure model – Momentum and heat vertical
diffusivities. Journal of Physical Oceanography, 31, 1413–1426.
Cartwright, D.E., & Edden, A.C. 1973. Corrected tables of tidal harmonics.
Geophysical Journal of the Royal Astronomical Society, 33, 253–264.
Cartwright, D.E., & Tayler, R.J. 1971. New computations of the tide-
generating potential. Geophysical Journal of the Royal Astronomical So-
ciety, 23, 45–74.
Chao, S.-Y. 1988. River-forced estuarine plumes. Journal of Physical Ocea-

nography, 18, 72–88.
BIBLIOGRAPHY 647
Chao, S.-Y., & Boicourt, W.C. 1986. Onset of estuarine plumes. Journal of
Physical Oceanography, 16, 2137–2149.
Charnock, H. 1955. Wind stress on a water surface. Quarterly Journal Royal

Meteorological Society, 81, 639–640.
Charnock, H., Dyer, K.R., Huthnance, J.M., Liss, P.S., Simpson, J.H., &
Tett, B. 1994. Understanding the North Sea System. The Royal Society,
Chapman & Hall.
Chen, C., Beardsley, R.C, & Cowles, G. 2006. An unstructured Grid, Finite-
Volume Coastal Ocean Model. Tech. rept. School for Marine Science and
Technology, Univ. of Massaschusetts-Dartmouth, New Bedford, Massa-
schusetts, US.
Chu, P.C., & Fan, C. 1997. Sixth-order difference scheme for sigma coordinate
ocean models. Journal of Physical Oceanography, 27, 2064–2071.
Colella, P., & Woodward, P.R. 1984. The piecewise parabolic method (PPM)
for gas-dynamical simulations. Journal of Computational Physics, 54, 174–
201.
Craig, P.D., & Banner, M.L. 1994. Modeling wave-enhanced turbulence in

the ocean surface layer. Journal of Physical Oceanography, 24, 2546–2559.
Daly, B.J., & Harlow, F.H. 1970. Transport equations in turbulence. Physics
of Fluids, 13, 2634–2649.
Davies, A.M. 1990. On extracting tidal current profiles from vertically in-
tegrated two-dimensional hydrodynamic models. Journal of Geophysical
Research, 95, 18317–18342.
Davies, A.M. 1993. A bottom boundary layer-resolving three-dimensional

tidal model: A sensitivity study of eddy viscosity formulation. Journal of
Davies, A.M., & Jones, J.E. 1991. On the numerical solution of the turbu-
lence energy equations for wave and tidal flows. International Journal for
Numerical Methods in Fluids, 12, 17–41.
Davies, A.M., & Jones, J.E. 1992. A three-dimensional wind driven circula-
tion model of the Celtic and Irish Seas. Continental Shelf Research, 12,
159–188.
648 BIBLIOGRAPHY
Davies, A.M., Kwong, S.C.M., & Flather, R.A. 1997. Formulation of a

variable-function three-dimensional model, with applications to the M2
and M4 tide on the North-West European continental shelf. Continental
Shelf Research, 17, 165–204.
Deleersnijder, E. 1993. Numerical mass conservation in a free-surface sigma

coordinate marine model with mode splitting. Journal of Marine Systems,
4, 365–370.
Demarcq, H., & Wald, L. 1984. Surface dynamics of the Rhone plume inferred
from infrared imagery. Oceanologica Acta, 7, 159–162.
Dogniaux, R. 1984a. Eclairement énergétique solaire direct diffus et global

des surfaces orientées et inclinées. Partie I: Algorithmes et méthodologies.
Tech. rept. Institut Royal Météorologique de Belgique. Miscellanea Série
B No. 59.
Dogniaux, R. 1984b. Programme général de calcul des éclairements solaires

énergétiques et lumineux des surfaces orientées et inclinées. Ciels clairs,
couverts et variables. Tech. rept. Institut Royal Météorologique de Bel-
gique. Miscellanea Série C No. 21.
Doodson, A.T. 1921. The harmonic development of the tide-generating po-

tential. Proceedings of the Royal Society of London A, 100, 305–329.
Ferziger, J. 2005. Turbulence: its origins and structure. Pages 4–13 of:
Baumert, H.Z., Simpson, J., & Sündermann, J. (eds), Marine Turbulence.
Theories, Observations and Models. Cambridge University Press.
Flather, R.A. 1976. A tidal model of the northwest European continental

shelf. Mémoires de la Société Royale des Sciences de Liège, 10, 141–164.
Foreman, M.G.G., Henry, R.F., Walters, R.A., & Ballantyne, V.A. 1993.
A finite element model for tides and resonance along the north coast of
British Columbia. Journal of Geophysical Research, 98, 2509–2532.
Forget, P., Devenon, J.L., De Maistre, J.C., & Broche, P. 1990. VHF remote
sensing for mapping plume circulation. Geophysical Research Letters, 17,
1097–1100.
Frey, H. 1991. A three-dimensional, baroclinic shelf sea circulation model

– 1. The turbulence closure scheme and the one-dimensional test model.
Continental Shelf Research, 11, 365–395.
BIBLIOGRAPHY 649
Galperin, B., Kantha, L.H., Hassid, S., & Rosati, A. 1988. A quasi-
equilibrium turbulent energy model for geophysical flows. Journal of the
Atmospheric Sciences, 45, 55–62.
Galperin, B., A., Rosati, Kantha, L.H., & Mellor, G.L. 1989. Modeling
rotating stratified turbulent flows with application to oceanic mixed layers.
Journal of Physical Oceanography, 19, 901–916.
Garvine, R.W. 1974. Dynamics of small-scale oceanic fronts. Journal of

Geernaert, G.L.. 1990. Bulk parameterizations for the wind stress and heat
fluxes. Pages 91–172 of: Geernaert, G.L., & Plant, W.J. (eds), Surface
Waves and Fluxes, Vol. 1 – Current theory.
Geernaert, G.L., Katsaros, K.B., & Richter, K. 1986. Variation of the drag
coefficient and its dependence on sea state. Journal of Geophysical Re-
search, 91, 7667–7679.
Gill, A.E. 1982. Atmospheric-Ocean Dynamics. International Geophysics

Series, vol. 30. Orlando: Academic Press.
Glorioso, P.D., & Davies, A.M. 1995. The influence of eddy viscosity formu-
lation, bottom topography, and wind wave effects upon the circulation of
a shallow bay. Journal of Physical Oceanography, 25, 1243–1264.
Godin, G. 1972. The Analysis of Tides. Liverpool University Press.
Gradshteyn, I.S., & Ryzhik, I.M. 1981. Table of integrals, series and products.
Academic Press.
Griffies, S.M. 2004. Fundamentals of ocean climate modelling. Princeton

University Press.
Griffies, S.M., Gnanadesikan, A., Pacanowski, R.C., Larichev, V.D., Dukow-

icz, J.K., & R.D., Smith. 1998. Isoneutral diffusion in a z-coordinate ocean
model. Journal of Physical Oceanography, 28, 805–830.
Griffiths, R.W., & Linden, P.F. 1981. The stability of vortices in a rotating,
stratified fluid. Journal of Fluid Mechanics, 105, 283–316.
Haney, R.L. 1991. On the pressure gradient force over steep topography in
sigma coordinate ocean models. Journal of Physical Oceanography, 21,
610–619.
650 BIBLIOGRAPHY
Heaps, N.S. 1972. Estimation of density currents in the Liverpool Bay area
of the Irish Sea. Geophysical Journal of the Royal Astronomical Society,
30, 415–432.
Heathershaw, A.D. 1981. Comparisons of measured and predicted sediment

transport rates in tidal currents. Marine Geology, 42, 75–104.
Hedstrom, G.W. 1979. Nonreflecting boundary conditions for nonlinear hy-

perbolic systems. Journal of Computational Physics, 30, 222–237.
Hirsch, C. 1990. Numerical computation of internal and external flows. Vo-

lume 2: Computational methods for inviscid and viscous flows. New York:
Wiley.
Hofmann, M., & Maqueda, M.A.M. 2006. Performance of a second-order

moments advection scheme in an ocean general circulation model. Journal
of Geophysical Research, 111.
Hossain, M.S., & Rodi, W. 1982. A turbulence model for buoyant flows and
its application to vertical buoyant jets. Pages 121–178 of: Rodi, W. (ed),
Turbulent buoyant jets and plumes. HMT-Series, vol. 6. Oxford: Pergamon
Press.
Huthnance, J.M. (ed). 1997. Processes in Regions of Freshwater Influence

– PROFILE, MAS2-CT93-0054. Final Report. Proudman Oceanographic
Laboratory. POL Internal Document No. 102.
Jacket, D.R., & McDougall, T.J. 1995. Minimal adjustment of hydrographic

profiles to achieve static stability. Journal of Atmospheric and Oceanic
Technology, 12, 381–389.
James, I.D. 1996. Advection schemes for shelf sea models. Journal of Marine
Systems, 8, 237–254.
Janssen, P.A.E.M. 1991. Quasi-linear theory of wind-wave generation applied

to wave forecasting. Journal of Physical Oceanography, 21, 1631–1642.
Jensen, T.G. 1998. Open boundary conditions in stratified ocean models.

Jerlov, N.G. 1968. Optical Oceanography. Elsevier.
Kantha, L.H., & Clayson, C.A. 1994. An improved mixed layer model for
geophysical applications. Journal of Geophysical Research, 99, 25235–
25266.
BIBLIOGRAPHY 651
Kantha, L.H., & Clayson, C.A. 2000a. Small Scale Processes in Geophysical
Fluid Flows. San Diego, California: Academic Press.
Kantha, L.H., & Clayson, C.A. 2000b. Numerical Models of Oceans and
Oceanic Processes. San Diego, California: Academic Press.
Kantha, L.H., Rosati, A., & Galperin, B. 1989. Effect of rotation on vertical
mixing and associated turbulence in stratified fluids. Journal of Geophy-
sical Research, 94, 4843–4854.
Kato, H., & Phillips, O.M. 1969. On the penetration of a turbulent layer
into stratified fluid. Journal of Fluid Mechanics, 37, 643–655.
Katsaros, K.B. 1990. Parameterization schemes and models for estimat-

ing the surface radiation budget. Pages 339–368 of: Geernaert, G.L., &
W.J. Plant, W.J. (eds), Surface Waves and Fluxes, Vol. 2 – Remote sens-
ing.
Kliem, N., & Pietrzak, J.D. 1999. On the pressure gradient error in sigma
coordinate ocean models: A comparison with a laboratory experiment.
Journal of Geophysical Research, 104, 29781–29799.
Kondo, J. 1975. Air-sea bulk transfer coefficients in diabatic conditions.

Boundary-Layer Meteorology, 9, 91–112.
Kourafalou, V.H., Oey, L.-Y., Wang, J.D., & Lee, T.N. 1996. The fate of
river discharge on the continental shelf - 1. Modeling the river plume and
the inner shelf coastal current. Journal of Geophysical Research, 101,
3415–3434.
Kranenburg, C. 1983. The influence of side-wall friction on shear-stress driven

entrainment experiments. Journal of Hydraulic Research, 21, 99–117.
Kundu, P.K. 1981. Self-similarity in stress-driven entrainment experiments.

Large, W.G., & Pond, S. 1981. Open ocean momentum flux measurements in
moderate to strong winds. Journal of Physical Oceanography, 11, 324–336.
Large, W.G., & Pond, S. 1982. Sensible and latent heat flux measurements
over the ocean. Journal of Physical Oceanography, 12, 464–482.
Large, W.G., McWilliams, J.C., & Doney, S.C. 1994. Oceanic vertical mixing:
A review and a model with a nonlocal boundary layer parameterization.
Reviews of Geophysics, 32, 363–403.
652 BIBLIOGRAPHY
L’Ecuyer, P., & Côté, S. 1991. Implementing a random number package

with splitting facilities. ACM Transactions on Mathematical Software, 17,
98–111.
Leonard, B.P. 1979. A stable and accurate convective modelling procedure

based on quadratic upstream interpolation. Computer Methods in Applied
Mechanics and Engineering, 19, 59–98.
Luyten, P.J. 1996. An analytical and numerical study of surface and bottom
boundary layers with variable forcing and application to the North Sea.
Luyten, P.J. 1997. Modelling physical processes of haline stratification in

ROFIs with application to the Rhine outflow region. Journal of Marine
Systems, 12, 277–298.
Luyten, P.J. (ed). 1999. COHERENS – Dissemination and exploitation of a

coupled hydrodynamical-ecological model for regional and shelf seas, MAS3-
CT97-0088. Final Report. Management Unit of the Mathematical Models.
MUMM internal report.
Luyten, P.J., Deleersnijder, E., Ozer, J., & Ruddick, K.G. 1996. Presentation
of a family of turbulence closure models for stratified shallow water flows
and preliminary application to the Rhine outflow region. Continental Shelf
Research, 16, 101–130.
Luyten, P.J., Jones, J.E., Proctor, R., Tabor, A., Tett, P., & Wild-Allen,
K. 1999. COHERENS – A coupled hydrodynamical-ecological model for
regional and shelf seas: User Documentation. Tech. rept. Management
Unit of the Mathematical Models of the North Sea (MUMM), Belgium.
Luyten, P.J., Carniel, S., & Umgiesser, G. 2002. Validation of turbulence

closure parameterisations for stably stratified flows using the PROVESS
turbulence measurements in the North Sea. Journal of Sea Research, 47,
239–267.
Luyten, P.J., Jones, J.E., & Proctor, R. 2003. A numerical study of the
long- and short-term temperature variability and thermal circulation in
the North Sea. Journal of Physical Oceanography, 33, 37–56.
Luyten, P.J., Andreu-Burillo, I., Norro, A., Ponsar, S., & Proctor, R. 2006.
A new version of the European public domain code COHERENS. Pages
474–481 of: Dahlin, H., Flemming, N.C., Marchand, P., & Petersson, S.E.
(eds), European Operational Oceanography: Present and Future.
BIBLIOGRAPHY 653
Madec, G., Chartier, M., Delecluse, P., & Crépon, M. 1991. A three-
dimensional numerical study of deep-water formation in the northwestern
Mediterranean Sea. Journal of Physical Oceanography, 21, 1349–1371.
Martinsen, E.A., & Engedahl, H. 1987. Implementation and testing of a
lateral boundary scheme as an open boundary condition in a barotropic
ocean model. Coastal Engineering, 11, 603–627.
McCalpin, J.D. 1994. A comparison of second-order and fourth-order pres-
sure gradient algorithms in a σ-coordinate ocean model. International
Journal for Numerical Methods in Fluids, 18, 361–383.
McDougall, T.J., Jackett, D.R., Wright, D.G., & Feistel, R. 2003. Accurate
and computationally efficient algorithms for potential temperature and
density of seawater. Journal of Atmospheric and Oceanic Technology, 20,
730–741.
Mellor, G.L., & Yamada, T. 1974. A hierarchy of turbulence closure models
for planetary boundary layers. Journal of the Atmospheric Sciences, 31,
1791–1806.
Mellor, G.L., & Yamada, T. 1982. Development of a turbulence closure model
for geophysical fluid problems. Reviews of Geophysics and Space Physics,
20, 851–875.
Mesinger, F., & Arakawa, A. 1976. Numerical methods used in atmospheric
models. Tech. rept. Global Atmospheric Research Programme (GARP)
publication series.
Millero, F.J., Chen, C.-T., Bradshaw, A., & Schleicher, K. 1980. A new high
pressure equation of state for seawater. Deep-Sea Research, 27A.
Monin, A., & Obukhov, A. 1954. Basic turbulent mixing laws in the atmo-
spheric near-surface layer. Trans. Geophys. Inst. Akad. Nauk USSR, 151,
163–187.
MPI. 1995. A message-passing interface standard (version 1.1). Message
Passing Interface Forum, Univ. of Tennessee, Knoxville, Tennessee.
Munk, W.H., & Anderson, E.R. 1948. Notes on a theory of the thermocline.
Journal of Marine research, VII(3), 276–295.
Naimie, C.E., Loder, J.W., & Lynch, D.R. 1994. Seasonal variation of the
three-dimensional residual circulation on Georges Bank. Journal of Geo-
physical Research, 99, 15967–15989.
654 BIBLIOGRAPHY
Naudin, J.J., Cauwet, G., Leveau, M., Lochet, F., Pauc, H., Romano, J.-C.,
& Sempere, R. 1992. The bottom nepheloid layer off the Rhone River
mouth. Particulate transfer at the land-ocean interaction. Oceanologica
Acta, 15, 621–638.
Officer, C.B. 1976. Physical Oceanography of Estuaries (and Associated

Coastal Waters). New York: John Wiley.
Orlanski, I. 1976. A simple boundary condition for unbounded hyperbolic

flows. Journal of Computational Physics, 21, 251–269.
Pacanowski, R., & Griffies, S.M. 2000. MOMM 3.0 Manual. Tech. rept.
Geophysical Fluid Dynamics Laboratory.
Pacanowski, R.C., & Philander, S.G.H. 1981. Parameterization of vertical

mixing in numerical models of tropical oceans. Journal of Physical Ocea-
nography, 11, 1443–1451.
Palma, E.D., & Matano, R.P. 1998. On the implementation of passive open
boundary conditions for a general circulation model: The barotropic mode.
Patankar, S.V. 1980. Numerical Heat Transfer and Fluid Flow. Lecture Notes
in Earth Sciences. New York: McGraw-Hill.
Paulson, C.A., & Simpson, J.J. 1977. Irradiance measurements in the upper
ocean. Journal of Physical Oceanography, 7, 952–956.
Payne, R.E. 1972. Albedo of the sea surface. Journal of the Atmospheric
Sciences, 29, 959–970.
Peters, H., Gregg, M.C., & Toole, J.M. 1988. On the parameterization of
equatorial turbulence. Journal of Geophysical Research, 93, 1199–1218.
Phillips, N.A. 1957. A coordinate system having some special advantages for
numerical forecasting. Journal of Meteorology, 14, 184–185.
Pincus, R., & Rew, R. 2008. The NetCDF Fortran 90 Interface Guide.
UNIDATA Program Center of the University Corporation for Atmospheric
Research.
Pope, S.B. 2001. Turbulent Flows. Cambridge, U.K.: Cambridge University

Press.
BIBLIOGRAPHY 655
Prandle, D. 1982. The vertical structure of tidal currents and other oscillatory
flows. Continental Shelf Research, 1, 191–207.
Prather, M.J. 1986. Numerical advection by conservation of second-order

moments. Journal of Geophysical Research, 91, 6671–6681.
Press, W.H., Teukolsky, S.A., Vetterling, W.T., & Flannery, B.P. 1992. Nu-
merical Recipes. The art of scientific computing. 2 edn. Cambridge: Cam-
bridge University Press.
Price, J.F. 1979. On the scaling of stress-driven entrainment experiments.

Journal of Fluid Mechanics, 90, 509–529.
Proctor, R. (ed). 1997. NOMADS – North Sea Model Advection-Dispersion

study, MAS2-CT94-0105. Technical Report IV: Model Intercomparison.
Proudman Oceanographic Laboratory. POL Internal Document No. 107.
Proctor, R., & Davies, A.M. 1996. A three dimensional hydrodynamic model
of tides off the north-west coast of Scotland. Journal of Marine Systems,
7, 43–66.
Reed, R.K. 1977. On estimating insolation over the ocean. Journal of Physical
Oceanography, 7, 482–485.
Rodi, W. 1984. Turbulence models and their application in hydraulics. 2 edn.

Delft, Netherlands: International Association for Hydraulic Research.
Roe, P.L. 1985. Some contributions to the modelling of discontinuous flows.

Pages 163–193 of: Proceedings of 1983 AMS-SIAM summer seminar on
large scale computing in fluid mechanics. Lectures in Applied Mathematics,
vol. 22.
Roe, P.L. 1986. Characteristic-based schemes for the Euler equations. Annual
Review of Fluid Mechanics, 18, 337–365.
Røed, L.P., & Cooper, C.K. 1987. A study of various open boundary condi-
tions for wind-forced barotropic numerical ocean models. Pages 305–335
of: Nihoul, J.C.J., & Jamart, B.M. (eds), Three-dimensional models of
marine and estuarine dynamics. Amsterdam: Elsevier.
Røed, L.P., & Smedstad, O.M. 1984. Open boundary conditions for forced
waves in a rotating fluid. SIAM J. Sci. Stat. Comput., 5, 414–426.
Rosati, A., & Miyakoda, K. 1988. A general circulation model for upper
ocean simulation. Journal of Physical Oceanography, 18, 1601–1626.
656 BIBLIOGRAPHY
Rotta, J.C. 1951. Statistische theorie nichthomogener turbulenz. Zeitshrift

für Physik, 129, 547–572.
Ruddick, K.G. 1995. Modelling of coastal processes influenced by the fresh-
water discharge of the Rhine. Ph.D. thesis, Univ. de Liège, Belgium.
Ruddick, K.G., Deleersnijder, E., Luyten, P.J., & Ozer, J. 1995. Haline
stratification in the Rhine-Meuse freshwater plume: A three-dimensional
model sensitivity analysis. Continental Shelf Research, 15, 1597–1630.
Russ, R., Davis, G., Emmerson, S., & Davis, H. 2004. The NetCDF User’s
Guide. Data model, programming interfaces and format for self-describing,
portable data. UNIDATA Program Center of the University Corporation
for Atmospheric Research.
Schureman, P. 1941. Manual of Harmonic Analysis and Prediction of Tides.
Dept. of Commerce Special Publication 98, U.S. Government Printing Of-
fice, Washington D.C.
Semtner, A.J., & Chervin, R.M. 1988. A simulation of the global ocean cir-
culation with residual eddies. Journal of Geophysical Research, 93, 15502–
15522.
Shchepetkin, A.F., & McWilliams, J.C. 2003. A method for computing the
horizontal pressure-gradient force in an oceanic model with a nonaligned
vertical coordinate. Journal of Geophysical Research, 108.
Slørdal, L.H. 1997. The pressure gradient force in sigma-coordinate ocean
models. International Journal for Numerical Methods in Fluids, 24, 987–
1017.
Smagorinsky, J. 1963. General circulation experiments with the primitive
equations - I. The basic experiment. Monthly Weather Review, 91, 99–
164.
Smith, S.D., & Banke, E.G. 1975. Variation of the sea surface drag coefficient
with windspeed. Quarterly Journal Meteorological Society, 101, 665–673.
Song, Y., & Haidvogel, D. 1994. A semi-implicit ocean circulation model
using a generalized topography-following coordinate system. Journal of
Computational Physics, 115, 228–244.
Song, Y.T. 1998. A general pressure gradient formulation for ocean models,
1. Scheme design and diagnostic analysis. Monthly Weather Review, 126,
3213–3230.
BIBLIOGRAPHY 657
Soulsby, R.L. 1983. The bottom boundary layers of shelf seas. Pages 189–266
of: Johns, B. (ed), Physical Oceanography of Coastal and Shelf Seas, vol.
35. Elsevier Oceanography Series.
Sournia, A., Brylinski, J.-M., Dallot, S., Le Corre, P., Leveau, M., Prieur,
L., & Froget, C. 1990. Fronts hydrologiques au large des côtes françaises:
Les sites-ateliers du programme Frontal. Oceanologica Acta, 13, 413–436.
Steinhorn, I. 1991. Salt flux and evaporation. Journal of Physical Oceano-

graphy, 21, 1681–1683.
Stelling, G.S., & Van Kester, J.A.T.M. 1994. On the approximation of ho-
rizontal gradients in sigma coordinates for bathymetry with steep bottom
slopes. International Journal for Numerical Methods in Fluids, 18, 915–
935.
Sweby, P.K. 1984. High resolution schemes using flux limiters for hyperbolic
conservation laws. SIAM Journal of Numerical Analysis, 21, 995–1011.
Takacs, L.L. 1985. A two-step scheme for the advection equation with min-
imized dissipation and dispersion errors. Monthly Weather Review, 1050–
1065.
Tartinville, B., Deleersnijder, E., Lazure, P., Proctor, R., Ruddick, K.G., &
Uittenbogaard, R.E. 1998. A coastal ocean model intercomparison study
for a three-dimensional idealised test case. Applied Mathematical Model-
ling, 165–182.
Tsimplis, M.N., Proctor, R., & Flather, R.A. 1995. A two-dimensional model
for the Mediterranean Sea. Journal of Geophysical Research, 100, 16223–
16239.
UDUNITS. 1997. Udunits software package. UNIDATA Program Center of

the University Corporation for Atmospheric Research.
Visser, A.W., Souza, A.J., Hessner, K., & Simpson, J.H. 1994. The effect of
stratification on tidal current profiles in a region of freshwater influence.
Oceanologica Acta, 17, 369–381.
Warrach, K. 1998. Modelling the thermal stratification in the North Sea.

Wu, J. 1980. Wind stress coefficients over the sea surface near neutral con-
ditions – A revisit. Journal of Physical Oceanography, 10, 727–740.
658 BIBLIOGRAPHY
Xing, J., & Davies, A.M. 1996. Application of turbulence energy models
to the computation of tidal currents and mixing intensities in shelf edge
regions. Journal of Physical Oceanography, 26, 417–447.
Yanenko, N.N. 1971. The method of fractional steps. New York: Springer
Verlag.
Part VI
Reference manual
659
Appendix 22
Description of external routines
22.1 Advection Terms.F90

Advective terms in all transport equations: scalar equations at the C-node, 2-
D and 3-D momentum equations at the U- and V-nodes, turbulence equations
at the W-nodes.
Xadv at C
SUBROUTINE Xadv at C(psic,tridcfc,novars,iopt adv,nh,klo,kup,psiobu)
INTEGER, INTENT(IN) :: iopt adv, klo, kup, nh, novars
REAL, INTENT(IN), DIMENSION(1-nhalo:ncloc+nhalo,&
& 1-nhalo:nrloc+nhalo,nz,novars) :: psic
REAL, INTENT(INOUT), DIMENSION(ncloc,nrloc,nz,4,novars) :: tridcfc
REAL, INTENT(IN), DIMENSION(nobu,nz,novars) :: psiobu
File
Advection Terms.F90
Type
Subroutine
Purpose
Advective term in the X-direction for one or more scalar quantities at
the C-nodes
Reference
Section 5.5.4.1
Arguments
661
662 APPENDIX 22. DESCRIPTION OF EXTERNAL ROUTINES
psic C-node quantity or quantities to be advected [psic]

tridcfc Tridiagonal matrix for storing explicit and implicit (at
open boundaries) parts of the advective term [psic]
novars Number of variables to be advected
iopt adv Switch to select the advection scheme
nh Halo size of local arrays
klo 1 for a Neumann, 2 for a Dirichlet condition at the bottom
kup nz for a Neumann, nz-1 for a Dirichlet condition at the
surface
psiobu Data profiles at open boundaries. Flagged data indicate
zero gradient conditions. [psic]
Calling procedures
transport at C 3d, transport at C 4d1, transport at C 4d2
Xadv at U 2d
SUBROUTINE Xadv at U 2d(psiu,xadvatu2d,nh,vintflag)
LOGICAL, INTENT(INOUT) :: vintflag
INTEGER, INTENT(IN) :: nh
& 1-nhalo:nrloc+nhalo) :: psiu
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc) :: xadvatu2d
File
Advection Terms.F90
Type
Subroutine
Purpose
Alongstream advective term for the X-component of the depth-integrated
current U at the U-nodes
Reference
Section 5.3.4.1
Arguments
psiu U-node quantity to be advected [m2 /s]
xadvatu2d Advective term (times ∆τ ) [m2 /s]
22.1. ADVECTION TERMS.F90 663

vintflag Add the result to the third (2-D barotropic) part of equa-
tion (5.151) if set to .TRUE. at predictor time steps.
Calling procedures
transport at U 2d
Xadv at U 3d
SUBROUTINE Xadv at U 3d(psiu,xadvatu3d,nh,vintflag)
LOGICAL, INTENT(IN) :: vintflag
& 1-nhalo:nrloc+nhalo,nz) :: psiu
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,nz) :: xadvatu3d
File
Advection Terms.F90
Type
Subroutine
Purpose
Alongstream advection term for the 3-D current u at the U-nodes
Reference
Section 5.3.3.1
Arguments
psiu U-node quantity to be advected [m/s]

xadvatu3d Advective term (times hu3 ) [m2 /s2 ]
vintflag Add the result to the first (3-D) part of equation (5.151)
if set to .TRUE. at predictor time steps.
Calling procedures
transport at U 3d
Xadv at V 2d
SUBROUTINE Xadv at V 2d(psiv,xadvatv2d,nh,vintflag)
& 1-nhalo:nrloc+nhalo) :: psiv
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc) :: xadvatv2d
File
Advection Terms.F90
Type
Subroutine
Purpose
Cross-stream advective term in the X-direction for the Y-component
of the depth-integrated current V at the V-nodes
Reference
Section 5.3.4.3
Arguments
psiv V-node quantity to be advected [m2 /s]
xadvatv2d Advective term (times ∆τ ) [m2 /s]
Calling procedures
transport at V 2d
Xadv at V 3d
SUBROUTINE Xadv at V 3d(psiv,xadvatv3d,nh,vintflag)
& 1-nhalo:nrloc+nhalo,nz) :: psiv
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,nz) :: xadvatv3d
File
Advection Terms.F90
Type
Subroutine
Purpose
Cross-stream advective term for the 3-D current v at the V-nodes
Reference
Section 5.3.3.3
Arguments
psiv V-node quantity to be advected [m/s]
xadvatv3d Advective term (times hv3 ) [m2 /s2 ]
vintflag Add the result to the second (3-D) part of equation (5.152)
Calling procedures
transport at V 3d
Xadv at W
SUBROUTINE Xadv at W(psiw,tridcfw,uadvatuw,nh,klo,kup)
INTEGER, INTENT(IN) :: klo, kup, nh
& 1-nhalo:nrloc+nhalo,nz+1) :: psiw
REAL, INTENT(INOUT), DIMENSION(ncloc,nrloc,nz+1,4) :: tridcfw
& nrloc,2:nz) :: uadvatuw
File
Advection Terms.F90
Type
Subroutine
Purpose
Advective term in the X-direction for a quantity at the W-nodes
Reference
Section 5.6.2.1
Arguments
psiw W-node quantity to be advected [psiw]

tridcfw Tridiagonal matrix to store explicit and implicit (at open
boundaries) parts of the advective term [psiw]
uadvatuw Advective velocity at the UW-nodes [m/s]
klo 2 for a Neumann or a Dirichlet condition at the bottom,
3 for a Dirichlet condition at the first W-node above the
bottom
kup nz for a Neumann condition or a Dirichlet condition at the
surface, nz-1 for a Dirichlet condition at the first W-node
below the surface
Calling procedures
transport at W
Yadv at C
SUBROUTINE Yadv at C(psic,tridcfc,novars,iopt adv,nh,klo,kup,psiobv)
INTEGER, INTENT(IN) :: iopt adv, klo, kup, nh, novars
REAL, INTENT(IN), DIMENSION(nobv,nz,novars) :: psiobv
File
Advection Terms.F90
Type
Subroutine
Purpose
Advective term in the Y-direction for one or more scalar quantities at
the C-nodes
Reference
Section 5.5.4.2
Arguments
tridcfc Tridiagonal matrix for storing explicit and implicit (at
open boundaries) parts of advective term [psic]
novars Number of variables to be advected.

iopt adv Switch to select the advection scheme
surface
psiobv Data profiles at open boundaries. Flagged data indicate
zero gradient conditions. [psic]
Calling procedures
Yadv at U 2d
SUBROUTINE Yadv at U 2d(psiu,yadvatu2d,nh,vintflag)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc) :: yadvatu2d
File
Advection Terms.F90
Type
Subroutine
Purpose
Cross-stream advective term for the X-component of the depth-integrated
current U at the U-nodes
Reference
Section 5.3.4.2
Arguments
psiu U-node quantity to be advected [m2 /s]
yadvatu2d Advective term (times ∆τ ) [m2 /s]
vintflag Add the result to the fourth (2-D barotropic) part of equa-
Calling procedures
transport at U 2d
Yadv at U 3d
SUBROUTINE Yadv at U 3d(psiu,yadvatu3d,nh,vintflag)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,nz) :: yadvatu3d
File
Advection Terms.F90
Type
Subroutine
Purpose
Cross-stream advective term for the 3-D current u at the U-nodes
Reference
Section 5.3.3.2
Arguments
yadvatu3d Advective term (times hu3 ) [m2 /s2 ]
Calling procedures
transport at U 3d
Yadv at V 2d
SUBROUTINE Yadv at V 2d(psiv,yadvatv2d,nh,vintflag)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc) :: yadvatv2d
File
Advection Terms.F90
Type
Subroutine
Purpose
Alongstream advective term for the Y-component of the depth-integrated
current V at the V-nodes
Reference
Section 5.3.4.4
Arguments
psiv V-node quantity to be advected [m2 /s]
yadvatv2d Advective term (times ∆τ ) [m2 /s]
Calling procedures
transport at V 2d
Yadv at V 3d
SUBROUTINE Yadv at V 3d(psiv,yadvatv3d,nh,vintflag)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,nz) :: yadvatv3d
File
Advection Terms.F90
Type
Subroutine
Purpose
Alongstream advective term for the 3-D current v at the V-nodes
Reference
Section 5.3.3.4
Arguments
yadvat3d Advective term (times hv3 ) [m2 /s2 ]
Calling procedures
transport at V 3d
Yadv at W
SUBROUTINE Yadv at W(psiw,tridcfw,vadvatvw,nh,klo,kup)
INTEGER, INTENT(IN) :: klo, kup, nh
REAL, INTENT(IN), DIMENSION(ncloc,2-nhalo:nrloc+nhalo,&
& 2:nz) :: vadvatvw
File
Advection Terms.F90
Type
Subroutine
Purpose
Advective term in the Y-direction for a quantity at the W-nodes
Reference
Section 5.6.2.2
Arguments
tridcfw Tridiagonal matrix for storing explicit and implicit (at
open boundaries) parts of the advective term [psiw]
vadvatvw Advective velocity at the VW-nodes [m/s]
bottom

below the surface
Calling procedures
transport at W
Zadv at C
SUBROUTINE Zadv at C(psic,tridcfc,wadvatw,novars,iopt adv,klo,kup)
INTEGER, INTENT(IN) :: iopt adv, klo, kup, novars
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nz+1,novars) :: wadvatw
File
Advection Terms.F90
Type
Subroutine
Purpose
Advective term in the vertical direction for one or more scalar quantities
at the C-nodes
Reference
Section 5.5.4.3
Arguments
psic C-node quantity or quantities be advected [psic]
tridcfc Tridiagonal matrix for storing implicit and explicit terms
[psic]
wadvatw Advective velocity at the W-nodes [m/s]
iopt adv Switch to select the vertical advection scheme
surface
Calling procedures
Zadv at U
SUBROUTINE Zadv at U(psiu,tridcfu,wadvatuw)
REAL, INTENT(INOUT), DIMENSION(ncloc,nrloc,nz,4) :: tridcfu
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nz+1) :: wadvatuw
File
Advection Terms.F90
Type
Subroutine
Purpose
Vertical advective term for the 3-D current u at the the U-nodes
Reference
Section 5.3.6.1
Arguments
tridcfu Tridiagonal matrix for storing implicit and explicit terms
[m/s]
wadvatuw Advective velocity at the UW-nodes [m/s]
Calling procedures
transport at U 3d
Zadv at V
SUBROUTINE Zadv at V(psiv,tridcfv,wadvatvw)
REAL, INTENT(INOUT), DIMENSION(ncloc,nrloc,nz,4) :: tridcfv
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nz+1) :: wadvatvw
File
Advection Terms.F90
Type
Subroutine
Purpose
Vertical advective term for the 3-D current v at the V-nodes
Reference
Section 5.3.6.2
Arguments
tridcfv Tridiagonal matrix for storing implicit and explicit terms
[m/s]
wadvatvw Advective velocity at the VW-nodes [m/s]
Calling procedures
transport at V 3d
Zadv at W
SUBROUTINE Zadv at W(psiw,tridcfw,wadvatc,klo,kup)
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nz) :: wadvatc
File
Advection Terms.F90
Type
Subroutine
Purpose
Vertical advective term for a quantity at the W-nodes
Reference
Section 5.6.2.3
Arguments
tridcfw Tridiagonal matrix for storing implicit and explicit terms
[psiw]
wadvatw Advective velocity at the W-nodes [m/s]

bottom
below the surface
Calling procedures
transport at W
22.2 Allocate Arrays.f90

Allocation and deallocation of arrays which have a global scope in the pro-
gram. The arrays are declared as allocatable arrays in the respective module
files (see Table 10.1).
allocate global grid

SUBROUTINE allocate global grid
File
Allocate Arrays.f90
Type
Subroutine
Purpose
Allocate grid arrays on the global (parallel) grid.
Calling procedures
initialise model
allocate mod arrays

SUBROUTINE allocate mod arrays
File
Allocate Arrays.f90
Type
Subroutine
22.3. BOTTOM FLUXES.F90 675
Purpose
Allocate model arrays on the local sub-domain (mostly including an
halo) with a “global” scope in the program, i.e. arrays used in different
program routines. The arrays are declared as allocatable arrays in
MODULE units of the program.
Reference
Sections 8.1.1
Arguments
None
Calling procedures
initialise model ,
simulation end
deallocate mod arrays

SUBROUTINE deallocate mod arrays
File
Allocate Arrays.f90
Type
Subroutine
Purpose
Deallocate all model arrays with a “global” scope at the end of a sim-
ulation.
Calling procedures
simulation end
22.3 Bottom Fluxes.f90

Routines used for the calculation of the bottom stress.
bottom stress
SUBROUTINE bottom stress
File
Bottom Fluxes.f90
Type
Subroutine
Purpose
Base program unit for the evaluation of the bottom stress.
Reference
Sections 4.9.2, 5.3.1.2 and 5.3.14.2
Called internal procedures
bottom currents, bottom drag coef1, bottom drag coef2,
bottom stress linear, bottom stress quadr
Calling procedures
current corr, current corr 1d, current 2d, initialise model
bottom currents
SUBROUTINE bottom currents
File
Bottom Fluxes.f90
Type
Internal subroutine
Purpose
Magnitude of the current at the bottom level of the model grid
Calling procedures
bottom stress
bottom drag coef1

SUBROUTINE bottom drag coef1
File
Bottom Fluxes.f90
Type
Internal subroutine
Purpose
Interpolate the externally imposed bottom drag coefficient at the U-
and the V-nodes when iopt bstres drag≤2.
22.3. BOTTOM FLUXES.F90 677
Calling procedures
bottom stress
bottom drag coef2

SUBROUTINE bottom drag coef2
File
Bottom Fluxes.f90
Type
Internal subroutine
Purpose
Update the bottom drag coefficients using imposed roughness lengths
when iopt bstres drag>2.
Reference
Equation (5.18)
Calling procedures
bottom stress
bottom stress linear

SUBROUTINE bottom stress linear
File
Bottom Fluxes.f90
Type
Internal subroutine
Purpose
Evaluate the bottom stress using a linear friction law.
Reference
Equation (4.326) or (4.327)
Calling procedures
bottom stress
bottom stress quadr

SUBROUTINE bottom stress quadr
File
Bottom Fluxes.f90
Type
Internal subroutine
Purpose
Evaluate the bottom stress using a quadratic friction law.
Reference
Equation (4.328) or (4.329)
Calling procedures
bottom stress
22.4 Coherens Program.f90

coherens main
SUBROUTINE coherens main
File
Coherens Program.f90
Type
Main program
Purpose
Main program unit of COHERENS
Called external procedures

astronomical tides, baroclinic gradient, biological model, coherens end,
coherens start, equation of state, harmonic analysis, horizontal diff coeffs,
hydrodynamic equations, initialise model, mask function, meteo input,
salinity equation, simulation end, simulation start, store depths old,
temperature equation, time averages, time series, usrdef output, verti-
cal diff coefs, write bioics, write physics
22.5. CORRECTOR TERMS.F90 679
22.5 Corrector Terms.F90

Evaluate the corrector terms in the scalar transport equations. For a defi-
nition see equations (5.337)–(5.339) for scalars at the C-nodes and (5.459)–
(5.461) for scalars at the W-nodes.
Xcorr at C
SUBROUTINE Xcorr at C(psic,ucorratc,novars,klo,kup)
INTEGER, INTENT(IN) :: klo, kup, novars
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,klo:kup,novars) :: ucorratc
File
Corrector Terms.F90
Type
Subroutine
Purpose
Corrector term in the X-direction for a quantity at the C-nodes
Reference
Equation (5.377)
Arguments
ucorratc Corrector term (times ∆t) [psic]
surface
Calling procedures
Xcorr at W
SUBROUTINE Xcorr at W(psiw,ucorratw,uvelatuw,klo,kup)
INTEGER, INTENT(IN) :: klo, kup

REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,klo:kup) :: ucorratw
& nrloc,2:nz) :: uvelatuw
File
Corrector Terms.F90
Type
Subroutine
Purpose
Corrector term in the X-direction for a quantity at the W-nodes
Reference
Equation (5.459)
Arguments
ucorratw Corrector term (times ∆t) [psiw]
uvelatuw X-component of the current u at the UW-nodes [m/s]
bottom
below the surface
Calling procedures
transport at W
Ycorr at C
SUBROUTINE Ycorr at C(psic,vcorratc,novars,klo,kup)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,klo:kup,novars) :: vcorratc
File
Corrector Terms.F90
Type
Subroutine
Purpose
Corrector term in the Y-direction for a quantity at the C-nodes
Reference
Equation (5.378)
Arguments
vcorratc Corrector term (times ∆t) [psic]
surface
Calling procedures
Ycorr at W
SUBROUTINE Ycorr at W(psiw,vcorratw,vvelatvw,klo,kup)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,klo:kup) :: vcorratw
REAL, INTENT(IN), DIMENSION(ncloc,&
& 2-nhalo:nrloc+nhalo,2:nz) :: vvelatvw
File
Corrector Terms.F90
Type
Subroutine
Purpose
Corrector term in the Y-direction for a quantity at the W-nodes
Reference
Equation (5.460)
Arguments

vcorratw Corrector term (times ∆t) [psiw]
vvelatvw Y-component of the current v at the VW-nodes [m/s]
bottom
below the surface
Calling procedures
transport at W
Zcorr at C
SUBROUTINE Zcorr at C(psic,wcorratc,novars,klo,kup)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,klo:kup,novars) :: wcorratc
File
Corrector Terms.F90
Type
Subroutine
Purpose
Corrector term in the Z-direction for a quantity at the C-nodes
Reference
Equation (5.379)
Arguments
wcorratc Corrector term (times ∆t) [psic]
surface
Calling procedures
Zcorr at W
SUBROUTINE Zcorr at W(psiw,wcorratw,wvelatc,klo,kup)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,klo:kup) :: wcorratw
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nz) :: wvelatc
File
Corrector Terms.F90
Type
Subroutine
Purpose
Corrector term in the Z-direction for a quantity at the W-nodes
Reference
Equation (5.461)
Arguments

wcorratw Corrector term (times ∆t) [psiw]
wvelatc Transformed vertical current ω at the C-nodes [m/s]
bottom
below the surface
Calling procedures
transport at W
22.6 Density Equations.F90

Routines for all kinds of calculations related to density: salinity and tempe-
rature equations, equation of state, optical formulation, baroclinic pressure
gradient.
baroclinic gradient
SUBROUTINE baroclinic gradient
File
Density Equations.F90
Type
Subroutine
Purpose
Evaluate the baroclinic pressure gradient using different formulations
selected by iopt dens grad.
Reference
Section 5.3.12

hcube deriv, hcube fluxes
Calling procedures
coherens main
equation of state
SUBROUTINE equation of state
File
Type
Subroutine
Purpose
Evaluate the density and temperature/salinity expansion/contraction
coefficients using different versions of the equation of state.
22.6. DENSITY EQUATIONS.F90 685
Reference
Section 4.2.3
Calling procedures
initialise model
hcube deriv
SUBROUTINE hcube deriv(psi,dpsi,cdir)
CHARACTER (LEN=1), INTENT(IN) :: cdir
& 1-nhalo:nrloc+nhalo,nz) :: psi
REAL, INTENT(OUT), DIMENSION(0:ncloc+1,0:nrloc+1,nz) :: dpsi
File
Type
Subroutine
Purpose
Evaluate the horizontal or vertical derivative terms in the cube-H method
for the baroclininic pressure gradient using the discretisations (5.220)–
(5.223).
Reference
Section 5.3.12.3
Arguments
psi Input array
dpsi Array of derivatives
cdir Direction of derivative (‘X’,‘Y’,‘Z’)
Calling procedures
baroclinic gradient
hcube fluxes
SUBROUTINE hcube fluxes(psi,zcoord,dpsi,dzcoord,fcube,cdir)
CHARACTER (LEN=1), INTENT(IN) :: cdir
& 1-nhalo:nrloc+nhalo,nz) :: psi, zcoord
REAL, INTENT(IN), DIMENSION(0:ncloc+1,0:nrloc+1,nz) :: dpsi, dzcoord

REAL, INTENT(OUT), DIMENSION(0:ncloc,0:nrloc,nz) :: fcube
File
Type
Subroutine
Purpose
Evaluate the integrals F U , F V , F W in the cube-H method for the
baroclinic pressure gradient using the discretisations (5.215)–(5.219).
Reference
Section 5.3.12.3
Arguments
psi Density (temperature or salinity) array
zcoord Array of Z-coordinates
dpsi Array of psi-derivatives
dzcoord Array of Z-derivatives
fcube Pseudo fluxes
cdir Direction of derivative (‘X’,‘Y’,‘Z’)
Calling procedures
baroclinic gradient
heat optics
SUBROUTINE heat optics
File
Type
Subroutine
Purpose
Evaluate the solar radiance within the water column using the optical
formulation (4.48).
Reference
Section 4.2.1.1
22.6. DENSITY EQUATIONS.F90 687
Calling procedures
temperature equation
salinity equation
SUBROUTINE salinity equation
File
Type
Subroutine
Purpose
Solve the salinity equation (4.72).
Reference
Section 4.2.1.2
define profobc spec, open boundary conds prof, salinity flux,
transport at C 3d, update nest data prof, update profobc data
Calling procedures
initialise model
SUBROUTINE temperature equation
File
Type
Subroutine
Purpose
Solve the temperature equation (4.71).
Reference
Section 4.2.1.2
define profobc spec, define surface input grid, heat flux, heat optics,
open boundary conds prof, solar irradiance, transport at C 3d,
update nest data prof, update profobc data, update surface data
Calling procedures
initialise model
22.7 Diffusion Coefficients.F90

Calculation of the horizontal and vertical diffusion coefficients.
horizontal diff coefs

SUBROUTINE horizontal diff coefs
File
Diffusion Coefficients.F90
Type
Subroutine
Purpose
Set the horizontal diffusion coefficients to a constant value on first call
if iopt hdif coef=1. If iopt hdif coef=2, the coefficients are determined
using the Smagorinsky formulation.
Reference
Sections 5.3.11.1 and 5.5.6.1
Calling procedures
coherens main
vertical diff coefs

SUBROUTINE vertical diff coefs
File
Diffusion Coefficients.F90
Type
Subroutine
Purpose
Calculate the vertical diffusion coefficients νT and λT using the turbu-
lence model selected by the user. The actual calculation is performed
by the routines in Turbulence Equations.F90.
22.8. DIFFUSION TERMS.F90 689
Reference
Section 4.4

dissipation equation, eddy coefs alg, eddy coefs tc, init turbulence,
kl equation, mixing length, tke equation, tke equilibrium
Calling procedures
coherens main
22.8 Diffusion Terms.F90

Calculate the diffusion terms in all transport equations: scalar equations
at the C-node, 2-D and 3-D momentum equations at the U- and V-nodes,
turbulence equations at the W-nodes.
Xdif at C
SUBROUTINE Xdif at C(psic,tridcfc,hdifcoefatu,novars,klo,kup)
REAL, INTENT(IN), DIMENSION(ncloc+1,nrloc,nz) :: hdifcoefatu
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Diffusion term in the X-direction for one or more scalar quantities at
the C-nodes
Reference
Section 5.5.5.1
Arguments
psic C-node quantity or quantitites to be diffused [psic]
tridcfc Tridiagonal solution matrix. The result is stored as an
explicit term. [psic]
hdifcoefatu Horizontal diffusion coefficient at the U-nodes [m2 /s]

novars Number of variables to be diffused
surface
Calling procedures
Xdif at U 2d
SUBROUTINE Xdif at U 2d(psiu,xdifatu2d,hdifcoefatc,vintflag)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc) :: xdifatu2d
REAL, INTENT(IN), DIMENSION(0:ncloc,0:nrloc) :: hdifcoefatc
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Alongstream diffusion term for the X-component of the depth current-
integrated current U at the U-nodes
Reference
Section 5.3.8
Arguments
psiu U-node quantity to be diffused [m2 /s]
xdifatu2d Diffusion term times ∆τ [m2 /s]
hdifcoefatc Horizontal diffusion coefficient at the C-nodes [m2 /s]
Calling procedures
transport at U 2d
Xdif at U 3d
SUBROUTINE Xdif at U 3d(psiu,xdifatu3d,hdifcoefatc,vintflag)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,nz) :: xdifatu3d
REAL, INTENT(IN), DIMENSION(0:ncloc,0:nrloc,nz) :: hdifcoefatc
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Along-stream diffusion term in the X-direction for the X-component of
the current u at the U-nodes
Reference
Section 5.3.7
Arguments
psiu U-node quantity to be diffused [m/s]
xdifatu3d Diffusion term (times hu3 ) [m2 /s2 ]
Calling procedures
transport at U 3d
Xdif at V 2d
SUBROUTINE Xdif at V 2d(psiv,xdifatv2d,hdifcoefatuv,vintflag)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc) :: xdifatv2d
REAL, INTENT(IN), DIMENSION(ncloc+1,nrloc+1) :: hdifcoefatuv
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Diffusion term in the X-direction for the 2-D current V at the V-nodes
Reference
Section 5.3.8
Arguments
psiv V-node quantity to be diffused [m2 /s]
xdifatv2d Diffusion term (times ∆τ ) [m2 /s]
hdifcoefatuv Horizontal diffusion coefficient at the UV-nodes [m2 /s]
Calling procedures
transport at V 2d
Xdif at V 3d
SUBROUTINE Xdif at V 3d(psiv,xdifatv3d,hdifcoefatuv,vintflag)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,nz) :: xdifatv3d
REAL, INTENT(IN), DIMENSION(ncloc+1,nrloc+1,nz) :: hdifcoefatuv
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Cross-stream advection term for the 3-D current v at the V-nodes
Reference
Section 5.3.7
Arguments
psiv V-node quantity to be diffused [m/s]
xdifatv3d Diffusion term (times hv3 ) [m2 /s2 ]

Calling procedures
transport at V 3d
Xdif at W
SUBROUTINE Xdif at W(psiw,tridcfw,hdifcoefatuw,klo,kup)
& 1-nhalo:nrloc+nhalo,nz+1):: psiw
REAL, INTENT(IN), DIMENSION(ncloc+1,nrloc,2:nz) :: hdifcoefatuw
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Diffusion term in the X-direction for a quantity at the W-nodes
Reference
Section 5.6.3.1
Arguments
psiw W-node quantity to be diffused [psiw]
tridcfw Tridiagonal solution matrix. The result is stored as an
explicit term. [psiw]
hdifcoefatuw Horizontal diffusion coefficient at the UW-nodes
bottom
below the surface
Calling procedures
transport at W
Ydif at C
SUBROUTINE Ydif at C(psic,tridcfc,hdifcoefatv,novars,klo,kup)
REAL, INTENT(IN), DIMENSION(ncloc,nrloc+1,nz) :: hdifcoefatv
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Diffusion term in the Y-direction for one or more scalar quantities at
the C-nodes
Reference
Section 5.5.5.2
Arguments
psic C-node quantity or quantities to be diffused [psic]

tridcfc Tridiagonal solution matrix. The result is stored as an
explicit term. [psic]
hdifcoefatv Diffusion coefficient at the V-nodes [m2 /s]
surface
Calling procedures
Ydif at U 2d
SUBROUTINE Ydif at U 2d(psiu,ydifatu2d,hdifcoefatuv,vintflag)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc) :: ydifatu2d
REAL, INTENT(IN), DIMENSION(ncloc+1,nrloc+1) :: hdifcoefatuv
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Cross-stream diffusion term for the X-component of the depth current-
integrated current U at the U-nodes
Reference
Section 5.3.8
Arguments
psiu U-node quantity to be diffused [m2 /s]
ydifatu2d Diffusion term (times ∆τ ) [m2 /s]
Calling procedures
transport at U 2d
Ydif at U 3d
SUBROUTINE Ydif at U 3d(psiu,ydifatu3d,hdifcoefatuv,vintflag)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,nz) :: ydifatu3d
REAL, INTENT(IN), DIMENSION(ncloc+1,nrloc+1,nz) :: hdifcoefatuv
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Cross-stream diffusion term in the X-direction for the X-component of
the current u at the U-nodes
Reference
Section 5.3.7
Arguments
ydifatu3d Diffusion term (times hu3 ) [m2 /s2 ]
Calling procedures
transport at U 3d
Ydif at V 2d
SUBROUTINE Ydif at V 2d(psiv,ydifatv2d,hdifcoefatc,vintflag)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc) :: ydifatv2d
REAL, INTENT(IN), DIMENSION(0:ncloc,0:nrloc) :: hdifcoefatc
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Diffusion term in the Y-direction for the 2-D current V at the V-nodes
Reference
Section 5.3.8
Arguments
psiv V-node quantity to be diffused [m2 /s]

ydifatv2d Diffusion term [m2 /s2 ]
Calling procedures
transport at V 2d
Ydif at V 3d
SUBROUTINE Ydif at V 3d(psiv,ydifatv3d,hdifcoefatc,vintflag)
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,nz) :: ydifatv3d
REAL, INTENT(IN), DIMENSION(0:ncloc,0:nrloc,nz) :: hdifcoefatc
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Along-stream diffusion term in the Y-direction for the Y-component of
the current v at the V-nodes
Reference
Section 5.3.7
Arguments
ydifatv3d Diffusion term (times hv3 ) [m2 /s2 ]
Calling procedures
transport at V 3d
Ydif at W
SUBROUTINE Ydif at W(psiw,tridcfw,hdifcoefatvw,klo,kup)
& 1-nhalo:nrloc+nhalo,nz+1)::psiw
REAL, INTENT(IN), DIMENSION(ncloc,nrloc+1,2:nz) :: hdifcoefatvw
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Diffusion term in the Y-direction for a quantity at the W-nodes
Reference
Section 5.6.3.2
Arguments
tridcfw Tridiagonal solution matrix. The result is stored as an
explicit term. [psiw]
hdifcoefatvw Horizontal diffusion coefficient at the VW-nodes [m2 /s]
bottom
below the surface
Calling procedures
transport at W
Zdif at C
SUBROUTINE Zdif at C(psic,tridcfc,vdifcoefatw,novars,ibcsur,&
& ibcbot,nbcs,nbcb,bcsur,bcbot,klo,kup)
INTEGER, INTENT(IN) :: ibcbot, ibcsur, klo, kup, nbcb, nbcs, novars

REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nz+1) :: vdifcoefatw
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nbcs,novars) :: bcsur
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nbcb,novars) :: bcbot
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Vertical diffusion term for one or more scalar quantities at the C-nodes
Reference
Sections 5.5.5.3 and 5.5.7
Arguments
psic C-node quantity or quantities to be diffused [psic]
tridcfc Tridiagonal matrix to store implicit and explicit terms
[psic]
vdifcoefatw Vertical diffusion coefficient at the W-nodes [m2 /s]
ibcsur Type of surface boundary condition
0: zero flux (Neumann) condition
1: prescibed flux (Neumann) condition (5.391)
2: Neumann condition using a transfer velocity (5.392)
3: Dirichlet condition at the first C-node below the surface
(5.393)
4: Dirichlet condition (5.394) at the surface
ibcbot Type of bottom boundary condition
3: Dirichlet condition (5.398) at the first C-node above the
bottom
4: Dirichlet condition (5.399) at the bottom
nbcs Last dimension of the array bcsur

nbcb Last dimension of the array bcbot
bcsur Data for the surface boundary condition. The third index
determines the type of the data
1: prescribed surface flux or surface value
[psic] or [psic m/s]
2: transfer velocity [m/s]
bcbot Data for the bottom boundary condition. The third index
1: prescribed bottom flux or bottom value
[psic] or [psic m/s]
surface
Calling procedures
Zdif at U
SUBROUTINE Zdif at U(psiu,tridcfu,vdifcoefatuw,ibcsur,ibcbot,&
& nbcs,nbcb,bcsur,bcbot)
INTEGER, INTENT(IN) :: ibcbot, ibcsur, nbcb, nbcs
REAL, INTENT(INOUT), DIMENSION(ncloc,nrloc,nz,4) :: tridcfu
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nz+1) :: vdifcoefatuw
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nbcs) :: bcsur
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nbcb) :: bcbot
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Vertical diffusion term for the 3-D current u at the U-nodes
Reference
Sections 5.3.10 and 5.3.14
Arguments
tridcfu Tridiagonal matrix to store implicit and explicit terms
[m/s]
vdifcoefatuw Diffusion coefficient at the UW-nodes [m2 /s]
1: prescibed flux (Neumann) condition
2: Neumann condition using a transfer velocity (see equa-
tions (5.236), (5.238), (5.239))
[m2 /s2 ] or [m/s]
defines the type of the data
[m2 /s2 ] or [m/s]
Calling procedures
transport at U 3d
Zdif at V
SUBROUTINE Zdif at V(psiv,tridcfv,vdifcoefatvw,ibcsur,ibcbot,&
& nbcs,nbcb,bcsur,bcbot)
INTEGER, INTENT(IN) :: ibcbot, ibcbot, nbcb, nbcs

REAL, INTENT(INOUT), DIMENSION(ncloc,nrloc,nz,4) :: tridcfv
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nz+1) :: vdifcoefatvw
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Vertical diffusion term for the 3-D current v at the V-nodes
Reference
Arguments
tridcfv Tridiagonal matrix to store implicit and explicit terms
[m/s]
vdifcoefatvw Diffusion coefficient at the VW-nodes [m2 /s]
tions (5.237), (5.238), (5.240))
nbcs Last dimension of array bcsur
nbcb Last dimension of array bcbot
[m2 /s2 ] or [m/s]

[m2 /s2 ] or [m/s]
Calling procedures
transport at V 3d
Zdif at W
SUBROUTINE Zdif at W(psiw,tridcfw,vdifcoefatc,ibcsur,ibcbot,&
& bcsur,bcbot)
INTEGER, INTENT(IN) :: ibcbot, ibcsur
& 1-nhalo:nrloc+nhalo,nz+1)::psiw
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nz) :: vdifcoefatc
REAL, INTENT(IN), DIMENSION(ncloc,nrloc) :: bcbot, bcsur
File
Diffusion Terms.F90
Type
Subroutine
Purpose
Vertical diffusion term for a quantity at the W-nodes
Reference
Sections 5.6.3.3 and 5.6.6
Arguments
tridcfw Tridiagonal matrix to store implicit and explicit terms
[psiw]
vdifcoefatc Diffusion coefficient at the C-nodes [m2 /s]
1: prescibed (Neumann) flux at the surface (see equations

(5.472)–(5.474))
2: prescribed Neumann flux at the first C-node below the
surface (5.475)
4: Dirichlet condition (5.477) at the first W-node below
the surface
1: prescibed (Neumann) flux at the bottom (see equations
(5.478)–(5.480))
2: prescribed Neumann flux at the first C-node above the
bottom (5.481)
3: Dirichlet condition at the bottom (5.482)
4: Dirichlet condition at the first W-node above the bot-
tom (5.483)
bcsur Imposed surface flux or surface value
bcbot Imposed bottom flux or bottom value
Calling procedures
transport at W
22.9 Grid Arrays.F90

Ensemble of routines for setting up the model grid, definition of pointer
arrays and arrays for applying the open boundary conditions, update of the
water depths.
define global grid

SUBROUTINE define global grid
File
Grid Arrays.F90
Type
Subroutine
22.9. GRID ARRAYS.F90 705
Purpose
Define the global domain grid
Calling procedures
initialise model
define local grid

SUBROUTINE define local grid
File
Grid Arrays.F90
Type
Subroutine
Purpose
Define the coordinates and bathymetry of each local sub-domain.
Calling procedures
initialise model
depth at nodes
SUBROUTINE depth at nodes
File
Grid Arrays.F90
Type
Subroutine
Purpose
Interpolate mean water depths at different nodes
Calling procedures
initialise model
grid arrays
SUBROUTINE grid arrays
File
Grid Arrays.F90
Type
Subroutine
Purpose
Define the arrays related to the model grid at different nodes: grid
spacings in the horizontal and vertical, transformed vertical coordina-
tes, Coriolis frequency, acceleration of gravity.
Reference
Section 8.1.2.3
Calling procedures
initialise model
open boundary arrays

SUBROUTINE open boundary arrays
File
Grid Arrays.F90
Type
Subroutine
Purpose
Allocate and define the arrays at open boundaries: locations, index
mapping arrays, number of open sea and river boundaries on each local
sub-domain, arrays to store information for open boundary conditions.
Calling procedures
initialise model
pointer arrays
SUBROUTINE pointer arrays
File
Grid Arrays.F90
Type
Subroutine
Purpose
Cell pointers arrays at the different nodes, orientation of the cell faces
at open boundary locations.
22.9. GRID ARRAYS.F90 707
Reference
Section 8.1.2.4
Calling procedures
initialise model
read grid
SUBROUTINE read grid
File
Grid Arrays.F90
Type
Subroutine
Purpose
Read the model grid arrays, bathymetry and open boundary locations
from a file in standard COHERENS format.
Calling procedures
initialise model
store depths old

SUBROUTINE store depths old
File
Grid Arrays.F90
Type
Subroutine
Purpose
Store total dephts at the old (3-D) time level.
Calling procedures
coherens main, initialise physical arrays
water depths
SUBROUTINE water depths
File
Grid Arrays.F90
Type
Subroutine
Purpose
Update the total water depths at different nodes.

minimum depths
Calling procedures
default phsics, initialise model, initialise model, surface elevation,
update 1dsur data
write grid
SUBROUTINE write grid
File
Grid Arrays.F90
Type
Subroutine
Purpose
Write the model grid arrays, bathymetry and open boundary locations
to a file in standard COHERENS format.
Calling procedures
initialise model
22.10 Harmonic Analysis.f90

Routines for performing harmonic analysis and writing harmonic data.
22.10. HARMONIC ANALYSIS.F90 709
ellips params
FUNCTION ellips params(uacoef,vacoef,ubcoef,vbcoef)
REAL, INTENT(IN) :: uacoef, ubcoef, vacoef, vbcoef
REAL, DIMENSION(7) :: ellips params
File
Harmonic Analysis.f90
Type
Function
Purpose
Parameters of tidal ellipses
Reference
Section 4.12.2
Arguments
uacoef Coefficient of the cosine-term in the harmonic expansion
for the X-component of the current vector
vacoef Coefficient of the cosine-term in the harmonic expansion
for the Y-component of the current vector
ubcoef Coefficient of the sine-term in the harmonic expansion for
the X-component of the current vector
vbcoef Coefficient of the sine-term in the harmonic expansion for
the Y-component of the current vector
Calling procedures
harmonic analysis data
harmonic analysis
SUBROUTINE harmonic analysis
File
Type
Subroutine
Purpose
Base program unit for performing harmonic analysis
Reference
Section 4.12.1
harmonic analysis data, harmonic analysis grid, harmonic analysis init,
harmonic analysis reset, harmonic analysis update
Calling procedures
coherens main
harmonic analysis data

SUBROUTINE harmonic analysis data
File
Type
Internal subroutine
Purpose
Solve the linear system of equations (4.390), evaluate residuals, am-
plitudes, phases and elliptic parameters and write the results to the
output files where requested
Reference
Section 4.12.1
Calling procedures
harmonic analysis
harmonic analysis grid

SUBROUTINE harmonic analysis grid
File
Type
Internal subroutine
Purpose
Write the coordinates of the output grid to the data file
Calling procedures
harmonic analysis
22.10. HARMONIC ANALYSIS.F90 711
harmonic analysis init

SUBROUTINE harmonic analysis init
File
Type
Internal subroutine
Purpose
Define the arrays for the setup of harmonic analysis and data output.
Write the metadata to the data file. Set up the matrices for solving
the linear systems (4.390)–(4.391)
Reference

usrdef anal freqs, usrdef anal params
Calling procedures
harmonic analysis
harmonic analysis reset

SUBROUTINE harmonic analysis reset
File
Type
Internal subroutine
Purpose
Initialise buffers for storing temporary data
Calling procedures
harmonic analysis
harmonic analysis update

SUBROUTINE harmonic analysis update
File
Type
Internal subroutine
Purpose
Update the sums Rm and Sm defined by equations( 4.395) and (4.396).
Reference
Section 4.12.1

usrdef anal0d vals, usrdef anal2d vals, usrdef anal3d vals
Calling procedures
harmonic analysis
22.11 Hydrodynamic Equations.F90

Update all hydrodynamic parameters (2-D transports, water elevations, 3-D
currents) by solving the 2-D and 3-D momentum and continuity equations.
current corr
SUBROUTINE current corr
File
Hydrodynamic Equations.F90
Type
Subroutine
Purpose
Solve the 3-D momentum equations at the corrector step.
Reference
Section 5.3.1.3
22.11. HYDRODYNAMIC EQUATIONS.F90 713

bottom stress, current corr 1d, define profobc spec,
open boundary conds 3d, physical vertical current, relaxation at U,
relaxation at V, surface stress, transf vertical current,
update nest data 3d, update profobc data
Calling procedures
hydrodynamic equations, initialise model
current corr 1d
SUBROUTINE current corr 1d
File
Type
Subroutine
Purpose
Evaluate the depth-mean and depth-integrated currents in case of a
1-D water column application.

bottom stress, surface stress
Calling procedures
current corr
current pred
SUBROUTINE current pred
File
Type
Subroutine
Purpose
Solve the 3-D momentum equations (4.50) and (4.51) for u and v at
the predictor step.
Reference
Sections 4.2.1.2 and 5.3.1.1

transport at U 3d, transport at V 3d, update 1dsur data
Calling procedures
hydrodynamic equations
current 2d
SUBROUTINE current 2d
File
Type
Subroutine
Purpose
Solve the 2-D momentum and continuity equations (4.74)–(4.76) for ζ,
U, V .
Reference
Sections 4.2.2, 5.3.1.2 and 5.3.2.2

bottom stress, open boundary conds 2d, surface elevation, sur-
face stress, transport at U 2d, transport at V 2d, update nest data 2d,
update 2dobc data
Calling procedures
SUBROUTINE hydrodynamic equations
File
Type
Subroutine
22.11. HYDRODYNAMIC EQUATIONS.F90 715
Purpose
Base program unit for solving the hydrodynamic equations
current corr, current pred, current 2d
Calling procedures
coherens main
physical vertical current

SUBROUTINE physical vertical current
File
Type
Subroutine
Purpose
Update the physical vertical current w using the discretised equa-
tion (5.28).
Reference
Sections 4.2.1.2 and 5.3.1.4
Calling procedures
current corr
surface elevation
SUBROUTINE surface elevation
File
Type
Subroutine
Purpose
Solve the 2-D continuity equation (4.74) for the surface elevation ζ
using the discretised form (5.12).
Reference
Sections 4.2.2 and 5.3.1.2

drying factor, water depths
Calling procedures
current 2d
transf vertical current

SUBROUTINE transf vertical current
File
Type
Subroutine
Purpose
Solve the baroclinic continuity equation (4.91) for the (transformed)
vertical current ω using the discretised form (5.27).
Reference
Sections 4.2.2 and 5.3.1.4
Calling procedures
current corr
22.12 Inundation Schemes.f90

Routines used by the drying/wetting and flooding algorithms.
drying factor
SUBROUTINE drying factor
File
Inundation Schemes.f90
Type
Subroutine
Purpose
Update the α-factor used by the drying/wetting algorithm.
22.12. INUNDATION SCHEMES.F90 717
Reference
Section 5.4.1 and equation (5.318)
Calling procedures
surface elevation
mask function
SUBROUTINE mask function
File
Type
Subroutine
Purpose
Evaluate the mask criteria for the flooding scheme, reset the pointer
arrays and set the currents to zero at blocked velocity nodes.
Reference
Section 5.4.2 and equations (5.323)–(5.334)
Calling procedures
coherens main
minimum depths
SUBROUTINE minimum depths
File
Type
Subroutine
Purpose
Evaluate the minimum depth criteria (5.319)–(5.321).
Reference
Section 5.4.1
Calling procedures
water depths
22.13 Model Finalisation.f90

Perform all actions used for finalisation of a simulation (writing of initial
conditions, timer report, resetting of all model parameters to their defaults,
deallocation of all allocated arrays, closing of all file connections, closing the
program after the last simulation).
coherens end
SUBROUTINE coherens end
File
Model Finalisation.f90
Type
Subroutine
Purpose
Finalise the program after execution of all simulations. This is the last
routine called by the program after closing the defruns file.
Reference
Section 10.2.5
Calling procedures
coherens main
simulation end
SUBROUTINE simulation end
File
Type
Subroutine
Purpose
Finalise the current simulation before starting an eventual new one.
Reference
Section 10.2.5
22.13. MODEL FINALISATION.F90 719

allocate mod arrays, deallocate mod arrays, timer report
Calling procedures
coherens main
timer report
SUBROUTINE timer report
File
Type
Subroutine
Purpose
Write the timer report file.
Reference
Section 7.3.4
Calling procedures
simulation end
write phsics
SUBROUTINE write phsics
File
Type
Subroutine
Reference
Table 7.3
Purpose
Write the physical initial conditions to a file in standard COHERENS
format.
Calling procedures
coherens main
22.14 Model Initialisation.F90

Start-up of the program and initialisation of a simulation.
coherens start
SUBROUTINE coherens start
File
Model Initialisation.F90
Type
Subroutine
Purpose
Start-up procedure of the program beforing execution of the first sim-
ulation. This is the first routine called by the main program before
opening the defruns file.
Calling procedures
coherens main
default grid
SUBROUTINE default grid
File
Type
Subroutine
Purpose
Set the default bathymetry using uniform water depths.
Calling procedures
initialise model
default phsics
SUBROUTINE default phsics
File
22.14. MODEL INITIALISATION.F90 721
Type
Subroutine
Reference
Section 4.11
Purpose
Set the default initial conditions.

init turbulence, mixing length, water depths
Calling procedures
initialise model
exchange phsics
SUBROUTINE exchange phsics
File
Type
Subroutine
Purpose
Perform exchange communications which store the initial conditions
into the respective halos.
Calling procedures
initialise model
initialise model
SUBROUTINE initialise model
File
Type
Subroutine
Purpose
Ensemble of routine calls for initialisation of a simulation
Reference
Section 10.2.2

allocate bio arrays, allocate global grid, allocate mod arrays, as-
tronomical tides, biological model, bottom stress, current corr,
default grid, default phsics, define global grid, define local grid,
define rlxobc spec, depth at nodes, domain decomposition,
equation of state, exchange phsics, grid arrays, harmonical analysis,
heat flux, initialise physical arrays, meteo input, nest locations,
open boundary arrays, pointer arrays, read bioics, read cif mod params,
read grid, read phsics, relaxation weights, salinity equation,
set procnums, set workers comm, surface stress, temperature equation,
time averages, time series, update nest data 2d, update 1dsur data,
update 2dobc data, usrdef bioics, usrdef bio params, usrdef grid,
usrdef mod params, usrdef output, usrdef phsics, water depths,
write bioics, write cif mod params, write grid, write phsics
Calling procedures
coherens main
initialise physical arrays

SUBROUTINE initialise physical arrays
File
Type
Subroutine
Purpose
Initialise a series of arrays, not obtained from the initial conditions file.
Calling procedures
initialise model
read phsics
SUBROUTINE read phsics
File
22.15. MODEL PARAMETERS.F90 723
Type
Subroutine
Purpose
Read the physical initial conditions from a file in standard COHERENS
format.
Reference
Table 7.3
Calling procedures
initialise model
simulation start
SUBROUTINE simulation start(next simul)
LOGICAL, INTENT(OUT) :: next simul
File
Type
Subroutine
Purpose
Read the title of the next simulation from the defruns file and define
the parameters for monitoring.
Arguments
next simul .TRUE. to start the next simulation, .FALSE. to exit the
program

usrdef init params
Calling procedures
coherens main
22.15 Model Parameters.f90

Read/write model setup parameters from/to a central input file (CIF).
assign cif vars

SUBROUTINE assign cif vars(iddesc,cname,cvals,numvars)
CHARACTER (LEN=lenname), INTENT(IN) :: cname
CHARACTER (LEN=lencifvar), INTENT(IN), DIMENSION(MaxCIFvars) :: cvals
INTEGER, INTENT(IN) :: iddesc, numvars
File
Model Parameters.F90
Type
Subroutine
Purpose
Convert a data string from a CIF input line to the appropriate numer-
ical, logical or character values of the corresponding model variables.
Reference
Section 7.4
Arguments
iddesc Key id of the CIF
cname Variable name(s)
cvals Data values in string format
numvars Number of model variables
Calling procedures
read cif mod params
read cif mod params

SUBROUTINE read cif mod params(iddesc,fass)
LOGICAL, INTENT(IN) :: fass
INTEGER, INTENT(IN) :: iddesc
File
Model Parameters.F90
Type
Subroutine
Purpose
General routines for reading a CIF. The actual data conversion is made
by calling read cif line and assign cif vars.
22.16. NESTED GRIDS.F90 725
Reference
Section 7.4
Arguments
fass File will be read with/without data assignment if .TRUE./.FALSE.
Calling procedures
harmonic analysis, harmonic analysis init, initialise model, simula-
tion start, time averages, time averages init, time series, time series init
write cif mod params

SUBROUTINE write cif mod params(iddesc)
File
Model Parameters.f90
Type
Subroutine
Purpose
Write the CIF for physical model setup.
Reference
Section 7.4
Arguments
Calling procedures
initialise model
22.16 Nested Grids.F90

Ensemble of routines for the definition of nested sub-grids, interpolation to
sub-grid locations and writing to the appropriate output files.
define nstgrd locs

SUBROUTINE define nstgrd locs(iset,nhdat,nzdat,nonodes,&
& hnests,zcoord,cnode)
CHARACTER (LEN=lennode), INTENT(IN) :: cnode
TYPE (HRelativeCoords), INTENT(OUT),&
& DIMENSION(nhdat,nonodes) :: hnests
File
Nested Grids.F90
Type
Subroutine
Purpose
Define the open boundary locations of all nested sub-grids. Absolute
coordinates are converted into relative ones if necessary.
Reference
Sections 8.5 and 15.3
Arguments
iset Index of the nested sub-grid
nhdat Number of sub-grid open boundary locations
nzdat Number of vertical levels
nonodes The number of nodes for which relative coordinates need
to be defined. Value is either 1 or 2.
hnests Relative coordinates of the sub-grid open boundary loca-
tions
zcoord Z-coordinates of the sub-grid open boundary locations
cnode Nodal type of the open boundary locations (‘C’, ‘U’, ‘V’)

read nstgrd abs, read nstgrd rel, usrdef nstgrd abs, usrdef nstgrd rel,
write nstgrd abs, write nstgrd rel
Calling procedures
nest locations
define nstgrd spec

SUBROUTINE define nstgrd spec
File
Nested Grids.F90
Type
Subroutine
Purpose
General specifications of all sub-grid nests (number of sub-grid open
boundary locations, number of vertical levels, type of required data)
Reference
Sections 8.5 and 15.3.1

read nstgrd spec, usrdef nstgrd spec, write nstgrd spec
Calling procedures
nest locations
nest locations
SUBROUTINE nest locations
File
Nested Grids.F90
Type
Subroutine
Purpose
Define the positions (in relative coordinates) of all open boundary lo-
cations on each sub-grid nest and a series of associated arrays.
Reference
Sections 8.5

define nstgrd locs, define nstgrd spec
Calling procedures
initialise model
read nstgrd abs

SUBROUTINE read nstgrd abs(iset,nhdat,nzdat,xcoord,ycoord,zcoord)
File
Nested Grids.F90
Type
Subroutine
Purpose
Read the absolute coordinates of the open boundary locations on a
sub-grid from a file in standard COHERENS format.
Reference
Section 15.3.2
Arguments
nhdat Number of open boundary locations on the sub-grid
xcoord X-coordinates of the sub-grid data points
[meters or longitude]
ycoord Y-coordinates of the sub-grid data points
[meters or latitude]
zcoord Z-coordinates of the sub-grid locations, defined as the posi-
tive distance to the mean water level (only when nzdat>0)
[m]
Calling procedures
define nstgrd locs
read nstgrd rel

SUBROUTINE read nstgrd rel(iset,nhdat,nzdat,nonodes,hnests,zcoord)
File
Nested Grids.F90
Type
Subroutine
Purpose
Read the relative coordinates of the open boundary locations on a sub-
grid from a file in standard COHERENS format.
Reference
Section 15.3.3
Arguments
nonodes Number of nodes for which relative coordinates need to be
provided. Its value equals 1 or 2 depending on the value
of cnode.
hnests Relative coordinates of the sub-grid data points
[m]
Calling procedures
define nstgrd locs
read nstgrd spec

SUBROUTINE read nstgrd spec
File
Nested Grids.F90
Type
Subroutine
Purpose
Read the general specifications of all sub-grid nests (number of sub-grid
open boundary locations, number of vertical levels, type of required
data) from a file in standard COHERENS format.
Reference
Section 15.3.1
Calling procedures
define nstgrd spec
update nest data prof

SUBROUTINE update nest data prof(psic,novars,novarsnst,instvars,iddesc)
INTEGER, INTENT(IN) :: iddesc, novars
INTEGER, INTENT(IN), DIMENSION(nonestsets) :: novarsnst
INTEGER, INTENT(IN), DIMENSION(novars,nonestsets) :: instvars
File
Nested Grids.F90
Type
Subroutine
Purpose
Interpolate 3-D scalar profile data from the model grid to the appropri-
ate open boundaries of each nested sub-grid and write the interpolated
data to the appropriate file(s).
Arguments
psic C-node scalar quantity used for the nesting
novars Total number of “state” variables (currently 1)
novarsnst Total number of “state” variables to be nested per sub-grid
(currentlty 1)
instvars Indices of the variables to be nested (currently 1)
iddesc Key id of the corresponding output file(s)

write nest data prof
Calling procedures
salinity equation, temperature equation
update nest data 2d

SUBROUTINE update nest data 2d
File
Nested Grids.F90
Type
Subroutine
Purpose
Interpolate 2-D model data (transports and/or elevations) from the
model grid to the appropriate open boundaries of each nested sub-grid
and write the interpolated data to the appropriate file(s).
Calling procedures
current 2d, initialise model
update nest data 3d

SUBROUTINE update nest data 3d
File
Nested Grids.F90
Type
Subroutine
Purpose
Interpolate 3-D baroclinic current data from the model grid to the
appropriate open boundaries of each nested sub-grid and write the in-
terpolated data to the appropriate file(s).

Calling procedures
current corr

SUBROUTINE write nest data prof(iddesc,iset,outvals,maxstats,nzdat,&
& nonst,nhdatloc,nostatsglb,nhdatprocs,&
& indexprocs)
INTEGER, INTENT(IN) :: iddesc, iset, maxstats, nhdatloc, nonst, nostatsglb, &

& nzdat
INTEGER, INTENT(IN), DIMENSION(nprocs) :: nhdatprocs
INTEGER, INTENT(IN), DIMENSION(nprocs,maxstats) :: indexprocs
REAL, INTENT(IN), DIMENSION(nhdatloc,nzdat,nonst) :: outvals
File
Nested Grids.F90
Type
Subroutine
Purpose
Write 3-D scalar data interpolated at a specific sub-grid to a file in
standard COHERENS format.
Arguments
iddesc Key id of the corresponding output file(s)
iset Index (file number) of the nested sub-grid
outvals Output data
maxstats Second dimension of the array indexprocs
nzdat Number of data points in the vertical
nonst Number of “state” variables to be nested (currently 1)
nhdatloc Number of output locations in the horizontal on the local
domain grid
nostatsglb Number of output locations on the global grid
nhdatprocs Number of output locations per process
indexprocs Index mapping array (see Section 9.5)
Calling procedures
update nest data prof
write nest data 2d

SUBROUTINE write nest data 2d(iset,ivar,outvals,maxstats,nhdatloc,&
& nostatsglb,nhdatprocs,indexprocs)
INTEGER, INTENT(IN) :: iset, ivar, maxstats, nhdatloc, nostatsglb
REAL, INTENT(IN), DIMENSION(nhdatloc) :: outvals
File
Nested Grids.F90
Type
Subroutine
Purpose
Write the 2-D data interpolated at a specific sub-grid to a file in stan-
dard COHERENS format.
Arguments
ivar (netCDF) Id of the variable within the file
outvals Output data
domain grid
Calling procedures
update nest data 2d
write nest data 3d

SUBROUTINE
write nest data prof(iset,outvals,maxstats,nzdat,nhdatloc,&
& nostatsglb,nhdatprocs,indexprocs)
INTEGER, INTENT(IN) :: iset, maxstats, nhdatloc, nostatsglb, nzdat
REAL, INTENT(IN), DIMENSION(nhdatloc,nzdat,nonst) :: outvals
File
Nested Grids.F90
Type
Subroutine
Purpose
Write 3-D baroclinic current data interpolated at a specific sub-grid to
a file in standard COHERENS format.
Arguments
outvals Output data
nzdat Number of data points in the vertical
domain grid
Calling procedures
update nest data 3d
write nstgrd abs

SUBROUTINE write nstgrd abs(iset,nhdat,nzdat,xcoord,ycoord,zcoord)
REAL, INTENT(IN), DIMENSION(nhdat) :: xcoord, ycoord
REAL, INTENT(IN), DIMENSION(nhdat,nzdat) :: zcoord
File
Nested Grids.F90
Type
Subroutine
Purpose
Write the absolute coordinates of the open boundary locations on a
sub-grid to a file in standard COHERENS format.
Reference
Section 15.3.2
Arguments

[m]
Calling procedures
define nstgrd locs
write nstgrd rel

SUBROUTINE write nstgrd rel(iset,nhdat,nzdat,nonodes,hnests,zcoord)
REAL, INTENT(IN), DIMENSION(nhdat,nzdat) :: zcoord
File
Nested Grids.F90
Type
Subroutine
Purpose
Write the relative coordinates of the open boundary locations on a
sub-grid to a file in standard COHERENS format.
Reference
Section 15.3.3
Arguments
nonodes Number of nodes for which relative coordinates need to be
provided. Its value equals 1 or 2 depending on the value
of cnode.
hnests Relative coordinates of the sub-grid data points

[m]
Calling procedures
define nstgrd locs
write nstgrd spec

SUBROUTINE write nstgrd spec
File
Nested Grids.F90
Type
Subroutine
Purpose
Write the general specifications of all sub-grid nests (number of sub-
grid open boundary locations, number of vertical levels, type of required
data) to a file in standard COHERENS format.
Reference
Section 15.3.1
Calling procedures
define nstgrd spec
22.17 Open Boundary Conditions.f90

Apply open boundary conditions for the 2-D and 3-D case.
open boundary conds prof

SUBROUTINE open boundary conds prof(psi,psiobu,psiobv,obcdata,&
& obcpsiatu,obcpsiatv,itypobu,&
& itypobv,iprofobu,iprofobv,&
& noprofs,novars)
INTEGER, INTENT(IN) :: noprofs, novars
INTEGER, INTENT(IN), DIMENSION(nobu) :: itypobu
INTEGER, INTENT(IN), DIMENSION(nobv) :: itypobv
22.17. OPEN BOUNDARY CONDITIONS.F90 737

& 1-nhalo:nrloc+nhalo,nz,novars) :: psi
REAL, INTENT(INOUT), DIMENSION(nobu,nz,novars) :: psiobu
REAL, INTENT(INOUT), DIMENSION(nobv,nz,novars) :: psiobv
REAL, INTENT(IN), DIMENSION(0:noprofs,nz,novars) :: obcdata
REAL, INTENT(INOUT), DIMENSION(nobu,nz,novars,0:2) :: obcpsiatu
REAL, INTENT(INOUT), DIMENSION(nobv,nz,novars,0:2) :: obcpsiatv
File
Open Boundary Conditions.f90
Type
Subroutine
Purpose
Apply the open open boundary conditions for a 3-D scalar C-node
quantity.
Reference
Section 4.10.2.1, 5.5.7.3 and 14.2.1
Arguments
psi C-node scalar quantity defined on the 3-D model grid
psiobu Returned values of the scalar quantity at West/East open
boundaries. The data are flagged if a zero gradient condi-
tion is applied at the open boundary location.
psiobv Returned values of the scalar quantity at South/North
open boundaries. The data are flagged if a zero gradient
condition is applied at the open boundary location.
obcdata Time-interpolated external data profiles. A zero gradient
condition is substituted for data which are flagged.
obcpsiatu Storage array in case the open boundary condition at the
U-nodes uses values from previous time steps
obcpsiatv Storage array in case the open boundary condition at the
V-nodes uses values from previous time steps
itypobu Type of open boundary condition at the U-nodes
0: External data profile or zero gradient condition

itypobv Type of open boundary condition at the V-nodes
0: External data profile or zero gradient condition
iprofobu Profile number at the U-nodes for each data variable. If
set to zero, the type of condition is determined by the
value of itypobu.
iprofobv Profile number at the V-nodes for each data variable. If
value of itypobv.
noprofs Number of data profiles
novars Number of C-node variables (currently 1)
Calling procedures
open boundary conds 2d

SUBROUTINE open boundary conds 2d
File
Type
Subroutine
Purpose
Apply the open boundary conditions for the 2-D mode.
Reference
Sections 4.10.1, 5.3.15.1 and 14.1
Calling procedures
current 2d
open boundary conds 3d

SUBROUTINE open boundary conds 3d(psiobu,psiobv,obcdata,itypobu,itypobv,&
& iprofobu,iprofobv,noprofs)
22.17. OPEN BOUNDARY CONDITIONS.F90 739
INTEGER, INTENT(IN) :: noprofs

INTEGER, INTENT(IN), DIMENSION(nobu) :: itypobu, iprofobu
INTEGER, INTENT(IN), DIMENSION(nobv) :: itypobv, iprofobv
REAL, INTENT(INOUT), DIMENSION(nobu,nz) :: psiobu
REAL, INTENT(INOUT), DIMENSION(nobv,nz) :: psiobv
REAL, INTENT(IN), DIMENSION(0:noprofs,nz) :: obcdata
File
Type
Subroutine
Purpose
Apply the open open boundary conditions for the 3-D baroclinic cur-
rent.
Reference
Sections 4.10.2.1, 5.3.16.1 and 14.2.1
Arguments
psiobu Returned values of the baroclinic current at West/East
condition is applied without external data.
psiobv Returned values of the baroclinic current at South/North
condition is applied without external data.
obcdata Time-interpolated external data profiles. A zero gradient
condition is substituted for data which are flagged.
itypobu Type of open boundary condition at the U-nodes
0: External data profile or first order zero gradient condi-
tion
2: Local solution
itypobv Type of open boundary condition at the V-nodes
0: External data profile or first order zero gradient condi-
tion

2: Local solution
iprofobu Profile number at the U-nodes. If set to zero, the type of
condition is determined by the value of itypobu.
iprofobv Profile number at the V-nodes. If set to zero, the type of
condition is determined by the value of itypobv.
noprofs Number of data profiles
Calling procedures
current corr
22.18 Open Boundary Data Prof.f90

Open boundary profile data for baroclinic currents and 3-D scalars.
define profobc data

SUBROUTINE define profobc data(iddesc,ifil,ciodatetime,psiprofdat,&
& numprofs)
File
Open Boundary Data Prof.f90
Type
Subroutine
Purpose
Define open boundary profiles.
Reference
Section 14.2.2
Arguments
iddesc Key id of the corresponding forcing data file
ifil File index of the data file
22.18. OPEN BOUNDARY DATA PROF.F90 741
ciodatetime Returned date and time of the data

psiprofdat Returned profile data
numprofs Number of profiles in the data file

read profobc data, usrdef profobc data, write profobc data
Calling procedures
update profobc data
define profobc spec

SUBROUTINE define profobc spec(iddesc,itypobu,itypobv,iprofobu,&
& iprofobv,iprofrlx,noprofsd,indexprof,&
& indexvar,novars,nofiles)
INTEGER, INTENT(INOUT), DIMENSION(nobu) :: itypobu
INTEGER, INTENT(INOUT), DIMENSION(nobv) :: itypobv
File
Type
Subroutine
Purpose
Provide the information needed for applying the open boundary con-
ditions for a 3-D quantity (baroclinic current, C-node scalar): type
of condition, profile number of each open boundary point, number of
profiles in each data file and index mapping arrays used to locate the
profiles and variables within each data file.
Reference
Arguments

itypobu Type of open boundary condition at the U-nodes (see Sec-
tion 14.2.1.1)
itypobv Type of open boundary condition at the V-nodes (see Sec-
tion 14.2.1.1)
value of itypobu.
value of itypobv.
iprofrlx Disables/enables relaxation in “relaxation” areas.
noprofsd Number of profiles per data file
indexprof Mapping array of the profile numbers in the data files to
the profile numbers assigned to the open boundaries. The
physical size of the first dimension equals the number of
profiles in a data file.
indexvar Defines the variable number of the profiles in a data file.
The physical size of the first dimension equals the number
of profiles in a data file.
novars Total number of (scalar) variables. Value in the current
implementation is 1.
nofiles Number of data files (minus 1)

read profobc spec, usrdef profobc spec, write profobc spec
Calling procedures
current corr, salinity equation, temperature equation
read profobc data

SUBROUTINE read profobc data(iddesc,ifil,ciodatetime,psiprofdat,numprofs)
CHARACTER (LEN=lentime), INTENT(OUT) :: ciodatetime
REAL, INTENT(OUT), DIMENSION(numprofs,nz) :: psiprofdat
File
Type
Subroutine
Purpose
Read the open boundary profile data in standard COHERENS format.
Reference Section 14.2.2
Arguments
psiprofdat Returned profile data
Calling procedures
define profobc data
read profobc spec

SUBROUTINE read profobc spec(iddesc,itypobu,itypobv,iprofobu,&
File
Type
Subroutine
Purpose
Read the information needed for applying the open boundary condi-
tions for a 3-D quantity (baroclinic current, C-node scalar) from a file
in standard COHERENS format: type of condition, profile number of

each open boundary point, number of profiles in each data file and in-
dex mapping array used to locate the profiles and variables within each
data file.
Reference
Arguments
tion 14.2.1.1)
tion 14.2.1.1)
value of itypobu.
value of itypobv.
novars Total number of (scalar) variables. Value is 1 in the cur-
rent implementation.
Calling procedures
define profobc spec
update profobc data

SUBROUTINE update profobc data(profdata,obcdata,noprofsd,indexprof,&
& indexvar,maxprofs,noprofs,novars,&
& nofiles,nosecsdat,iddesc)
INTEGER, INTENT(IN) :: iddesc, maxprofs, nofiles, noprofs, novars
INTEGER, INTENT(IN) , DIMENSION(2:nofiles) :: noprofsd
INTEGER, INTENT(IN), DIMENSION(maxprofs,2:nofiles) :: indexprof
INTEGER, INTENT(IN), DIMENSION(maxprofs,2:nofiles) :: indexvar
INTEGER (KIND=kndilong), INTENT(INOUT),&
& DIMENSION(2:nofiles,2) :: nosecsdat
REAL, INTENT(INOUT), DIMENSION(maxprofs,nz,2:nofiles,2) :: profdata
REAL, INTENT(INOUT), DIMENSION(0:noprofs,nz,novars) :: obcdata
File
Type
Subroutine
Purpose
Update the open boundary profile data by reading new data (if needed).
Interpolate at the current simulation time (if requested).
Reference
Section 10.2.4
Arguments
profdata Profile data at the latest time earlier than the current
date/time and at the earliest time later than the current
date/time
obcdata Returned profile arrays interpolated at the current simu-
lation time
maxprofs Maximum number of profiles in any data file
noprofs Total number of profiles
novars Total number of variables. Value is 1 in the current im-

plementation.
nosecsdat Number of seconds since the start of the simulation and
the latest data time earlier than the current time and the
earliest data time later than the current time

define profobc data
Calling procedures
current corr, salinity equation, temperature equation
write profobc data

SUBROUTINE write profobc data(iddesc,ifil,ciodatetime,psiprofdat,numprofs)
CHARACTER (LEN=lentime), INTENT(IN) :: ciodatetime
REAL, INTENT(IN), DIMENSION(numprofs,nz) :: psiprofdat
File
Type
Subroutine
Purpose
Write the open boundary profile data in standard COHERENS format.
Reference Section 14.2.2
Arguments
ciodatetime Date and time of the data
psiprofdat Profile data
Calling procedures
define profobc data
write profobc spec

SUBROUTINE write profobc spec(iddesc,itypobu,itypobv,iprofobu,&
INTEGER, INTENT(IN), DIMENSION(2:nofiles) :: noprofsd
INTEGER, INTENT(IN), DIMENSION(novars*(nobu+nobv),2:nofiles) :: indexprof
INTEGER, INTENT(IN), DIMENSION(novars*(nobu+nobv),2:nofiles) :: indexvar
INTEGER, INTENT(IN), DIMENSION(norlxzones) :: iprofrlx
File
Type
Subroutine
Purpose
Write the information needed for applying the open boundary condi-
tions for a 3-D quantity (baroclinic current, C-node scalar) to a file in
standard COHERENS format: type of condition, profile number of each
open boundary point, number of profiles in each data file and index
mapping array used to locate the profiles and variables within each
data file.
Reference
Arguments
tion 14.2.1.1)
tion 14.2.1.1)
value of itypobu.

value of itypobv.
novars Total number of (scalar) variables. Value is 1 in the cur-
rent implementation.
Calling procedures
define profobc spec
22.19 Open Boundary Data 2D.f90

Open boundary data for the 2-D mode.
define 2dobc data

SUBROUTINE define 2dobc data(ifil,ciodatetime,data2d,nodat,novars)
File
Open Boundary Data 2D.f90
Type
Subroutine
Purpose
Define open boundary data for the 2-D mode.
Reference
Section 14.1.2
22.19. OPEN BOUNDARY DATA 2D.F90 749
Arguments
data2d Returned open boundary data
nodat Number of open boundary locations in the data file
novars Number of data variables in the data file
read 2dobc data, usrdef 2dobc data, write 2dobc data
Calling procedures
update 2dobc data
define 2dobc spec

SUBROUTINE define 2dobc spec
File
Type
Subroutine
Purpose
Provide information for applying 2-D open boundary conditions: type
of conditions, location of the 2-D data in the data files, amplitudes and
phases in case an harmonic expansion is used.
Reference
Section 14.1.1
read 2dobc spec, usrdef 2dobc spec, write 2dobc spec
Calling procedures
update 2dobc data
read 2dobc data

SUBROUTINE read 2dobc data(ifil,ciodatetime,data2d,nodat,novars)
CHARACTER (LEN=lentime), INTENT(OUT) :: ciodatetime
File
Type
Subroutine
Purpose
Read the 2-D open boundary data from a file in COHERENS standard
format.
Reference
Section 14.1.2
Arguments
data2d Returned input data
novars Number of data variables in the data file (1 or 2)
Calling procedures
define 2dobc data
read 2dobc spec

SUBROUTINE read 2dobc spec
File
Type
Subroutine
Purpose
Read the arrays which specify the type of condition and data, the
location of the 2-D data within the data files, the amplitudes and phases
in case of an harmonic expansion is used. The file is read in standard
COHERENS format.
Reference
Section 14.1.1
Calling procedures
define 2dobc spec
22.19. OPEN BOUNDARY DATA 2D.F90 751
update 2dobc data

SUBROUTINE update 2dobc data
File
Type
Subroutine
Purpose
Update the 2-D open boundary data by reading new data (if needed).
Interpolate at the current simulation time. Update the harmonic ex-
pansions (where needed) for U , V , ζ.
Reference
Section 10.2.4

astro params, define 2dobc data, define 2dobc spec
Calling procedures
current 2d, initialise model
write 2dobc data

SUBROUTINE write 2dobc data(ifil,ciodatetime,data2d,nodat,novars)
REAL, INTENT(IN), DIMENSION(nodat,novars) :: data2d
File
Type
Subroutine
Purpose
Write the 2-D open boundary data to a file in COHERENS standard
format.
Arguments
data2d Output data

novars Number of data variables in the data file (1 or 2)
Calling procedures
define 2dobc data
write 2dobc spec

SUBROUTINE write 2dobc spec
File
Type
Subroutine
Purpose
Write the arrays which specify the type of condition and data, the
location of the 2-D data within the data files, the amplitudes and phases
in case of an harmonic expansion is used. The file is written in standard
COHERENS format.
Reference
Section 14.1.1
Calling procedures
define 2dobc spec
22.20 Parallel Initialisation.f90

Initialisation procedures for parallel applications.
define halo comms

SUBROUTINE define halo comms
File
Parallel Initialisation.f90
Type
Subroutine
22.20. PARALLEL INITIALISATION.F90 753
Purpose
Define the setup for exchange communications
Reference
Section 9.4.3.2
Calling procedures
domain coords
SUBROUTINE domain coords
File
Type
Subroutine
Purpose
Define the domain indices of each sub-domain in the decomposition.
Reference
Section 9.2.1
Calling procedures
SUBROUTINE domain decomposition
File
Type
Subroutine
Purpose
Create a domain decomposition for parallel applications.
Reference
Section 9.2.1

define halo comms, domain coords, read partition, regular partition,
usrdef partition, write partition
Calling procedures
initialise model
read partition
SUBROUTINE read partition
File
Type
Subroutine
Purpose
Read the arrays defining the domain decomposition from a file in stan-
Reference
Section 9.2.1
Calling procedures
regular partition
SUBROUTINE regular partition
File
Type
Subroutine
Purpose
Define a “simple” domain decomposition using a partitioning into
nprocsx*nprocsy sub-domains.
Calling procedures
22.20. PARALLEL INITIALISATION.F90 755
set domain dims

SUBROUTINE set domain dims(np,npx,npy)
INTEGER, INTENT(IN) :: np
INTEGER, INTENT(INOUT) :: npx, npy
File
Type
Subroutine
Purpose
Define the dimensions nprocxs, nprocsy of the domain decomposition in
case they are not supplied by the user.
Reference
Section 9.2.1
Arguments
np Number of processes
npx Returned X-dimension of the decomposition
npy Returned Y-dimension of the decomposition
Calling procedures
set procnums
set procnums
SUBROUTINE set procnums
File
Type
Subroutine
Purpose
Define the values of nprocs, nprocsx, nprocsy.
Reference
Section 9.2.1

set domain dims
Calling procedures
initialise model
set workers comm

SUBROUTINE set workers comm
File
Type
Subroutine
Purpose
Separate active from idle processes. Define the comm work communi-
cator for all active processes.
Calling procedures
initialise model
write partition
SUBROUTINE write partition
File
Type
Subroutine
Purpose
Write the arrays defining the domain decomposition to a file in standard
COHERENS format.
Reference
Section 9.2.1
Calling procedures
22.21. RELAXATION ZONES.F90 757
22.21 Relaxation Zones.f90

Routines for application of the relaxation scheme at open boundaries
define rlxobc spec

SUBROUTINE define rlxobc spec
File
Relaxation Zones.f90
Type
Subroutine
Purpose
Define the zones for application of the open boundary relaxation scheme.
Reference
Section 14.3
read rlxobc spec, usrdef rlxobc spec, write rlxobc spec
Calling procedures
initialise model
read rlxobc spec

SUBROUTINE read rlxobc spec
File
Type
Subroutine
Purpose
Read the arrays which define the areas for application of the open
boundary relaxation scheme from a file in standard COHERENS format.
Reference
Section 14.3
Calling procedures
define rlxobc spec
relaxation at C
SUBROUTINE relaxation at C(psi,psiobu,psiobv,novars,iprofrlx)
REAL, INTENT(INOUT), DIMENSION(1-nhalo:ncloc+nhalo,&
& 1-nhalo:nrloc+nhalo,nz,novars) :: psi
REAL, INTENT(INOUT), DIMENSION(nobu,nz,novars) :: psiobu
REAL, INTENT(INOUT), DIMENSION(nobv,nz,novars) :: psiobv
File
Type
Subroutine
Purpose
Apply the relaxation scheme for a quantity or quantities at C-nodes
Reference
Section 4.10.3
Arguments
psi Array of C-node quantity or quantities as defined on the
model grid [psi]
psiobu Vertical profiles of the C-node variable(s) at the U-open
boundaries [psi]
psiobv Vertical profiles of the C-node variable(s) at the V-open
boundaries [psi]
novars Number of C-node variables (currently 1)
iprofrlx Array which selects the zones for application of the scheme
Calling procedures
relaxation at U
SUBROUTINE relaxation at U(psi,psiobu,nzdim,iprofrlx)
INTEGER, INTENT(IN) :: nzdim
& 1-nhalo:nrloc+nhalo,nzdim) :: psi
REAL, INTENT(INOUT), DIMENSION(nobu,nzdim) :: psiobu
22.21. RELAXATION ZONES.F90 759
File
Type
Subroutine
Purpose
Apply the relaxation scheme for a quantity at the U-nodes
Reference
Section 4.10.3
Arguments
psi U-node variable as defined on the model grid [psi]
psiobu Vertical profiles of the U-node variables at the U-open
boundaries [psi]
nzdim Vertical dimension of the U-node variable
Calling procedures
current corr
relaxation at V
SUBROUTINE relaxation at V(psi,psiobv,nzdim,iprofrlx)
INTEGER, INTENT(IN) :: nzdim
& 1-nhalo:nrloc+nhalo,nzdim) :: psi
REAL, INTENT(INOUT), DIMENSION(nobv,nzdim) :: psiobv
File
Type
Subroutine
Purpose
Apply the relaxation scheme for a quantity at V-nodes
Reference
Section 4.10.3
Arguments
psi V-node variable as defined on the model grid [psi]
psiobv Vertical profiles of the V-node variables at the V-open
boundaries [psi]
nzdim Vertical dimension of the V-node variable
Calling procedures
current corr
relaxation weights
SUBROUTINE relaxation weights
File
Type
Subroutine
Purpose
Define the weight factors for the interpolation scheme.
Reference
Section 4.10.3
Calling procedures
initialise model
write rlxobc spec

SUBROUTINE write rlxobc spec
File
Type
Subroutine
Purpose
Write the arrays which define the areas for application of the open
boundary relaxation scheme to a file in standard COHERENS format.
22.22. SURFACE BOUNDARY DATA 1D.F90 761
Reference
Section 14.3
Calling procedures
define rlxobc spec
22.22 Surface Boundary Data 1D.f90

Ensemble of routines for the definition and application of surface boundary
conditions (surface slopes, elevations) in case of a 1-D water column appli-
cation
define 1dsur data

SUBROUTINE define 1dsur data(ciodatetime,data1d,novars)
File
Surface Boundary Data 1D.f90
Type
Subroutine
Purpose
Define the surface forcing data for 1-D applications.
Reference
Section 15.1.2
Arguments
data1d Returned surface forcing data

read 1dsur data, usrdef 1dsur data, write 1dsur data
Calling procedures
update 1dsur data
define 1dsur spec

SUBROUTINE define 1dsur spec
File
Type
Subroutine
Purpose
Define the amplitudes and phases of the forcing data (if any) and the
type of data in case there is an external data file.
Reference
Section 15.1.1

read 1dsur spec, usrdef 1dsur spec, write 1dsur spec
Calling procedures
update 1dsur data
read 1dsur data

SUBROUTINE read 1dsur data(ciodatetime,data1d,novars)
File
Type
Subroutine
Purpose
Read the surface forcing data for 1-D applications from a file in stan-
Reference
Section 15.1.2
Arguments
22.22. SURFACE BOUNDARY DATA 1D.F90 763

data1d Returned surface forcing data
Calling procedures
define 1dsur data
read 1dsur spec

SUBROUTINE read 1dsur spec
File
Type
Subroutine
Purpose
Read the amplitudes and phases of the forcing data (if any) and the
type of data in case there is an external data file from a file in standard
COHERENS format.
Reference
Section 15.1.1
Arguments
None
Calling procedures
define 1dsur spec
update 1dsur data

SUBROUTINE update 1dsur data
File
Type
Subroutine
Purpose
Update the surface forcing data (surface slopes, elevations) by read-
ing new data (if needed). Interpolate at the current simulation time.
Update the harmonic expansions for the surface slopes and the water
elevation (if requested).

astro params, define 1dsur data, define 1dsur spec, water depths
Calling procedures
current pred, initialise model
write 1dsur data

SUBROUTINE write 1dsur data(ciodatetime,data1d,novars)
REAL, INTENT(IN), DIMENSION(3) :: data1d
File
Type
Subroutine
Purpose
Write the surface forcing data to a file in standard COHERENS format.
Reference
Section 15.1.2
Arguments

data1d Surface forcing data
Calling procedures
define 1dsur data
22.23. SURFACE DATA.F90 765
write 1dsur spec

SUBROUTINE write 1dsur spec
File
Type
Subroutine
Purpose
Write the amplitudes and phases of the forcing data (if any) and the
type of data in case there is an external data file to a file in standard
COHERENS format.
Reference
Section 15.1.1
Calling procedures
define 1dsur spec
22.23 Surface Data.f90

Surface forcing data from a 2-D external grid.
define surface data

SUBROUTINE define surface data(iddesc,ifil,ciodatetime,surdata,&
& n1dat,n2dat,novars)
INTEGER, INTENT(IN) :: iddesc, ifil, n1dat, n2dat, novars
File
Surface Data.f90
Type
Subroutine
Purpose
Define (2-D) surface forcing data.
Reference
Section 15.2.3
Arguments
surdata Returned array of surface forcing data
n1dat Dimension of the data grid in the X-direction
n2dat Dimension of the data grid in the Y-direction
novars Number of forcing data variables

read surface data, usrdef surface data, write surface data
Calling procedures
update surface data
read surface data

SUBROUTINE read surface data(iddesc,ifil,ciodatetime,surdata,&
File
Surface Data.f90
Type
Subroutine
Purpose
Read the (2-D) surface forcing data from a file in standard COHERENS
format.
Reference
Section 15.2.3
Arguments
22.23. SURFACE DATA.F90 767
surdata Returned array of surface forcing data

Calling procedures
define surface data
update surface data

SUBROUTINE update surface data(iddesc,ifil,surindat,survals,surfgrid,&
& n1dat,n2dat,novars,n1grd,n2grd,&
& nosecsdat,datflag)
INTEGER, INTENT(IN) :: datflag, iddesc, ifil, novars, n1dat, n1grd, &
& n2dat, n2grd
INTEGER (KIND=kndilong), INTENT(INOUT), DIMENSION(2) :: nosecsdat
REAL, INTENT(INOUT), DIMENSION(n1dat,n2dat,novars,2) :: surindat
REAL, INTENT(INOUT), DIMENSION(ncloc,nrloc,novars) :: survals
TYPE (HRelativeCoords), INTENT(IN), DIMENSION(n1grd,n2grd) :: surfgrid
File
Surface Data.f90
Type
Subroutine
Purpose
Update surface input defined on an external 2-D data grid by reading
new data (if needed). Interpolate the data in space on the model grid
and in time at the current simulation time (if requested).
Reference
Section 10.2.4
Arguments
surindat Array of surface data at the latest time earlier than the
current date/time and at the earliest time later than the
current date/time
survals Surface data interpolated spatially on the model grid and

in time at the current time (if requested)
surfgrid Relative coordinates of the model grid with respect to the
surface data grid
n1dat Dimension of the data in the X-direction
n2dat Dimension of the data in the Y-direction
n1grd Dimension of the surface grid in the X-direction
n2grd Dimension of the surface grid in the Y-direction
nosecsdat Number of seconds since the start of the simulation and
the latest data time earlier than the current time and the
earliest data time later than the current time
datflag Type of data flagging for spatial interpolation
0: No data flags are applied
1: A data flag is applied if any of the surrounding data
values is flagged
2: A data flag is applied only when all surrounding data
values are flagged. Extrapolation is used if needed.

define surface data
Calling procedures
meteo input, temperature equation
write surface data

SUBROUTINE write surface data(iddesc,ifil,ciodatetime,surdata,&
REAL, INTENT(IN), DIMENSION(n1dat,n2dat,novars) :: surdata
File
Surface Data.f90
Type
Subroutine
22.24. SURFACE FLUXES.F90 769
Purpose
Write the (2-D) surface forcing data to a file in standard COHERENS
format.
Reference
Section 15.2.3
Arguments
surdata Array of surface forcing data
Calling procedures
define surface data
22.24 Surface Fluxes.F90

Meteorological forcing and surface fluxes.
heat flux
SUBROUTINE heat flux
File
Surface Fluxes.F90
Type
Subroutine
Purpose
Evaluate all non-solar surface heat fluxes.
Reference
Section 4.7.3

surface exchange coefs
Calling procedures
initialise model, temperature equation
meteo input
SUBROUTINE meteo input
File
Surface Fluxes.F90
Type
Subroutine
Purpose
Update meteorological forcing data.

define surface input grid, surface exchange MO, update surface data
Calling procedures
coherens main, initialise model
salinity flux
SUBROUTINE salinity flux
File
Surface Fluxes.F90
Type
Subroutine
Purpose
Surface salinity flux
Reference
Section 4.7.4
Calling procedures
salinity equation
solar irradiance
SUBROUTINE solar irradiance
File
Surface Fluxes.F90
Type
Subroutine
Purpose
Solar radiation at the surface
Reference
Section 4.6
Calling procedures
surface drag coef

SUBROUTINE surface drag coef(wind)
REAL, INTENT(IN), DIMENSION(0:ncloc,0:nrloc) :: wind
File
Surface Fluxes.F90
Type
Subroutine
Purpose
Surface drag coefficient Cds
Reference
Section 4.8
Arguments
wind Magnitude of the wind speed [m/s]
Calling procedures
surface stress
surface drag coef 0d

SUBROUTINE surface drag coef 0d(cdn,wind)
REAL, INTENT(OUT) :: cdn
REAL, INTENT(IN) :: wind
File
Surface Fluxes.F90
Type
Subroutine
Purpose
Neutral surface drag coefficient Cdn as function of the wind speed
Reference
Section 4.8.1
Arguments
cdn Returned neutral surface drag coefficient
Calling procedures
surface exchange MO
surface exchange coefs

SUBROUTINE surface exchange coefs(wind,tempdif)
REAL, INTENT(IN), DIMENSION(ncloc,nrloc) :: tempdif, wind
File
Surface Fluxes.F90
Type
Subroutine
Purpose
Surface exchange coefficients Ce and Ch used in the calculation of the
latent and sensible heat fluxes
Reference
Section 4.8
Arguments

tempdif Sea surface minus air temperature [0 C]
Calling procedures
heat flux
surface exchange coefs 0d

SUBROUTINE surface exchange coefs 0d(cen,chn,wind,tempdif)
REAL, INTENT(OUT) :: cen, chn
REAL, INTENT(IN) :: tempdif, wind
File
Surface Fluxes.F90
Type
Subroutine
Purpose
Neutral surface exchange coefficients Cen and Chn as function of the
wind speed and the sea minus air temperature difference
Reference
Section 4.8.1
Arguments
cen Returned neutral exchange coefficient Cen for the latent
heat flux
chn Returned neutral exchange coefficient Chn for the sensible
heat flux
temdif Sea surface minus air temperature difference [0 C]
Calling procedures
surface exchange MO
surface exchange MO
SUBROUTINE surface exchange MO
File
Surface Fluxes.F90
Type
Subroutine
Purpose
Solve the equations for the surface drag and exchange coefficients using
the Monin-Obukhov similarity theory as function of wind speed, air
minus sea temperature difference and relative humidity. The values
are obtained for discretised values of the meteorological data. The
results stored in tabular form.
Reference
Section 4.8.3
surface drag coef 0d, surface exchange coefs 0d
Calling procedures
meteo input
surface stress
SUBROUTINE surface stress
File
Surface Fluxes.F90
Type
Subroutine
Purpose
Evaluate the surface stress
Reference
Section 4.7.2
surface drag coef
Calling procedures
current corr, current corr 1d, current 2d, initialise model
22.25 Surface Grids.f90

Definition of external 2-D surface grids.
22.25. SURFACE GRIDS.F90 775
define surface input grid

SUBROUTINE define surface input grid(iddesc,ifil,surfgrid)
INTEGER, INTENT(IN) :: iddesc, ifil
TYPE (HRelativeCoords), INTENT(OUT), DIMENSION(ncloc,nrloc) :: surfgrid
File
Surface Grids.f90
Type
Subroutine
Purpose
Define the relative coordinates of the model grid with respect to an
external surface data grid
Reference
Sections 8.4.2 and 15.2
Arguments
iddesc Key id of the surface grid file
ifil File index of the grid file
surfgrid Relative coordinates (on the local sub-domain) of the model
grid with respect to the data grid

read surface absgrd, read surface relgrd, usrdef surface absgrd,
usrdef surface relgrd, write surface absgrd, write surface relgrd
Calling procedures
meteo input, temperature equation
define surface output grid

SUBROUTINE define surface output grid(iddesc,ifil,surfgridglb,nhdat)
INTEGER, INTENT(IN) :: iddesc, ifil, nhdat
TYPE (HRelativeCoords), INTENT(OUT), DIMENSION(nhdat,3) :: surfgridglb
File
Surface Grids.f90
Type
Subroutine
Purpose
Define the relative coordinates of an external surface data grid with
respect to the model grid. Intended for (future implementation of)
coupling with surface wave and meteorological models.
Reference
Sections 8.5
Arguments
surfgridglb Relative coordinates of the model grid with respect to the
external grid. The second dimension denotes the nodal
type of the model grid coordinates.
1: C-nodes
2: U-nodes
3: V-nodes
nhdat Number of horizontal locations on the data grid
read surface absgrd, read surface relgrd, usrdef surface absgrd,
usrdef surface relgrd, write surface absgrd, write surface relgrd
Calling procedures
Currently not implemented
read surface absgrd

SUBROUTINE read surface absgrd(iddesc,ifil,n1dat,n2dat,xcoord,ycoord)
REAL, INTENT(OUT), DIMENSION(n1dat,n2dat) :: xcoord
REAL, INTENT(OUT), DIMENSION(n1dat,n2dat) :: ycoord
File
Surface Grids.f90
Type
Subroutine
Purpose
Read the absolute coordinates of an external surface data grid from a
file in standard COHERENS format.
22.25. SURFACE GRIDS.F90 777
Reference
Section 15.2.1
Arguments
n1dat X-dimension of the surface data grid
n2dat Y-dimension of the surface data grid
xcoord X-coordinates of the data grid [m or degrees longitude]
ycoord Y-coordinates of the data grid [m or degrees latitude]
Calling procedures
define surface input grid, define surface output grid
read surface relgrd

SUBROUTINE read surface relgrd(iddesc,ifil,surfgridglb,nx,ny,nonodes)
TYPE (HRelativeCoords), INTENT(OUT), &
& DIMENSION(nx,ny,nonodes) :: surfgridglb
File
Surface Grids.f90
Type
Subroutine
Purpose
Read the relative coordinates of the model grid with respect to an
external surface data grid from a file in standard COHERENS format.
Reference
Section 15.2.2
Arguments
surfgridglb Relative coordinates of the (global) model grid with re-
spect to the external surface data grid.
nx X-dimension of the external surface grid
ny Y-dimension of the external surface grid

nonodes Number of nodes (currently set to 1)
Calling procedures
write surface absgrd

SUBROUTINE write surface absgrd(iddesc,ifil,n1dat,n2dat,xcoord,ycoord)
REAL, INTENT(IN), DIMENSION(n1dat,n2dat) :: xcoord
REAL, INTENT(IN), DIMENSION(n1dat,n2dat) :: ycoord
File
Surface Grids.f90
Type
Subroutine
Purpose
Write the absolute coordinates of an external surface data grid to a file
in standard COHERENS format.
Reference
Section 15.2.1
Arguments

n1dat X-dimension of the surface data grid
n2dat Y-dimension of the surface data grid
xcoord X-coordinates of the data grid [m or degrees longitude]
ycoord Y-coordinates of the data grid [m or degrees latitude]
Calling procedures
22.26. TIDAL FORCING.F90 779
write surface relgrd

SUBROUTINE write surface relgrd(iddesc,ifil,surfgridglb,nx,ny,nonodes)
TYPE (HRelativeCoords), INTENT(IN), &
& DIMENSION(nx,ny,nonodes) :: surfgridglb
File
Surface Grids.f90
Type
Subroutine
Purpose
Write the relative coordinates of the model grid with respect to an
external surface data grid to a file in standard COHERENS format.
Reference
Section 15.2.2
Arguments
surfgridglb Relative coordinates of the (global) model grid with re-
spect to the external surface data grid.
nx X-dimension of the external surface grid
ny Y-dimension of the external surface grid
nonodes Number of nodes (currently set to 1)
Calling procedures
22.26 Tidal Forcing.F90

Astronomical phases, nodal factors and tidal astronomical force.
astro params
SUBROUTINE astro params(index tides,fnode tides,phase tides,&
& notides,dlonref phase,cdatetime tides)
CHARACTER (LEN=lentime), INTENT(IN) :: cdatetime tides
INTEGER, INTENT(IN) :: notides

REAL, INTENT(IN) :: dlonref phase
INTEGER, INTENT(IN), DIMENSION(notides) :: index tides
REAL, INTENT(OUT), DIMENSION(notides) :: fnode tides, phase tides
File
Tidal Forcing.F90
Type
Subroutine
Purpose
Calculate nodal factors and astronomical arguments at the given date
and time.
Reference
Section 4.5
Arguments
index tides Key ids of the tidal constituents
fnode tides Returned nodal correction factors
phase tides Returned astronomical arguments
notides Number of tidal constituents
dlonref phase Reference longitude to be used for the phases
cdatetime tides Calendar date and time. Time is converted to GMT if
time zone is non-zero.
Calling procedures
astronomical tides, harmonic analysis data, update 1dsur data,
update 2dobc data
astronomical tides
SUBROUTINE astronomical tides
File
Tidal Forcing.F90
Type
Subroutine
22.27. TIME AVERAGES.F90 781
Purpose
Components of the astronomical tidal force
Reference
Section 4.5

astro params
Calling procedures
coherens main, current 2d, initialise model
22.27 Time Averages.f90

Time averaged output.
time averages
SUBROUTINE time averages
File
Time Averages.f90
Type
Subroutine
Purpose
Base program unit for time averaged output

time averages grid, time averages init, time averages reset,
time averages update, time averages write
Calling procedures
coherens main
time averages grid

SUBROUTINE time averages grid
File
Time Averages.f90
Type
Internal subroutine
Purpose
Calling procedures
time averages
time averages init

SUBROUTINE time averages init
File
Time Averages.f90
Type
Internal subroutine
Purpose
Define the arrays for the setup of time averaging. Write the metadata
to the data file.
Reference
Section 16.2.1

usrdef avr params
Calling procedures
time averages
time averages reset

SUBROUTINE time averages reset
File
Time Averages.f90
Type
Internal subroutine
Purpose
Initialise buffers for storing the averaged data.
22.28. TIME SERIES.F90 783
Calling procedures
time averages
time averages update

SUBROUTINE time averages update
File
Time Averages.f90
Type
Internal subroutine
Purpose
Add the current data to the buffers containing the current averages.

usrdef avr0d vals, usrdef avr2d vals, usrdef avr3d vals
Calling procedures
time averages
time averages write

SUBROUTINE time averages write
File
Time Averages.f90
Type
Internal subroutine
Purpose
Write the time-averaged output to the appropriate data files.
Calling procedures
time averages
22.28 Time Series.f90

Time series output.
time series
SUBROUTINE time series
File
Time Series.f90
Type
Subroutine
Purpose
Write time series output to the appropriate output files.

time series grid, time series init

usrdef tsr0d vals, usrdef tsr2d vals, usrdef tsr3d vals
Calling procedures
coherens main
time series grid

SUBROUTINE time series grid
File
Time Series.f90
Type
Internal subroutine
Purpose
Calling procedures
time series
time series init

SUBROUTINE time series init
File
Time Series.f90
22.29. TRANSPORT EQUATIONS.F90 785
Type
Internal subroutine
Purpose
Define the arrays for the setup of time series output. Write the meta-
data to the data file.
Reference
Section 16.1.1
usrdef tsr params
Calling procedures
time series
22.29 Transport Equations.F90

Solve the transport equations for scalar and vector quantities at the different
nodes.
transport at C 3d
SUBROUTINE transport at C 3d(psic,source,wadvatw,vdifcoefatw,iopt hadv,&
& iopt vadv,iopt hdif,psiobu,psiobv,iprofrlx,&
& ibcsur,ibcbot,nbcs,nbcb,bcsur,bcbot,ivarid)
INTEGER, INTENT(IN) :: ibcbot, ibcsur, iopt hadv, iopt hdif, &
& iopt vadv, ivarid, nbcb, nbcs
REAL, INTENT(IN), DIMENSION(nobu,nz) :: psiobu
REAL, INTENT(IN), DIMENSION(nobv,nz) :: psiobv
& 1-nhalo:nrloc+nhalo,nz) :: psic
REAL, INTENT(INOUT), DIMENSION(ncloc,nrloc,nz) :: source
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nz+1) :: vdifcoefatw, wadvatw
File
Transport Equations.F90
Type
Subroutine
Purpose
Solve the advection-diffusion equation for a 3-D scalar quantity at the
C-nodes.
Reference
Section 5.5
Arguments
psic C-node quantity for which a transport equation needs to
be solved [psic]
source Source terms in the transport equation [psic/s]
wadvatw Transformed vertical current ω plus (eventually) sinking/swimming
vertical current at the W-nodes [m/s]
iopt hadv Switch to select horizontal advection scheme
iopt vadv Switch to select vertical advection scheme
iopt hdif Switch to select horizontal diffusion scheme
psiobu Vertical profiles at the U-open boundaries (a zero gradient
condition is applied if flagged) [psic]
psiobv Vertical profiles at the V-open boundaries (a zero gradient
iprofrlx Selects whether a relaxation scheme is applied at each of
the defined open boundary zones.
3: Dirichlet condition (5.393) at the first C-node below the
surface
bottom

[psic m/s] or [psic]
ivarid Variable key id of the transported variable (used for log
info only, zero for undefined)

relaxation at C, Xadv at C, Xcorr at C, Xdif at C, Yadv at C, Ycorr at C,
Ydif at C, Zadv at C, Zcorr at C, Zdif at C
Calling procedures
transport at C 4d1
SUBROUTINE transport at C 4d1(psic,source,wadvatw,vdifcoefatw,novars,&
& iopt hadv,iopt vadv,iopt hdif,psiobu,&
& psiobv,iprofrlx,ibcsur,ibcbot,nbcs,nbcb,&
& bcsur,bcbot,ivarids)
INTEGER, INTENT(IN) :: ibcbot, ibcsur, iopt hadv, iopt hdif,&
& iopt vadv, nbcb, nbcs, novars
INTEGER, INTENT(IN), DIMENSION(novars) :: ivarids
REAL, INTENT(INOUT), DIMENSION(ncloc,nrloc,nz,novars) :: source

File
Type
Subroutine
Purpose
Solve the advection-diffusion equation for one or more scalar quantities
at the C-node. The equations are solved sequentially.
Reference
Section 5.5
Arguments
psic C-node quantity or quantities for which transport equa-
tion(s) need(s) to be solved [psic]
source Source terms in the transport equation(s) [psic/s]
vertical current(s) at the W-nodes [m/s]
novars Number of variables to be transported

surface
bottom
nbcs Second last dimension of the array bcsur
nbcb Second last dimension of the array bcbot
ivarids Variable key id(s) of the transported variable(s) (used for
log info only, zero for undefined)

Calling procedures
transport at C 4d2
SUBROUTINE transport at C 4d2(psic,source,wadvatw,vdifcoefatw,novars,&
& iopt hadv,iopt vadv,iopt hdif,psiobu,&
& psiobv,iprofrlx,ibcsur,ibcbot,nbcs,nbcb,&
& bcsur,bcbot,ivarid)
INTEGER, INTENT(IN) :: ibcbot, ibcsur, iopt hadv, iopt hdif,&
& iopt vadv, ivarid, nbcb, nbcs, novars
REAL, INTENT(INOUT), DIMENSION(ncloc,nrloc,nz,novars) :: source
File
Type
Subroutine
Purpose
Solve the advection-diffusion equation for a vector of scalar quantities
at the C-node. The equations are solved simultaneously for all vector
components.
Reference
Section 5.5
Arguments
psic C-node vector of scalar quantities for which transport equa-
tions need to be solved [psic]
source Source terms in the transport equations [psic/s]
vertical current(s) at the W-nodes [m/s]
novars Number of variables to be transported

surface
bottom
nbcs Second last dimension of the array bcsur
nbcb Second last dimension of the array bcbot
ivarid Variable key id for the vector of C-node scalars (used for
log info only, zero for undefined)

Calling procedures
transport at U 2d
SUBROUTINE transport at U 2d(source,sink)
REAL, INTENT(INOUT), DIMENSION(ncloc,nrloc) :: sink, source
File
Type
Subroutine
Purpose
Solve the 2-D momentum equation for the X-component U of the depth-
integrated current.
Reference
Section 5.3
Arguments
source Explicit source terms in the U -equation [m2 /s2 ]
sink Implicit sink terms in the U -equation arising from bottom
stress [s−1 ]
Xadv at U 2d, Xdif at U 2d, Yadv at U 2d, Ydif at U 2d
Calling procedures
current 2d
transport at U 3d
SUBROUTINE transport at U 3d(source,ibcsur,ibcbot,nbcs,nbcb,&
& bcsur,bcbot)
File
Type
Subroutine
Purpose
Solve the 3-D momentum equation for the X-component u of the 3-D
current.
Reference
Section 5.3
Arguments
source Source terms in the u-equation
tions (5.236), (5.238), (5.239))
[m2 /s2 ] or [m/s]
[m2 /s2 ] or [m/s]
Xadv at U 3d, Xdif at U 3d, Yadv at U 3d, Ydif at U 3d, Zadv at U,
Zdif at U
Calling procedures
current pred
transport at V 2d
SUBROUTINE transport at V 2d(source,sink)
REAL, INTENT(INOUT), DIMENSION(ncloc,nrloc) :: sink, source
File
Type
Subroutine
Purpose
Solve the 2-D momentum equation for the Y-component V of the depth-
integrated current.
Reference
Section 5.3
Arguments
source Explicit source terms in the V -equation [m2 /s2 ]
sink Implicit sink terms in the V -equation arising from bottom
stress [s−1 ]

Xadv at V 2d, Xdif at V 2d, Yadv at V 2d, Ydif at V 2d
Calling procedures
current 2d
transport at V 3d
SUBROUTINE transport at V 3d(source,ibcsur,ibcbot,nbcs,nbcb,&
& bcsur,bcbot)
File
Type
Subroutine
Purpose
Solve the 3-D momentum equation for the Y-component v of the 3-D
current.
Reference
Section 5.3
Arguments
source Source terms in the v-equation
tions (5.237), (5.238), (5.240))
[m2 /s2 ] or [m/s]
[m2 /s2 ] or [m/s]
Xadv at V 3d, Xdif at V 3d, Yadv at V 3d, Ydif at V 3d, Zadv at V,
Zdif at V
Calling procedures
current pred
transport at W
SUBROUTINE transport at W(psiw,source,sink,vdifcoefatw,&
& ibcsur,ibcbot,bcsur,bcbot,ivarid)
INTEGER, INTENT(IN) :: ibcbot, ibcsur, ivarid
REAL, INTENT(INOUT),DIMENSION(1-nhalo:ncloc+nhalo,&
REAL, INTENT(INOUT), DIMENSION(ncloc,nrloc,2:nz) :: sink, source
REAL, INTENT(IN), DIMENSION(ncloc,nrloc) :: bcbot, bcsur
File
Type
Subroutine
Purpose
Solve the advection-diffusion equation for a 3-D scalar (turbulent) quan-
tity at the W-node.
Reference
Section 5.6
Arguments
psiw W-node quantity for which a transport equation needs to
be solved [psiw]
source Explicit source terms in the transport equation [psic/s]
sink Implicit sink terms in the transport equation [s−1 ]
1: prescibed (Neumann) flux at the surface (see equations
(5.472)–(5.474))
2: prescribed Neumann flux at the first C-node below the
surface (5.475)
4: Dirichlet condition (5.477) at the first W-node below
the surface
22.30. TURBULENCE EQUATIONS.F90 797

1: prescibed (Neumann) flux at the bottom (see equa-
tions (5.478)–(5.480))
2: prescribed Neumann flux at the first C-node above the
bottom (5.481)
4: Dirichlet condition (5.483) at the first W-node above
the bottom
bcsur Imposed surface flux or surface value
bcbot Imposed bottom flux or bottom value
ivarid Variable key id of the transported variable (used for log
info only, zero for undefined)
Xadv at W, Xcorr at W, Xdif at W, Yadv at W, Ycorr at W, Ydif at W,
Zadv at W, Zcorr at W, Zdif at W
Calling procedures
dissipation equation, kl equation, tke equation
22.30 Turbulence Equations.F90

dissipation equation
SUBROUTINE dissipation equation
File
Turbulence Equations.F90
Type
Subroutine
Purpose
Solve the ε-equation (4.193).
Reference
Section 5.6
transport at W
Calling procedures
vertical diff coefs
eddy coefs alg

SUBROUTINE eddy coefs alg
File
Type
Subroutine
Purpose
Calculate the eddy coefficients νT and λT from an algebraic relation
Reference
Section 4.4.2
Calling procedures
vertical diff coefs
eddy coefs tc
SUBROUTINE eddy coefs tc
File
Type
Subroutine
Purpose
Calculate the eddy coefficients νT and λT from a RANS model.
Reference
Section 4.4.3
Calling procedures
vertical diff coefs
init turbulence
SUBROUTINE init turbulence
File
Type
Subroutine
Purpose
Initialise parameters for different turbulence closures schemes
Calling procedures
vertical diff coefs, default phsics
kl equation
SUBROUTINE kl equation
File
Type
Subroutine
Purpose
Solve the kl (q 2 l) equation (4.197).
Reference
Section 5.6

transport at W
Calling procedures
vertical diff coefs
mixing length
SUBROUTINE mixing length
File
Type
Subroutine
Purpose
Algebraic mixing length formulations
Reference
Section 4.4.3.5
Calling procedures
default phsics, vertical diff coefs
tke equation
SUBROUTINE tke equation
File
Type
Subroutine
Purpose
Solve the k-equation (4.192).
Reference
Section 5.6

transport at W
Calling procedures
vertical diff coefs
tke equilibrium
SUBROUTINE tke equilibrium
File
Type
Subroutine
Purpose
Calculate the turbulent energy k using the equilibrium (level ”2”)
method.
Reference
Section 4.4.3.3
Calling procedures
vertical diff coefs
Appendix 23
Description of modules routines
23.1 Array interpolation

Perform array interpolation on model grid arrays. The names of the routines
are of the form
Xarr at Y interpolation of a section of a model grid array defined at node X
to node Y
Xvar at Y interpolation of a model grid array defined at node X to a grid
point at node Y
Carr at U
SUBROUTINE Carr at U(xin,xout,intsrce,intdest,lbounds,ubounds,&
& nosize,ivarid,info,outflag,hregular)
LOGICAL, INTENT(IN) :: info
LOGICAL, INTENT(IN), OPTIONAL :: hregular
INTEGER, INTENT(IN) :: intdest, intsrce, ivarid, nosize
REAL, INTENT(IN), OPTIONAL :: outflag
INTEGER, INTENT(IN), DIMENSION(3) :: lbounds, ubounds
REAL, INTENT(IN), DIMENSION(lbounds(1):ubounds(1),lbounds(2):ubounds(2),&
& lbounds(3):ubounds(3),nosize) :: xin
REAL, INTENT(OUT), DIMENSION(lbounds(1)+1:ubounds(1),lbounds(2):ubounds(2),&
& lbounds(3):ubounds(3),nosize) :: xout
File
array interp.f90
Type
Module subroutine
803
804 APPENDIX 23. DESCRIPTION OF MODULES ROUTINES
Purpose
Interpolate a section of a model grid C-node array to the U-nodes.
Reference
Section 8.2
Arguments
xin Source array at the C-nodes
xout Destination array at the U-nodes
intsrce Selects valid points at the source node
0: all points
1: wet points only
intdest Selects valid points at the destination node
0: all points
1: coastal boundaries, interior points and open boundaries
only
2: interior points only
3: interior points and open boundaries only
4: coastal boundaries and interior points only
lbounds Lower bounds of the source array
ubounds Upper bounds of the source array
nosize Fourth dimension of the source array
ivarid Variable key id (used for log info only, zero for undefined)
info Disables/enables writing of a log info.
outflag Output flag for invalid points, if present. Zero otherwise.
hregular Flag to select uniform or area averaging in the horizontal,
if present. Otherwise, the type of averaging is selected by
iopt arrint hreg.
Carr at UV
SUBROUTINE Carr at UV(xin,xout,intsrce,intdest,lbounds,ubounds,&
23.1. ARRAY INTERPOLATION 805

REAL, INTENT(OUT), DIMENSION(lbounds(1)+1:ubounds(1),lbounds(2)+1:ubounds(2),&
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid C-node array to the UV-nodes.
Reference
Section 8.2
Arguments
xout Destination array at the UV-nodes
0: all points
1: wet points only
0: all points
1: wet points only
iopt arrint hreg.
Carr at UW
SUBROUTINE Carr at UW(xin,xout,intdest,lbounds,ubounds,nosize,&
& ivarid,info,outflag,hregular,vregular)
LOGICAL, INTENT(IN), OPTIONAL :: hregular, vregular
INTEGER, INTENT(IN) :: intdest, ivarid, nosize
& lbounds(3)+1:ubounds(3),nosize) :: xout
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid C-node array to the UW-nodes.
Reference
Section 8.2
Arguments
xout Destination array at the UW-nodes
only

iopt arrint hreg.
vregular Flag to select uniform or area averaging in the vertical, if
present. Otherwise, the type of averaging is selected by
iopt arrint vreg.
Carr at V
SUBROUTINE Carr at V(xin,xout,intsrce,intdest,lbounds,ubounds,&
REAL, INTENT(OUT), DIMENSION(lbounds(1):ubounds(1),lbounds(2)+1:ubounds(2),&
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid C-node array to the V-nodes.
Reference
Section 8.2
Arguments
xout Destination array at the V-nodes
0: all points
1: wet points only

0: all points
only
iopt arrint hreg.
Carr at VW
SUBROUTINE Carr at VW(xin,xout,intdest,lbounds,ubounds,nosize,&
& ivarid,info,outflag,hregular,vregular)
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid C-node array to the VW-nodes.
Reference
Section 8.2
Arguments
xout Destination array at the VW-nodes
only
iopt arrint hreg.
iopt arrint vreg.
Carr at W
SUBROUTINE Carr at W(xin,xout,lbounds,ubounds,nosize,ivarid,&
& info,outflag,vregular)
LOGICAL, INTENT(IN), OPTIONAL :: vregular
INTEGER, INTENT(IN) :: ivarid, nosize

REAL, INTENT(OUT), DIMENSION(lbounds(1):ubounds(1),lbounds(2):ubounds(2),&
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid C-node array to the W-nodes.
Reference
Section 8.2
Arguments
xout Destination array at the W-nodes
iopt arrint vreg.
Uarr at C
SUBROUTINE Uarr at C(xin,xout,intsrce,intdest,lbounds,ubounds,&
& nosize,ivarid,info,outflag)
REAL, INTENT(OUT), DIMENSION(lbounds(1):ubounds(1)-1,lbounds(2):ubounds(2),&

File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid U-node array to the C-nodes.
Reference
Section 8.2
Arguments
xin Source array at the U-nodes
xout Destination array at the C-nodes
0: all points
only
0: all points
1: wet points only
Uarr at UV
SUBROUTINE Uarr at UV(xin,xout,intsrce,intdest,lbounds,ubounds,&
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid U-node array to the UV-nodes.
Reference
Section 8.2
Arguments
0: all points
only
0: all points
2: interior points and UV-node open boundaries only

iopt arrint hreg.
Uarr at UW
SUBROUTINE Uarr at UW(xin,xout,intsrce,intdest,lbounds,ubounds,nosize,&
& ivarid,info,outflag,vregular)
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid U-node array to the UW-nodes.
Reference
Section 8.2
Arguments

only
only
iopt arrint vreg.
Uarr at V
SUBROUTINE Uarr at V(xin,xout,intsrce,intdest,lbounds,ubounds,&
REAL, INTENT(OUT), DIMENSION(lbounds(1):ubounds(1)-1,&
& lbounds(2)+1:ubounds(2),&
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid U-node array to the V-nodes.
Reference
Section 8.2
Arguments
0: all points
only
0: all points
only
iopt arrint hreg.
Uarr at W
SUBROUTINE Uarr at W(xin,xout,intsrce,lbounds,ubounds,nosize,&
INTEGER, INTENT(IN) :: intsrce, ivarid, nosize
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid U-node array to the W-nodes.
Reference
Section 8.2
Arguments
only

iopt arrint vreg.
UVarr at C
SUBROUTINE UVarr at C(xin,xout,intsrce,intdest,lbounds,ubounds,&
REAL, INTENT(OUT), DIMENSION(lbounds(1):ubounds(1)-1,lbounds(2):ubounds(2)-1,&
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid UV-node array to the C-nodes.
Reference
Section 8.2
Arguments
xin Source array at the UV-nodes
0: all points
1: wet points only
0: all points
1: wet points
UVarr at U
SUBROUTINE UVarr at U(xin,xout,intsrce,intdest,lbounds,ubounds,&
REAL, INTENT(OUT), DIMENSION(lbounds(1):ubounds(1),lbounds(2):ubounds(2)-1,&
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid UV-node array to the U-nodes.
Reference
Section 8.2
Arguments
0: all points

0: all points
only
UVarr at V
SUBROUTINE UVarr at V(xin,xout,intsrce,intdest,lbounds,ubounds,nosize,&
& ivarid,info,outflag)
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid UV-node array to the V-nodes.
Reference
Section 8.2
Arguments
0: all points
0: all points
1: coastal boundaries, interior points and open
UWarr at U
SUBROUTINE UWarr at U(xin,xout,intsrce,intdest,lbounds,ubounds,nosize,&
& lbounds(3):ubounds(3)-1,nosize) :: xout
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid UW-node array to the U-nodes.
Reference
Section 8.2
Arguments
xin Source array at the UW-nodes
only
only
UWarr at W
SUBROUTINE UWarr at W(xin,xout,intsrce,lbounds,ubounds,nosize,&

File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid UW-node array to the W-nodes.
Reference
Section 8.2
Arguments

only
Varr at C
SUBROUTINE Varr at C(xin,xout,intsrce,intdest,lbounds,ubounds,&
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid V-node array to the C-nodes.
Reference
Section 8.2
Arguments
xin Source array at the V-nodes
0: all points
only
0: all points
1: wet points only

Varr at U
SUBROUTINE Varr at U(xin,xout,intsrce,intdest,lbounds,ubounds,&
REAL, INTENT(OUT), DIMENSION(lbounds(1)+1:ubounds(1),&
& lbounds(2):ubounds(2)-1,&
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid V-node array to the U-nodes.
Reference
Section 8.2
Arguments
0: all points
only

0: all points
only
iopt arrint hreg.
Varr at UV
SUBROUTINE Varr at UV(xin,xout,intsrce,intdest,lbounds,ubounds,&
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid V-node array to the UV-nodes.
Reference
Section 8.2
Arguments

0: all points
only
0: all points
iopt arrint hreg.
Varr at VW
SUBROUTINE Varr at VW(xin,xout,intsrce,intdest,lbounds,ubounds,&
& nosize,ivarid,info,outflag,vregular)
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid V-node array to the VW-nodes.
Reference
Section 8.2
Arguments
only
only

iopt arrint vreg.
Varr at W
SUBROUTINE Varr at W(xin,xout,intsrce,lbounds,ubounds,nosize,&
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid V-node array to the W-nodes.
Reference
Section 8.2
Arguments

only
iopt arrint vreg.
VWarr at V
SUBROUTINE VWarr at V(xin,xout,intsrce,intdest,lbounds,ubounds,&
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid VW-node array to the V-nodes.
Reference
Section 8.2
Arguments
xin Source array at the VW-nodes
only
only
VWarr at W
SUBROUTINE VWarr at W(xin,xout,intsrce,lbounds,ubounds,nosize,&
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid VW-node array to the W-nodes.
Reference
Section 8.2
Arguments
only
Warr at C
SUBROUTINE Carr at W(xin,xout,lbounds,ubounds,nosize,ivarid,&
& info,outflag)
INTEGER, INTENT(IN) :: ivarid, nosize

File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid W-node array to the C-nodes.
Reference
Section 8.2
Arguments
xin Source array at the W-nodes
Warr at U
SUBROUTINE
Warr at U(xin,xout,intdest,lbounds,ubounds,nosize,ivarid,&
& info,outflag,hregular)
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid W-node array to the U-nodes.
Reference
Section 8.2
Arguments
only
iopt arrint hreg.
Warr at UW
SUBROUTINE Warr at UW(xin,xout,intdest,lbounds,ubounds,nosize,&
& ivarid,info,outflag,hregular)

File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid W-node array to the UW-nodes.
Reference
Section 8.2
Arguments
only
iopt arrint hreg.
Warr at V
SUBROUTINE
Warr at V(xin,xout,intdest,lbounds,ubounds,nosize,ivarid,&
& info,outflag,hregular)
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid W-node array to the V-nodes.
Reference
Section 8.2
Arguments
only

iopt arrint hreg.
Warr at VW
SUBROUTINE Warr at VW(xin,xout,intdest,lbounds,ubounds,nosize,&
& ivarid,info,outflag,hregular)
File
array interp.f90
Type
Module subroutine
Purpose
Interpolate a section of a model grid W-node array to the VW-nodes.
Reference
Section 8.2
Arguments
only

iopt arrint hreg.
Cvar at U
FUNCTION Cvar at U(xin,i,j,k,intsrce,intdest,outflag,hregular)
INTEGER, INTENT(IN) :: i, intdest, intsrce, j, k
REAL, INTENT(IN), DIMENSION(2) :: xin
REAL :: Cvar at U
File
array interp.f90
Type
Module function
Purpose
Interpolate a C-node variable to a U-nodal point.
Reference
Section 8.2
Arguments
i Lower X-index of the source array
j Y-index of the source array
k Vertical index of the source array
0: all points
1: wet points only

0: all points
only
iopt arrint hreg.
Cvar at U Interpolated value at the U-node destination point
Cvar at UV
FUNCTION Cvar at UV(xin,i,j,k,intsrce,intdest,outflag,hregular)
REAL, INTENT(IN), DIMENSION(2,2) :: xin
REAL :: Cvar at UV
File
array interp.f90
Type
Module function
Purpose
Interpolate a C-node variable to a UV-nodal point.
Reference
Section 8.2
Arguments
j Lower Y-index of the source array

0: all points
1: wet points only
0: all points
1: wet points only
iopt arrint hreg.
Cvar at UV Interpolated value at the UV-node destination point
Cvar at UW
FUNCTION Cvar at UW(xin,i,j,k,intdest,outflag,hregular,&
& vregular)
INTEGER, INTENT(IN) :: i, intdest, j, k
REAL :: Cvar at UW
File
array interp.f90
Type
Module function
Purpose
Interpolate a C-node variable to a UW-nodal point.
Reference
Section 8.2
Arguments
k Lower vertical index of the source array

only
iopt arrint hreg.
iopt arrint vreg.
Cvar at UW Interpolated value at the UW-node destination point
Cvar at V
FUNCTION Cvar at V(xin,i,j,k,intsrce,intdest,outflag,hregular)
REAL :: Cvar at V
File
array interp.f90
Type
Module function
Purpose
Interpolate a C-node variable to a V-nodal point.
Reference
Section 8.2
Arguments
i X-index of the source array

0: all points
1: wet points only
0: all points
only
iopt arrint hreg.
Cvar at V Interpolated value at the V-node destination point
Cvar at VW
FUNCTION Cvar at VW(xin,i,j,k,intdest,outflag,hregular,&
& vregular)
REAL :: Cvar at VW
File
array interp.f90
Type
Module function
Purpose
Interpolate a C-node variable to a VW-nodal point.
Reference
Section 8.2
Arguments
only
hregular Flag to select uniform or area averaging in the horizontal.
Otherwise, the type of averaging is selected by iopt arrint hreg.
iopt arrint vreg.
Cvar at VW Interpolated value at the VW-node destination point
Cvar at W
FUNCTION Cvar at W(xin,i,j,k,outflag,vregular)
INTEGER, INTENT(IN) :: i, j, k
REAL :: Cvar at W
File
array interp.f90
Type
Module function
Purpose
Interpolate a C-node variable to a W-nodal point.
Reference
Section 8.2
Arguments
iopt arrint vreg.
Cvar at W Interpolated value at the W-node destination point
Uvar at C
FUNCTION Uvar at C(xin,i,j,k,intsrce,intdest,outflag)
REAL :: Uvar at C
File
array interp.f90
Type
Module function
Purpose
Interpolate a U-node variable to a C-nodal point.
Reference
Section 8.2
Arguments

0: all points
only
0: all points
1: wet points only
Uvar at C Interpolated value at the C-node destination point
Uvar at UV
FUNCTION Uvar at UV(xin,i,j,k,intsrce,intdest,outflag,hregular)
REAL :: Uvar at UV
File
array interp.f90
Type
Module function
Purpose
Interpolate a U-node variable to a UV-nodal point.
Reference
Section 8.2
Arguments

0: all points
only
0: all points
iopt arrint hreg.
Uvar at UV Interpolated value at the UV-node destination point
Uvar at UW
FUNCTION Uvar at UW(xin,i,j,k,intsrce,intdest,outflag,vregular)
INTEGER, INTENT(IN) :: i, intdest, intsrce,j, k
REAL :: Uvar at UW
File
array interp.f90
Type
Module function
Purpose
Interpolate a U-node variable to a UW-nodal point.
Reference
Section 8.2
Arguments
only
only
iopt arrint vreg.
Uvar at UW Interpolated value at the UW-node destination point
Uvar at V
FUNCTION Uvar at V(xin,i,j,k,intsrce,intdest,outflag,hregular)
REAL :: Uvar at V
File
array interp.f90
Type
Module function
Purpose
Interpolate a U-node variable to a V-nodal point.
Reference
Section 8.2
Arguments
0: all points!
only
0: all points
only
iopt arrint hreg.
Uvar at V Interpolated value at the V-node destination point
Uvar at W
FUNCTION Uvar at W(xin,i,j,k,intsrce,outflag,vregular)
INTEGER, INTENT(IN) :: i, intsrce, j, k

REAL :: Uvar at W
File
array interp.f90
Type
Module function
Purpose
Interpolate a U-node variable to a W-nodal point.
Reference
Section 8.2
Arguments
only
iopt arrint vreg.
Uvar at W Interpolated value at the W-node destination point
UVvar at C
FUNCTION UVvar at C(xin,i,j,k,intsrce,intdest,outflag)
REAL :: UVvar at C
File
array interp.f90
Type
Module function
Purpose
Interpolate a UV-node variable to a C-nodal point.
Reference
Section 8.2
Arguments
0: all points
1: wet points only
0: all points
1: wet points only
UVvar at C Interpolated value at the C-node destination point
UVvar at U
FUNCTION UVvar at U(xin,i,j,k,intsrce,intdest,outflag)
REAL :: UVvar at U
File
array interp.f90
Type
Module function
Purpose
Interpolate a UV-node variable to a U-nodal point.
Reference
Section 8.2
Arguments
0: all points
0: all points
only
UVvar at U Interpolated value at the U-node destination point
UVvar at V
FUNCTION UVvar at V(xin,i,j,k,intsrce,intdest,outflag)
REAL :: UVvar at V
File
array interp.f90
Type
Module function
Purpose
Interpolate a UV-node variable to a V-nodal point.
Reference
Section 8.2
Arguments
0: all points
intdest Selects valid points at the source node
0: all points
1: coastal boundaries, interior points and open
UVvar at V Interpolated value at the V-node destination point
UWvar at U
FUNCTION UWvar at U(xin,i,j,k,intsrce,intdest,outflag)
REAL :: UWvar at U
File
array interp.f90
Type
Module function
Purpose
Interpolate a UW-node variable to a U-nodal point.
Reference
Section 8.2
Arguments
only
only
UWvar at U Interpolated value at the U-node destination point
UWvar at W
FUNCTION UWvar at W(xin,i,j,k,intsrce,outflag)
REAL :: UWvar at W
File
array interp.f90
Type
Module function
Purpose
Interpolate a UW-node variable to a W-nodal point.
Reference
Section 8.2
Arguments
only
UWvar at W Interpolated value at the W-node destination point
Vvar at C
FUNCTION Vvar at C(xin,i,j,k,intsrce,intdest,outflag)
REAL :: Vvar at C
File
array interp.f90
Type
Module function
Purpose
Interpolate a V-node variable to a C-nodal point.
Reference
Section 8.2
Arguments
0: all points
only
0: all points
1: wet points only
Vvar at C Interpolated value at the C-node destination point
Vvar at U
FUNCTION Vvar at U(xin,i,j,k,intsrce,intdest,outflag,hregular)
REAL :: Vvar at U
File
array interp.f90
Type
Module function
Purpose
Interpolate a V-node variable to a U-nodal point.
Reference
Section 8.2
Arguments
0: all points
only
0: all points
only
iopt arrint hreg.
Vvar at U Interpolated value at the U-node destination point
Vvar at UV
FUNCTION Vvar at UV(xin,i,j,k,intsrce,intdest,outflag,hregular)
REAL :: Vvar at UV
File
array interp.f90
Type
Module function
Purpose
Interpolate a V-node variable to a UV-nodal point.
Reference
Section 8.2
Arguments

0: all points
only
0: all points
2: interior points and UV-open boundaries only
iopt arrint hreg.
Vvar at UV Interpolated value at the UV-node destination point
Vvar at VW
FUNCTION Vvar at VW(xin,i,j,k,intsrce,intdest,outflag,vregular)
REAL :: Vvar at VW
File
array interp.f90
Type
Module function
Purpose
Interpolate a V-node variable to a VW-nodal point.
Reference
Section 8.2
Arguments
only
only

iopt arrint vreg.
Vvar at VW Interpolated value at the VW-node destination point
Vvar at W
FUNCTION Vvar at W(xin,i,j,k,intsrce,outflag,vregular)
REAL :: Vvar at W
File
array interp.f90
Type
Module function
Purpose
Interpolate a V-node variable to a W-nodal point.
Reference
Section 8.2
Arguments
only

iopt arrint vreg.
Vvar at W Interpolated value at the W-node destination point
VWvar at V
FUNCTION VWvar at V(xin,i,j,k,intsrce,intdest,outflag)
REAL :: VWvar at V
File
array interp.f90
Type
Module function
Purpose
Interpolate a VW-node variable to a V-nodal point.
Reference
Section 8.2
Arguments
only
only

VWvar at V Interpolated value at the V-node destination point
VWvar at W
FUNCTION VWvar at W(xin,i,j,k,intsrce,outflag)
REAL :: VWvar at W
File
array interp.f90
Type
Module function
Purpose
Interpolate a VW-node variable to a W-nodal point.
Reference
Section 8.2
Arguments
only
VWvar at W Interpolated value at the W-node destination point
Wvar at C
FUNCTION Wvar at C(xin,i,j,outflag)
INTEGER, INTENT(IN) :: i, j
REAL :: Wvar at C
File
array interp.f90
Type
Module function
Purpose
Interpolate a W-node variable to a C-nodal point.
Reference
Section 8.2
Arguments
Wvar at C Interpolated value at the C-node destination point
Wvar at U
FUNCTION Wvar at U(xin,i,j,k,intdest,outflag,hregular)
REAL :: Wvar at U
File
array interp.f90
Type
Module function
Purpose
Interpolate a W-node variable to a U-nodal point.
Reference
Section 8.2
Arguments
only
iopt arrint hreg.
Wvar at U Interpolated value at the U-node destination point
Wvar at UW
FUNCTION Wvar at UW(xin,i,j,k,intdest,outflag,hregular)
REAL :: Wvar at UW
File
array interp.f90
Type
Module function
Purpose
Interpolate a W-node variable to a UW-nodal point.
Reference
Section 8.2
Arguments
only
iopt arrint hreg.
Wvar at UW Interpolated value at the UW-node destination point
Wvar at V
FUNCTION Wvar at V(xin,i,j,k,intdest,outflag,hregular)
REAL :: Wvar at V
File
array interp.f90
Type
Module function
Purpose
Interpolate a W-node variable to a V-nodal point.
Reference
Section 8.2
Arguments
only
iopt arrint hreg.
Wvar at V Interpolated value at the V-node destination point
Wvar at VW
FUNCTION Wvar at VW(xin,i,j,k,intdest,outflag,hregular)
REAL :: Wvar at VW
File
array interp.f90
Type
Module function
23.2. NETCDF ROUTINE LIBRARY 865
Purpose
Interpolate a W-node variable to a VW-nodal point.
Reference
Section 8.2
Arguments
only
iopt arrint hreg.
Wvar at VW Interpolated value at the VW-node destination point
23.2 NetCDF routine library

The purpose is to provide “aliases” for each routine of the netCDF library. In
this way, a future upgrade to a newer version of netCDF can be implemented
within this file without affecting the other parts of the COHERENS source
code to a large extent. The implemented version of netCDF is compatible
with versions no earlier than 3.6.
The alias of a netCDF routine, whose name starts with NF90 , has the
prefix cf90 in its name.
cf90 abort
SUBROUTINE cf90 abort(ncid)
INTEGER, INTENT(IN) :: ncid
File
cf90 routines.F90
Type
Module subroutine
Purpose
Aborts a netCDF routine call in case an error has been detected. This
will be followed by an abortion of the program.
Arguments
ncid netCDF file ID
netcdf call
NF90 abort
cf90 close
SUBROUTINE cf90 close(ncid)
File
cf90 routines.F90
Type
Module subroutine
Purpose
Closes an open netCDF data file.
Arguments
ncid netCDF file ID
netcdf call
NF90 close
cf90 copy att

SUBROUTINE cf90 copy att(ncid in,varid in,name,ncid out,varid out)
CHARACTER (LEN=*), INTENT(IN) :: name
INTEGER, INTENT(IN) :: ncid in, ncid out, varid in, varid out
File
cf90 routines.F90
Type
Module subroutine
Purpose
Copies the attribute of variable in a netCDF file to the attribute of
another variable attribute in another file.
Arguments
ncid in netCDF ID of the source file
varid in netCDF variable ID in the source file
name Atrribute name
ncid out netCDF ID of destination file
varid out netCDF variable ID in the destination file
netcdf call
NF90 copy att
cf90 create
SUBROUTINE cf90 create(path,cmode,ncid,initialsize,chunksize)
CHARACTER (LEN=*), INTENT(IN) :: path
INTEGER, INTENT(IN) :: cmode
INTEGER, INTENT(OUT) :: ncid
INTEGER, INTENT(IN), OPTIONAL :: initialsize
INTEGER, INTENT(INOUT), OPTIONAL :: chunksize
File
cf90 routines.F90
Type
Module subroutine
Purpose
Opens a new netCDF file.
Reference
NetCDF user manual (Pincus & Rew, 2008)
Arguments
path Name of the new netCDF file
cmode Creation mode
ncid netCDF file ID

initialsize Initial file size in bytes
chunksize Chunksize
netcdf call
NF90 create
cf90 def dim

SUBROUTINE cf90 def dim(ncid,name,len,dimid)
INTEGER, INTENT(IN) :: len, ncid
INTEGER, INTENT(OUT) :: dimid
File
cf90 routines.F90
Type
Module subroutine
Purpose
Adds a new dimension to an open netCDF file.
Arguments
ncid netCDF file ID
name Name of the new dimension
len Value (length) of the new dimension
dimid Returned netCDF ID of the new dimension.
netcdf call
NF90 def dim
cf90 def var

SUBROUTINE cf90 def var(ncid,name,xtype,dimids,varid)
INTEGER, INTENT(IN) :: ncid, xtype
INTEGER, INTENT(OUT) :: varid
INTEGER, INTENT(IN), DIMENSION(:) :: dimids
File
cf90 routines.F90
Type
Module subroutine
Purpose
Adds a new variable to an open netCDF file.
Arguments
ncid netCDF file ID
name Name of the new variable
xtype Variables’s netCDF data type
dimids The netCDF IDs of the variable’s dimensions.
varid Returned netCDF variable ID
netcdf call
NF90 def var
cf90 del att

SUBROUTINE cf90 del att(ncid,varid,name)
INTEGER, INTENT(IN) :: ncid, varid
File
cf90 routines.F90
Type
Module subroutine
Purpose
Deletes a attribute from a netCDF file.
Arguments
ncid netCDF file ID
varid netCDF ID of the attribute’s variable, NF GLOBAL (global NF90)
for a global attribute
name Name of the attribute
netcdf call
NF90 del att
cf90 enddef
SUBROUTINE cf90 enddef(ncid,h minfree,v align,v minfree,r align)
INTEGER, INTENT(IN), OPTIONAL :: h minfree, r align, v align, v minfree
File
cf90 routines.F90
Type
Module subroutine
Purpose
Take an open netCDF dataset out of define mode.
Reference
Arguments
ncid netCDF file ID
h minfree Size in bytes of the pad at the end of the header
v align Alignment of the start of the data section for fixed size
variables
v minfree Size in bytes of the pad at the end of the data section for
fixed size variables
r align Alignment of the start of the data section in case of an
unlimited dimension
netcdf call
NF90 enddef
cf90 error
SUBROUTINE cf90 error(cf90name)
CHARACTER (LEN=*), INTENT(IN) :: cf90name
File
cf90 routines.F90
Type
Module subroutine
Purpose
Report an error in a netCDF routine.
Arguments
cf90name Name of the netCDF routine where the error occurred.
netcdf call
NF90 strerror
cf90 get att chars

SUBROUTINE cf90 get att chars(ncid,varid,name,lenstr,chardat)
INTEGER, INTENT(IN) :: ncid, lenstr, varid
CHARACTER (LEN=lenstr), INTENT(OUT) [,DIMENSION(:)] :: chardat
File
cf90 routines.F90
Type
Generic module subroutine
Purpose
Get the string value of a scalar or vector character-valued attribute.
Arguments
ncid netCDF file ID
varid netCDF ID of the attribute’s variable, NF GLOBAL
(global NF90) for a global attribute
lenstr Length of the scalar or vector string data
chardat Attribute values
Non-generic versions
cf90 get att chars 0d Scalar string values
cf90 get att chars 1d Vector string values
netcdf call
NF90 get att
cf90 get att

SUBROUTINE cf90 get att(ncid,varid,name,values)
INTEGER or REAL, INTENT(OUT)[, DIMENSION[:] :: values
File
cf90 routines.F90
Type
Purpose
Read the numeric value of a scalar or vector attribute.
Arguments
ncid netCDF file ID
varid Id of the attribute’s variable, NF GLOBAL (global NF90)
for a global attribute
values Attribute values
cf90 get att int 0d Scalar integer values
cf90 get att int 1d Vector integer values
cf90 get att real 0d Scalar real values
cf90 get att real 1d Vector real values
netcdf call
NF90 get att
cf90 get var chars

SUBROUTINE cf90 get att(ncid,varid,chardat,timerec)
INTEGER, INTENT(IN) :: ncid, timerec, varid
CHARACTER (LEN=*), INTENT(OUT) :: chardat
File
cf90 routines.F90
Type
Module subroutine
Purpose
Read a string variable from an open netCDF file.
Arguments
ncid netCDF file ID
chardat Returned string value
timerec Time record number
netcdf call
NF90 get var
cf90 get var

SUBROUTINE cf90 get var(ncid,varid,values,timerec,start,&
& count,stride)
INTEGER, INTENT(IN), OPTIONAL, DIMENSION([rank of values]) :: &
& count, start, stride
INTEGER or REAL, INTENT(OUT)[, DIMENSION[:[,:[,:[,:]]]]] :: values
File
cf90 routines.F90
Type
Purpose
Read an integer or real scalar or array (upto rank 4) variable from an
open netCDF file.
Arguments
ncid netCDF file ID
varid Variable ID
values Returned integer or real scalar of array data
start Vector of spatial start indices

count Number of data along each array dimension
stride Sampling interval along each spatial direction
The size of the optional start, count, stride arguments must be equal to
rank of the returned data array.
cf90 get var int 0d Scalar integer values. The optional arguments are
not available.
cf90 get var int 1d Vector integer values
cf90 get var int 2d 2-D array of integer values
cf90 get var real 0d Scalar real values. The optional arguments are not
available.
cf90 get var real 1d Vector real values
cf90 get var real 2d 2-D array of real values
netcdf call
NF90 get var
cf90 inq attname

SUBROUTINE cf90 inq attname(ncid,varid,attnum,name)
CHARACTER (LEN=*), INTENT(OUT) :: name
INTEGER, INTENT(IN) :: attnum, ncid, varid
File
cf90 routines.F90
Type
Module subroutine
Purpose
Returns the name of an attribute given its variable ID and number.
Arguments
ncid netCDF file ID

varid Id of the associated variable
attnum Attribute number
name Attribute name
netcdf call
NF90 inq attname
cf90 inq dimid

SUBROUTINE cf90 inq dimid(ncid,name,dimid)
INTEGER, INTENT(OUT) :: dimid
File
cf90 routines.F90
Type
Module subroutine
Purpose
Returns the dimension ID given the dimension’s name.
Arguments
ncid netCDF file ID
name Dimension name
dimid Returned netCDF dimension ID
netcdf call
NF90 inq dimid
cf90 inq libvers

FUNCTION cf90 inq libvers()
CHARACTER (LEN=80) :: cf90 inq libvers
File
cf90 routines.F90
Type
Module function
Purpose
Returns the netCDF library version.
netcdf call
NF90 inq libvers
cf90 inq varid

SUBROUTINE cf90 inq varid(ncid,name,varid)
INTEGER, INTENT(OUT) :: varid
File
cf90 routines.F90
Type
Module subroutine
Purpose
Returns the ID of a netCDF variable given its name.
Arguments
ncid netCDF file ID
name Variable name
varid Returned netCDF variable ID
netcdf call
NF90 inq varid
cf90 inquire
SUBROUTINE cf90 inquire(ncid,ndimensions,nvariables,&
& nattributes,unlimiteddimid)
INTEGER, INTENT(OUT), OPTIONAL :: nattributes, ndimensions,&
& nvariables, unlimiteddimid
File
cf90 routines.F90
Type
Module subroutine
Purpose
Returns information about an open netCDF file given its netCDF file
ID.
Arguments
ncid netCDF file ID
ndimensions Returned number of dimensions
nvariables Returned number of variables
nattributes Returned number of global attributes
unlimiteddimid Returned netCDF ID of the unlimited dimension (if any)
netcdf call
NF90 inquire
cf90 inquire attribute

SUBROUTINE cf90 inquire attribute(ncid,varid,name,xtype,len,attnum)
INTEGER, INTENT(OUT), OPTIONAL :: attnum, len, xtype
File
cf90 routines.F90
Type
Module subroutine
Purpose
Returns information about a netCDF attribute.
Arguments
ncid netCDF file ID
varid netCDF ID of the associated variable
name Attribute name
xtype Returned netCDF data type of the attribute
len Returned number of values stored in the attribute
attnum Returned attribute number
netcdf call
NF90 inquire attribute
cf90 inquire dimension

SUBROUTINE cf90 inquire dimension(ncid,dimid,name,len)
INTEGER, INTENT(IN) :: dimid, ncid
CHARACTER (LEN=*), INTENT(OUT), OPTIONAL :: name
INTEGER, INTENT(OUT), OPTIONAL :: len
File
cf90 routines.F90
Type
Module subroutine
Purpose
Returns information about a netCDF dimension.
Arguments
ncid netCDF file ID
dimid netCDF dimension ID
name Returned dimension name
len Returned dimension length
netcdf call
NF90 inquire dimension
cf90 inquire variable

SUBROUTINE cf90 inquire variable(ncid,varid,name,xtype,&
& ndims,dimids,natts)
CHARACTER (LEN=*), INTENT(OUT), OPTIONAL :: name
INTEGER, INTENT(OUT), OPTIONAL :: natts, ndims, xtype
INTEGER, INTENT(OUT), OPTIONAL, DIMENSION(:) :: dimids
File
cf90 routines.F90
Type
Module subroutine
Purpose
Returns information about a netCDF variable.
Arguments
ncid netCDF file ID
varid netCDF variable ID
name Returned variable name
xtype Returned netCDF data type
ndims Returned variable rank
dimids Returned netCDF IDs of the variable’s dimensions
natts Returned number of associated attributes
netcdf call
NF90 inquire variable
cf90 open
SUBROUTINE cf90 open(path,mode,ncid,chunksize)
CHARACTER (LEN=*), INTENT(IN) :: path
INTEGER, INTENT(IN) :: mode
INTEGER, INTENT(OUT) :: ncid
INTEGER, INTENT(INOUT), OPTIONAL :: chunksize
File
cf90 routines.F90
Type
Module subroutine
Purpose
Opens an existing netCDF dataset.
Reference
Arguments
path Name of the netCDF file
mode Access mode
ncid netCDF file ID
chunksize Chunksize
netcdf call
NF90 open
cf90 put att chars

SUBROUTINE cf90 put att chars(ncid,varid,name,lenstr,chardat)
INTEGER, INTENT(IN) :: lenstr, ncid, varid
CHARACTER (LEN=lenstr), INTENT(IN) [,DIMENSION(:)] :: chardat
File
cf90 routines.F90
Type
Purpose
Write or change the value of a scalar or vector character-valued at-
tribute.
Arguments
ncid netCDF file ID
lenstr Length of the scalar or vector string data
chardat Attribute values
cf90 put att chars 0d Scalar string values
cf90 put att chars 1d Vector string values
netcdf call
NF90 put att
cf90 put att

SUBROUTINE cf90 put att(ncid,varid,name,values)
INTEGER or REAL, INTENT(OUT)[, DIMENSION[:]] :: values
File
cf90 routines.F90
Type
Purpose
Write the numeric value of a scalar or vector attribute to an open
netCDF file.
Arguments
ncid netCDF file ID
varid ID of the attribute’s variable, NF GLOBAL
values Attribute values
cf90 put att int 0d Scalar integer values
cf90 put att int 1d Vector integer values
cf90 put att real 0d Scalar real values
cf90 put att real 1d Vector real values
netcdf call
NF90 put att
cf90 put var chars

SUBROUTINE cf90 put var chars(ncid,varid,chardat,timerec)
CHARACTER (LEN=*), INTENT(IN) :: chardat
File
cf90 routines.F90
Type
Module subroutine
Purpose
Write a string variable to an open netCDF file.
Arguments
ncid netCDF file ID
varid Variable ID
chardat Character output data
netcdf call
NF90 put var
cf90 put var

SUBROUTINE cf90 put var(ncid,varid,values,timerec,start,&
& count,stride)
INTEGER, INTENT(IN), OPTIONAL, DIMENSION([rank of values]) :: &
& count, start, stride
INTEGER or REAL, INTENT(OUT)[, DIMENSION[:[,:[,:[,:]]]] :: values
File
cf90 routines.F90
Type
Purpose
Write an integer or real scalar or array (upto rank 4) variable to an
open netCDF file.
Arguments
ncid netCDF file ID
varid Variable ID
values Integer or real, scalar or array output data
start Vector of spatial start indices
count Number of data along each array dimension
stride Sampling interval along each spatial direction
The size of the optional start, count, stride arguments must be equal to
rank of the output data array.
cf90 put var int 0d Scalar integer values. The optional arguments are
not available.
cf90 put var int 1d Vector integer values

cf90 put var int 2d 2-D array of integer values
cf90 put var real 0d Scalar real values. The optional arguments are not
available.
cf90 put var real 1d Vector real values
cf90 put var real 2d 2-D array of real values
netcdf call
NF90 put var
cf90 redef
SUBROUTINE cf90 redef(ncid)
File
cf90 routines.F90
Type
Module subroutine
Purpose
Puts an open netCDF file in define mode.
Arguments
ncid netCDF file ID
netcdf call
NF90 redef
cf90 rename att

SUBROUTINE cf90 rename att(ncid,varid,curname,newname)
CHARACTER (LEN=*), INTENT(IN) :: curname, newname
File
cf90 routines.F90
Type
Module subroutine
Purpose
Renames an existing attribute.
Arguments
ncid netCDF file ID
varid netCDF ID of the associated variable or NF GLOBAL
curname current name of the attribute
newname new name of the attribute
netcdf call
NF90 rename att
cf90 rename dim

SUBROUTINE cf90 rename dim(ncid,dimid,name)
CHARACTER (LEN=*), INTENT(OUT) :: name
INTEGER, INTENT(IN) :: dimid, ncid
File
cf90 routines.F90
Type
Module subroutine
Purpose
Renames an existing dimension.
Arguments
ncid netCDF file ID
dimid the dimension’s netCDF ID
name new dimension name
netcdf call
NF90 rename dim
cf90 rename var

SUBROUTINE cf90 rename var(ncid,varid,newname)
CHARACTER (LEN=*), INTENT(OUT) :: newname
File
cf90 routines.F90
Type
Module subroutine
Purpose
Changes the name of an existing variable.
Arguments
ncid netCDF file ID
varid the variable’s netCDF ID
newname new variable name
netcdf call
NF90 rename var
cf90 set fill

SUBROUTINE cf90 set fill(ncid,fillmode,old mode)
INTEGER, INTENT(IN) :: fillmode, ncid
INTEGER, INTENT(OUT) :: old mode
File
cf90 routines.F90
Type
Module subroutine
Purpose
Resets the fill mode for a netCDF dataset open for writing.
Arguments
ncid netCDF file ID
fillmode New fill mode for the netCDF file
old mode Returned old fill mode of the netCDF file
netcdf call
NF90 set fill
cf90 sync
SUBROUTINE cf90 sync(ncid)
File
cf90 routines.F90
Type
Module subroutine
Purpose
Resets the fill mode for a netCDF dataset open for writing.
Arguments
ncid netCDF file ID
netcdf call
NF90 sync
23.3 Checking of model setup

Checks all kind of model setup for possible errors. One or more error messages
are written followed by a program abort.
check grid arrays

SUBROUTINE check grid arrays
File
check model.f90
Type
Module subroutine
Purpose
Check model grid arrays, as e.g. defined in usrdef grid.
23.3. CHECKING OF MODEL SETUP 887
check hrel coords

SUBROUTINE check hrel coords(hcoords,nhdat,varname)
CHARACTER (LEN=*), INTENT(IN) :: varname
INTEGER, INTENT(IN) :: nhdat
TYPE (HRelativeCoords), INTENT(IN), DIMENSION(nhdat) :: hcoords
File
check model.f90
Type
Module subroutine
Purpose
Check an derived type array with the horizontal relative coordinates of
a number of data points with respect to the model grid.
Arguments
hcoords Derived type array containing the relative coordinates
nhdat Number of horizontal data locations.
varname Name of the derived type array
check initial conditions

SUBROUTINE check initial conditions
File
check model.f90
Type
Module subroutine
Purpose
Check initial condition arrays, as e.g. defined in usrdef phsics.
check mod filepars

SUBROUTINE check mod filepars
File
check model.f90
Type
Module subroutine
Purpose
Check the attributes of model forcing files, as e.g. defined in usrdef mod params.
check mod params

SUBROUTINE check mod params
File
check model.f90
Type
Module subroutine
Purpose
Check model setup parameters (switches, date and time, physical model
parameters, . . . ), as e.g. defined in usrdef mod params.
check out filepars

SUBROUTINE check out filepars(filepars,arrname,maxvars)
CHARACTER (LEN=*), INTENT(IN) :: arrname
INTEGER, INTENT(IN), OPTIONAL :: maxvars
TYPE (FileParams), INTENT(INOUT), DIMENSION(:[,:]) :: filepars
File
check model.f90
Type
Purpose
Check the attributes of user-defined output files.
Arguments
filepars Derived type array of file attributes
arrname Name of the derived type array
maxvars Maximum allowed number of variables in the file
check out filepars 1d Vector array
check out filepars 2d Two-dimensional array
23.3. CHECKING OF MODEL SETUP 889
check out gpars

SUBROUTINE check out gpars(outgpars,arrname,maxstats)
CHARACTER (LEN=*) :: arrname
INTEGER, INTENT(IN) :: maxstats
TYPE (OutGridParams), INTENT(IN), DIMENSION(:) :: outgpars
File
check model.f90
Type
Module subroutine
Purpose
Check the attributes of user-defined output grids.
Arguments
outgpars Derived type array of output grid attributes
maxstats Maximum number of output stations (as given by the user-
defined parameter nostatstsr, nostatsavr or nostatsanal)
check partition
SUBROUTINE check partition
File
check model.f90
Type
Module subroutine
Purpose
Check whether all wet and open boundary points are inside the domain
of a local process.
check statlocs
SUBROUTINE check statlocs(outlocs,arrname)
TYPE (StationLocs), INTENT(IN), DIMENSION(:) :: outlocs
File
check model.f90
Type
Module subroutine
Purpose
Check whether the stations locations are inside the computational do-
main.
Arguments
outlocs Derived type array of output station attributes
check surface grid

SUBROUTINE check surface grid(surfgrid,n1dat,n2dat,varname)
INTEGER, INTENT(IN) :: n1dat, n2dat
TYPE (HReleativeCoords), INTENT(INOUT), DIMENSION(:[,:]) :: surfgrid
File
check model.f90
Type
Purpose
Check the relative coordinates of model grid points with respect to an
external data grid.
Arguments
surfgrid Derived type array containing the relative coordinates
n1dat X-dimension of the external data grid
n2dat Y-dimension of the external data grid
varname Name of the derived type array
check surface grid 1d Vector array
check surface grid 2d Two-dimensional array
23.4. CIF UTILITY ROUTINES 891
check variables
SUBROUTINE check variables(varatts,arrname)
TYPE (VariableAtts), INTENT(IN), DIMENSION(:) :: varatts
File
check model.f90
Type
Module subroutine
Purpose
Check a derived type vector array with variable attributes.
Arguments
varatts Derived type array of variable attributes
23.4 CIF utility routines

Ensemble of routines for reading data to or converting data from a central
input file.
check cif lbound vars

SUBROUTINE check cif lbound novars(iddesc,novars,novarsmin)
INTEGER, INTENT(IN) :: iddesc, novars, novarsmin
File
cif routines.f90
Type
Module subroutine
Purpose
Check whether the number of parameters on the input line of a CIF is
not lower than a minimum limit.
Arguments
novars Number of data values read from a line of the CIF
novarsmin Minimum number of data values to be extracted from the

input line.
conv from chars

SUBROUTINE conv from chars(string,cifdat,iddesc,lvar)
CHARACTER (LEN=*), INTENT(IN) :: string
CHARACTER (LEN=*), INTEGER, LOGICAL, or REAL, INTENT(OUT) :: cifdat
INTEGER, INTENT(INOUT) :: lvar
File
cif routines.f90
Type
Purpose
Convert a data value from the CIF into the appropriate numerical or
non-numerical format.
Arguments
string Data value in character format on input
cifdat Returned data value in numerical (INTEGER or REAL) or
non-numerical (LOGICAL or CHARACTER) format
lvar Number of the variable on the CIF input line
conv from chars chars Convert to a character string
conv from chars int Convert to an integer value
conv from chars log Convert to a logical value
conv from chars real Convert to a real value
conv from chars gridpars

SUBROUTINE conv from chars gridpars(cvals,gridpars,iddesc,lvar)
CHARACTER (LEN=*), INTENT(IN), DIMENSION(20) :: cvals
TYPE (OutGridParams), INTENT(INOUT) :: gridpars
File
cif routines.f90
Type
Module subroutine
Purpose
Convert data values from the CIF to the components of a derived type
variable of type OutGridParams, representing a user-defined output grid.
Arguments
cvals CIF data in string format
gridpars Returned components in the appropriate numerical or non-
numerical format
conv from chars infiles

SUBROUTINE conv from chars infiles(cvals,filepars,iddesc,lvar)
TYPE (FileParams), INTENT(INOUT) :: filepars
File
cif routines.f90
Type
Module subroutine
Purpose
variable of type FileParams, representing a model forcing file.
Arguments
filepars Returned components in the appropriate numerical or non-
numerical format
conv from chars outfiles

SUBROUTINE conv from chars outfiles(cvals,filepars,iddesc,lvar)
File
cif routines.f90
Type
Module subroutine
Purpose
variable of type FileParams, representing a user output file.
Arguments
filepars Returned components in the appropriate numerical or non-
numerical format
conv from chars statlocs

SUBROUTINE conv from chars statlocs(cvals,statlocs,iddesc,lvar)
TYPE (StationLocs), INTENT(INOUT) :: statlocs
File
cif routines.f90
Type
Module subroutine
Purpose
variable of type StationLocs, representing output data stations.
Arguments
statlocs Returned components in the appropriate numerical or non-
numerical format
conv from chars surfgrd

SUBROUTINE conv from chars statlocs(cvals,surfgrd,iddesc,lvar)
TYPE (GridParams), INTENT(INOUT) :: surfgrd
File
cif routines.f90
Type
Module subroutine
Purpose
variable of type GridParams, representing a surface grid.
Arguments
surfgrd Returned components in the appropriate numerical or non-
numerical format
conv from chars varatts

SUBROUTINE conv from chars varatts(cvals,varatts,iddesc,lvar)
TYPE (VariableAtts), INTENT(INOUT) :: varatts
File
cif routines.f90
Type
Module subroutine
Purpose
variable of type VariableAtts.
Arguments
varatts Returned components in the appropriate numerical or non-
numerical format
conv to chars
SUBROUTINE conv to chars(string,cifdat)
CHARACTER (LEN=*), INTENT(OUT) :: string
INTEGER, LOGICAL or REAL, [DIMENSION(:),] INTENT(IN) :: cifdat
File
cif routines.f90
Type
Purpose
Convert a INTEGER, LOGICAL or REAL scalar or vector model variable
to a character string.
Arguments
string Returned data string
cifdat Scalar or vector data on input
conv to chars int 0d Integer scalar
conv to chars int 1d Integer vector
conv to chars log 0d Logical scalar
conv to chars log 1d Logical vector

conv to chars real 0d Real scalar
conv to chars real 1d Real vector
conv to chars gridpars

SUBROUTINE conv to chars gridpars(cvals,gridpars)
CHARACTER (LEN=*), INTENT(OUT), DIMENSION(20) :: cvals
TYPE (OutGridParams), INTENT(IN) :: gridpars
File
cif routines.f90
Type
Module subroutine
Purpose
Convert the attributes of a user-defined output grid to a vector of string
data.
Arguments
cvals Returned data in string format
gridpars Attributes of the output grid
conv to chars infiles

SUBROUTINE conv to chars infiles(cvals,filepars)
TYPE (FileParams), INTENT(IN) :: filepars
File
cif routines.f90
Type
Module subroutine
Purpose
Convert the attributes of a model forcing file to a vector of string data.
Arguments
filepars Attributes of the forcing file
conv to chars outfiles

SUBROUTINE conv to chars outfiles(cvals,filepars)
File
cif routines.f90
Type
Module subroutine
Purpose
Convert the attributes of a usder-defined output file to a vector of string
data.
Arguments
filepars Attributes of the output file
conv to chars statlocs

SUBROUTINE conv to chars statlocs(cvals,statlocs)
TYPE (StationLocs), INTENT(IN) :: statlocs
File
cif routines.f90
Type
Module subroutine
Purpose
Convert the attributes of a user-defined output station to a vector of
string data.
Arguments
statlocs Attributes of the output station
conv to chars surfgrd

SUBROUTINE conv to chars surfgrd(cvals,surfgrd)
TYPE (GridParams), INTENT(IN) :: surfgrd
File
cif routines.f90
Type
Module subroutine
Purpose
Convert the attributes of a surface grid to a vector of string data.
Arguments

surfgrd Attributes of the surface grid
conv to chars varatts

SUBROUTINE conv to chars varatts(cvals,varatts)
TYPE (VariableAtts), INTENT(IN) :: varatts
File
cif routines.f90
Type
Module subroutine
Purpose
Convert the attributes of a model variable to a vector of string data.
Arguments

varatts Attributes of the variable
error cif var

SUBROUTINE error cif var(iddesc,lvar)
INTEGER, INTENT(IN) :: iddesc, lvar
File
cif routines.f90
Type
Module subroutine
Purpose
Write an error message if a variable in a CIF cannot be read
Arguments
read cif line

SUBROUTINE read cif line(iddesc,cline,cvals,numvars,cname)
CHARACTER (LEN=lencifline), INTENT(INOUT) :: cline
CHARACTER (LEN=lenname), INTENT(OUT), OPTIONAL :: cname
CHARACTER (LEN=lencifvar), INTENT(OUT), DIMENSION(:) :: cvals
INTEGER, INTENT(OUT) :: numvars
File
cif routines.f90
Type
Module subroutine
Purpose
Parse a series of variables, separated by a delimiter as character data
on a data input line
Arguments
cline Input line string
cvals Returned data value(s) in string format
numvars Returned number of data variable(s)
cname Returned name of the data variable(s) (if requested)
23.5. MPI ROUTINE LIBRARY 901
write cif line

SUBROUTINE write cif line(iddesc,cvals,cname)
CHARACTER (LEN=*), INTENT(IN) :: cname
CHARACTER (LEN=*), INTENT(INOUT), DIMENSION(:) :: cvals
File
cif routines.f90
Type
Module subroutine
Purpose
Write one or more string data to a CIF
Arguments
cvals Data value(s) in string format
cname Name of the data variable(s)
23.5 MPI routine library

The purpose is to provide “aliases” for the routines of the MPI library, used in
the present version of the program. In this way, a future upgrade to a newer
version of MPI can be implemented within this file without affecting the other
parts of the COHERENS source code to much. The current implemented
version of MPI is Version 1.1. For a detailed description of the MPI library
routines see (MPI, 1995).
comms allgather int

SUBROUTINE comms allgather int(sendbuf,count,nprocs,recvbuf,&
& comm,ivarid)
INTEGER, INTENT(IN) :: comm, count, ivarid, nprocs
INTEGER, INTENT(IN), DIMENSION(count) :: sendbuf
INTEGER, INTENT(OUT), DIMENSION(count,nprocs) :: recvbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Gather (collect) integer data on all processes in communicator comm.
Arguments
sendbuf Starting address of send buffer
count Number of data in send and receive buffers
nprocs Number of processes
recvbuf Starting address of receive buffer
comm Communicator id
MPI call
MPI allgather
comms allgather log

SUBROUTINE comms allgather log(sendbuf,count,nprocs,recvbuf,&
& comm,ivarid)
LOGICAL, INTENT(IN), DIMENSION(count) :: sendbuf
LOGICAL, INTENT(OUT), DIMENSION(count,nprocs) :: recvbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Gather (collect) logical data on all processes in communicator comm.
Arguments
MPI call
MPI allgather
comms allgather real

SUBROUTINE comms allgather log(sendbuf,count,nprocs,recvbuf,&
& comm,ivarid)
REAL, INTENT(IN), DIMENSION(count) :: sendbuf
REAL, INTENT(OUT), DIMENSION(count,nprocs) :: recvbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Gather (collect) real data on all processes in communicator comm.
Arguments
MPI call
MPI allgather
comms barrier
SUBROUTINE comms barrier(comm)
INTEGER, INTENT(IN) :: comm
File
comms MPI.F90
Type
Module subroutine
Purpose
Synchronise processes in communicator comm.
Arguments
MPI call
MPI barrier
comms bcast char

SUBROUTINE comms bcast char(cbuf,count,root,comm,ivarid)
INTEGER, INTENT(IN) :: comm, count, ivarid, root
CHARACTER, INTENT(INOUT), DIMENSION(count) :: cbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Broadcast (copy) character data from the root process to all other pro-
cesses in communicator comm.
Arguments
cbuf Starting address of buffer

root Process id of root process
MPI call
MPI bcast
comms bcast int

SUBROUTINE comms bcast int(ibuf,count,root,comm,ivarid)
INTEGER, INTENT(INOUT), DIMENSION(count) :: ibuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Broadcast (copy) integer data from the root process to all other pro-
Arguments
ibuf Starting address of buffer
MPI call
MPI bcast
comms bcast log

SUBROUTINE comms bcast log(lbuf,count,root,comm,ivarid)
LOGICAL, INTENT(INOUT), DIMENSION(count) :: lbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Broadcast (copy) logical data from the root process to all other pro-
Arguments
lbuf Starting address of buffer

MPI call
MPI bcast
comms bcast real

SUBROUTINE comms bcast real(rbuf,count,root,comm,ivarid)
REAL, INTENT(INOUT), DIMENSION(count) :: rbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Broadcast (copy) real data from the root process to all other processes
in communicator comm.
Arguments
rbuf Starting address of buffer
MPI call
MPI bcast
comms comm free

SUBROUTINE comms comm free(comm)
INTEGER, INTENT(INOUT) :: comm
File
comms MPI.F90
Type
Module subroutine
Purpose
Deallocates (frees) communicator comm.
Arguments
MPI call
MPI comm free
comms comm rank

SUBROUTINE comms comm rank(comm,rank)
INTEGER, INTENT(OUT) :: rank
File
comms MPI.F90
Type
Module subroutine
Purpose
Returns the rank (process id) of the calling process.
Arguments
rank Returned rank
MPI call
MPI comm rank
comms comm size

SUBROUTINE comms comm size(comm,size)
INTEGER, INTENT(OUT) :: size
File
comms MPI.F90
Type
Module subroutine
Purpose
Returns the number of processes in communicator comm.
Arguments
rank Returned number of processes
MPI call
MPI comm size
comms comm split

SUBROUTINE comms comm split(comm,color,key,newcomm)
INTEGER, INTENT(IN) :: color, comm, key
INTEGER, INTENT(OUT) :: newcomm
File
comms MPI.F90
Type
Module subroutine
Purpose
Create a new communicator newcomm by partinioning of communicator
comm.
Arguments
comm Id of existing communicator
color Control parameter for subset assignment
key Control parameter for rank assignment
newcomm Id of new communicator
MPI call
MPI comm split
comms dims create

SUBROUTINE comms dimms create(nnodes,ndims,dims)
INTEGER, INTENT(IN) :: ndims, nnodes
INTEGER, INTENT(INOUT), DIMENSION(ndims) :: dims
File
comms MPI.F90
Type
Module subroutine
Purpose
Create a Cartesian (parallel) grid of dimension ndims and a total of
nnodes nodes and store the domain dimensions in dims.
Arguments
ndims Dimension of the Cartesian grid
nnodes Number of nodes for creating the grid
dims Vector with the number of nodes (processes) per grid di-
rection
MPI call
MPI dims create
comms errhandler
SUBROUTINE comms errhandler(comm)
File
comms MPI.F90
Type
Module subroutine
Purpose
Sets the error handler to MPI errors return.
Arguments
MPI calls
MPI errhandler free, MPI errhandler get, MPI errhandler set
comms finalize
SUBROUTINE comms finalize
File
comms MPI.F90
Type
Module subroutine
Purpose
Finalise MPI.
MPI call
MPI finalize
comms initialise
SUBROUTINE comms initialise
File
comms MPI.F90
Type
Module subroutine
Purpose
Initialise MPI.
MPI calls
MPI init, MPI initialized
comms irecv char

SUBROUTINE comms irecv char(cbuf,count,source,tag,comm,request,ivarid)
INTEGER, INTENT(IN) :: comm, count, ivarid, source, tag
INTEGER, INTENT(OUT) :: request
CHARACTER, INTENT(OUT), DIMENSION(count) :: cbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a non-blocking receive of character data from process source.
Arguments
cbuf Starting address of receive buffer
count Number of data in receive buffer
source Rank of source process
tag Message tag
request Communication request
MPI call
MPI irecv
comms irecv int

SUBROUTINE comms irecv int(ibuf,count,source,tag,comm,request,ivarid)
INTEGER, INTENT(OUT), DIMENSION(count) :: ibuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a non-blocking receive of integer data from process source.
Arguments
ibuf Starting address of receive buffer
tag Message tag
MPI call
MPI irecv
comms irecv log

SUBROUTINE comms irecv int(lbuf,count,source,tag,comm,request,ivarid)
LOGICAL, INTENT(OUT), DIMENSION(count) :: lbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a non-blocking receive of logical data from process source.
Arguments
lbuf Starting address of receive buffer
tag Message tag
MPI call
MPI irecv
comms irecv real

SUBROUTINE comms irecv real(rbuf,count,source,tag,comm,request,ivarid)
REAL, INTENT(OUT), DIMENSION(count) :: rbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a non-blocking receive of real data from process source.
Arguments
rbuf Starting address of receive buffer
tag Message tag
MPI call
MPI irecv
comms isend char

SUBROUTINE comms isend char(cbuf,count,dest,tag,comm,mode,&
& request,ivarid)
INTEGER, INTENT(IN) :: comm, count, dest, ivarid, mode, tag
CHARACTER, INTENT(IN), DIMENSION(count) :: cbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a non-blocking send of character data to process dest.
Arguments
cbuf Starting address of send buffer
count Number of data in send buffer
dest Rank of destination process
tag Message tag
mode Selects type of send
1: standard send
2: synchronous send
MPI calls
MPI isend, MPI issend
comms isend int

SUBROUTINE comms isend int(ibuf,count,dest,tag,comm,mode,&
& request,ivarid)
INTEGER, INTENT(IN), DIMENSION(count) :: ibuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a non-blocking send of integer data to process dest.
Arguments
ibuf Starting address of send buffer
tag Message tag
1: standard send
2: synchronous send
MPI calls
comms isend log

SUBROUTINE comms isend log(lbuf,count,dest,tag,comm,mode,&
& request,ivarid)
LOGICAL, INTENT(IN), DIMENSION(count) :: lbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a non-blocking send of logical data to process dest.
Arguments
lbuf Starting address of send buffer
tag Message tag
1: standard send
2: synchronous send
MPI calls
comms isend real

SUBROUTINE comms isend real(rbuf,count,dest,tag,comm,mode,&
& request,ivarid)

REAL, INTENT(IN), DIMENSION(count) :: rbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a non-blocking send of real data to process dest.
Arguments
rbuf Starting address of send buffer
tag Message tag
1: standard send
2: synchronous send
MPI calls
comms recv char

SUBROUTINE comms recv char(cbuf,count,source,tag,comm,ivarid)
CHARACTER, INTENT(OUT), DIMENSION(count) :: cbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a blocking receive of character data from process source.
Arguments
cbuf Starting address of receive buffer
tag Message tag
MPI call
MPI recv
comms recv int

SUBROUTINE comms recv int(ibuf,count,source,tag,comm,ivarid)
INTEGER, INTENT(OUT), DIMENSION(count) :: ibuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a blocking receive of integer data from process source.
Arguments
ibuf Starting address of receive buffer
tag Message tag
MPI call
MPI recv
comms recv log

SUBROUTINE comms recv log(lbuf,count,source,tag,comm,ivarid)
LOGICAL, INTENT(OUT), DIMENSION(count) :: lbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a blocking receive of logical data from process source.
Arguments
lbuf Starting address of receive buffer
tag Message tag
MPI call
MPI recv
comms recv real

SUBROUTINE comms recv real(rbuf,count,source,tag,comm,ivarid)
REAL, INTENT(OUT), DIMENSION(count) :: rbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a blocking receive of real data from process source.
Arguments
rbuf Starting address of receive buffer

tag Message tag
MPI call
MPI recv
comms reduce int

SUBROUTINE comms reduce int(sendbuf,recvbuf,iop,comm,root,ivarid)
INTEGER, INTENT(IN) :: comm, iop, ivarid
INTEGER, INTENT(IN), OPTIONAL :: root
INTEGER, INTENT(IN) :: sendbuf
INTEGER, INTENT(OUT) :: recvbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a global reduction operation on integer data.
Arguments
sendbuf Address of send buffer
recvbuf Address of receive buffer
iop Type of reduce operation
1 : maximum (MPI max)
2 : minimum (MPI min)
3 : sum (MPI sum)
4 : product (MPI prod)
6 : logical and (MPI band)
8 : bit-wise or (MPI bor)
10: bot-wise xor (MPI bxor)
root Rank of root process to which the result is returned, if
present. Otherwise the result is returned to all processes.
MPI calls
MPI reduce, MPI allreduce
comms reduce 2int

SUBROUTINE comms reduce 2int(sendbuf,recvbuf,iop,comm,root,ivarid)
INTEGER, INTENT(IN), DIMENSION(2) :: sendbuf
INTEGER, INTENT(OUT), DIMENSION(2) :: recvbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a global reduction operation on pairs of integer data.
Arguments
11: maximum value and location (MPI maxloc)
12: minimum value and location (MPI minloc)
MPI calls
comms reduce log

SUBROUTINE comms reduce log(sendbuf,recvbuf,iop,comm,root,ivarid)
LOGICAL, INTENT(IN) :: sendbuf
LOGICAL, INTENT(OUT) :: recvbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a global reduction operation on logical data.
Arguments
5: logical and (MPI land)
7: logical or (MPI lor)
9: logical xor (MPI lxor)
MPI calls
comms reduce real

SUBROUTINE comms reduce real(sendbuf,recvbuf,iop,comm,root,ivarid)
REAL, INTENT(IN) :: sendbuf
REAL, INTENT(OUT) :: recvbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a global reduction operation on real data.
Arguments
1: maximum (MPI max)
2: minimum (MPI min)
3: sum (MPI sum)
4: product (MPI prod)
MPI calls
comms reduce 2real

SUBROUTINE comms reduce 2real(sendbuf,recvbuf,iop,comm,root,ivarid)
REAL, INTENT(IN), DIMENSION(2) :: sendbuf
REAL, INTENT(OUT), DIMENSION(2) :: recvbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a global reduction operation on pairs of real data.
Arguments
11: maximum value and location (MPI maxloc)
12: minimum value and location (MPI minloc)
MPI calls
MPI allreduce, MPI reduce
comms send char

SUBROUTINE comms send char(cbuf,count,dest,tag,comm,mode,ivarid)
CHARACTER, INTENT(IN), DIMENSION(count) :: cbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a blocking send of character data to process dest.
Arguments
cbuf Starting address of send buffer
tag Message tag
1: standard send
2: synchronous send
MPI calls
MPI send, MPI ssend
comms send int

SUBROUTINE comms send int(ibuf,count,dest,tag,comm,mode,ivarid)
INTEGER, INTENT(IN), DIMENSION(count) :: ibuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a blocking send of integer data to process dest.
Arguments
ibuf Starting address of send buffer
tag Message tag
1: standard send
2: synchronous send
MPI calls
MPI send, MPI ssend
comms send log

SUBROUTINE comms send log(lbuf,count,dest,tag,comm,mode,ivarid)
LOGICAL, INTENT(IN), DIMENSION(count) :: lbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a blocking send of logical data to process dest.
Arguments
lbuf Starting address of send buffer
tag Message tag
1: standard send
2: synchronous send
MPI calls
MPI send, MPI ssend
comms send real

SUBROUTINE comms send real(rbuf,count,dest,tag,comm,mode,ivarid)
REAL, INTENT(IN), DIMENSION(count) :: rbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Performs a blocking send of real data to process dest.
Arguments
rbuf Starting address of send buffer

tag Message tag
1: standard send
2: synchronous send
MPI calls
MPI send, MPI ssend
comms sendrecv char

SUBROUTINE comms sendrecv char(sendbuf,sendcount,dest,sendtag,&
& recvbuf,recvcount,source,recvtag,&
& comm,ivarid)
INTEGER, INTENT(IN) :: comm, dest, ivarid, recvcount, recvtag,&
& sendcount, sendtag, source
CHARACTER, INTENT(IN), DIMENSION(sendcount) :: sendbuf
CHARACTER, INTENT(OUT), DIMENSION(recvcount) :: recvbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Combines a send and a receive operation on character data.
Arguments
sendcount Number of data in send buffer
sendtag Message tag of send operation
recvcount Number of data in receive buffer

recvtag Message tag of receive operation
MPI call
MPI sendrecv
comms sendrecv int

SUBROUTINE comms sendrecv int(sendbuf,sendcount,dest,sendtag,&
& comm,ivarid)
INTEGER, INTENT(IN), DIMENSION(sendcount) :: sendbuf
INTEGER, INTENT(OUT), DIMENSION(recvcount) :: recvbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Combines a send and a receive operation on integer data.
Arguments
MPI call
MPI sendrecv
comms sendrecv log

SUBROUTINE comms sendrecv log(sendbuf,sendcount,dest,sendtag,&
& comm,ivarid)
LOGICAL, INTENT(IN), DIMENSION(sendcount) :: sendbuf
LOGICAL, INTENT(OUT), DIMENSION(recvcount) :: recvbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Combines a send and a receive operation on logical data.
Arguments
MPI call
MPI sendrecv
comms sendrecv real

SUBROUTINE comms sendrecv real(sendbuf,sendcount,dest,sendtag,&
& comm,ivarid)

REAL, INTENT(IN), DIMENSION(sendcount) :: sendbuf
REAL, INTENT(OUT), DIMENSION(recvcount) :: recvbuf
File
comms MPI.F90
Type
Module subroutine
Purpose
Combines a send and a receive operation on real data.
Arguments
MPI call
MPI sendrecv
comms waitall
SUBROUTINE comms waitall(count,requests)
INTEGER, INTENT(IN) :: count
INTEGER, INTENT(INOUT), DIMENSION(count) :: requests
File
comms MPI.F90
Type
Module subroutine
Purpose
Complete communications associated with an array of requests.
Arguments
count Number of requests
requests Array of requests
MPI call
MPI waitall
error MPI
SUBROUTINE error MPI(mpiname,abort)
LOGICAL, INTENT(IN), OPTIONAL :: abort
CHARACTER (LEN=*), INTENT(IN) :: mpiname
File
comms MPI.F90
Type
Module subroutine
Purpose
Report an error in a MPI routine. The program is aborted either in
this routine or in the calling routine.
Arguments
mpiname Name of the MPI routine where the error occurred
abort Abort the program if present and .TRUE.. If not present,
abortion is executed only if iopt MPI abort is set to 1.
MPI calls
MPI error string
error MPI comm

SUBROUTINE error MPI(mpiname,idsrce,iddest)
CHARACTER (LEN=*), INTENT(IN) :: mpiname
INTEGER, INTENT(IN) :: iddest, idsrce
File
comms MPI.F90
23.6. INITIALISATION OF DERIVED TYPES VARIABLES 931
Type
Module subroutine
Purpose
Report an error in a MPI send or receive communication.
Arguments
mpiname Name of the MPI routine where the error occurred
idsrce Rank of the source (sending) process
iddest Rank of the destination (receiving) process
23.6 Initialisation of derived types variables

Initialise derived type scalar and array variables. The intention is to provide
an initial value for each component of the derived type variable. These values
are not to be considered as default ones. Default values are set by the routines
in default model.f90 (see Section 23.7 below).
exchange comms init

SUBROUTINE exchangecomms init(comms)
TYPE (ExchComms), INTENT(OUT), DIMENSION(:) :: comms
File
datatypes init.f90
Type
Module subroutine
Purpose
Initialise parameters for exchange communications.
Arguments
comms Derived type variable to be initialised
filepars init
SUBROUTINE filepars init(filepars)
TYPE (FileParams), INTENT(INOUT)[, DIMENSION(:[,:[,:]])] :: filepars
File
datatypes init.f90
Type
Purpose
Initialise file attributes.
Arguments
filepars Derived type variable (scalar or array) to be initialised
filepars init 0d Derived type scalar
filepars init 1d Derived type vector
filepars init 2d Derived type 2-D array
filepars init 3d Derived type 3-D array
gridpars init
SUBROUTINE gridpars init(gridpars)
TYPE (GridParams), INTENT(OUT), DIMENSION(:,:) :: gridpars
File
datatypes init.f90
Type
Module subroutine
Purpose
Initialise attributes of 2-D external data grids.
Arguments
gridpars Derived type variable to be initialised
hrelativecoords init
SUBROUTINE hrelativecoords init(hgrid,flag undef)
LOGICAL, INTENT(IN) :: flag undef
TYPE (FileParams), INTENT(OUT)[, DIMENSION(:[,:])] :: hgrd
File
datatypes init.f90
23.6. INITIALISATION OF DERIVED TYPES VARIABLES 933
Type
Purpose
Initialise the horizontal relative coordinates of one or more data (model
grid) locations.
Arguments
hgrid Derived type variable (scalar or array) to be initialised
flag undef If .TRUE., values are set to undefined values. Otherwise
they are set to zero.
hrelativecoords init 0d Derived type scalar
hrelativecoords init 1d Derived type vector
hrelativecoords init 2d Derived type 2-D array
outgpars init
SUBROUTINE outgpars init(outgpars)
TYPE (OutGridParams), INTENT(OUT), DIMENSION(:) :: outgpars
File
datatypes init.f90
Type
Module subroutine
Purpose
Initialise attributes of a user-defined output grid.
Arguments
outgpars Derived type array to be initialised
statlocs init
SUBROUTINE statlocs init(statlocs)
TYPE (StationLocs), INTENT(OUT), DIMENSION(:) :: statlocs
File
datatypes init.f90
Type
Module subroutine
Purpose
Initialise attributes of user-defined output stations.
Arguments
outgpars Derived type array to be initialised
varatts init
SUBROUTINE varatts init(varatts)
TYPE (VariableAtts), INTENT(OUT)[, DIMENSION(:)] :: varatts
File
datatypes init.f90
Type
Purpose
Initialise the attributes of program variables.
Arguments
varatts Derived type variable (scalar or vector) to be initialised
varatts init 0d Derived type scalar
varatts init 1d Derived type vector
vrelativecoords init
SUBROUTINE vrelativecoords init(vgrid,flag undef)
LOGICAL, INTENT(IN) :: flag undef
TYPE (VRelativeCoords), INTENT(OUT) &
& [,DIMENSION(:[,:[,:[,]]])] :: vgrid
File
datatypes init.f90
Type
23.7. DEFAULT MODEL SETUP 935
Purpose
Initialise the vertical relative coordinates of one or more data (model
grid) locations.
Arguments
vgrid Derived type variable (scalar or array) to be initialised
flag undef If .TRUE., values are set to undefined values. Otherwise
they are set to zero.
vrelativecoords init 0d Derived type scalar
vrelativecoords init 1d Derived type vector
vrelativecoords init 2d Derived type 2-D array
23.7 Default model setup

Default settings of all model parameters
default ellvars
SUBROUTINE default ellvars(ellvars)
TYPE (VariableAtts), INTENT(OUT), DIMENSION(14) :: ellvars
File
default model.f90
Type
Module subroutine
Purpose
Attributes of tidal ellipse variables
Arguments
ellvars Derived type array containing the attributes of the tidal
ellipse parameters. These defaults cannot be changed.
default init params

SUBROUTINE default init params
File
default model.f90
Type
Module subroutine
Purpose
Default settings of parameters for monitoring
default mod params

SUBROUTINE default mod params
File
default model.f90
Type
Module subroutine
Purpose
Default settings of model setup parameters (which can be re-defined in
usrdef mod params)
default out files

SUBROUTINE default out files(filepars,file type)
CHARACTER (LEN=2), INTENT(IN) :: file type
TYPE (FileParams), INTENT(OUT), DIMENSION(:[,:]) :: filepars
File
default model.f90
Type
Purpose
Default attributes of user-defined output files
Arguments
23.7. DEFAULT MODEL SETUP 937
filepars Derived type variable (vector or 2-D array) in which the

attributes are stored
file type Type of user output
‘TS’: time series
‘TA’: time averaged
‘HR’: harmonic residuals
‘HA’: harmonic amplitudes
‘HP’: harmonic phases
‘HE’: tidal ellipse parameters
default out files 1d Derived type vector
default out files 2d Derived type 2-D array
default out files grd

SUBROUTINE default out files grd(filepars,file type)
TYPE (FileParams), INTENT(OUT), DIMENSION(:) :: filepars
File
default model.f90
Type
Module subroutine
Purpose
Default settings for the attributes of an output grid file
Arguments
filepars Output grid file
file type Type of user output
‘TS’: time series
‘TA’: time averaged
‘HR’: harmonic residuals
‘HA’: harmonic amplitudes
‘HP’: harmonic phases
‘HE’: tidal ellipse parameters
default out gpars

SUBROUTINE default out gpars(outgpars)
TYPE (OutGridParams), INTENT(OUT), DIMENSION(:) :: outgpars
File
default model.f90
Type
Module subroutine
Purpose
Default settings for the attributes of a user-defined output grid
Arguments
outgpars Attrinutes of the output grid
23.8 Error checking routines

Ensemble of routines for performing different kinds of error checking or to
check for suspicious values of model setup parameters. Error or warning
messages are written if requested.
check space limits

SUBROUTINE check space limits(slims,arrname,limmax)
INTEGER, INTENT(IN) :: limmax
INTEGER, INTENT(IN), DIMENSION(3) :: slims
File
error routines.F90
Type
Module subroutine
Purpose
Check the start/end/step values defining a spatial section on the model
grid.
Arguments
slims Start/end/increment values defining the array section
arrname Array name
limmax Maximum allowed value for the end index
23.8. ERROR CHECKING ROUTINES 939
check space limits arr struc

SUBROUTINE check space limits arr struc(slims,arrname,compname,&
& limmax,ndims,indx)
CHARACTER (LEN=*), INTENT(IN) :: arrname, compname
INTEGER, INTENT(IN) :: limmax, ndims
INTEGER, INTENT(IN), DIMENSION(3) :: slims
INTEGER, INTENT(IN), DIMENSION(ndims) :: indx
File
error routines.F90
Type
Module subroutine
Purpose
Check the start/end/step values, stored in a component of a derived
type array, defining a spatial section on the model grid.
Arguments
slims Start/end/increment values defining the array section
compname Name of the derived type component
limmax Maximum allowed value for the end index
ndims Rank of the derived type array
indx Vector index of the derived type array
check time limits

SUBROUTINE check time limits(tlims,arrname,minstep,maxstep)
INTEGER, INTENT(IN) :: maxstep, minstep
INTEGER, INTENT(INOUT), DIMENSION(3) :: tlims
File
error routines.F90
Type
Module subroutine
Purpose
Check start/end/increment time index values.
Arguments
tlims Start/end/increment values
arrname Name of the tlims variable
minstep Minimum allowed value for the start index
maxstep Maximum allowed value for the end index
check time limits arr struc

SUBROUTINE check time limits arr struc(tlims,arrname,compname,&
& minstep,maxstep,ndims,indx)
INTEGER, INTENT(IN) :: maxstep, minstep, ndims
INTEGER, INTENT(INOUT), DIMENSION(3) :: tlims
File
error routines.F90
Type
Module subroutine
Purpose
Check the start/end/increment time index values, stored in a compo-
nent of a derived type array.
Arguments
tlims Start/end/increment values
minstep Minimum allowed value for the start index
maxstep Maximum allowed value for the end index
ndims Rank of the derived type array
indx Vector index of the derived type array
error abort
SUBROUTINE error abort(prname,icode)
CHARACTER (LEN=*), INTENT(IN) :: prname
INTEGER, INTENT(IN) :: icode
File
error routines.F90
Type
Module subroutine
Purpose
If errors have been detected from a previous error checking routine or
by some error coding within a program routine, the error message as-
sociated with error code icode is displayed and the program is aborted.
Arguments
prname Name of the routines where the error occurred
icode Error code key id number
error alloc
SUBROUTINE error alloc(arrname,ndims,nshape,data type,lenstr,abort)
INTEGER, INTENT(IN) :: data type, ndims
INTEGER, INTENT(IN), OPTIONAL :: lenstr
INTEGER, INTENT(IN), DIMENSION(ndims) :: nshape
File
error routines.F90
Type
Module subroutine
Purpose
Write an appropriate error message when an error occurred during
allocation of an array.
Arguments
arrname Name of the array
ndims Rank of the array
nshape Shape of the array
data type COHERENS data type id
lenstr Length of the array strings if the array contains character
data
abort Abort the program if present and .TRUE.. Otherwise the

program is aborted in the calling routine.
error alloc struc

SUBROUTINE error alloc struc(arrname,ndims,nshape,structype,abort)
CHARACTER (LEN=*), INTENT(IN) :: arrname, structype
INTEGER, INTENT(IN) :: ndims
INTEGER, INTENT(IN), DIMENSION(ndims) :: nshape
File
error routines.F90
Type
Module subroutine
Purpose
Write an appropriate error message when an error occurred during
allocation of a derived type array.
Arguments
nshape Shape of the array
structype TYPE of the derived type array
abort Abort the program if present and .TRUE.. Otherwise the
program is aborted in the calling routine.
error arg var

SUBROUTINE error arg var(val,argname,fix)
CHARACTER (LEN=*), INTENT(IN) :: argname
CHARACTER (LEN=*) or INTEGER or LOGICAL, INTENT(IN) :: val
CHARACTER (LEN=*) or INTEGER or LOGICAL , INTENT(IN),&
& OPTIONAL ::& fix
File
error routines.F90
Type
Purpose
Checks whether argument val in a routine call equals fix. It is clear
that the two arguments must be of the same type and have the same
string length in case they are of type CHARACTER. Argument fix is
OPTIONAL only in case of CHARACTER arguments.
Arguments
val Value of the routine argument
argname FORTRAN name of the argument
fix Allowed value for val. If not present and val is of type
CHARACTER, its value is automatically taken as invalid.
error arg var char The arguments are of type CHARACTER
error arg var int The arguments are of type INTEGER
error arg var log The arguments are of type LOGICAL
error array index

SUBROUTINE error array index(ival,arrname,minval,maxval,ndim)
INTEGER, INTENT(IN) :: ival, minval, maxval, ndim
File
error routines.F90
Type
Module subroutine
Purpose
Checks whether the value the index ival belonging to dimension ndim
of an array is between the bounds minval and maxval.
Arguments
ival Array index to be checked
minval Lower array bound
maxval Upper array bound
ndim Array dimension to be checked
error diff vals arrlist

SUBROUTINE error diff vals arrlist(ilist,arrname,ndims,idim,&
& indx,nozero)
LOGICAL, INTENT(IN), OPTIONAL :: nozero
INTEGER, INTENT(IN) :: idim, ndims
INTEGER, INTENT(IN), DIMENSION(:) :: ilist
File
error routines.F90
Type
Module subroutine
Purpose
Checks if the elements of the vector ilist are all different. Zero values are
not allowed unless nozero is present and .TRUE.. The routine is called
to check the values along a certain array dimension of an INTEGER
array.
Arguments
ilist List of integer values to be checked
idim Array dimension to which ilist applies
indx Array index vector with the index for dimension idim omit-
ted
nozero Zeros are allowed only if present and .TRUE.
error diff vals varlist

SUBROUTINE error diff vals varlist(ilist,listname,nozero)
LOGICAL, INTENT(IN), OPTIONAL :: nozero
CHARACTER (LEN=*), INTENT(IN) :: listname
File
error routines.F90
Type
Module subroutine
Purpose
Checks if the elements of the vector ilist are all different. Zero values
are not allowed unless nozero is present and .TRUE..
Arguments
ilist List of integer values to be checked
listname Name of the vector list
nozero Zeros are allowed only if present and .TRUE.
error dim arr

SUBROUTINE error dim arr(nrank,arrname,nfix)
INTEGER, INTENT(IN) :: nfix, nrank
File
error routines.F90
Type
Module subroutine
Purpose
Checks whether an array has the rank given by nfix.
Arguments
nrank Rank of the array
nfix Assumed rank of the array
error file
SUBROUTINE error file(ierr,iounit,filepars,abort)
INTEGER, INTENT(IN) :: ierr
INTEGER, INTENT(IN), OPTIONAL :: iounit
TYPE(FileParams), INTENT(IN), OPTIONAL :: filepars
File
error routines.F90
Type
Module subroutine
Purpose
Report an input/output error detected during a file read/write.
Arguments
ierr Error code (as given by its key id of the form ierrno *)
iounit File unit number (must be present if filepars is not present)
filepars File attributes (must be present if iounit is not present)
abort The program is aborted unless abort is present and .FALSE.
error lbound arr

SUBROUTINE error lbound arr(val,arrname,minval,matchmin,ndims,indx)
LOGICAL, INTENT(IN) :: matchmin
INTEGER or REAL, INTENT(IN) :: minval, val
File
error routines.F90
Type
Purpose
Checks whether the value val of an array element is greater than or equal
to minval if matchmin is .TRUE. or greater than minval if matchmin is
.FALSE..
Arguments
val Value of the array element
arrname Array name
minval Lower bound for val
matchmin If .TRUE., val may be equal to minval.
indx Vector index of the array element
error lbound arr int val and minval are of type INTEGER
error lbound arr real val and minval are of type REAL
error lbound arr struc

SUBROUTINE error lbound arr struc(val,arrname,compname,minval,&
& matchmin,ndims,indx)
File
error routines.F90
Type
Purpose
Checks whether the value val of a component of a derived array element
is greater than or equal to minval if matchmin is .TRUE. or greater than
minval if matchmin is .FALSE..
Arguments
val Value of the component of the array element
error lbound arr struc int val and minval are of type INTEGER
error lbound arr struc real val and minval are of type REAL
error lbound var

SUBROUTINE error lbound var(val,varname,minval,matchmin)
File
error routines.F90
Type
Purpose
Checks whether val is greater than or equal to minval if matchmin is
.TRUE. or greater than minval if matchmin is .FALSE..
Arguments
val Value of the (scalar) variable
varname Variable name
error lbound var int val and minval are of type INTEGER
error lbound var real val and minval are of type REAL
error limits arr

SUBROUTINE error limits arr(val,arrname,minval,maxval,ndims,indx)
INTEGER or REAL, INTENT(IN) :: maxval, minval, val
File
error routines.F90
Type
Purpose
Checks whether the value val of an array element is not lower than
minval and not greater than maxval.
Arguments
arrname Array name
maxval Upper bound for val
error limits arr int val, minval, maxval are of type INTEGER
error limits arr real val, minval, maxval are of type REAL
error limits arr struc

SUBROUTINE error limits arr struc(val,arrname,compname,minval,&
& maxval,ndims,indx)
File
error routines.F90
Type
Purpose
Checks whether the value val of a component of a derived array element
is not lower than minval and not greater than maxval.
Arguments
val Value of the component of the derived type array element

error limits arr struc int val, minval, maxval are of type INTEGER
error limits arr struc real val, minval, maxval are of type REAL
error limits var

SUBROUTINE error limits var(val,varname,minval,maxval)
File
error routines.F90
Type
Purpose
Checks whether val is not lower than minval and not greater than
maxval.
Arguments

error limits var int val, minval, maxval are of type INTEGER
error limits var real val, minval, maxval are of type REAL
error mult
SUBROUTINE error mult(ival,varname,multval)
INTEGER, INTENT(IN) :: ival, multval
File
error routines.F90
Type
Module subroutine
Purpose
Checks whether ival is a divisor of multval.
Arguments
ival Integer input variable
multval Integer multiple of ival
error proc
SUBROUTINE error proc(ierr,abort)
INTEGER, INTENT(IN) :: ierr
File
error routines.F90
Type
Module subroutine
Purpose
Write the number of the error code and the name of the routine where
the error occurred to the error file.
Arguments
ierr Number of the error code
abort Abort the program if present and .TRUE.
error shape
SUBROUTINE error shape(arrshape,arrname,fixshape,ndim)
INTEGER, INTENT(IN) :: ndim
INTEGER, INTENT(IN) , DIMENSION(ndim) :: arrshape, fixshape
File
error routines.F90
Type
Module subroutine
Purpose
Check whether shape arrshape equals the vector shape.
Arguments
arrshape Shape of the array
arrname Array name
fixshape Vector to which arrshape should be equal
ndim Array rank
error ubound arr

SUBROUTINE error ubound arr(val,arrname,maxval,matchmax,&
& ndims,indx)
LOGICAL, INTENT(IN) :: matchmax
INTEGER or REAL, INTENT(IN) :: maxval, val
File
error routines.F90
Type
Purpose
Check whether the value val of an array element is not greater than
maxval if matchmax is .TRUE. or lower than maxval if matchmax is
.FALSE..
Arguments
arrname Array name
matchmax If .TRUE., val may be equal to maxval.
error ubound arr int val and maxval are of type INTEGER
error ubound arr real val and maxval are of type REAL
error ubound arr struc

SUBROUTINE error ubound arr struc(val,arrname,compname,maxval,&
& matchmax,ndims,indx)
File
error routines.F90
Type
Purpose
Check whether the value val of a component of a derived type array
element is not greater than maxval if matchmax is .TRUE. or lower than
maxval if matchmax is .FALSE..
Arguments
val Value of the component of the array element

error ubound arr struc int val and maxval are of type INTEGER
error ubound arr struc real val and maxval are of type REAL
error ubound var

SUBROUTINE error ubound var(val,varname,maxval,matchmax)
File
error routines.F90
Type
Purpose
Check whether val is not greater than maxval if matchmax is .TRUE. or
lower than maxval if matchmax is .FALSE..
Arguments
error ubound var int val and maxval are of type INTEGER
error ubound var real val and maxval are of type REAL
error vals arr

SUBROUTINE error vals arr(val,arrname,fixval,ndims,indx)
CHARACTER (LEN=*) or INTEGER, INTENT(IN) :: val
CHARACTER (LEN=*) or INTEGER, DIMENSION(:), INTENT(IN) :: fixval

File
error routines.F90
Type
Purpose
Check whether the character string array element val (without trailing
blanks) is a substring of fixval or check whether the element val of an
integer array equals one of the values in the vector list fixval.
Arguments
val Character string or integer array element
arrname Array name
fixval Character string to which val should be equal or integer
vector list of allowed integer values.
ndims Array rank
error vals arr char Checks character string
error vals arr int Checks integer array element
error vals arr struc

SUBROUTINE error vals arr struc(val,arrname,compname,fixval,&
& ndims,indx)
CHARACTER(LEN=*) or INTEGER, INTENT(IN) :: val
CHARACTER(LEN=*) or INTEGER, DIMENSION(:), INTENT(IN) :: fixval
File
error routines.F90
Type
Purpose
Check whether the string component val of a derived type array is
a substring of fixval or check whether the element val of an integer
component of a derived type array equals one of the values in the
vector list fixval.
Arguments
val Character string or integer component of the derived type
array
arrname Name of derived type array
ndims Array rank
error vals arr struc char Checks character string component
error vals arr struc int Checks integer component
error vals var

SUBROUTINE error vals var(val,varname,fixval)
CHARACTER (LEN=*) or INTEGER, INTENT(IN) :: val
CHARACTER (LEN=*) or INTEGER, DIMENSION(:), INTENT(IN) :: fixval
File
error routines.F90
Type
Purpose
Check whether the string val is a substring of fixval or check whether
the integer val equals one of the values in the vector list fixval.
Arguments
val Character string or integer array element

error vals var char Checks character string

error vals arr int Checks integer variable
error value arr

SUBROUTINE error value arr(val,arrname,fixval,ndims,indx)
INTEGER or LOGICAL, INTENT(IN) :: fixval, val
File
error routines.F90
Type
Purpose
Check whether the integer or logical array element val equals the integer
or logical value fixval.
Arguments
val Integer or logical array element

arrname Array name
fixval Integer or logical value to which val should be equal
ndims Array rank
error value arr int val and fixval are of type INTEGER
error value arr log val and fixval are of type LOGICAL
error value arr struc

SUBROUTINE error value arr struc(val,arrname,compname,fixval,&
& ndims,indx)
File
error routines.F90
Type
Purpose
Check whether the value val of a component of a derived type array
element equals fixval.
Arguments
val Value of the component of the derived type array element
arrname Name of derived type array
compname Name of derived type component
fixval Value to which val should be equal
ndims Array rank
error value arr struc int val and fixval are of type INTEGER
error value arr struc log val and fixval are of type LOGICAL
error value var

SUBROUTINE error value var(val,varname,fixval)
File
error routines.F90
Type
Purpose
Check whether the integer or logical variable val equals the integer or
logical value fixval.
Arguments
val Integer or logical variable
fixval Integer or logical value to which val should be equal
error value var int val and fixval are of type INTEGER
error value var log val and fixval are of type LOGICAL
warning reset arr

SUBROUTINE warning reset arr(val,arrname,set,ndims,indx)
CHARACTER (LEN=*), INTEGER or LOGICAL, INTENT(IN) :: set
CHARACTER (LEN=*), INTEGER or LOGICAL, INTENT(INOUT) :: val
File
error routines.F90
Type
Purpose
Reset the array element val to set with a warning message if needed.
Arguments
val Character string, integer or logical array element
arrname Array name
set Value to which val should be reset
ndims Array rank
warning reset arr char Resets a character string array element
warning reset arr int Resets an integer array element

warning reset arr log Resets a logical array element
warning reset arr struc

SUBROUTINE warning reset arr struc(val,arrname,compname,set,&
& ndims,indx)
CHARACTER (LEN=*), INTEGER or LOGICAL, INTENT(IN) :: set
CHARACTER (LEN=*), INTEGER or LOGICAL, INTENT(INOUT) :: val
File
error routines.F90
Type
Purpose
Reset array element val to set with a warning message if needed.
Arguments
val Character string, integer or logical component
ndims Rank of derived type array
warning reset arr struc char Resets a character string component
warning reset arr struc int Resets an integer component
warning reset arr struc log Resets a logical component
warning reset var

SUBROUTINE warning reset var(val,varname,set)
CHARACTER (LEN=*), INTEGER, LOGICAL or REAL, INTENT(IN) :: set
CHARACTER (LEN=*), INTEGER, LOGICAL or REAL, INTENT(INOUT) :: val
File
error routines.F90
Type
Purpose
Reset val to set with a warning message if needed.
Arguments
val Character string, integer, logical or real variable
warning reset var char Resets a character string variable
warning reset var int Resets an integer variable
warning reset var log Resets a logical variable
warning reset var real Resets a real variable
warning ubound var real

SUBROUTINE warning ubound var real(rval,varname,maxval,matchmax)
REAL, INTENT(IN) :: maxval, rval
File
error routines.F90
Type
Module subroutine
Purpose
Writes a warning message if the real variable rval is not greater than
maxval if matchmax is .TRUE. or lower than maxval if matchmax is
.FALSE.
Arguments
rval Real variable to be checked
maxval Upper bound for rval

matchmax If .TRUE., rval may be equal to maxval.
23.9 Grid interpolation from and to the model

grid
The routines in this files deal with
• the relative coordinates of external (gridded or non-gridded) data points

with respect to a rectangular model grid
• the relative coordinates of the model grid with respect to an external

rectangular data grid
• interpolation of external data on the model grid, model grid data on

an external grid or between external grids
data to data vcoords 2d

SUBROUTINE data to data vcoords 2d(zin,zout,vcoords,nhdat,
& nzdatin,nzdatout,nzeff)
INTEGER, INTENT(IN) :: nhdat, nzdatin, nzdatout, nzeff
REAL, INTENT(IN), DIMENSION(nhdat,nzdatin) :: zin
REAL, INTENT(IN), DIMENSION(nhdat,nzdatout) :: zout
TYPE (VRelativeCoords), INTENT(OUT),&
& DIMENSION(nhdat,nzdatout) :: vcoords
File
grid interp.F90
Type
Module subroutine
Purpose
Returns the relative vertical coordinates of input data with respect to
a series of output data locations.
Arguments
zin Vertical coordinates (measured as the positive distance to
the sea surface) of the input data
23.9. GRID INTERPOLATION FROM AND TO THE MODEL GRID 963
zout Vertical coordinates (measured as the positive distance to

the sea surface) of the points to which the data are to
be interpolated. The interpolating and interpolated data
have the same horizontal locations.
vcoords Returned derived type array of relative coordinates
nhdat Number of horizontal data locations.
nzdatin Number of interpolating data along the vertical
nzdatout Number of interpolated data along the vertical
nzeff “Effective” number of interpolated data along the vertical.
This means that interpolation is only performed for levels
1 to nzeff (equal or lower than nzdatout).
data to model hcoords glb

SUBROUTINE data to model hcoords glb(xdat,ydat,hcoords,n1dat,&
& n2dat,cnode,intflag)
INTEGER, INTENT(IN) :: intflag, n1dat, n2dat
REAL, INTENT(IN), DIMENSION(n1dat,n2dat) :: xdat, ydat
& DIMENSION(n1dat*n2dat) :: hcoords
File
grid interp.F90
Type
Module subroutine
Purpose
Returns the relative horizontal coordinates of a gridded array of exter-
nal data points with respect to the global model grid.
Arguments
xdat X-coordinates of the data points
ydat Y-coordinates of the data points
hcoords Returned array of relative coordinates
n1dat X-dimension of the external data grid
n2dat Y-dimension of the external data grid
cnode Nodal type of the model grid points used for interpolation
(‘C’, ‘U’, ‘V’)
intflag Type of flagging for invalid (land) points
1: all locations are valid, interpolation to nearest wet points
if necessary
2: locations are valid only if at least one neighbouring
point is wet
3: locations are only valid if all neighbouring points are
wet
data to model vcoords 1d

SUBROUTINE data to model vcoords 1d(zcoord,vcoords,i,j,nzdat,cnode)
INTEGER, INTENT(IN) :: i, j, nzdat
REAL, INTENT(IN), DIMENSION(nzdat) :: zcoord
TYPE (VRelativeCoords), INTENT(OUT), DIMENSION(nzdat) :: vcoords
File
grid interp.F90
Type
Module subroutine
Purpose
Returns the relative vertical coordinates of a 1-D vertical grid (with
horizontal position on the model grid) with respect to the model grid.
Arguments
zcoord Vertical coordinates (measured as the positive distance to
the sea surface) of the data locations
vcoords Returned array of vertical relative coordinates
i X-index of the data locations on the model grid
j Y-index of the data locations on the model grid
nzdat Number of vertical levels of the 1-D data grid
cnode Nodal type of the horizontal locations on the model grid
(‘C’, ‘U’, ‘V’)

SUBROUTINE data to model vcoords 2d(zcoord,vcoords,nzdat,cnode)
INTEGER, INTENT(IN) :: nzdat
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nzdat) :: zcoord
TYPE (VRelativeCoords), INTENT(OUT), &
& DIMENSION(ncloc,nrloc,nzdat) :: vcoords
File
grid interp.F90
Type
Module subroutine
Purpose
Returns the relative coordinates of a 3-D data grid with respect to the
model grid. The data grid is assumed to be positioned horizontally on
the model grid. Dry cells are not taken into account.
Arguments
the sea surface) of the data locations
vcoords Returned array of vertical relative coordinates
nzdat Number of vertical levels in the data array
(‘C’, ‘U’, ‘V’)

SUBROUTINE data to model vcoords 3d(zcoord,hcoords,vcoords,&
& n1dat,n2dat,n3dat,cnode)
INTEGER, INTENT(IN) :: n1dat, n2dat, n3dat
REAL, INTENT(IN), DIMENSION(n1dat,n2dat,n3dat) :: zcoord
TYPE (HRelativeCoords), INTENT(IN), DIMENSION(n1dat*n2dat) :: hcoords
TYPE (VRelativeCoords), INTENT(OUT), &
& DIMENSION(2,2,n1dat*n2dat,n3dat) :: vcoords
File
grid interp.F90
Type
Module subroutine
Purpose
Returns the relative coordinates of a 3-D data grid with respect to the
model grid. The horizontal grids are different. Since horizontal inter-
polation is performed after vertical one and vertical model grid points
with the same vertical index do not have the vertical Z-coordinate,
the vertical relative coordinates are to be taken at the four model grid
points surrounding the data point in the horizontal. This explains why
the first two dimensions of vcoords have a size of 2.
Arguments
the sea surface) of the data grid
hcoords Horizontal relative coordinates of the data grid with re-
spect to the model grid.
vcoords Returned array of vertical relative coordinates. The first
two dimensions refer to the four adjacent model grid loca-
tions in the X- and Y-directions.
n1dat X-dimension of the data grid.
n2dat Y-dimension of the data grid.
n3dat Vertical dimension of the data grid.
(‘C’, ‘U’, ‘V’)
intpol data to model 2d

SUBROUTINE intpol data to model 2d(invals,outvals,ncin,nrin,&
& nosize,surfgrid,datflag,land,&
& inflag,outflag)
LOGICAL, INTENT(IN) :: land
INTEGER, INTENT(IN) :: datflag, ncin, nosize, nrin
REAL, INTENT(IN), OPTIONAL :: inflag, outflag
REAL, INTENT(IN), DIMENSION(ncin,nrin,nosize) :: invals
REAL, INTENT(OUT), DIMENSION(ncloc,nrloc,nosize) :: outvals
TYPE (HRelativeCoords), INTENT(IN),&
& DIMENSION(ncloc,nrloc) :: surfgrid
File
grid interp.F90
Type
Module subroutine
Purpose
Interpolate a 2-D gridded horizontal data array on the model grid.
Data and model grid are assumed to be different.
Arguments
invals Array of data values
outvals Returned data interpolated on the model grid
ncin X-dimension of the data grid
nrin Y-dimension of the data grid.
nosize Number of data variables
surfgrid Relative (horizontal) coordinates of the data grid with re-
spect to the model grid
datflag Enables flagging in case of invalid data points
0: flagging is disabled
1: flagging is enabled, no extrapolation is allowed
2: flagging is enabled, extrapolation is allowed
land Land points on the model grid are included if set to .TRUE.
inflag Flag for invalid input data which must be defined if datflag>0.
If not present, its value is set to the minimum value real min
used for flagged data.
outflag Replacement flag at model grid locations where no inter-
polation could be performed. If not present, its value is
set to the undefined value real fill.
intpol1d model to dep

SUBROUTINE intpol1d_model_to_dep(invals,outval,i,j,dep,cnode,nzmin,nzmax,&
& outflag)
INTEGER, INTENT(IN), OPTIONAL :: nzmax, nzmin
REAL, INTENT(IN) :: dep

REAL, INTENT(IN), DIMENSION(:) :: invals
REAL, INTENT(OUT) :: outval
File
grid interp.F90
Type
Module subroutine
Purpose
Interpolate a vertical model profile at a given depth
Arguments
invals Vertical input profile
outval Returned value interpolated at the specified depth
i (Local) X-index of the model grid location
j (Local) Y-index of the model grid location
dep Interpolation depth (positive distance from the free sur-
face)
cnode Vertical grid node where invals is defined (’C’ or ’W’)
nzmin Lowest physical vertical level in case invals is defined at
the W-nodes (1 otherwise)
nzmax Highest physical vertical level in case invals is defined at
the W-nodes (nz otherwise)
outflag Replacement flag if dep is larger than the water depth at
the given location
intpol model to data 2d

SUBROUTINE intpol2d model to data 2d(invals,outvals,hcoords,nhdims,&
& nhdat,nosize,cnode,&
& datvals,outflag)
INTEGER, INTENT(IN) :: nhdat, nosize
INTEGER, INTENT(IN), DIMENSION(4) :: nhdims
REAL, INTENT(INOUT), OPTIONAL, DIMENSION(nhdat) :: datvals
REAL, INTENT(OUT), DIMENSION(nhdat,nosize) :: outvals
REAL, INTENT(IN), DIMENSION(1-nhdims(1):ncloc+nhdims(2),&

& 1-nhdims(3):nrloc+nhdims(4),&
& nosize) :: invals
File
grid interp.F90
Type
Module subroutine
Purpose
Interpolate a 2-D gridded horizontal model array at a series of data
locations.
Arguments
invals 2-D model grid array
outvals Returned model data interpolated at the external data
locations
hcoords Relative (horizontal) coordinates of the data points with
respect to the model grid
nhdims Halo sizes of the model array (WESN directions)
nhdat Number of horizontal data locations
nosize Number of data variables for which interpolation is applied
(added as an extra array dimension)
cnode Nodal type of the variable(s) on the model grid (‘C’, ‘U’,
‘V’)
datvals Optional array of data values. If present, its values are
flagged at points where the relative coordinates are given
as undefined.
outflag Optional replacement flag at data locations where no in-
terpolation could be performed. Otherwise the flag is set
to the undefined value.
intpol3d data to data 2d

SUBROUTINE intpol3d data to data 2d(invals,outvals,vcoords,nhdat,&
& nzdatin,nzdatout,nzeff,&
& nosize,outflag)
INTEGER, INTENT(IN) :: nhdat, nosize, nzdatin, nzdatout, nzeff

REAL, INTENT(IN), DIMENSION(nhdat,nzdatin,nosize) :: invals
REAL, INTENT(OUT), DIMENSION(nhdat,nzdatout,nosize) :: outvals
TYPE (VRelativeCoords), INTENT(IN),&
& DIMENSION(nhdat,nzdatout) :: vcoords
File
grid interp.F90
Type
Module subroutine
Purpose
Interpolate data vertically from a 3-D data array to another 3-D output
data array. The two grids share the same horizontal locations.
Arguments
invals Interpolating data array, defined on the input grid
outvals Returned interpolated data, defined on the output grid
vcoords Vertical relative coordinates of the data points with re-
spect to the output grid
nhdat Number of horizontal locations on both grids
nzdatin Vertical dimension of the input grid
nzdatout Vertical dimension of the output grid
nzeff “Effective” number of interpolated data along the vertical.
This means that interpolation is only performed for levels
1 to nzeff (equal or lower than nzdatout).
intpol3d model to data 1d

SUBROUTINE intpol3d model to data 1d(invals,outvals,vcoords,nzdim,&
& nzdat,nosize,datvals,outflag)
INTEGER, INTENT(IN) :: nosize, nzdat, nzdim

REAL, INTENT(INOUT), OPTIONAL, DIMENSION(nzdat) :: datvals
REAL, INTENT(IN), DIMENSION(nzdim,nosize) :: invals
REAL, INTENT(OUT), DIMENSION(nzdat,nosize) :: outvals
TYPE (VRelativeCoords), INTENT(IN), DIMENSION(nzdat) :: vcoords
File
grid interp.F90
Type
Module subroutine
Purpose
Interpolate model data vertically to an external (1-D) vertical grid.
Model and external grid are assumed to be defined along the same
horizontal grid, but the interpolation is taken at one horizontal location
only.
Arguments
invals Vertical profile on the model grid
outvals Returned profile of model data interpolated along the ex-
ternal vertical grid
vcoords Vertical relative coordinates of the model locations with
respect to the vertical external grid
nzdim Vertical dimension of the model grid
nzdat Vertical dimension of the external grid
as undefined.
to the undefined value real fill.

SUBROUTINE intpol3d model to data 2d(invals,outvals,vcoords,nhdims,&
& nzdim,nzdat,nosize,&
& datvals,outflag)
INTEGER, INTENT(IN) :: nosize, nzdat, nzdim

& nzdim,nosize) :: invals
REAL, INTENT(OUT),&
& DIMENSION(ncloc,nrloc,nzdat,nosize) :: outvals
REAL, INTENT(INOUT), OPTIONAL,&
& DIMENSION(ncloc,nrloc,nzdat) :: datvals
& DIMENSION(ncloc,nrloc,nzdat) :: vcoords
File
grid interp.F90
Type
Module subroutine
Purpose
Interpolate model data (vertically) to an external 3-D grid. Model and
external grid are assumed to be defined along the same horizontal grid.
Arguments
invals Model grid array
outvals Returned model data interpolated on the external grid
vcoords Vertical relative coordinates of the model grid with respect
to the vertical external grid
nhdims Halo sizes of model array (WESN directions)
as undefined.

SUBROUTINE intpol3d model to data 3d(invals,outvals,hcoords,&
& vcoords,nhdims,nzdim,nhdat,nzdat,&
& nosize,cnode,datvals,outflag)
INTEGER, INTENT(IN) :: nhdat, nosize, nzdat, nzdim
REAL, INTENT(INOUT), OPTIONAL, DIMENSION(nhdat,nzdat) :: datvals
REAL, INTENT(OUT), DIMENSION(nhdat,nzdat,nosize) :: outvals
& nzdim,nosize) :: invals
& DIMENSION(2,2,nhdat,nzdat) :: vcoords
File
grid interp.F90
Type
Module subroutine
Purpose
Interpolate model data to an external 3-D grid. Model and external
grids are assumed to be different in the horizontal and vertical.
Arguments
invals Model grid array
outvals Returned model data interpolated on the external grid
hcoords Horizontal relative coordinates of the model grid with re-
spect to the external grid
vcoords Vertical relative coordinates of the model grid with re-
spect to the external grid. Since horizontal interpolation
is performed before the vertical one and vertical model grid
points with the same vertical index do not have the same
vertical Z-coordinate, the vertical relative coordinates are
to be taken at the four model grid points surrounding the
data point in the horizontal. The explains the two ex-
tra dimensions of size 2 used to store the values at these
adjacent points.
nhdims Halo sizes of the model array (WESN directions)

nhdat Size of the external grid in the horizontal
cnode Nodal type of the variable(s) on the model grid (‘C’, ‘U’,
‘V’)
as undefined.
to the undefined value real fill.
model to data coords

SUBROUTINE model to data coords(idgrd,ifil,surfgrid,xdat,ydat,&
& ncdat,nrdat,cnode)
INTEGER, INTENT(IN) :: idgrd, ifil, ncdat, nrdat
REAL, INTENT(IN), DIMENSION(ncdat,nrdat) :: xdat, ydat
& DIMENSION(ncloc,nrloc) :: surfgrid
File
grid interp.F90
Type
Module subroutine
Purpose
Returns the horizontal relative coordinates of the model grid with re-
spect to an external (2-D) grid.
Arguments
idgrd Key grid id of the external grid
ifil File number of the external data grid (currently 1)
surfgrid Returned horizontal relative coordinates of the model grid
with respect to the external grid
23.10. ROUTINES PERFORMING OPERATIONS ON THE MODEL GRID 975
xdat X-coordinates of the external data grid

ydat Y-coordinates of the external data grid
ncdat X-dimension of the external data grid
nrdat Y-dimension of the external data grid
cnode Nodal type of the model grid locations (‘C’, ‘U’, ‘V’)
23.10 Routines performing operations on the

model grid
construct regular grid
SUBROUTINE construct regular grid(xstart,ystart,delx,dely,&
& ncgrd,nrgrd,xcoord,ycoord)
INTEGER, INTENT(IN) :: ncgrd, nrgrd
REAL, INTENT(IN) :: delx, dely, xstart, ystart
REAL, INTENT(OUT), DIMENSION(ncgrd,nrgrd) :: xcoord, ycoord
File
grid routines.F90
Type
Module subroutine
Purpose
Construct a uniform rectangular grid kwowing its size, grid spacings
and the position of the Southwest corner.
Arguments
xstart X-coordinate of the Southwest corner at the (global) grid
location (1,1)
[m or fractional degrees longitude]
ystart Y-coordinate of the Southwest corner at the (global) grid
location (1,1)
[m or fractional degrees latitude]
delx Grid spacing in the X-direction
dely Grid spacing in the Y-direction
ncgrd Size of the grid in the X-direction
nrgrd Size of the grid in the Y-direction

xcoord Returned X-coordinates
ycoord Returned Y-coordinates
convert loc to char

FUNCTION convert loc to char(xcoord,ycoord) RESULT(charloc)
REAL, INTENT(IN) :: xcoord, ycoord
CHARACTER (LEN=21) :: charloc
File
grid routines.F90
Type
Module function
Purpose
Returns a geographical location in string format (degrees, minutes,
seconds).
Arguments
xcoord X-coordinate of the geographical location
[fractional degrees longitude]
ycoord Y-coordinate of the geographical location
[fractional degrees latitude]
charloc Returned string format in degrees, minutes, seconds
distance minloc
SUBROUTINE distance minloc(x,y,xcoord,ycoord,nx,ny,iunit,distmin,locmin,mask)
INTEGER, INTENT(IN) :: iunit, nx, ny
INTEGER, INTENT(OUT), OPTIONAL, DIMENSION(2) :: locmin
REAL, INTENT(IN) :: x, y
LOGICAL, INTENT(IN), OPTIONAL, DIMENSION(nx,ny) :: mask
REAL, INTENT(IN), DIMENSION(nx,ny) :: xcoord, ycoord
REAL, INTENT(OUT), OPTIONAL :: distmin
File
grid routines.F90
Type
Module function
Purpose
Returns the index positions of the location on a horizontal grid which
is closest to a given location.
Arguments
x X-coordinate of the given location
y Y-coordinate of the given location
xcoord X-coordinates of the grid
ycoord Y-coordinates of the grid
nx Size of the grid in the X-direction
ny Size of the grid in the Y-direction
iunit Units of xcoord, ycoord in case of spherical coordinates
1: radians
2: degrees
distmin If present, the returned minimum distance
locmin If present, the location of the nearest distance
mask Mask to exclude dry or invalid points if present and .TRUE.
distance pts
FUNCTION distance pts(x1,x2,y1,y2,inunit,outunit) RESULT(dist)
INTEGER, INTENT(IN) :: inunit, outunit
REAL, INTENT(IN) :: x1, x2, y1, y2
REAL :: dist
File
grid routines.F90
Type
Module function
Purpose
Returns the distance between two given locations.
Arguments
x1 X-coordinate of the first location

x2 X-coordinate of the second location
y1 Y-coordinate of the first location
y2 Y-coordinate of the second location
inunit Units of the locations in case of spherical coordinates
1: radians
2: degrees
outunit Units of the result
1: radians
2: degrees
3: meters (always the case in case of a Cartesian grid)
find obc index glb

FUNCTION find obc index glb(i,j,cnode,ierr)
INTEGER, INTENT(OUT), OPTIONAL :: ierr
INTEGER :: find obc index glb
File
grid routines.F90
Type
Module function
Purpose
Returns the index of an open boundary point given its grid index lo-
cation.
Arguments
i X-index of the location
j Y-index of the location
cnode Type of open boundary node (‘U’, ‘V’, ‘X’, ‘Y’)
ierr Error code in case no match has been found. If zero, no
error occurred.
fixed rotate vec arr

SUBROUTINE fixed rotate vec arr(vxin,vyin,vxout,vyout,ndims,angle)
INTEGER, INTENT(IN) :: ndims(4)
REAL, INTENT(IN) :: angle
REAL, INTENT(IN), DIMENSION(ndims(1),ndims(2),&
& ndims(3),ndims(4)) :: vxin, vyin
REAL, INTENT(OUT), DIMENSION(ndims(1),ndims(2),&
& ndims(3),ndims(4)) :: vxout, vyout
File
grid routines.F90
Type
Module subroutine
Purpose
Rotate an array of vectors through a given angle.
Arguments
vxin X-component of the array vector
vyin Y-component of the array vector
vxout Returned X-component of the rotated array vector
vyout Returned Y-component of the rotated array vector
ndims Shape of the array
angle Rotation angle [radians]
fixed rotate vec var

SUBROUTINE fixed rotate vec var(vxin,vyin,vxout,vyout,angle)
REAL, INTENT(IN) :: angle
REAL, INTENT(IN) :: vxin, vyin
REAL, INTENT(OUT) :: vxout, vyout
File
grid routines.F90
Type
Module subroutine
Purpose
Rotate a vector through a given angle.
Arguments
vxin X-component of the vector
vyin Y-component of the vector
vxout Returned X-component of the rotated vector
vyout Returned Y-component of the rotated vector
angle Rotation angle [radians]
global mask
SUBROUTINE global mask(maskglb,cnode,wetonly)
LOGICAL, INTENT(IN) :: wetonly
LOGICAL, INTENT(OUT), DIMENSION(nc,nr) :: maskglb
File
grid routines.F90
Type
Module subroutine
Purpose
Combine a local grid mask to a global one (used for parallel applica-
tions).
Arguments
maskglb Returned global mask
cnode Grid node to which the mask should apply (‘C’, ‘U’, ‘V’,
‘X’, ‘Y’)
wetonly Considers open boundary points as land points if set to
.TRUE..
grid rotate vec arr

SUBROUTINE grid rotate vec arr(vxin,vyin,vxout,vyout,lbounds,ubounds,&
& nzdim,nosize,mask,idir,outflag)
LOGICAL, INTENT(IN) :: mask
INTEGER, INTENT(IN) :: idir, nosize, nzdim
REAL, INTENT(IN), DIMENSION(lbounds(1):ubounds(1),&
& lbounds(2):ubounds(2),&
& nzdim,nosize) :: vxin, vyin
REAL, INTENT(OUT), DIMENSION(lbounds(1):ubounds(1),&
& nzdim,nosize) :: vxout, vyout
File
grid routines.F90
Type
Module subroutine
Purpose
Transform a vector array, defined on the model grid, from the reference
(Cartesian or spherical) coordinate system to the curvilinear grid if
idir=1. The inverse transformation is invoked if idir=-1. The vectors
are assumed to be defined at the C-nodes.
Arguments
vxin X-component of the array vector to be transformed
vyin Y-component of the array vector to be transformed
vxout Returned X-component of the transformed array vector
vyout Returned Y-component of the transformed array vector
lbounds Lower bounds of the first two array dimensions
ubounds Upper bounds of the first two array dimensions
nzdim Third (vertical) array dimension
nosize Fourth (variable) array dimension
mask Dry points are flagged if set to .TRUE..
idir Direction of the transformation
1 : from reference to transformed coordinates
-1: from transformed to reference
outflag Flag used for dry points. If not present, a zero is taken.
grid rotate vec var

SUBROUTINE grid rotate vec var(vxin,vyin,vxout,vyout,i,j,&
& idir,outflag)
INTEGER, INTENT(IN) :: i, idir, j

REAL, INTENT(IN) :: vxin, vyin
REAL, INTENT(OUT) :: vxout, vyout
File
grid routines.F90
Type
Module subroutine
Purpose
Transform a (scalar) vector, defined at a given grid index position on
the model grid, from the reference (Cartesian or spherical) coordinate
system to the curvilinear grid if idir=1. The inverse transformation
is invoked if idir=-1. The vectors are assumed to be defined at the
C-nodes.
Arguments
vxin X-component of the vector to be transformed
vyin Y-component of the vector to be transformed
vxout Returned X-component of the transformed vector
vyout Returned Y-component of the transformed vector
i (Local) X-index of the grid point where the vector is de-
fined
j (Local) Y-index of the grid point where the vector is de-
fined
idir Direction of the transformation
1 : from the reference to the transformed coordinate sys-
tem
-1: from the transformed to the reference coordinate sys-
tem
outflag Flag used for dry points. If not present, a zero is taken.
grid spacings
SUBROUTINE grid spacings(dist,x1,x2,y1,y2,nx,ny,nhtype,&
& inunit,outunit,hdel,cdir)
CHARACTER (LEN=1), INTENT(IN), OPTIONAL :: cdir
INTEGER, INTENT(IN) :: inunit, nhtype, nx, ny, outunit
REAL, INTENT(IN), OPTIONAL :: hdel

REAL, INTENT(IN), DIMENSION(nx,ny) :: x1, x2, y1, y2
REAL, INTENT(OUT), DIMENSION(nx,ny) :: dist
File
grid routines.F90
Type
Module subroutine
Purpose
Calculate the (horizontal) grid spacings on a given (Cartesian or sphe-
rical) grid. The spacings are defined as distance between two arrays of
grid points.
Arguments
dist Returned grid spacings
x1 X-coordinates of the start locations
x2 X-coordinates of the end locations
y1 Y-coordinates of the start locations
y2 Y-coordinates of the end locations
nx X-dimension of the grid
ny Y-dimension of the grid
nhtype Type of the grid
1: uniform rectangular
2: non-uniform rectangular
3: curvilinear
inunit Units of the grid locations in case of a spherical grid
1: radians
2: fractional degrees
outunit Unit of the returned grid spacings in case of a spherical
grid
1: radians
2: fractional degrees
3: meters
hdel Grid spacings in case of a uniform rectangular grid
cdir Coordinate direction with respect to which the spacings

are taken in case of a rectangular grid
‘X’: X-direction
‘Y’: Y-direction
local proc
FUNCTION local proc(i,j,iproc)
INTEGER, INTENT(IN), OPTIONAL :: iproc
LOGICAL :: local proc
File
grid routines.F90
Type
Module function
Purpose
Returns .TRUE. if the point with local grid indices (i,j) belongs to the
domain of the local process calling the function. If iproc is present, (i,j)
are global indices and the function returns .TRUE. if the points belongs
to the domain with process number iproc.
Arguments
i X-index (local or global) of the grid point
j Y-index (local or global) of the grid point
iproc Process number in case (i,j) represent global indices. Must
be present if i and j are global indices.
mask array
FUNCTION mask array(idim,jdim,lims,node)
CHARACTER (LEN=1), INTENT(IN) :: node
INTEGER, INTENT(IN) :: idim, jdim
INTEGER, INTENT(IN), DIMENSION(3,2) :: lims
LOGICAL, DIMENSION(idim,jdim) :: mask array
File
grid routines.F90
Type
Module function
Purpose
Define a local mask array on a sub-section of the model grid.
Arguments
idim X-dimension of the mask array
jdim Y-dimension of the mask array
lims Vector selecting the sub-grid indices in the X- and Y-
direction (start/end/step)
node Grid node to which the mask applies (‘C’, ‘U’, ‘V’, ‘W’)
num proc
FUNCTION num proc(i,j)
INTEGER :: num proc
File
grid routines.F90
Type
Module function
Purpose
Returns the number of the local process domain containing the point
with global indices (i,j).
Arguments
i X-index of the location
j Y-index of the location
Zcoord arr
SUBROUTINE Zcoord arr(zcoord,lbounds,ubounds,cnode,&
& meanlevel,outflag)
LOGICAL, INTENT(IN) :: meanlevel
REAL, INTENT(OUT), DIMENSION(lbounds(1):ubounds(1),&

& lbounds(3):ubounds(3)) :: zcoord
File
grid routines.F90
Type
Module subroutine
Purpose
Return the z-coordinates on a section of the model grid.
Arguments
zcoord Returned z-coordinates
lbounds Lower bounds of the grid section
ubounds Upper bounds of the grid section
cnode Type of grid node (‘C’, ‘U’, ‘V’, ‘W’, ‘UW’, ‘VW’)
meanlevel The z-coordinates are taken with respect to the mean or
total water level if set to .TRUE. or .FALSE.
outflag Output flag for dry points. If not present, a zero value is
taken.
Zcoord var
FUNCTION Zcoord var(i,j,k,cnode,meanlevel)
LOGICAL, INTENT(IN) :: meanlevel
REAL :: Zcoord var
File
grid routines.F90
Type
Module function
Purpose
Returns the z-coordinate of a model grid point.
Arguments
23.11. ROUTINES COMBINING COMMUNICATION AND I/O OPERATIONS 987
i X-index of the grid point

j Y-index of the grid point
k Vertical index of the grid point
cnode Type of grid node (‘C’, ‘U’, ‘V’, ‘W’, ‘UW’, ‘VW’)
meanlevel The z-coordinate is taken with respect to the mean or total
water level if set to .TRUE. or .FALSE.
23.11 Routines combining communication and

I/O operations
The following combined operations are implemented
• Construction of a global array from local arrays by a combine commu-
nication. The global array is written to an output file by the master
process.
• A global array is read by the master process and copied to all other
processes.
• A global array is read and distributed to all local sub-domains.
combine write mod

SUBROUTINE combine write mod(values,filepars,varid,lbounds,&
& ubounds,rfill,varatts,vecids,nowet,&
& comm,commtype)
INTEGER, INTENT(IN) :: varid
INTEGER, INTENT(IN), OPTIONAL :: comm, commtype, nowet
REAL, INTENT(IN) :: rfill
TYPE(FileParams), INTENT(INOUT) :: filepars
INTEGER, INTENT(IN), DIMENSION(:) :: lbounds, ubounds
INTEGER, INTENT(IN), OPTIONAL, DIMENSION(:) :: vecids
REAL, INTENT(IN), DIMENSION(lbounds(1):,lbounds(2):[,lbounds(3):&
& [,lbounds(4):)]]) :: values
TYPE (VariableAtts), INTENT(IN), OPTIONAL, DIMENSION(:) :: varatts
File
inout paral.f90
Type
Purpose
Combine local model grid arrays with real data into a global array and
write the resulting array to a file in standard COHERENS format. The
array has a rank between 2 and 4.
Arguments
values Local model grid array
filepars Derived type variable containing the attributes of the out-
put file
varid If positive, the id of the only variable written to the output
file (between 1 and the number of variables in the file). If
zero, the last dimension of values is considered as a variable
dimension.
lbounds Lower array bounds. The size must match the rank of the
array.
ubounds Upper array bounds. The size must match the rank of the
array.
rfill Fill value substituted at places in the global array where
no values are obtained from the combine operation.
varatts If present, the attributes of the data variable(s) (used only
for log info, error checking and a header line in the output
file)
vecids If present, list of the variable ids in the output file (i.e.
numbers between 1 and the number of variables in the file)
and the size of the vector must match the last dimension of
values. If not present, the last dimension is considered as
a variable dimension and the ids are defined as 1, 2, up to
the size of the last dimension. In case values is a 2-D array
or varid is defined with a positive value, the argument is
not allowed since only one data variable is present.
nowet If present and positive, a land mask is applied. The num-
ber present then equals the number of dry points.
comm MPI communicator. If not present, its value is comm work.
commtype Communication type for the combine operation (between 1
and 4). If not present, its value is set to iopt MPI comm gath.
1: blocking, standard send
2: blocking, synchronous send
3: non-blocking, standard send

4: non-blocking, synchronous send
combine write mod real 2d Combine/write a 2-D real model grid array
combine write obc

SUBROUTINE combine write obc(realglb,filepars,varid,cnode,&
& varatts,comm,commtype)
INTEGER, INTENT(IN), OPTIONAL :: comm, commtype
REAL, INTENT(INOUT), DIMENSION(:,[:,[:]]) :: realglb
File
inout paral.f90
Type
Purpose
Perform a combine operation on a open boundary array which is defined
globally, but whose values are distributed among different processes and
write the array to a file in standard COHERENS format. The array has
a rank between 1 and 3.
Arguments
realglb Local section of the open boundary array
put file
varid If positive, variable id of the array within the output file.
cnode Type of open boundary node (‘U’, ‘V’, ‘X’, ‘Y’)
file)

combine write obc real 1d Combine/write a 1-D real open boundary ar-
ray
ray
ray
combine write stats

SUBROUTINE combine write stats(realloc,filepars,varid,maxstats,&
& nostatsglb,nostatprocs,lstatprocs,&
& varatts,vecids,comm,commtype)
INTEGER, INTENT(IN) :: maxstats, nostatsglb, varid
INTEGER, INTENT(IN), DIMENSION(nprocs) :: nostatprocs
INTEGER, INTENT(IN), DIMENSION(nprocs,maxstats) :: lstatprocs
REAL, INTENT(IN), DIMENSION(:[,:[,:]]) :: realloc
File
inout paral.f90
Type
Purpose
Combine local real data at a number of stations on the model grid
onto a global array and write the resulting array to a file in standard
COHERENS format. The array has a rank between 1 and 3.
Arguments
realloc Array with the local station data
put file
file (between 1 and the number of variables in the file).
If zero, the last dimension of realloc is considered as a
variable dimension.
maxstats Second dimension of the array lstatprocs
nostatsglb Total number (over all sub-domains) of stations within the
global array
nostatprocs Vector array with the number stations on each sub-domain
lstatprocs Index mapping array of the local station indices to the
ones in the global array
file)
and the size of the vector must match the last dimension
of realloc. If not present, the last dimension is considered
as a variable dimension and the ids are defined as 1, 2, up
to the size of the last dimension. In case realloc is a vector
combine write stats real 1d Combine/write a vector of station data
combine write stats real 2d Combine/write a 2-D array of station data
combine write stats real 3d Combine/write a 3-D array of station data
combine write submod

SUBROUTINE combine write submod(realloc,filepars,varid,ndimsglb,&
& limprocs,rfill,varatts,vecids,&
& nowet,comm,commtype)
INTEGER, INTENT(IN), OPTIONAL :: comm, commtype, nowet
INTEGER, INTENT(IN), DIMENSION(:) :: ndimsglb
INTEGER, INTENT(IN), DIMENSION(2,2,nprocs) :: limprocs
REAL, INTENT(IN), DIMENSION(:,:[,:[,:)]]) :: realloc
File
inout paral.f90
Type
Purpose
Combine local real model sub-grid arrays into a global (sub-grid) array
and write the resulting array to a file in standard COHERENS format.
The array has a rank between 2 and 4.
Arguments
realloc Local model sub-grid array
put file
variable dimension.
ndimsglb Shape of the global array. Size of the vector must match
the rank of realloc.
limprocs Location of a local array section within the global array
by means of lower and upper index bounds.
rfill Fill value substituted at places in the global array where
no values are obtained from the combine operation.

file)
realloc. If not present, the last dimension is considered as
the size of the last dimension. In case realloc is a 2-D array
nowet If present and positive, a land mask is applied. The num-
ber then equals the number of dry points.
combine write submod real 2d Combine/write a 2-D real sub-grid array
read distribute mod

SUBROUTINE read distribute mod(realloc,filepars,varid,lbounds,ubounds,&
& nhdist,fdist,land mask,rfill,varatts,&
& vecids,maskvals,shared,comm,commtype)
LOGICAL, INTENT(IN) :: fdist, land mask
LOGICAL, INTENT(IN), OPTIONAL :: shared
TYPE(FileParams), INTENT(IN) :: filepars
INTEGER, INTENT(IN), DIMENSION(:) :: lbounds, ubounds
LOGICAL, INTENT(IN), OPTIONAL, DIMENSION(lbounds(1):,&

& lbounds(2):) :: maskvals
INTEGER, INTENT(IN), DIMENSION(4) :: nhdist
REAL, INTENT(INOUT), DIMENSION(lbounds(1):,lbounds(2):[,lbounds(3):&
& [,lbounds(4):)]]) :: realloc
File
inout paral.f90
Type
Purpose
Read and copy an integer or real scalar or array (upto rank 4) from a
file in standard COHERENS format and copy to all other processes.
Arguments
realloc Returned array
filepars Derived type variable containing the attributes of the in-
put file
varid If positive, the id of the only variable read from the input
variable dimension.
lbounds Lower array bounds. The size must match the rank of the
array.
ubounds Upper array bounds. The size must match the rank of the
array.
nhdist Halo sizes used for the distribute operation (WESN direc-
tions)
fdist Data are distributed only if this argument is set to .TRUE.
land mask A land mask is applied if set to .TRUE.
rfill Fill value substituted at places in the local array where no
values can be obtained from the distribute operation.
for log info and error checking)
23.12. INPUT/OUTPUT OPERATIONS 995
vecids If present, list of the variable ids in the input file (i.e.
realloc. If not present, the last dimension is considered as
the size of the last dimension. In case realloc is a 2-D array
maskvals Array of mask values used in case a land mask is applied
shared The global array is known to (read by) all processes if
.TRUE., to the master process only if .FALSE.. If not
present, its value is set to shared read.
commtype Communication type for the distribute operation (between
1 and 4). If not present, its value is set to iopt MPI comm scat.
read distribute mod real 2d Read/distribute a real 2-D array
23.12 Input/output operations

Ensemble of routines for model input and output.
• open file, open filepars: open a file connection
• close file, close filepars: close a file connection
• read vars: read data from a file in standard COHERENS format
• write vars: write data to a file in standard COHERENS format
• read glbatts mod: read the global attributes from a forcing file in stan-
dard COHERENS format
• read varatts mod: read the variable attributes from a forcing file in
standard COHERENS format
• read glbatts out: read the global attributes from a user output file in
• read varatts out: read the variable attributes from a user output file in
• write atts mod: write the global and variable attributes to a forcing file
in standard COHERENS format
• inout atts out: write the global and variable attributes to a user output
file in standard COHERENS format
close file
SUBROUTINE close file(iounit,ioform,filename,fildel)
LOGICAL, INTENT(IN), OPTIONAL :: fildel
CHARACTER (LEN=1), INTENT(IN) :: ioform
CHARACTER (LEN=*), INTENT(IN), OPTIONAL :: filename
INTEGER, INTENT(INOUT) :: iounit
File
inout routines.f90
Type
Module subroutine
Purpose
Close a file connection.
Arguments
iounit File unit number
ioform File format
‘A’ ASCII
‘U’ unformatted binary
‘D’ direct access binary (currently not used in the pro-
gram)
‘N’ netCDF
filename File name
fildel If present and .TRUE., the file is deleted after closing.
close filepars
SUBROUTINE close filepars(filepars,fildel)
LOGICAL, INTENT(IN), OPTIONAL :: fildel
File
inout routines.f90
Type
Module subroutine
Purpose
Closes a file connection and resets file attributes.
Arguments
filepars File attributes
fildel If present and .TRUE., the file is deleted after closing.
get unit
FUNCTION get unit()
INTEGER :: get unit
File
inout routines.f90
Type
Module function
Purpose
Returns the smallest available unit number not connected to a file.
inout atts out

SUBROUTINE inout atts out(file type)
File
inout routines.f90
Type
Module subroutine
Purpose
Define and write the global, coordinate and variable attributes to a
user-defined output file.
Arguments
file type Output type
‘TS’ time series
‘TA’ time averaged
‘HR’ harmonic residuals
‘HA’ harmonic amplitudes
‘HP’ harmonic phases
‘HE’ tidal ellipse parameters
monitor files
SUBROUTINE monitor files
File
inout routines.f90
Type
Module subroutine
Purpose
Set some parameters for monitoring, open and close the log, error and
warning files.
open file
SUBROUTINE open file(iounit,filename,iotype,ioform,lenrec)
CHARACTER (LEN=*), INTENT(IN) :: filename, ioform, iotype
INTEGER, INTENT(INOUT) :: iounit
INTEGER, INTENT(IN), OPTIONAL :: lenrec
File
inout routines.f90
Type
Module subroutine
Purpose
Open a file connection.
Arguments
iounit Returned file unit number
filename File name
iotype Type of file access
‘IN’ for reading only
‘OUT’ for writing only
‘INOUT’ for reading and writing
ioform File format
‘A’ ASCII
‘U’ unformatted binary
‘D’ direct access binary (currently not used in the pro-
gram)
‘N’ netCDF
lenrec Length of a data record in case the file is opened for direct
access
open filepars
SUBROUTINE open filepars(filepars,iotype)
CHARACTER (LEN=*), INTENT(IN), OPTIONAL :: iotype
File
inout routines.f90
Type
Module subroutine
Purpose
Open a file connection and set file attributes.
Arguments
iotype If present, the file access (‘IN’, ‘OUT’, ‘INOUT’). Other-
wise, the access is defined through the status attribute of
filepars.
read glbatts mod

SUBROUTINE read glbatts mod(filepars)
File
inout routines.f90
Type
Module subroutine
Purpose
Read the global attributes of a standard forcing file. In case of a se-
quential file, the file pointer must be located at the start of the data
record.
Arguments
read glbatts out

SUBROUTINE read glbatts out(filepars,gridpars,outgpars)
TYPE (FileParams), INTENT(INOUT) :: gridpars
TYPE (OutGridParams), INTENT(OUT) :: outgpars
File
inout routines.f90
Type
Module subroutine
Purpose
Read the global attributes of a user output file. In case of a sequential
file, the file pointer must be located at the start of the data record.
Arguments
filepars Attributes of the user output file
gridpars Attributes of the file containing the output grid (equal to
filepars if outgpars%grid file=.FALSE.)
outgpars Attributes of the output grid
read skip out

SUBROUTINE read skip out(filepars)
File
inout routines.f90
Type
Module subroutine
Purpose
Read the global and variable attributes and the coordinate data of a
user output file without storing the data. In case the file is opened for
sequential access, the file pointer is located at the first output time on
exit. The routine should not be called in case of a netCDF file.
Arguments
read station names

SUBROUTINE read station names(filepars,station names,nostats)
INTEGER, INTENT(IN) :: nostats
CHARACTER (LEN=lenname), INTENT(OUT),&
& DIMENSION(nostats) :: station names
File
inout routines.f90
Type
Module subroutine
Purpose
Read the names of data stations from a user output file. In case of se-
quential access, the file pointer must be located at the correct position.
Arguments
station names Returned station names
nostats Number of stations
read submod
SUBROUTINE read submod(realsub,filepars,varid,&
& land mask,varatts,vecids,maskvals)
LOGICAL, INTENT(IN) :: land mask
TYPE(FileParams), INTENT(IN) :: filepars
LOGICAL, INTENT(IN), OPTIONAL, DIMENSION(:,:) :: maskvals
REAL, INTENT(INOUT), DIMENSION(:,:[,:[,:)]]) :: realsub
File
inout routines.f90
Type
Purpose
Read a subgrid section of a model array defined on the global grid from
a file in COHERENS standard format. In case of a sequential file, the
file pointer must be located at the appropriate position.
Arguments
realsub Returned sub-grid array
put file
If zero, the last dimension of realsub is considered as a
variable dimension.
land mask A (horizontal) land mask is applied if set to .TRUE..
for log info and error checking).
realsub. If not present, the last dimension is considered as
the size of the last dimension. In case realsub is a 2-D array

maskvals Array of mask values used in case a land mask is applied
read submod real 2d Read a real 2-D sub-grid array
read time
SUBROUTINE read time(time,filepars,timerec)
CHARACTER (LEN=lentime) or REAL, INTENT(OUT) :: time
INTEGER, INTENT(IN), OPTIONAL :: timerec
File
inout routines.f90
Type
Purpose
Read a time record from a file in standard COHERENS format.
Arguments
time Returned time either in the form of an absolute date/time
in string format or a relative time in numerical format.
put file
timerec If not present, the timerec global attribute is increased
by one. The iostat global attribute is set to 1 or 3 for a
sequential read or to 1, 2 or 3 in case of a non-sequential
read.
read time char Read the time in string format.
read time real Read the time in (real) numeric format.
read varatts mod

SUBROUTINE read varatts mod(filepars,varatts,numvars)
INTEGER, INTENT(IN) :: numvars
TYPE (VariableAtts), INTENT(OUT), OPTIONAL,&
& DIMENSION(numvars) :: varatts
File
inout routines.f90
Type
Module subroutine
Purpose
Read the variable attributes from a forcing file in standard COHERENS
format. An information file is written if requested. In case of a sequen-
tial file, the file pointer must be located at the appropriate position.
Arguments
filepars Attributes of the input file
varatts If present, returned variable attributes. Otherwise the at-
tributes are read but not stored.
numvars Number of variables
read varatts out

SUBROUTINE read varatts out(filepars,varatts,novars,bufid,vector)
LOGICAL, INTENT(IN) :: vector
INTEGER, INTENT(IN) :: bufid, novars
TYPE (VariableAtts), INTENT(OUT), DIMENSION(novars) :: varatts
File
inout routines.f90
Type
Module subroutine
Purpose
Read the variable attributes from a user output file in standard COHERENS
format. The routine can be called a first time to read the attributes
of the coordinate variables in which case bufid must be 0 and vector is

not present, and a second time to read the attributes of the data vari-
ables in which case bufid should be equal to the number of coordinate
variables and vector must be present. In case of a sequential file, the
file pointer must be located at the appropriate position.
Arguments
filepars Attributes of the input file
varatts Returned variable attributes
novars Number of coordinate or data variables
bufid In case of a netCDF file, the netCDF variable id of the first
variable equals bufid+1. Otherwise, its value is irrelevant.
vector Reads the vector attribute of the variables (if needed).
read vars
SUBROUTINE read vars(values,filepars,varid,varatts,vecids)
INTEGER or REAL, INTENT(OUT) [, DIMENSION(:[,:[,:[,:]]])] :: values
File
inout routines.f90
Type
Purpose
Read scalar or array data from a file in standard COHERENS format.
In case of a sequential file, the file pointer must be located at the
appropriate position.
Arguments
values Returned scalar or array data
put file
dimension.
for log info and error checking)
and the size of the vector must match the last dimension
of values. If not present, the last dimension is considered
as a variable dimension and the ids are defined as 1, 2, up
to the size of the last dimension. In case values is a scalar
read vars int 0d Integer scalar
read vars int 1d Integer vector
read vars int 2d Integer 2-D array
read vars real 0d Real scalar
read vars real 1d Real vector
read vars real 2d Real 2-D array
write atts mod

SUBROUTINE write atts mod(filepars,varatts,numvars)
TYPE (VariableAtts), INTENT(INOUT), DIMENSION(numvars) :: varatts
File
inout routines.f90
Type
Module subroutine
Purpose
Write all global and variable (coordinate and data) attributes to a
forcing file in standard COHERENS format.
Arguments
filepars Attributes of the output file
varatts Variable attributes
numvars Number of coordinate plus data variables
write info mod

SUBROUTINE write info mod(filepars,varatts,numvars)
TYPE (VariableAtts), INTENT(IN), OPTIONAL,&
& DIMENSION(numvars) :: varatts
File
inout routines.f90
Type
Module subroutine
Purpose
Write the info file associated with a forcing file in standard COHERENS
format.
Arguments
filepars Attributes of the forcing file
varatts Variable attributes
numvars Number of (coordinate plus data) variables. Must be zero
if varatts is not present.
write time
SUBROUTINE write time(time,filepars,timerec)
CHARACTER (LEN=lentime) or REAL, INTENT(IN) :: time
INTEGER, INTENT(IN), OPTIONAL :: timerec
File
inout routines.f90
Type
Purpose
Write a time record to a file in standard COHERENS format.
Arguments
time Time record either in the form of an absolute date/time
in string format or a relative time in numerical format.
put file
timerec Time record for output to a netCDF file. If not present,
the time record attribute is increased by one and used as
the output time record.
write time char Write the time in string format.
write time real Write the time in (real) numeric format.
write vars
SUBROUTINE write vars(values,filepars,varid,varatts,vecids)
INTEGER or REAL, INTENT(IN)&
& [, DIMENSION(:[,:[,:[,:]]])] :: values
File
inout routines.f90
Type
Purpose
Write scalar or array data to a file in standard COHERENS format.
Arguments
23.13. LIBRARY OF MATHEMATICAL ROUTINES 1009
values Scalar or array data to be written.

put file
dimension.
file)
values. If not present, the last dimension is considered as
the size of the last dimension. In case that values is a scalar
write vars int 0d Integer scalar
write vars int 1d Integer vector
write vars int 2d Integer 2-D array
write vars real 0d Real scalar
write vars real 1d Real vector
write vars real 2d Real 2-D array
23.13 Library of mathematical routines

brent root
FUNCTION brent root(func,varname,ipars,rpars,noint,noreal,x1,x2,&
& tol,fval,ierr)

INTEGER, INTENT(OUT) :: ierr
INTEGER, INTENT(IN) :: noint, noreal
REAL, INTENT(IN) :: tol
REAL, INTENT(IN) :: x1, x2
REAL, INTENT(OUT) :: fval
INTEGER, INTENT(IN), DIMENSION(noint) :: ipars
REAL, INTENT(IN), DIMENSION(noreal) :: rpars
INTERFACE
FUNCTION func(x,ipars,rpars,noint,noreal)
INTEGER, INTENT(IN) :: noint, noreal
INTEGER, INTENT(IN), DIMENSION(noint) :: ipars
REAL, INTENT(IN), DIMENSION(noreal) :: rpars
REAL,INTENT(IN) :: x
REAL :: func
END FUNCTION func
END INTERFACE
File
math library.f90
Type
Module function
Purpose
Find the root of the function func using Brent’s method. The initial
guess is assumed to be in the interval [x1,x2].
Reference
Press et al. (1992)
Arguments
func Input function
varname Function name
ipars List of integer parameters used in the function call.
rpars List of real parameters used in the function call.
noint Size of the vector ipars which may be zero
noreal Size of the vector rpars which may be zero
x1 Lower bound of the initial interval
x2 Upper bound of the initial interval
tol Required accuracy of the result

fval Value of the function at the root.
ierr Returned error code
0: No error occurred
1: x1 is equal to or larger than x2
2: Unable to adjust the interval [x1,x2] after maxcount=20
iterations
3: Unable to locate the root after maxiter=100 iterations
complex polar
SUBROUTINE complex polar(xreal,ximag,xamp,xpha,maskvals,outflag)
LOGICAL, INTENT(IN), OPTIONAL, DIMENSION(:,:) :: maskvals
REAL, INTENT(IN) [, DIMENSION(:[,:])] :: ximag, xreal
REAL, INTENT(OUT), OPTIONAL [, DIMENSION(:[,:])] :: xamp, xpha
File
math library.f90
Type
Purpose
Returns the aplitude and phase of a complex scalar, vector or 2-D array.
Arguments
xreal Real part of the complex scalar or array
ximag Imaginary part of the complex scalar or array
xamp If present, returned amplitude of the complex scalar or
array
xpha If present, returned phase of the complex scalar or array
[radians]
maskvals If present, 2-D mask array to exclude dry points. The
argument is only allowed for 2-D arrays.
outflag Output flag for invalid points, if present. Equal to real min
otherwise. The argument is only used when maskvals is
present.
complex polar 0d Complex scalars
complex polar 1d Complex vector
complex polar 2d Complex 2-D array
complex sqrt arr

FUNCTION complex sqrt arr(z,ndims,mask,maskvals,outflag)
INTEGER, INTENT(IN), DIMENSION(4) :: ndims
LOGICAL, INTENT(IN), OPTIONAL,&
& DIMENSION(ndims(1),ndims(2)) :: maskvals
COMPLEX, INTENT(IN), DIMENSION(ndims(1),ndims(2),&
& ndims(3),ndims(4)) :: z
COMPLEX, DIMENSION(ndims(1),ndims(2),&
& ndims(3),ndims(4)) :: complex sqrt arr
File
math library.f90
Type
Module function
Purpose
Returns the square root of the elements of a complex (4-D) array.
Reference
Press et al. (1992)
Arguments
z Complex input array
ndims Shape of the complex array
mask A mask is applied on the first two dimensions to exclude
invalid (land) points if set to .TRUE.
maskvals Values of the land mask. Must be present if mask =
.TRUE.
outflag Flag for land values. If not present, the flag is set to
real min
complex sqrt var

FUNCTION complex sqrt var(z)
COMPLEX, INTENT(IN) :: z
COMPLEX :: complex sqrt var
File
math library.f90
Type
Module function
Purpose
Returns the square root of a complex scalar.
Reference
Press et al. (1992)
Arguments
z Complex input scalar
poly root
SUBROUTINE poly root(a,x,m,ierr)
INTEGER, INTENT(IN) :: m
COMPLEX, INTENT(INOUT) :: x
REAL, INTENT(IN), DIMENSION(m+1) :: a
File
math library.f90
Type
Module subroutine
Purpose
Find the root of a polynomial with initial guess x using Laguerre’s
method.
Reference
Press et al. (1992)
Arguments
a Coefficients of the polynomial where a(k+1) represents the

coefficient of the kth power
x Initial guess on input, root on output.
m Degree of the polynomial
1: No solution obtained after maxit=80 iterations
quadratic root arr

SUBROUTINE quadratic root arr(coef,root1,root2,ndims,outflag,&
& mask,maskvals)
REAL, INTENT(IN) :: outflag
INTEGER, INTENT(IN), DIMENSION(4) :: ndims
& DIMENSION(ndims(1),ndims(2)) :: maskvals
REAL, INTENT(IN), DIMENSION(ndims(1),ndims(2),&
& ndims(3),ndims(4),3) :: coef
COMPLEX, INTENT(OUT), DIMENSION(ndims(1),ndims(2),&
& ndims(3),ndims(4)) :: root1, root2
File
math library.f90
Type
Module subroutine
Purpose
Returns the roots of a series second degree equations.
Reference
Press et al. (1992)
Arguments
coef Coefficients of the quadratic equation. The coefficients of
the zero, first and second power are given by respectively
the first, second and third index of the last dimension.
root1 First root
root2 Second root
23.14. OUTPUT DATA FOR STANDARD VARIABLES 1015
ndims Shape of the first four dimensions of the coefficient arrays

outflag Flag for invalid (land) values.
mask A mask is applied on the first two dimensions to exclude
invalid (land) points if set to .TRUE.
maskvals Values of the land mask. Must be present if mask =
.TRUE.
quadratic root var

SUBROUTINE quadratic root var(coef,root1,root2,outflag)
REAL, INTENT(IN), DIMENSION(3) :: coef
REAL, INTENT(IN) :: outflag
COMPLEX, INTENT(OUT) :: root1, root2
File
math library.f90
Type
Module subroutine
Purpose
Returns the roots of a second degree equation.
Reference
Press et al. (1992)
Arguments
coef The coefficients of the zero, first and second power in the
quadratic equation are given by respectively the first, sec-
ond and third index.
root1 First root
root2 Second root
outflag In the case that the solutions are complex, the roots are
set to this value.
23.14 Output data for standard variables

Defines output for standard variables using their key ids.
• An output operator can optionally be provided: minimum, maximum

or mean value, value at a given vertical level or specified depth. For
details see Sections 16.1.1.1, 16.2.1.1, 16.3.2.1.
• The routines replace the user-defined usrdef *vals routines if the key ids
of the output variables have been supplied by the user as part of the
setup.
define out0d vals

SUBROUTINE define out0d vals(outdat,novars,outvars,ivarid,oopt)
REAL, INTENT(OUT), DIMENSION(novars) :: outdat
INTEGER, INTENT(IN), OPTIONAL, DIMENSION(novars) :: ivarid, oopt
TYPE (VariableAtts), INTENT(IN), OPTIONAL, DIMENSION(novars) :: outvars
File
model output.f90
Type
Module subroutine
Purpose
Define 0-D output data.
Arguments
outdat Returned output data
novars Number of output variables
outvars Attributes of the output variables (if ivarid is not defined)
ivarid Variables’s key ids (if outvars is not defined)
oopt Optional output operator applied for each variable. Al-
lowed values are:
oopt null no operator applied
oopt mean volume (3-D variable) or surface (2-D variable)
averaged value
oopt max volume (3-D variable) or surface (2-D variable)
maximum value
oopt min volume (3-D variable) or surface (2-D variable)
minimum value
23.14. OUTPUT DATA FOR STANDARD VARIABLES 1017
define out2d vals

SUBROUTINE define out2d vals(outdat,i,j,novars,outvars,ivarid,oopt,klev,dep,&
& node)
INTEGER, INTENT(IN) :: i, j, novars
CHARACTER (LEN=lennode), OPTIONAL, DIMENSION(novars) :: node
INTEGER, INTENT(IN), OPTIONAL, DIMENSION(novars) :: ivarid, klev, oopt
REAL, INTENT(IN), OPTIONAL, DIMENSION(novars) :: dep
File
model output.f90
Type
Module subroutine
Purpose
Define 2-D output data at a given location.
Arguments
i X-index of the output location
j Y-index of the output location
oopt Optional output operator applied for each variable. Al-
lowed values are:
oopt null no operator applied
oopt mean vertically averaged value (in case ivarid repre-
sents a 3-D variable)
oopt max maximum value over the vertical (in case ivarid
represents a 3-D variable)
oopt min minimum value over the vertical (in case ivarid
represents a 3-D variable)
oopt klev value at a vertical level (in case ivarid repre-
oopt dep value at a specified depth (in case ivarid repre-

klev vertical level(s) taken when oopt equals oopt klev
dep depth(s) below the sea surface taken when oopt equals
oopt dep
node defines the vertical node (’C’ (default if not present) or
’W’ where a W-node (3-D) quantity is evaluated (see Sec-
tion 16.1.1.1 for details)
define out3d vals

SUBROUTINE
define out3d vals(outdat,i,j,k,novars,outvars,ivarid,node)
INTEGER, INTENT(IN) :: i, j, k, novars
CHARACTER (LEN=lennode), OPTIONAL, DIMENSION(novars) :: node
INTEGER, INTENT(IN), OPTIONAL, DIMENSION(novars) :: ivarid
File
model output.f90
Type
Module subroutine
Purpose
Define 2-D output data at a given location.
Arguments
i X-index of the output location
j Y-index of the output location
k vertical index of the output location
node defines the vertical node (’C’ (default if not present) or ’W’
where a W-node quantity is evaluated (see Section 16.1.1.1
for details)
23.15. STANDARD ATTRIBUTES FOR VARIABLES AND FORCING FILES 1019
23.15 Standard attributes for variables and

forcing files
inquire var
SUBROUTINE inquire var(varid,f90 name,long name,units,node,vector name,&
& data type,nodim,shape,dom dims,halo size,varatts)
CHARACTER (LEN=lenname), INTENT(OUT), OPTIONAL :: f90 name
CHARACTER (LEN=lendesc), INTENT(OUT), OPTIONAL :: long name, vector name
CHARACTER (LEN=lenunit), INTENT(OUT), OPTIONAL :: units
CHARACTER (LEN=lennode), INTENT(OUT), OPTIONAL :: node
INTEGER, INTENT(OUT), OPTIONAL :: data type, nodim
TYPE (VariableAtts), INTENT(OUT), OPTIONAL :: varatts
INTEGER, INTENT(OUT), OPTIONAL, DIMENSION(4) :: dom dims, halo size,&
& shape
File
modvars routines.f90
Type
Module subroutine
Purpose
Returns attributes of a model array variable given its variable key id.
Arguments
varid Variable key id
f90 name If present, returned FORTRAN 90 name attribute
long name If present, returned long name attribute
units If present, returned units attribute
node If present, returned grid node where the variable is defined
on the model grid
vector name If present, returned vector name attribute
data type If present, returned data type attribute
nodim If present, returned array rank
shape If present, returned array shape
dom dims If present, returned array shape without halo
halo size If present, returned halo sizes
varatts If present, the variable attributes are returned in a variable

of type VariableAtts
set modfiles atts

SUBROUTINE set modfiles atts(iddesc,ifil,iotype,numvars)
INTEGER, INTENT(IN) :: iddesc, ifil, iotype
INTEGER, INTENT(IN), OPTIONAL :: numvars
File
Type
Module subroutine
Purpose
Define the global attributes of a forcing file.
Arguments
iddesc Forcing file key id
ifil File number of the forcing file
iotype I/O type of the forcing file
1: Input file
2: Output file
numvars Currently not used
set modfiles name

SUBROUTINE set modfiles name(iddesc,ifil,iotype)
INTEGER, INTENT(IN) :: iddesc, ifil, iotype
File
Type
Module subroutine
Purpose
Define the default name of a forcing file. The result is stored in the
filename attribute if no name has been defined by the user.
Arguments
23.15. STANDARD ATTRIBUTES FOR VARIABLES AND FORCING FILES 1021

1: Input file
2: Output file
set modvars atts

SUBROUTINE set modvars atts(iddesc,ifil,iotype,varatts,novars,&
& noprofsd,novarsd,nzdat,numprofs,numvars)
INTEGER, INTENT(IN) :: iddesc, ifil, iotype, novars
INTEGER, INTENT(IN), OPTIONAL, DIMENSION(2:) :: noprofsd, novarsd
INTEGER, INTENT(IN), OPTIONAL :: numprofs, numvars, nzdat
TYPE (VariableAtts), INTENT(INOUT), DIMENSION(:) :: varatts
File
Type
Module subroutine
Purpose
Define the variable attributes of a forcing file.
Arguments
1: Input file
2: Output file
novars Number of data (excluding coordinate) variables in the
data file
noprofsd Number of open boundary data profiles in each data file.
The parameter is only used if the forcing contains speci-
fiers for 3-D open boundary conditions (iddesc = io 3uvobc,
io salobc or io tmpobc and ifil = 1).
novarsd Number of open boundary data variables in each data file.

io salobc or io tmpobc and ifil = 1). In the current version,
its value must be 1.
nzdat Vertical dimension of the 3-D open boundary profiles. The
parameter is only used if the forcing contains specifiers
for 3-D open boundary conditions (iddesc = io 3uvobc,
io salobc or io tmpobc and ifil = 1). In the current ver-
sion, its value must be nz.
numprofs Number of profiles in an open boundary data file. The pa-
rameter is only used if the forcing contains specifiers for 3-
D open boundary conditions (iddesc = io 3uvobc, io salobc
or io tmpobc and ifil > 1).
numvars Number of data variables in an open boundary data file.
io salobc or io tmpobc and ifil > 1). In the current version,
its value must be 1.
23.16 Library routines for linear algebra

cholesky decomp
SUBROUTINE cholesky decomp(a,n,ndim,varname,ierr,info)
INTEGER, INTENT(IN) :: n, ndim
REAL, INTENT(INOUT), DIMENSION(ndim,ndim) :: a
File
nla library.F90
Type
Module subroutine
Purpose
Perform a Cholesky decomposition on a symmetric positive definite
matrix.
23.16. LIBRARY ROUTINES FOR LINEAR ALGEBRA 1023
Reference
Press et al. (1992)
Arguments
a Symmetric, positive-definite matrix on input. On output,
the Cholesky matrix is returned in the lower triangular
and diagonal part.
n Physical dimensions of the square matrix a
ndim Array dimensions of the square matrix a
varname FORTRAN name of the variable a
1: Error occurred
info Writes info to the log file if .TRUE.
cholesky solve
SUBROUTINE cholesky solve(a,b,n,ndim,varname,info)
REAL, INTENT(INOUT), DIMENSION(ndim) :: b
REAL, INTENT(IN), DIMENSION(ndim,ndim) :: a
File
nla library.F90
Type
Module subroutine
Purpose
Solve a linear system of equations using Cholesky decomposition. The
coefficient matrix is obtained from a previous call to cholesky decomp.
Reference
Press et al. (1992)
Arguments
a Cholesky coefficient matrix
b Right hand side of the linear system on input. Solution

vector on output.
n Number of linear equations (physical dimensions of the
square matric a and the vector b)
ndim Array dimensions of the square matrix a and size of the
vector b
LU decomp
SUBROUTINE LU decomp(a,indx,n,ndim,varname,ierr,info)
INTEGER, INTENT(OUT), DIMENSION(ndim) :: indx
REAL, INTENT(INOUT), DIMENSION(ndim,ndim) :: a
File
nla library.F90
Type
Module subroutine
Purpose
Decompose the matrix a into a lower (L) and upper (U) triangular part.
Reference
Press et al. (1992)
Arguments
a On input, the matrix to be decomposed. On output, L is
substituted below the diagonal, U at and above the diag-
onal.
indx Returned vector recording the row permutation effected by
partial pivoting. The vector must be given as argument to
a subsequent call to LU solve
n Physical dimensions of the square matrix a
ndim Array dimensions of the square matrix a

0: No error occurred.
1: A zero is found on the diagonal of the matrix a.
2: The matrix a is singular.
LU solve
SUBROUTINE LU decomp(a,indx,b,n,ndim,varname,info)
INTEGER, INTENT(IN), DIMENSION(ndim) :: indx
REAL, INTENT(INOUT), DIMENSION(ndim) :: b
REAL, INTENT(IN), DIMENSION(ndim,ndim) :: a
File
nla library.F90
Type
Module subroutine
Purpose
Solve a linear system of equations using LU decomposition
Reference
Press et al. (1992)
Arguments
a LU-decomposed coefficient matrix returned from a previ-
ous call to LU decomp
indx Vector recording the row permutation effected by partial
pivoting as returned from a previous call to LU decomp
b Right hand side of the linear system on input. Solution
vector on output.
n Number of linear equations (physical dimensions of the
square matrix a and size of the vector b)
ndim Array dimensions of the square matrix a and size of the
vector b

svd decomp
SUBROUTINE svd decomp(a,w,v,m,n,varname,ierr,info)
INTEGER, INTENT(IN) :: m,n
REAL, INTENT(OUT), DIMENSION(n) :: w
REAL, INTENT(INOUT), DIMENSION(m,n) :: a
REAL, INTENT(OUT), DIMENSION(n,n) :: v
File
nla library.F90
Type
Module subroutine
Purpose
Performs a singular value decomposition on the matrix a, i.e. a = udt v
where u, v are unitary matrices and d a diagonal matrix. The diagonal
elements of w are the singular values of a.
Reference
Press et al. (1992)
Arguments
a Matrix to be decomposed on input, unitary matrix u on
output
w Returned vector of singular values (diagonal elements of
the diagonal matrix d). If n>m, the last n-m elements are
zero.
v Returned unitary matrix v
m Number of rows in a
n Number of columns in a
1: Error occurred
symm eigen
SUBROUTINE symm eigen(a,d,n,vectors,varname,ierr,info)
LOGICAL, INTENT(IN) :: info, vectors
INTEGER, INTENT(IN) :: n
REAL, INTENT(OUT), DIMENSION(n) :: d
REAL, INTENT(INOUT), DIMENSION(n,n) :: a
File
nla library.F90
Type
Module subroutine
Purpose
Returns the eigenvalues and eigenvectors of a real symmetric matrix.
Reference
Press et al. (1992)
Arguments
a Real symmetric matrix on input. On output, the eigen-
vectors are stored in the columns of a if vectors is .TRUE..
If vectors is .FALSE., the matrix a is modified as well but
no longer contains useful information.
d Vector of eigenvalues in descending order
n Dimensions of the square matrix a
vectors Returns the eigenvectors if .TRUE.
1: Error occurred
tridiag reduce
SUBROUTINE tridiag reduce(a,d,e,n,vectors,varname,info)
LOGICAL, INTENT(IN) :: vectors
REAL, INTENT(OUT), DIMENSION(n) :: d, e
REAL, INTENT(INOUT), DIMENSION(n,n) :: a
File
nla library.F90
Type
Module subroutine
Purpose
Performs a Householder reduction to a tridiagonal form on a real sym-
metric matrix.
Reference
Press et al. (1992)
Arguments
a Real symmetric matrix on input. On output, the orthog-
onal matrix effecting the transformation.
d Diagonal elements of the output tridiagonal matrix
e Off-diagonal elements of the output tridiagonal matrix (e(1)=0)
n Dimensions of the square matrix a
vectors No eigenvectors are needed if .FALSE.
tridiag vert
SUBROUTINE tridiag vert(tridcf,psi,nhdims,nzdim,novars,cnode)
INTEGER, INTENT(IN) :: novars, nzdim
REAL, INTENT(IN), DIMENSION(ncloc,nrloc,nzdim,4,novars) :: tridcf
REAL, INTENT(INOUT), DIMENSION(1-nhdims(1):ncloc+nhdims(2),&
& nzdim,novars) :: psi
File
nla library.F90
Type
Module subroutine
Purpose
Update a 3-D variable or variables in time by solving a system of tridi-
agonal equations on each grid point in the horizontal.
Reference
Press et al. (1992)
Arguments
tridcf The first three dimensions correspond to respectively the
X-, Y- and vertical directions of the model grid. Index
elements 1, 2, 3 and 4 in the last dimension represent res-
pectively the coefficient matrices A, B, C, D in equations
(5.302).
psi Returned updated value of psi
nhdims Halo sizes of the model grid array psi (WESN directions)
nzdim Vertical array dimension
novars Number of model variables stored in psi
cnode Nodal type of the variables(s) psi
tridiag vert 1d
SUBROUTINE tridiag vert(tridcf,psi,nzdim,novars,info)
INTEGER, INTENT(IN) :: novars, nzdim
REAL, INTENT(IN), DIMENSION(nzdim,4,novars) :: tridcf
REAL, INTENT(INOUT), DIMENSION(nzdim,novars) :: psi
File
nla library.F90
Type
Module subroutine
Purpose
Update a variable or variables in time by solving a system of tridiagonal
equations in the vertical.
Reference
Press et al. (1992)
Arguments
tridcf The size of the first dimension represents the number of
vertical points. Index elements 1, 2, 3 and 4 in the second
dimension represents respectively the coefficient matrices
A, B, C, D in equations (5.302). The size of the third
dimension is the number of variables for which the linear
system has to be solved.
psi Returned updated value of psi
nzdim Vertical array dimension
novars Number of model variables stored in psi
info Writes log info if set to .TRUE.
23.17 Parallel communications

collect vars
SUBROUTINE collect vars(locvals,procvals,noprocs,ivarid,&
& comm,commtype)
INTEGER, LOGICAL or REAL, INTENT(IN) &
& [,DIMENSION(:[,:[,:[,:]]])] :: locvals
INTEGER, INTENT(IN) :: ivarid, noprocs
INTEGER, LOGICAL or REAL, INTENT(INOUT),&
& DIMENSION (:[,:[,:[,:[,:]]]]) :: procvals
File
paral comms.f90
Type
Purpose
Performs a collect operation, i.e. copies local arrays of the same shape
23.17. PARALLEL COMMUNICATIONS 1031
into one globally defined array. The index of the last dimension corre-
sponds to the process number of each local array.
Reference
Section 9.4.3
Arguments
locvals Local scalar array. Can be of type INTEGER, LOGICAL,
REAL. Rank is between 0 and 2 for LOGICAL logical arrays
and between 0 and 4 otherwise.
procvals Array which collects the contributions of all local arrays.
The array is globally defined. Rank is between 1 and 3 for
LOGICAL logical arrays and between 1 and 5 otherwise.
noprocs Number of involved processes
commtype Communication type for the collect operation (between 1
and 5). If not present, its value is set to iopt MPI comm all
if iopt MPI comm coll=0 or to 5 otherwise.
5: collective communication
collect vars int 0d Integer scalar
collect vars int 1d Integer vector
collect vars int 2d Integer 2-D array
collect vars log 0d Logical scalar
collect vars log 1d Logical vector
collect vars log 2d Logical 2-D array
collect vars real 0d Real scalar
collect vars real 1d Real vector
collect vars real 2d Real 2-D array

combine mod
SUBROUTINE combine mod(glbvals,locvals,lbounds,ivarid,&
& fill,idroot,comm,commtype,commall)
LOGICAL, INTENT(IN), OPTIONAL :: commall
INTEGER, LOGICAL or REAL, INTENT(IN) :: fill
INTEGER, INTENT(IN) :: ivarid
INTEGER, INTENT(IN), OPTIONAL :: comm, commtype, idroot
INTEGER, INTENT(IN), DIMENSION(:) :: lbounds
INTEGER, LOGICAL or REAL, INTENT(OUT), &
& DIMENSION(lbounds(1):,lbounds(2)&
& [,lbounds(3):[,lbounds(4):]]) :: glbvals
INTEGER, LOGICAL or REAL, INTENT(IN), &
& DIMENSION(lbounds(1):,lbounds(2)&
& [,lbounds(3):[,lbounds(4):]]) :: locvals
File
paral comms.f90
Type
Purpose
Performs a combine or combine-all operation on local model grid arrays.
Reference
Section 9.4.2
Arguments
glbvals Global array. Can be of type INTEGER, LOGICAL, REAL.
Rank is 2 for LOGICAL arrays and between 2 and 4 other-
wise.
locvals Local array. Type and rank is the same as glbvals.
lbounds Lower bounds of the local and global arrays. Size must be
equal to the rank of glbvals and locvals.
fill Fill value for elements in the global array outside all lo-
cal domain grids. Type must be the same as glbvals and
locvals.
idroot Root process where the global array is defined in case of
a combine operation. If not present, the root equals the
master process.
for combine-all operations or iopt MPI comm gath other-
wise.
commall A combine-all operation is performed only if present and
set to .TRUE.
combine mod int 2d Integer 2-D array
combine mod log 2d Logical 2-D array
combine mod real 2d Real 2-D array
combine obc
SUBROUTINE combine obc(glbvals,cnode,ivarid,idroot,&
& comm,commtype,commall)
INTEGER, LOGICAL or REAL, INTENT(INOUT),&
& DIMENSION(:[,:[,:]]) :: glbvals
File
paral comms.f90
Type
Purpose
Combines the values of local index elements into a global open boun-
dary array. The result may or may not be available on all processes.
Arguments
glbvals Global array. Can be of type INTEGER, LOGICAL, REAL.
Rank is 1 for LOGICAL arrays and between 1 and 3 other-
wise.
cnode Nodal type of the open boundary array (‘U’, ‘V’, ‘X’, ‘Y’)
master process.
for combine-all operations or iopt MPI comm gath other-
wise.
commall A combine-all operation is performed only if present and
set to .TRUE.
combine obc int 1d Integer vector
combine obc int 2d Integer 2-D array
combine obc int 3d Integer 3-D array
combine obc log 1d Logical vector
combine obc real 1d Real vector
combine obc real 2d Real 2-D array

combine obc real 3d Real 3-D array
combine stats
SUBROUTINE combine stats(realglb,realloc,maxstats,nostatprocs,&
& lstatprocs,ivarid,idroot,comm,commtype)
INTEGER, INTENT(IN) :: ivarid, maxstats
INTEGER, INTENT(IN), DIMENSION(nprocs) :: nostatprocs
INTEGER, INTENT(IN), DIMENSION(nprocs,maxstats) :: lstatprocs
REAL, INTENT(OUT), DIMENSION(:[,:[,:]]) :: realglb
REAL, INTENT(IN), DIMENSION(:[,:[,:]]) :: realloc
File
paral comms.f90
Type
Purpose
Combine local station data into a global array on the root process.
Reference
Section 9.5
Arguments
realglb Global array. Rank is between 1 and 3.
realloc Local array. Rank is the same as realglb.
maxstats Second dimension of array lstatprocs
nostatprocs Number of local data stations
lstatprocs Index mapping array
idroot Root process where the global array is defined. If not
present, the root equals the master process.

combine stats real 1d Real vector
combine stats real 2d Real 2-D array
combine stats real 3d Real 3-D array
combine submod
SUBROUTINE combine submod(realglb,realloc,limprocs,ivarid,rfill,&
& idroot,comm,commtype)
INTEGER, INTENT(IN), DIMENSION(2,2,nprocs) :: limprocs
REAL, INTENT(OUT), DIMENSION(:,:[,:[,:]]) :: realglb
REAL, INTENT(IN), DIMENSION(:,:[,:[,:]]) :: realloc
File
paral comms.f90
Type
Purpose
Combine local sub-grid model arrays into a global array on the root
process.
Reference
Section 9.4.2
Arguments
realglb Global array. Rank is between 2 and 4.
realloc Local array. Rank is the same as realglb.
limprocs Start/end indices in the X- and Y-direction of the local
array section within the global array
rfill Fill values for elements in the global array with no corres-
ponding element in a local array
master process.
combine submod real 2d Real 2-D array
copy chars
SUBROUTINE copy chars(chardat,lenstr,ivarid,idroot,comm,commtype)
INTEGER, INTENT(IN) :: ivarid, lenstr
CHARACTER (LEN=lenstr), INTENT(INOUT) &
& [, DIMENSION(:[,:[,:[,:]]])] :: chardat
File
paral comms.f90
Type
Purpose
Copies a scalar string or an array of strings from the root to all other
processes.
Reference
Section 9.4.2
Arguments
chardat String scalar or array to be copied. Rank is between 0 and

4.
lenstr Length of the string(s)
commtype Communication type for the copy operation (between 1
and 5). If not present, its value is set to iopt MPI comm scat
copy chars 0d Character string
copy chars 1d Character string vector
copy chars 2d Character string 2-D array
copy vars
SUBROUTINE copy vars(values,ivarid,idroot,comm,commtype)
INTEGER, LOGICAL or REAL, INTENT(INOUT) &
& [, DIMENSION(:[,:[,:[,:]]])] :: values
File
paral comms.f90
Type
Purpose
Copies an integer, logical or real scalar or array data from the root to
all other processes.
Reference
Section 9.4.2
Arguments
values Scalar or array data to be copied. Rank is between 0 and
4.
commtype Communication type for the copy operation (between 1
and 5). If not present, its value is set to iopt MPI comm scat
copy vars int 0d Integer scalar
copy vars int 1d Integer vector
copy vars int 2d Integer 2-D array
copy vars log 0d Integer scalar
copy vars log 1d Logical vector
copy vars log 2d Logical 2-D array
copy vars real 0d Real scalar
copy vars real 1d Real vector
copy vars real 2d Real 2-D array

distribute mod
SUBROUTINE distribute mod(glbvals,locvals,lbounds,nhdist,&
& ivarid,fill,shared,idroot,comm,commtype)
INTEGER, LOGICAL or REAL, INTENT(IN) :: fill
INTEGER, LOGICAL or REAL, INTENT(IN), DIMENSION(lbounds(1):,lbounds(2):&
& [,lbounds(3):[,lbounds(4):]]) :: glbvals
INTEGER, LOGICAL or REAL, INTENT(IN), DIMENSION(lbounds(1):,lbounds(2):&
& [,lbounds(3):[,lbounds(4):]]) :: locvals
File
paral comms.f90
Type
Purpose
Distributes an integer, logical or real model grid array from the root to
all other processes.
Reference
Section 9.4.2
Arguments
glbvals Global integer, logical or real model grid array to be dis-
tributed. Rank is 2 for logical arrays and between 2 and
4 otherwise.
locvals Returned distributed array. Type and rank is the same as
glbvals.
lbounds Lower bounds of the local and global arrays. Size must be
equal to the rank of glbvals and locvals.
nhdist Halo sizes used in the distribution operation (WESN di-

rections)
fill Fill values for the local array. Type must be the same as
glbvals, locvals.
shared The global array is defined on all processes if .TRUE. (in-
which case no communication is performed), on the root
process only if .FALSE.
idroot Root process where the global array is defined, if shared is
.FALSE. If not present, the root equals the master process.
distribute mod int 2d Integer 2-D array
distribute mod log 2d Logical 2-D array
distribute mod real 2d Real 2-D array
distribute mod hgrid 2d

SUBROUTINE distribute mod hgrid 2d(surfglb,surfloc,lbounds,&
& nhdist,ivarid,ifill,rfill,&
& shared,idroot,comm,commtype)
INTEGER, INTENT(IN) :: ifill, ivarid
INTEGER, INTENT(IN), DIMENSION(2) :: lbounds

TYPE (HRelativeCoords), INTENT(IN),&
& DIMENSION(lbounds(1):,lbounds(2):) :: surfglb
TYPE (HRelativeCoords), INTENT(INOUT),&
& DIMENSION(lbounds(1):,lbounds(2):) :: surfloc
File
paral comms.f90
Type
Module subroutine
Purpose
Distributes a “global” derived type 2-D model grid array of type
HRelativeCoords from the root to all other processes.
Reference
Section 9.4.2
Arguments
surfglb Global derived type array to be distributed
surfloc Local distributed derived type array
lbounds Lower bounds of the local and global arrays.
nhdist Halo sizes used in the distribution operation (WESN di-
rections)
ifill Fill value for integer components
rfill Fill value for real components
shared The global array is defined on all processes if .TRUE. (in
which case no communication is performed), on the root
process only if .FALSE.
idroot Root process where the global array is defined if shared is
.FALSE. If not present, the root equals the master process.

exchange mod
SUBROUTINE exchange mod(values,lbounds,nhexch,ivarid,comm,corners,commtype)
LOGICAL, INTENT(IN), OPTIONAL :: corners
INTEGER, INTENT(IN), DIMENSION(4) :: nhexch
INTEGER, LOGICAL or REAL, INTENT(INOUT), &
& DIMENSION(lbounds(1):,lbounds(2):&
& [,lbounds(3):[,lbounds(4):]]) :: values
File
paral comms.f90
Type
Purpose
Perform exchange communications between a local process and its
neighbours.
Reference
Section 9.4.3
Arguments
values Local integer, logical or real model grid array. Rank is 2
for logical arrays and between 2 and 4 otherwise.
lbounds Lower bounds of the local array. Size must be equal to the
rank of values.
nhexch Halo sizes used in the exchange operations (WESN direc-
tions). A zero value means that no exchange is made in
the corresponding direction.
corners Corner communications are disabled if present and set to
.FALSE.
commtype Communication type for the exchange operation (between

1 and 5). If not present, its value is set to iopt MPI comm exch.
5: combined send-receive communication
exchange mod int 2d Integer 2-D array
exchange mod log 2d Logical 2-D array
exchange mod real 2d Real 2-D array
halo exch comms

SUBROUTINE halo exch comms(arrcomms,nhexch,corners)
LOGICAL, INTENT(IN) :: corners
INTEGER, INTENT(IN), DIMENSION(4) :: nhexch
TYPE(ExchComms), INTENT(OUT), DIMENSION(MaxHaloComms) :: arrcomms
File
paral comms.f90
Type
Module subroutine
Purpose
Set parameters for exchange communications. The routine is called by
exchange mod.
Arguments
arrcomms Properties of the communications performing the exchanges
nhexch Halo sizes used in the exchange operations (WESN direc-
tions). A zero value means that no exchange is made in
the corresponding direction.
corners Corner communications are disabled if set to .TRUE.
23.18. UTILITY ROUTINES FOR PARALLEL APPLICATION 1045
23.18 Utility routines for parallel application
max vars
SUBROUTINE max vars(values,maxval,ivarid,idroot,comm,commtype,&
& commall,mask)
INTEGER or REAL, INTENT(OUT) :: maxval
LOGICAL, INTENT(IN), OPTIONAL, DIMENSION(:,:) :: mask
INTEGER or REAL, INTENT(IN) [, DIMENSION(:,:[,:])] :: values
File
paral utilities.f90
Type
Purpose
Compute the global maximum of a scalar or array integer or real vari-
able.
Arguments
values Local integer or real scalar, 2-D or 3-D model grid array
maxval Returned global maximum. Type must be the same as
values.
idroot Root process which returns the result in case of a all-to-
one communication. If not present, the root equals the
master process.
commtype Communication type (between 1 and 5). If not present, its
value is set to iopt MPI comm gath or iopt MPI comm all
if iopt MPI comm coll=0 or to 5 (collective call) other-
wise.

commall Result is returned by all processes if present and .TRUE.
mask If present, points where mask is .FALSE. are excluded.
Otherwise all points are included. The argument is not
allowed for scalar input data.
max vars int 0d Integer scalar
max vars int 2d Integer 2-D array
max vars int 3d Integer 3-D array
max vars real 0d Real scalar
max vars real 2d Real 2-D array
max vars real 3d Real 3-D array
maxloc vars
SUBROUTINE maxloc vars(values,maxval,maxpos,ivarid,&
& idroot,comm,commtype,commall,mask)
INTEGER or REAL, INTENT(OUT) :: maxval
INTEGER, INTENT(OUT), DIMENSION(:) :: maxpos
INTEGER or REAL, INTENT(IN), DIMENSION(:,:[,:])] :: values
File
paral utilities.f90
Type
Purpose
Compute the value and index location of a global maximum of an
integer or real 2-D or 3-D model grid array.
Arguments
values Local integer or real 2-D or 3-D model grid array

maxval Returned global maximum. Type must be the same as
values.
maxpos Global indices of the location of the maximum. Size equals
the rank of values.
master process.
value is set to iopt MPI comm gath or iopt MPI comm all.
maxloc vars int 2d Integer 2-D array
maxloc vars int 3d Integer 3-D array
maxloc vars real 2d Real 2-D array
maxloc vars real 3d Real 3-D array
min vars
SUBROUTINE min vars(values,minval,ivarid,idroot,comm,commtype,&
& commall,mask)
INTEGER or REAL, INTENT(OUT) :: minval
File
paral utilities.f90
Type
Purpose
Compute the global minimum of a scalar or array integer or real vari-
able.
Arguments
minval Returned global minimum. Type must be the same as
values.
master process.
wise.
min vars int 0d Integer scalar
min vars int 2d Integer 2-D array
min vars int 3d Integer 3-D array
min vars real 0d Real scalar

min vars real 2d Real 2-D array
min vars real 3d Real 3-D array
minloc vars
SUBROUTINE minloc vars(values,minval,minpos,ivarid,&
& idroot,comm,commtype,commall,mask)
INTEGER or REAL, INTENT(OUT) :: minval
INTEGER, INTENT(OUT), DIMENSION(:) :: minpos
INTEGER or REAL, INTENT(IN), DIMENSION(:,:[,:])] :: values
File
paral utilities.f90
Type
Purpose
Compute the value and index location of a global minimum of an integer
or real 2-D or 3-D model grid array.
Arguments
values Local integer or real 2-D or 3-D model grid array
minval Returned global minimum. Type must be the same as
values.
minpos Global indices of the location of the minimum. Size equals
the rank of values.
master process.

minloc vars int 2d Integer 2-D array
minloc vars int 3d Integer 3-D array
minloc vars real 2d Real 2-D array
minloc vars real 3d Real 3-D array
sum vars
SUBROUTINE sum vars(values,sumval,ivarid,idroot,comm,commtype,&
& commall,mask)
INTEGER or REAL, INTENT(OUT) :: sumval
File
paral utilities.f90
Type
Purpose
Compute the global sum of a scalar or array integer or real variable.
The result depends on the number of processes, but it more efficient
than sum2 vars (see below).
Arguments
sumval Returned global sum. Type must be the same as values.

master process.
wise.
sum vars int 0d Integer scalar
sum vars int 2d Integer 2-D array
sum vars int 3d Integer 3-D array
sum vars real 0d Real scalar
sum vars real 2d Real 2-D array
sum vars real 3d Real 3-D array
sum2 vars
SUBROUTINE sum2 vars(realdat,realsum,nhdims,cnode,ivarid,idroot,&
& comm,commtype,commall,mask)
REAL, INTENT(OUT) :: realsum

REAL, INTENT(IN), DIMENSION(:,:[,:[,:]])] :: realdat
File
paral utilities.f90
Type
Purpose
Compute the global sum of a real model grid array. The process does
not depend on the domain decomposition, but is less efficient than
sum vars. A land mask is always applied.
Arguments
realdat Local real scalar, 2-D, 3-D or 4-D model grid array
realsum Returned global sum.
nhdims Halo sizes of the model grid array (WESN directions)
cnode Grid node where the model array is defined: ‘C’, ‘U’, ‘V’,
‘E’ (corner node)
master process.
Otherwise, the dry points are obtained from the grid point-
ers arrays. The argument has primarily been introduced
to make allowance for either permanently (land) or tem-
porarily dry grid points at C-nodes.
23.19. RESET OF SETUP PARAMETERS 1053
sum2 vars real 2d Real 2-D array
23.19 Reset of setup parameters

When a usrdef routines is called (or parameters are read from a CIF),
some parameters may need to be reset by calling appropriate “reset” rou-
tines. For example, reset mod params is called after usrdef mod params and
reset initial conditions after usrdef phsics.
reset initial conditions

SUBROUTINE reset initial conditions
File
reset model.F90
Type
Module subroutine
Purpose
Reset initial conditions.
reset mod params

SUBROUTINE reset mod params
File
reset model.F90
Type
Module subroutine
Purpose
Reset model parameters, defined either by default or by the user. A
warning message is written in most cases.
reset mod vars

SUBROUTINE reset mod vars(varatts)
TYPE (VariableAtts), INTENT(INOUT) :: varatts
File
reset model.F90
Type
Module subroutine
Purpose
Define the attributes of variables in model forcing files.
Arguments
reset out files

SUBROUTINE rest out files(filepars,status)
TYPE (FileParams), INTENT(INOUT), DIMENSION(:[,:]) :: filepars
CHARACTER (LEN=1), INTENT(IN),&
& DIMENSION(SIZE(filepars,DIM=1)) :: status
File
reset model.F90
Type
Purpose
Reset the status and iunit attributes of user output files.
Arguments
filepars Attributes of the user output files
status Values of the new status attributes
reset out files 1d Vector array of files
reset out files 2d 2-D array of files
23.19. RESET OF SETUP PARAMETERS 1055
reset out gpars

SUBROUTINE rest out gpars(outgpars,arrname,tseries,end reset)
LOGICAL, INTENT(IN) :: end reset, tseries
TYPE (OutGridParams), INTENT(INOUT), DIMENSION(:) :: outgpars
File
reset model.F90
Type
Module subroutine
Purpose
Reset the attributes of a user defined output grid.
Arguments
outgpars Attributes of the user output grid
arrname Name of the attributes array
tseries .TRUE. for time series output, .FALSE. otherwise
end reset If .TRUE., resets the last output time (defined by the
tlims(2) attribute) to the latest possible value before the
end of the simulation.
reset out stats

SUBROUTINE rest out stats(statlocs)
TYPE (StationLocs), INTENT(INOUT), DIMENSION(:) :: statlocs
File
reset model.F90
Type
Module subroutine
Purpose
Reset the attributes of user defined output station attributes.
Arguments
statlocs Attributes of the user defined output stations
reset out vars

SUBROUTINE reset out vars(varatts)
TYPE (VariableAtts), INTENT(INOUT), DIMENSION(:) :: varatts
File
reset model.F90
Type
Module subroutine
Purpose
Define the attributes of user output variables in case they are not de-
fined by the user.
Arguments
23.20 Random generators

A library for the generation of random numbers is implemented. The rou-
tines are based on the algorithm developed by L’Ecuyer & Côté (1991). The
random numbers are either taken between a given interval or from a nor-
malised distribution with a given mean and standard deviation. The latter
routines are taken form Press et al. (1992). The library is used as follows
1. All random generators are initialised in the program by calling rng init.
In the current implementation all generators use the default initial
seeed.
2. A random generator is opened by rng open. The routine returns a
“generator” id number which is used in all subsequent calls. Up to 32
independent generators can be open at the same time.
3. Random number(s) are generated by the following routines
• within a given interval: rng uniform var, rng uniform arr
• with a given mean and standard deviation: rng normal var,
rng normal arr
4. A random generator can be re-set for a new independent series of ran-
dom numbers by calling rng reset. The routine can be used for parallel
applications to prevent that the same numbers are generated on diffe-
rent sub-domains.
23.20. RANDOM GENERATORS 1057
5. A random generator is closed by calling rng close. After this call the
generator number id can no longer be used.
6. All generators are closed and parameters are reset to their initial de-
fault conditions by a call in the program of rng finalize at the end of a
simulation.
rng close
SUBROUTINE rng close(numgen)
INTEGER, INTENT(IN), OPTIONAL :: numgen
File
rng library.f90
Type
Module subroutine
Purpose
Disable (“close”) a random generator.
Arguments
numgen Generator id
rng finalize
SUBROUTINE rng finalize
File
rng library.f90
Type
Module subroutine
Purpose
Close all generators and reset parameters to the their default values.
The routine is called by the program at the end of a simulation.
rng init
SUBROUTINE rng init
File
rng library.f90
Type
Module subroutine
Purpose
Set the random seed for all generators and initialise other parameters.
rng multmod decompos

FUNCTION rng multmod decompos(a,s,m)
INTEGER, INTENT(IN) :: a, m, s
INTEGER :: rng multmod decompos
File
rng library.f90
Type
Module function
Purpose
Returns (as)mod(m). The function is used internally in the library.
Reference
L’Ecuyer & Côté (1991)
rng normal arr

SUBROUTINE rng normal arr(xrand,ncount,numgen,xmean,xstd)
INTEGER, INTENT(IN) :: ncount, numgen
REAL, INTENT(IN) :: xmean, xstd
REAL, INTENT(OUT), DIMENSION(ncount) :: xrand
File
rng library.f90
Type
Module subroutine
Purpose
Generate a vector of random numbers with mean xmean and standard
deviation xstd.
Arguments
xrand Returned random numbers
ncount Size of the returned vector
numgen Generator id
xmean Mean value
xstd Standard deviation
rng normal var

SUBROUTINE rng normal var(xrand,numgen,xmean,xstd)
INTEGER, INTENT(IN) :: numgen
REAL, INTENT(OUT) :: xrand
REAL, INTENT(IN) :: xmean, xstd
File
rng library.f90
Type
Module subroutine
Purpose
Generate a random number with mean xmean and standard deviation
xstd.
Arguments
xrand Returned random number
numgen Generator id
xmean Mean value
xstd Standard deviation
rng open
SUBROUTINE rng open(numgen)
INTEGER, INTENT(OUT) :: numgen
File
rng library.f90
Type
Module subroutine
Purpose
Enable (“open”) a random generator.
Arguments
numgen Returned generator id
rng opened
SUBROUTINE rng opened(numgen,flag)
LOGICAL, INTENT(OUT) :: flag
File
rng library.f90
Type
Module subroutine
Purpose
Returns flag as .TRUE. if the generator with id numgen has been opened.
Arguments
numgen Generator id
flag Returned flag
rng reset
SUBROUTINE rng reset(numgen,seedtype)
CHARACTER (LEN=1), INTENT(IN) :: seedtype
File
rng library.f90
Type
Module subroutine
Purpose
Reset an open generator according to the value of seedtype. The rou-
tine is called in parallel mode to enable independent series of random
numbers on different sub-domains with the same random generator.
Reference
Arguments
numgen Generator id
seedtype Type of reset
‘I’ reset to the initial state
‘L’ no reset
‘N’ a new set a random numbers will be generated which
are different from the initial state
rng standard normal

SUBROUTINE rng standard normal(xran,numgen)
REAL, INTENT(OUT) :: xran
File
rng library.f90
Type
Module subroutine
Purpose
Generate a random number with zero mean and unit variance.
Reference
Routine gasdev from Press et al. (1992)
Arguments
xran Returned random number
numgen Generator id
rng standard uniform

SUBROUTINE rng standard normal uniform(xran,numgen)
REAL, INTENT(OUT) :: xran
File
rng library.f90
Type
Module subroutine
Purpose
Generate a random number between 0 and 1.
Reference
Arguments
xran Returned random number
numgen Generator id
rng uniform arr

SUBROUTINE rng uniform arr(xrand,nosize,numgen,xlo,xhi)
INTEGER, INTENT(IN) :: nosize, numgen
REAL, INTENT(IN) :: xhi, xlo
REAL, INTENT(OUT), DIMENSION(nosize) :: xrand
File
rng library.f90
Type
Module subroutine
Purpose
Generate a vector of random numbers between xlo and xhi.
Arguments
xrand Returned vector of random numbers
nosize Size of the random vector
numgen Generator id
xlo Lower limit
xhi Upper limit
rng uniform var

SUBROUTINE rng uniform var(xrand,numgen,xlo,xhi)
REAL, INTENT(OUT) :: xrand
REAL, INTENT(IN) :: xhi, xlo
23.21. TIME AND CALENDAR DATE ROUTINES 1063
File
rng library.f90
Type
Module subroutine
Purpose
Generate a random number between xlo and xhi.
Arguments
xrand Returned vector of random numbers
numgen Generator id
xlo Lower limit
xhi Upper limit
23.21 Time and calendar date routines

add secs to date
SUBROUTINE add secs to date(datetime1,datetime2,numsteps,dsecs)
CHARACTER (LEN=lentime) or INTEGER, DIMENSION(7),&
& INTENT(IN) :: datetime1
& INTENT(OUT) :: datetime2
INTEGER, INTENT(IN) :: numsteps
REAL, INTENT(IN) :: dsecs
File
time routines.f90
Type
Purpose
Add a number of number of time steps to a given date.
Arguments
datetime1 Initial date and time
datetime2 Returned new date and time. Must have the same type as
datetime1.
numsteps Number of time steps
dsecs Number of seconds in one time step [s]
add secs to date char date and time in string format
add secs to date int date and time in integer vector format
add secs to phase

SUBROUTINE add secs to phase(phasein,phaseout,numsteps,dsecs,freq)
INTEGER, INTENT(IN) :: numsteps
REAL, INTENT(IN) :: dsecs, freq, phasein
REAL, INTENT(OUT) :: phaseout
File
time routines.f90
Type
Module subroutine
Purpose
Update an harmonic phase after a number of time steps. The result is
returned modulo 2π.
Arguments
phasein Initial phase [rad]
phaseout Returned updated phase [rad]
numsteps Number of time steps
dsecs Number of seconds in one time step [s]
freq Harmonic frequency [rad/s]
check date
SUBROUTINE check date(datetime,varname)
& INTENT(IN) :: datetime
File
time routines.f90
Type
Purpose
Check a calendar time and time in string or integer format.
Arguments
datetime Calendar date and time
varname Name of the date/time variable
check date char calendar date and time in string format
check date int calendar date and time in integer vector format
clock date time

SUBROUTINE clock date time(charclock)
CHARACTER (LEN=lentime), INTENT(OUT) :: charclock
File
time routines.f90
Type
Module subroutine
Purpose
Returns the calendar date and time from the machine’s internal real-
time clock.
Arguments
charclock Returned internal calendar date and time in COHERENS
string format
convert date
FUNCTION convert date(datetime1) RESULT(datetime2)
& INTENT(IN) :: datetime1
INTEGER, DIMENSION(7) or CHARACTER (LEN=lentime) : datetime2
File
time routines.f90
Type
Purpose
Convert a calendar date and time from string to integer format or vice
versa.
Arguments
datetime1 Calendar date and time on input
datetime2 Returned calendar date and time in the opposite format
of datetime1
check date to char convert to integer format
check date to int convert to string format
date to year
SUBROUTINE date to year(datetime,yearnum)
REAL, INTENT(OUT) :: yearnum
File
time routines.f90
Type
Purpose
Convert a calendar date and time in string or integer format to a year
number with a decimal part.
Arguments
yearnum Returned year number
date to year char calendar date and time is in string format
date to year int calendar date and time is in integer format
date number
SUBROUTINE date to year(datetime,daynum)
REAL, INTENT(OUT) :: daynum
File
time routines.f90
Type
Purpose
Returns the day number of the year. Result is between 0 and 365 (or
366 for a leap year).
Arguments
daynum Returned day number
day number char calendar date and time is in string format
day number int calendar date and time is in integer format
diff clock
FUNCTION diff clock(npccold)
INTEGER, INTENT(IN) :: npccold
INTEGER :: diff clock
File
time routines.f90
Type
Module function
Purpose
Returns the number of clock counts since a previous call to read clock.
Arguments
npccold Number of previous clock counts
diff dates
SUBROUTINE diff dates(datetime1,datetime2,tunit,nosecs,&
& millisecs,rtime)
& INTENT(IN) :: datetime1, datetime2
INTEGER, INTENT(IN) :: tunit
INTEGER, INTENT(OUT), OPTIONAL :: millisecs
INTEGER (KIND=kndilong), INTENT(OUT), OPTIONAL :: nosecs
REAL, INTENT(OUT), OPTIONAL :: rtime
File
time routines.f90
Type
Purpose
Returns the time between two given calendar dates. Result is negative
if the second date is earlier than the first one.
Arguments
datetime1 First calendar date and time
datetime2 Second calendar date and time in the same format as date-
time1
tunit Time unit for the result
0: seconds and (optionally) milliseconds
1: seconds
2: minutes
3: hours
4: days
5: months
6: years
nosecs If present and tunit=0, the result is in integer seconds.
millisecs If present and tunit=0, the residual number of milliseconds
(between 0 and 999).
rtime If present and tunit>0, the result is in real format (with
milliseconds set to zero).
diff dates char calendar dates are in string format
diff dates int calendar dates are in integer format
.earlier.
Usage: datetime1.earlier.datetime2
CHARACTER (LEN=lentime) or INTEGER(7),&
LOGICAL operator :: earlier
File
time routines.f90
Type
Generic operator
Purpose
Returns .TRUE. is datetime1 is earlier than datetime2.
Arguments
time1
earlier char compares calendar dates in string format
earlier int compares calendar dates in integer format
error lbound var date

SUBROUTINE error lbound var date(cdate,varname,cdatemin,matchmin)
CHARACTER (LEN=lentime), INTENT(IN) :: cdate, cdatemin
File
time routines.f90
Type
Module subroutine
Purpose
Checks whether cdate is not earlier than datemin if matchmin is .TRUE.
or is later than cdatemin if matchmin is .FALSE.
Arguments
cdate Calendar date and time to be checked
varname Name of the calendar date variable
cdatemin Earliest allowed calendar date
machtmin If .FALSE. (.TRUE.), cdate must be later (not earlier) than
cdatemin.
error ubound var date

SUBROUTINE error ubound var date(cdate,varname,cdatemax,matchmax)
CHARACTER (LEN=lentime), INTENT(IN) :: cdate, cdatemax
File
time routines.f90
Type
Module subroutine
Purpose
Checks whether cdate is not later than cdatemax if matchmax is .TRUE.
or is earlier than cdatemax if matchmax is .FALSE.
Arguments
cdate Calendar date and time to be checked
varname Name of the calendar date variable
cdatemax Latest allowed calendar date
matchmin If .FALSE. (.TRUE.), cdate must be earlier (not later) than
cdatemax.
initialise time
SUBROUTINE initialise time
File
time routines.f90
Type
Module subroutine
Purpose
Routine called by the program at the initial time to initialise a series
of parameters related to date and time.
.later.
Usage: datetime1.later.datetime2
LOGICAL operator :: .later.
File
time routines.f90
Type
Generic operator
Purpose
Returns .TRUE. is datetime1 is later than datetime2.
Arguments
time1
later char compares calendar dates in string format
later int compares calendar dates in integer format
leap year
FUNCTION leap year(iyear)
INTEGER, INTENT(IN) :: iyear
INTEGER :: leap year
File
time routines.f90
Type
Module function
Purpose
Returns the number of leap days (0 or 1) in a given year.
Arguments
iyear Given year
log timer in
SUBROUTINE log timer in(npcc,ivarid,logname,info)
LOGICAL, INTENT(IN), OPTIONAL :: info
CHARACTER (LEN=*), INTENT(IN), OPTIONAL :: logname
INTEGER, INTENT(IN), OPTIONAL :: ivarid
INTEGER, INTENT(OUT), OPTIONAL :: npcc
File
time routines.f90
Type
Module subroutine
Purpose
Writes the tracing info to a log file when a routine is called and reads
(optionally) the current machine’s clock count.
Arguments
npcc If present, the returned clock count.
ivarid If present, the key id of variable whose name is added in
the log message
logname If not present, the log message writes the name of the
calling routine (i.e. the one at the highest program level).
Otherwise, this name is replaced by the string logname.
info No log message will be written if this argument is present
and .FALSE.
log timer out

SUBROUTINE log timer out(npcc,itm type,info)
LOGICAL, INTENT(IN), OPTIONAL :: info
INTEGER, INTENT(IN), OPTIONAL :: itm type, npcc
File
time routines.f90
Type
Module subroutine
Purpose
Writes the tracing info to a log file before a routine is exited and update
the number of clock counts for a given timer.
Arguments
npcc If present, the clock count from a previous call to log timer in.
itm type If present, the key id of the timer which needs to be up-
dated.
info No log message will be written if this argument is present
and .FALSE.
.noearlier.
Usage: datetime1.noearlier.datetime2
LOGICAL operator :: noearlier
File
time routines.f90
Type
Generic operator
Purpose
Returns .TRUE. is datetime1 is not earlier than datetime2.
Arguments
time1
noearlier char compares calendar dates in string format
noearlier int compares calendar dates in integer format
.nolater.
Usage: datetime1.nolater.datetime2
LOGICAL operator :: .nolater.
File
time routines.f90
Type
Generic operator
Purpose
Returns .TRUE. is datetime1 is not later than datetime2.
Arguments
time1
nolater char compares calendar dates in string format
nolater int compares calendar dates in integer format
num time steps

SUBROUTINE num time steps(datetime1,datetime2,dsecs,numsteps)
INTEGER, INTENT(OUT) :: numsteps
REAL, INTENT(IN) :: dsecs
File
time routines.f90
Type
Purpose
Returns the number of time steps between two given calendar dates.
Result is negative if the second date is earlier than the first one and
rounded from below if the number of seconds between the two dates is
not an integer multiple of dsecs.
Arguments
time1
descs Number of seconds in one time step [s]
numsteps Returned number of time steps
num time steps char calendar dates are given in string format
num time steps int calendar dates are given in integer format
read clock
FUNCTION read clock()
File
time routines.f90
Type
Module function
Purpose
Returns the machine’s internal clock count.
suspend proc
SUBROUTINE suspend proc(nosecswait)
INTEGER, INTENT(IN) :: nosecswait
File
time routines.f90
Type
Module function
Purpose
Suspends program execution of the calling process for the given number
of seconds.
Arguments
nosecswait Wait time [s]
update time
SUBROUTINE update time
File
time routines.f90
Type
Module subroutine
Purpose
Updates the calendar date/time and a series of parameters related to
date and time (e.g. the number of seconds since the start of the simu-
lation) at the start of a new iteration in the time loop.
year to date
SUBROUTINE year to date(yearnum,datetime)
& INTENT(OUT) :: datetime
REAL, INTENT(IN) :: yearnum
File
time routines.f90
Type
Purpose
Convert an absolute year number to a calendar date and time in a
string or integer vector format.
Arguments
yearnum Absolute date in years
datetime Returned calendar date
year to date char result is returned in string format
year to date int result is returned in integer format
23.22. ROUTINES USED BY THE TURBULENCE MODEL 1077
23.22 Routines used by the turbulence model
buoyancy frequency
SUBROUTINE buoyancy frequency
File
turbulence routines.F90
Type
Module subroutine
Purpose
Calculate the squared buoancy frequency N 2 on the model grid using
the algorithm given in Section 5.3.11.2.
Reference
Section 5.3.11.2
dissip lim conds

SUBROUTINE dissip lim conds
File
Type
Module subroutine
Purpose
Apply the limiting condition for the dissipation rate ε given by equa-
tion (4.213).
Reference
Section 4.4.3.6
dissip to zlmix
SUBROUTINE dissip to zlmix
File
Type
Module subroutine
Purpose
Calculate the mixing length l from the dissipation rate ε using equa-
tion (4.191).
mom strat MA
FUNCTION mom strat MA(ricnum,mask)
LOGICAL, INTENT(IN), DIMENSION(ncloc,nrloc) :: mask
REAL, INTENT(IN), DIMENSION(ncloc,nrloc) :: ricnum
REAL, DIMENSION(ncloc,nrloc) :: mom strat MA
File
Type
Module function
Purpose
Returns the Munk-Anderson stratification function for momentum fm (Ri)
using (4.127). Result is returned at wet points only.
Arguments
ricnum Richardson number
mask Mask to exclude land areas
richardson number
FUNCTION richardson number(k,mask)
INTEGER, INTENT(IN) :: k
LOGICAL, INTENT(IN), DIMENSION(:,:) :: mask
REAL, DIMENSION(LBOUND(mask,1):UBOUND(mask,1),&
& LBOUND(mask,2):UBOUND(mask,2)) :: richardson number
File
Type
Module function
23.22. ROUTINES USED BY THE TURBULENCE MODEL 1079
Purpose
Returns the Richardson number Ri defined by (4.118) at the vertical
level k. Result is returned at wet points only.
Arguments
k Index of vertical level
richardson number 0d
FUNCTION richardson number 0d(i,j,k)
REAL :: richardson number 0d
File
Type
Module function
Purpose
Returns the Richardson number Ri defined by (4.118) at a location on
the model grid.
Arguments
i X-location on the model grid
j Y-location on the model grid
k Vertical location on the model grid
scal strat MA
FUNCTION scal strat MA(ricnum,mask)
LOGICAL, INTENT(IN), DIMENSION(ncloc,nrloc) :: mask
REAL, INTENT(IN), DIMENSION(ncloc,nrloc) :: ricnum
REAL, DIMENSION(ncloc,nrloc) :: scal strat MA
File
Type
Module function
Purpose
Returns the Munk-Anderson stratification function for scalars gm (Ri)
using (4.128). Result is returned at wet points only.
Arguments
ricnum Richardson number
shear frequency
SUBROUTINE shear frequency
File
Type
Module subroutine
Purpose
Calculate the squared shear frequency M 2 on the model grid using the
algorithm given in Section 5.3.11.2.
Reference
Section 5.3.11.2
zlmix lim conds

SUBROUTINE zlmix lim conds
File
Type
Module subroutine
Purpose
Apply the limiting condition for the mixing length l given by equa-
tion (4.213).
Reference
Section 4.4.3.6
23.23. MISCELLANEOUS UTILITY ROUTINES 1081
zlmix to dissip
SUBROUTINE zlmlix to dissip
File
Type
Module subroutine
Purpose
Calculate the dissipation rate ε from the mixing length l using equa-
tion (4.191).
23.23 Miscellaneous utility routines

cfl orlan
FUNCTION cfl orlan(x1,x2,x3)
REAL, INTENT(IN) :: x1, x2, x3
REAL :: cfl orlan
File
utility routines.f90
Type
Module function
Purpose
Evaluate the Orlanski function OR (r1 , r2 , r3 ) defined by equation (5.256).
diff vals
FUNCTION diff vals(ilist)
LOGICAL :: diff vals
File
Type
Module function
Purpose
Returns .TRUE. if the elements of the vector array ilist are all different.
Arguments
ilist Input list
digit number int

FUNCTION digit number int(ival)
INTEGER, INTENT(IN) :: ival
INTEGER :: digit number int
File
Type
Module function
Purpose
Returns the number of significant (decimal) digits needed to represent
the integer number ival.
digit number longint

FUNCTION digit number longint(ival)
INTEGER (KIND=kndilong), INTENT(IN) :: ival
INTEGER :: digit number longint
File
Type
Module function
Purpose
Returns the number of significant (decimal) digits needed to represent
the long integer number ival.
index position
FUNCTION index position(ival,ilist)
INTEGER, INTENT(IN) :: ival
INTEGER :: index position
File
Type
Module function
Purpose
Returns the index of the first occurrence of ival in the vector list ilist
or zero if ival is not included.
least squares fit

SUBROUTINE least squares fit(x,y,nodat,afit,bfit,corrcoef)
INTEGER, INTENT(IN) :: nodat
REAL, INTENT(OUT) :: afit, bfit, corrcoef
REAL, INTENT(IN), DIMENSION(nodat) :: x, y
File
Type
Module subroutine
Purpose
Perform a least squares on the input data (a,b).
Arguments
x Data values on the X-axis
y Data values on the Y-axis
nodat Number of data values
afit Returned slope parameter of the interpolated straight line
bfit Returned X-value at the intersection of the straight line
with the X-axis
corrcoef Returned correlation coefficient r2
lim dims
FUNCTION lim dims(lims)
INTEGER, INTENT(IN), DIMENSION(3) :: lims
INTEGER :: lim dims
File
Type
Module function
Purpose
Returns the number of iterations within the loop whose first, end and
step values are given by respectively the first, second and third element
of lims.
loop index
FUNCTION loop index(lims,iloop)
INTEGER, INTENT(IN) :: iloop
INTEGER, INTENT(IN), DIMENSION(3) :: lims
LOGICAL :: loop index
File
Type
Module function
Purpose
Returns .TRUE. if iloop is within the loop whose first, end and step
values are given by respectively the first, second and third element of
lims.
mult index
FUNCTION mult index(ix,iy)
INTEGER, INTENT(IN) :: ix, iy
LOGICAL :: mult index
File
Type
Module function
Purpose
Returns .TRUE. if iy is non-zero and ix an integer multiple of iy.
num halo
FUNCTION num halo(iopt adv)
INTEGER, INTENT(IN) :: iopt adv
INTEGER :: num halo
File
Type
Module function
Purpose
Returns the halo size needed for advection.
Arguments
iopt adv Type of advection scheme
0: no advection
1: upwind
2: central or Lax-Wendroff
3: TVD
outer product
FUNCTION outer product(a,b)
REAL, DIMENSION(:), INTENT(IN) :: a, b
REAL, DIMENSION(SIZE(a), SIZE(b)) :: outer product
File
Type
Module function
Purpose
Returns the outer product of the vectors a, b. The elements of the
resulting matrix A are Aij = ai bj .
prime factoring
SUBROUTINE prime factoring(nx,nfacs,ifacs,maxfacs,maxprime)
INTEGER, INTENT(IN) :: maxfacs, maxprime, nx
INTEGER, INTENT(OUT) :: nfacs
INTEGER, INTENT(OUT), DIMENSION(maxfacs) :: ifacs
File
Type
Module subroutine
Purpose
Returns the prime number factors of an integer number.
Arguments
nx Integer number
nfacs Returned number of prime factors (lower or equal than
maxfacs)
ifacs Returned vector of prime numbers in descending order
(lower or equal than maxprime)
maxfacs Maximum number of prime numbers
maxprime Largest allowed prime factor
qsort index
SUBROUTINE qsort_index(arr,indx,iorder)
INTEGER, INTENT(IN) :: iorder
REAL, INTENT(IN), DIMENSION(:) :: arr
INTEGER, INTENT(OUT), DIMENSION(SIZE(arr)) :: indx
File
Type
Module subroutine
Purpose
Uses the “quick-sort” algorithm to create the index array indx such that
the values of arr(indx(j)) are sorted in ascending (descending) order if
iorder = 1 (-1)
Reference
Routine indexx from Press et al. (1992)
relax factor
FUNCTION relax factor(idist,ityp,width)
INTEGER, INTENT(IN) :: idist, ityp
REAL, INTENT(IN) :: width
REAL :: relax factor
File
Type
Module function
Purpose
Returns the weighting factor for the relaxation scheme.
Arguments
idist Distance of the grid point from the open boundary in grid
indices
ityp Type of weight function
1: linear form (4.375)
2: quadratic form (4.376)
3: hyperbolic form (4.377)
width Width of the relaxation zone in grid indices
string replace
SUBROUTINE string replace(string,cin,cout)
CHARACTER (LEN=*), INTENT(INOUT) :: string
CHARACTER (LEN=1), INTENT(IN) :: cin, cout
File
Type
Module subroutine
Purpose
Replaces each occurence of character cin by the character cout in string.
If the string contains blanks only, the string is replaced by cout.
swap data
SUBROUTINE swap data(var1,var2)
INTEGER, REAL or COMPLEX &
& [, DIMENSION(:[,:])], INTENT(INOUT) :: var1, var2
File
Type
Purpose
Exchange (“swap”) the two integer, real or complex arguments. In case
of integers, only scalars allowed. In case of real or complex data the
arguments are either scalars, vectors or 2-D arrays.
swap data var int integer scalars
swap data var real real scalars
swap data var cmplx complex scalars
swap data 1d real real vectors
swap data 1d cmplx complex vectors
swap data 2d real real 2-D arrays
swap data 2d cmplx complex 2-D array
tvd limiter
FUNCTION tvd limiter(x,mask)
REAL, INTENT(IN), DIMENSION(:,:) :: x
& DIMENSION(LBOUND(x,1):UBOUND(x,1),&
& LBOUND(x,2):UBOUND(x,2)[,&
& LBOUND(x,3):UBOUND(x,3)]) :: mask
REAL[, DIMENSION(LBOUND(x,1):UBOUND(x,1),&
& LBOUND(x,2):UBOUND(x,2)[,&
& LBOUND(x,3):UBOUND(x,3)])] :: tvd limiter
File
Type
Generic module function
Purpose
Evaluate the TVD limiting function Ω(r) on the model grid using ei-
ther the superbee (5.39) or the monotonic (5.40) limiter. No result is
returned on land areas.
Arguments
x Argument r of the limiting function
mask Mask to exclude land areas. Shape must be the same as
the result.
tvd limiter 0d Scalar result
tvd limiter 2d 2-D result
tvd limiter 3d 3-D result
two power
FUNCTION two power(n)
INTEGER :: two power
File
Type
Module function
Purpose
Returns the smallest number p for which 2p ≥ n.
upper case
SUBROUTINE upper case(string)
CHARACTER (LEN=*), INTENT(INOUT) :: string
File
Type
Module routine
Purpose
Converts a string to upper case
Appendix 24
Description of user defined

routines
A series of usrdef routines have been created where the user can define all
parameters and arrays needed for the setup of an application. The contents of
these routines are discussed in Part IV. A summary is given in this chapter.
24.1 Harmonic analysis and output

usrdef anal freqs
SUBROUTINE usrdef anal freqs
File
Usrdef Harmonic Analysis.f90
Type
Subroutine
Purpose
Define frequencies and related parameters for performing harmonic
analysis.
Reference
Section 16.3.1
usrdef anal params

SUBROUTINE usrdef anal params
1091
1092 APPENDIX 24. DESCRIPTION OF USER DEFINED ROUTINES
File
Type
Subroutine
Purpose
Define specifiers for harmonic output.
Reference
Section 16.3.2
usrdef anal0d vals

SUBROUTINE usrdef anal0d vals(out0ddat,n0vars)
File
Type
Subroutine
Purpose
Define the 0-D variables for harmonic analysis.
Reference
Section 16.3.3.1
Arguments
out0ddat 0-D data. The variables are given in the same order as
they are defined in analvars.
n0vars The number of 0-D harmonic variables
usrdef anal2d vals

SUBROUTINE usrdef anal2d vals(out2ddat,i,j,n2vars)
File
24.1. HARMONIC ANALYSIS AND OUTPUT 1093
Type
Subroutine
Purpose
Reference
Section 16.3.3.2
Arguments
out2ddat 2-D output data. The variables are given in the same order
as they are defined in the array analvars.
usrdef anal3d vals

SUBROUTINE usrdef anal3d vals(out3ddat,i,j,k,n3vars)
File
Type
Subroutine
Purpose
Reference
Section 16.3.3.3
Arguments
as they are defined in the array analvars.
k Vertical index of the data location on the model grid
24.2 Model setup

usrdef init params
SUBROUTINE usrdef init params
File
Usrdef Model.f90
Type
Subroutine
Purpose
Define parameters for monitoring.
Reference
Section 12.2
usrdef mod params

SUBROUTINE usrdef mod params
File
Usrdef Model.f90
Type
Subroutine
Purpose
The following setup parameters are defined:
- number of processes and dimensions of the parallel grid (Sec-
tion 12.3)
- model switches (Section 12.4)
- time parameters (Section 12.5.1)
- grid and other integer parameters (Sections 12.5.2–12.5.3)
- physical model parameters (Section 12.5.4)
- turbulence model parameters (Section 12.5.5)
- parameters for surface data grids (Section 12.6)
- attributes of forcing files (Section 12.7)
- parameters for user-defined output (Section 12.8)
Reference
Chapter 12
24.2. MODEL SETUP 1095
usrdef grid
SUBROUTINE usrdef grid
File
Usrdef Model.f90
Type
Subroutine
Purpose
Define model grid, bathymetry and locations of open boundaries.
Reference
Section 13.1
usrdef partition
SUBROUTINE usrdef partition
File
Usrdef Model.f90
Type
Subroutine
Purpose
Define domain decomposition for parallel applications.
Reference
Section 12.9
usrdef phsics
SUBROUTINE usrdef phsics
File
Usrdef Model.f90
Type
Subroutine
Purpose
Define physical initial conditions.
Reference
Section 13.2
usrdef 1dsur spec

SUBROUTINE usrdef 1dsur spec
File
Usrdef Model.f90
Type
Subroutine
Purpose
Define the surface forcing specifiers in case of a water column (1-D)
application.
Reference
Section 15.1.1
usrdef 2dobc spec

SUBROUTINE usrdef 2dobc spec
File
Usrdef Model.f90
Type
Subroutine
Purpose
Define open boundary conditions for the 2-D mode.
Reference
Section 14.1.1
usrdef profobc spec

SUBROUTINE usrdef profobc spec(iddesc,itypobu,itypobv,iprofobu,&
& iprofobv,iprofrlx,noprofsd,&
& indexprof,indexvar,novars,nofiles)

File
Usrdef Model.f90
Type
Subroutine
Purpose
Define open boundary conditions for baroclinic currents and 3-D scalars.
Reference
Section 14.2.1
Arguments
iddesc The file descriptor key id of the 3-D quantity which may
take the following values
io salobc salinity
itypobu Type of the open boundary condition at the U-nodes (see
Section 14.2.1.1)
itypobv Type of the open boundary condition at the V-nodes (see
Section 14.2.1.1)
iprofobu Profile number used at the U-open boundaries for each
data variable (0 is none)
iprofobv Profile number used at the V-open boundaries for each
data variable (0 is none)
iprofrlx Disables/enables the application of the open boundary re-
laxation scheme within the zones defined in usrdef rlxobc spec
(0/1).

novars Total number of variables. Value is 1 in the current im-
plementation.
nofiles The number of data files minus 1 (the file index for data
files ranges from 2 to nofiles)
usrdef 1dsur data

SUBROUTINE usrdef 1dsur data(ciodatetime,data1d,novars)
File
Usrdef Model.f90
Type
Subroutine
Purpose
Define the surface forcing data in case of a water column (1-D) appli-
cation.
Reference
Section 15.1.2
Arguments
ciodatetime Returned date and time in string format
data1d Returned forcing data. The array elements are:
1: X-component of the pressure gradient if isur1dtype=1
or 3, surface elevation if isur1dtype=2
2: Y-component of the pressure gradient if isur1dtype=1
or 3
3: surface elevation if isur1dtype=1
novars The number of data variables depending on the value of
isur1dtype
1: three data values (X- and Y-component of the pressure
gradient and elevation)

3: two data values (X- and Y-component of the pressure
gradient)
usrdef 2dobc data

SUBROUTINE usrdef 2dobc data(ifil,ciodatetime,data2d,nodat,novars)
File
Usrdef Model.f90
Type
Subroutine
Purpose
Define the open boundary data for 2-D quantities.
Reference
Section 14.1.2
Arguments
ifil File number index of the data file (>1)
data2d Returned values of the open boundary data
nodat Number of data points as given by no2dobc(ifil)
novars The number of data variables depending on the value of
iobc2dtype(ifil)
1: two data values (depth integrated current and eleva-
tion)
3: one data value (depth integrated current)
usrdef profobc data

SUBROUTINE usrdef profobc data(iddesc,ifil,ciodatetime,psiprofdat,numprofs)
File
Usrdef Model.f90
Type
Subroutine
Purpose
Define the open boundary data for 3-D quantities.
Reference
Section 14.2.2
Arguments
iddesc The file descriptor key id of the 3-D quantity which may
take the following values:
io salobc salinity
ifil File number index of the data file (>1)
psiprofdat Returned values of the open boundary profile data
numprofs The number of profiles in the data file
usrdef rlxobc spec

SUBROUTINE usrdef rlxobc spec
File
Usrdef Model.f90
Type
Subroutine
Purpose
Define specifier arrays for the use of relaxation conditions near open
boundaries.
Reference
Section 14.3
24.3. SETUP OF NESTED SUB-GRIDS 1101
24.3 Setup of nested sub-grids

usrdef nstgrd spec
SUBROUTINE usrdef nstgrd spec
File
Usrdef Nested Grids.f90
Type
Subroutine
Purpose
Define the number of nested open boundary locations and type of coor-
dinates.
Reference
Section 15.3.1
usrdef nstgrd abs

SUBROUTINE usrdef nstgrd abs(iset,nhdat,nzdat,xcoord,ycoord,zcoord,cnode)
File
Type
Subroutine
Purpose
Define the absolute geographical positions of the open boundaries for
the sub-grid with index iset.
Reference
Section 15.3.2
Arguments
iset The index number of the sub-grid
nhdat Number of sub-grid points in the horizontal, equal to the

value of either nohnstglbc(iset), nohnstglbu(iset) or nohnst-
glbv(iset) depending on the value of cnode
nzdat Number of data points in the vertical equal to novnst(iset)
zcoord Z-coordinates of the sub-grid locations, defined as the neg-
ative distance to the mean water level (only when nzdat>0)
[m]
cnode Grid node of the sub-grid data points which may take the
values ‘C’, ‘U’, ‘V’
usrdef nstgrd rel

SUBROUTINE usrdef nstgrd rel(iset,nhdat,nzdat,nonodes,hnests,zcoord,cnode)
TYPE (HRelativeCoords), INTENT(OUT), DIMENSION(nhdat,nonodes) :: hnests
File
Type
Subroutine
Purpose
Define the geographical positions of the open boundaries in relative
coordinates for the sub-grid with index iset.
Reference
Section 15.3.3
Arguments
iset The index number of the sub-grid
nhdat Number of sub-grid points in the horizontal, equal to the
value of either nohnstglbc(iset), nohnstglbu(iset) or nohnst-
glbv(iset) depending on the value of cnode
24.4. USER-FORMATTED OUTPUT 1103
nzdat Number of data points in the vertical equal to novnst(iset)

nonodes The number of nodes on the model grid for which relative
coordinates need to be provided. Its value equals 1 or 2
depending on the value of cnode.
hnests Relative coordinates of the sub-grid (‘C’, ‘U’, ‘V’) loca-
tions with respect to either the C-, U- or V-node model
grid
zcoord Z-coordinates of the sub-grid locations, taken as the nega-
[m]
cnode Grid node of the sub-grid data points which may take the
values ‘C’, ‘U’, ‘V’
24.4 User-formatted output

usrdef output
SUBROUTINE usrdef output
File
Usrdef Output.f90
Type
Subroutine
Purpose
User-formatted output
Reference
Section 16.4
24.5 Surface grids and data

usrdef surface absgrd
SUBROUTINE usrdef surface absgrd(iddesc,ifil,n1dat,n2dat,xcoord,ycoord)
REAL, INTENT(INOUT), DIMENSION(n1dat,n2dat) :: xcoord, ycoord
File
Usrdef Surface Data.f90
Type
Subroutine
Purpose
Define a surface grid in (absolute) geographical coordinates.
Reference
Section 15.2.1
Arguments
iddesc The file descriptor of the corresponding data file. The
key id in parentheses below is the associated grid key id
(idgrd).
io sstgrd surface grid for sea surface temperature (igrd sst)
ifil File index. In the current implementation its value is 1.
xcoord X-coordinates of the data grid
[m or degrees longitude]
ycoord Y-coordinates of the data grid
[m or degrees latitude]
usrdef surface relgrd

SUBROUTINE usrdef surface relgrd(iddesc,ifil,surfgridglb,nx,ny,nonodes)
TYPE (HRelativeCoords), INTENT(INOUT), DIMENSION(nx,ny,nonodes) :: surfgridgl
File
Type
Subroutine
Purpose
Define the relative coordinate arrays of a surface grid with respect to
model grid.
Reference
Section 15.2.2
24.5. SURFACE GRIDS AND DATA 1105
Arguments
iddesc The file descriptor of the corresponding data file. The
key id in parentheses below is the associated grid key id
(idgrd).
io sstgrd surface grid for sea surface temperature (igrd sst)
ifil File index. In the current implementation its value is 1.
surfgridglb Returned relative coordinates of the model C-node grid
with respect to a data grid represented by iddesc
nx Currenly equal to the global X-dimension nc of the model
grid.
ny Currenly equal to the global Y-dimension nr of the model
grid.
nonodes Number of nodes. In the current implementation its value
equals 1.
usrdef surface data

SUBROUTINE usrdef surface data(iddesc,ifil,ciodatetime,surdata,&
File
Type
Subroutine
Purpose
Define the input surface forcing data.
Reference
Section 15.2.3
Arguments
iddesc The file descriptor of the corresponding data file
io metsur surface meteo data
io sstsur sea surface temperature data

ifil File index. In the current version its value is 1.
surdata Returned surface forcing data as defined on the surface
data grid
novars Number of data variables. In case of meteorological data
its value ranges from 2 to 7, in case of SST data its value
is 1.
24.6 Time averaged output

usrdef avr params
SUBROUTINE usrdef avr params
File
Usrdef Time Averages.f90
Type
Subroutine
Purpose
Define specifiers for time averaged output.
Reference
Section 16.2.1
usrdef avr0d vals

SUBROUTINE usrdef avr0d vals(out0ddat,n0vars)
File
Type
Subroutine
Purpose
Define the 0-D variables for time averaged output.
Reference
Section 16.2.2.1
Arguments
they are defined in avrvars.
n0vars The number of 0-D output variables
usrdef avr2d vals

SUBROUTINE usrdef avr2d vals(out2ddat,i,j,n2vars)
File
Type
Subroutine
Purpose
Reference
Section 16.2.2.2
Arguments
as they are defined in the array avrvars.
usrdef avr3d vals

SUBROUTINE usrdef avr3d vals(out3ddat,i,j,k,n3vars)
File
Type
Subroutine
Purpose
Reference
Section 16.2.2.3
Arguments
as they are defined in the array avrvars.
24.7 Time series output

usrdef tsr params
SUBROUTINE usrdef tsr params
File
Usrdef Time Series.f90
Type
Subroutine
Purpose
Define specifiers for time series output.
Reference
Section 16.1.1
usrdef tsr0d vals

SUBROUTINE usrdef tsr0d vals(out0ddat,n0vars)
File
Type
Subroutine
Purpose
Define the 0-D variables for time series output.
Reference
Section 16.1.2.1
Arguments
they are defined in tsrvars.
usrdef tsr2d vals

SUBROUTINE usrdef tsr2d vals(out2ddat,i,j,n2vars)
File
Type
Subroutine
Purpose
Reference
Section 16.1.2.2
Arguments
as they are defined in the array tsrvars.

usrdef tsr3d vals

SUBROUTINE usrdef tsr3d vals(out3ddat,i,j,k,n3vars)
File
Type
Subroutine
Purpose
Reference
Section 16.1.2.3
Arguments
as they are defined in the array tsrvars.
Appendix 25
Description of program
variables
25.1 Currents
MODULE currents
REAL, DIMENSION(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo) :: udvel, uvdvel old,&
& vdvel, vdvel old
REAL, DIMENSION(1-nhalo:ncloc+nhalo,0:nrloc+1) :: umvel
REAL, DIMENSION(0:ncloc+1,1-nhalo:nrloc+nhalo) :: vmvel
REAL, DIMENSION(0:ncloc+1,nrloc) :: umpred
REAL, DIMENSION(ncloc,0:nrloc+1) :: vmpred
REAL, DIMENSION(ncloc+1,nrloc) :: udfvel
REAL, DIMENSION(ncloc,nrloc+1) :: vdfvel
REAL, DIMENSION(ncloc,nrloc) :: p2dbcgradatu, p2dbcgradatv, udevint, vdevint
REAL, DIMENSION(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz) :: uvel, uvel old,&
& vvel, vvel old
REAL, DIMENSION(2-nhalo:ncloc+nhalo,nrloc,nz) :: ufvel
REAL, DIMENSION(ncloc,2-nhalo:nrloc+nhalo,nz) :: vfvel
REAL, DIMENSION(0:ncloc,0:nrloc,nz+1) :: wvel
REAL, DIMENSION(ncloc,nrloc,nz) :: p3dbcgradatu, p3dbcgradatv, wphys
File
currents.f90
Type
Module
Purpose
Velocity arrays
1111
1112 APPENDIX 25. DESCRIPTION OF PROGRAM VARIABLES
Description
p2dbcgradatu X-component of the depth-integrated baroclinic pressure
gradient F1b [m2 /s2 ]
p2dbcgradatv Y-component of the depth-integrated baroclinic pressure
gradient F2b [m2 /s2 ]
p3dbcgradatu X-component of the baroclinic pressure gradient F1b [m/s2 ]
p3dbcgradatv Y-component of the baroclinic pressure gradient F2b [m/s2 ]
udevint Depth-integrated baroclinic terms δDh1 − δAh1 in the U -
equation [m2 /s2 ]
udfvel X-component of the filtered depth-integrated current Uf
[m2 /s]
udvel X-component of the depth-integrated current U [m2 /s]
udvel old X-component of the depth-integrated current U at the
previous 2-D time step [m2 /s]
ufvel X-component of the filtered 3-D current uf [m/s]
p
umpred X-component of the depth-mean current u at the pre-
dictor step [m/s]
umvel X-component of the depth-mean current u [m/s]
uvel X-component of the 3-D current u [m/s]
uvel old X-component of the 3-D current u at the previous cor-
rector (baroclinic) time step [m/s]
vdevint Depth-integrated baroclinic terms δDh2 − δAh2 in the V -
equation [m2 /s2 ]
vdfvel Y-component of the filtered depth-integrated current Vf
[m2 /s]
vdvel Y-component of the depth-integrated current V [m2 /s]
vdvel old Y-component of the depth-integrated current V at the
previous 2-D time step [m2 /s]
vfvel Y-component of the filtered 3-D current vf [m/s]
vmpred Y-component of the depth-mean current v p at the pre-
dictor step [m/s]
vmvel Y-component of the depth-mean current v [m/s]
vvel Y-component of the 3-D current v [m/s]
vvel old Y-component of the 3-D current v at the previous cor-
rector (baroclinic) time step [m/s]
25.2. DERIVED TYPE DEFINITIONS 1113
wphys Physical vertical velocity w [m/s]

wvel Transformed vertical velocity ω [m/s]
25.2 Derived type definitions

MODULE datatypes
ExchComms
TYPE :: ExchComms
LOGICAL :: sfirst
INTEGER :: iddest, idsrce, tag
INTEGER, DIMENSION(2) :: i1rcv, i2rcv, j1rcv, j2rcv
INTEGER, DIMENSION(2) :: i1snd, i2snd, j1snd, j2snd
END TYPE ExchComms
File
datatypes.f90
Type
Derived type definition
Purpose
Parameters for exchange (send and receive) communications in parallel
mode
Description
iddest Destination process in case of a send operation
idsrce Source process in case of a receive operation
i1rcv Start (local) grid index in the X-direction for the receive opera-
tion
i1snd Start (local) grid index in the X-direction for the send operation
i2rcv End (local) grid index in the X-direction for the receive operation
i2snd End (local) grid index in the X-direction for the send operation
j1rcv Start (local) grid index in the Y-direction for the receive opera-
tion
j1snd Start (local) grid index in the Y-direction for the send operation
j2rcv End (local) grid index in the Y-direction for the receive operation
j2snd End (local) grid index in the Y-direction for the send operation
sfirst Switch which determines for a local domain whether a send oper-
ation is performed before a receive operation (see Section 9.4.3.2)
tag Communication tag
FileParams
(MODULE datatypes)
TYPE :: FileParams
CHARACTER (LEN=10) :: coherens version
CHARACTER (LEN=lentime-4) :: creation date
INTEGER :: endfile, header_type, iostat, iunit, lenrec, maxrecs, &
& nocoords, nodim, novars, timeid, timerec, tskips, &
& varid, zetaid
END TYPE FileParams
File
datatypes.f90
Type
Purpose
Global file attributes
Description
coherens version Current COHERENS version
creation date Date and time of creation
defined .TRUE. if the file is activated (status is different from
‘0’)
endfile Switch to select which action needs to be taken in case
an end of file condition occurs during input
0: The program aborts with an error message.
1: The program continues. No further read attempt
is made.
2: The program waits until the data are available. If

the data are not available after a given period of
time, the program aborts.
filedesc A character string with a description of the file con-
tents
filename File name
form File format
‘A’ ASCII
‘U’ sequential unformatted binary
‘N’ netCDF
‘D’ direct access unformatted binary (currently not
implemented)
header type Type of file header
0: No header (not allowed for netCDF files)
1: Indicates that the file contains forcing data.
2: Indicates that the file contains user-defined output
data.
3: Indicates that the file contains user-defined output
with output grid data only.
info Header information is written to a separate informa-
tion file if .TRUE.
iostat File I/O status
-1: unable to open file
0 : The file is not opened
1 : The file pointer is located before the end of the file
2 : The file pointer is located at the end of the file.
An end of file condition did not yet occurred.
3 : The file pointer is located at the end of the file.
An end of file condition did occur.
iunit File unit number
lenrec Record length (direct access files only)
maxrecs Total amount of time records in case of a time series
file
nocoords Number of coordinate variables
nodim Rank of the data variables (user output only)

novars Number of data variables
opened .TRUE. (.FALSE.) if the file is connected (not con-
nected)
pathname Preappended file path
status File status
‘0’ undefined, i.e. the file is not activated
‘N’ the file is available in a user-defined (non-COHERENS)
format for input
‘R’ the file is available in COHERENS standard format
for input
‘W’ the file is created for output in COHERENS stan-
dard format
‘P’ as ‘W’ but the data are appended to an already
existing standard COHERENS file. The option is
currently not implemented.
‘T’ temporary file (for internal use only). The option
is currently not used.
timeid NetCDF variable id of the time coordinate variable
timerec Current time record number
time regular .TRUE. if the file contains time series data at regular
time intervals.
tlims Start/End/Step time indices used in updating the data
from a forcing file
tskips Currently not implemented
varid ID of a variable in the file (only used internally)
zetaid NetCDF variable file ID of the surface elevation coor-
dinate variable
GridParams
(MODULE datatypes)
TYPE :: GridParams
END TYPE GridParams
File
datatypes.f90
Type
Purpose
Attributes of surface grids
Description
delxdat Spacing in the X-direction in case of a regular grid
delydat Spacing in the Y-direction in case of a regular grid
nhtype Type of data grid
0: single point data grid or data grid not defined
1: rectangular grid with uniform grid spacings in Cartesian or
spherical coordinates (data grid is constructed from x0dat,
y0dat, delxdat, delydat)
2: rectangular grid with non-uniform spacings
3: non-rectangular (curvilinear or non-structured) grid
4: data grid coincides with the model grid
n1dat Number of grid points in the X-direction or, in case of a non-
rectangular grid, the total number of grid points
n2dat Number of grid points in the Y-direction or equal to one in case
of a non-rectangular grid
x0dat X-coordinate of the lower left (Southwest) corner in case of a
regular grid [meters or longitude]
y0dat Y-coordinate of the lower left (Southwest) corner in case of a
regular grid [meters or latitude]
HRelativeCoords
(MODULE datatypes)
File
datatypes.f90
Type
Purpose
Horizontal relative coordinates
Reference
Section 8.4.1
Description
icoord Integer part of the ξ1 curvilinear coordinate with respect to the
reference coordinate system
jcoord Integer part of the ξ2 curvilinear coordinate with respect to the
reference coordinate system
xcoord Fractional part of the ξ1 curvilinear coordinate with respect to
the reference coordinate system
ycoord Fractional part of the ξ2 curvilinear coordinate with respect to
the reference coordinate system
OutGridParams
(MODULE datatypes)
TYPE :: OutGridParams
LOGICAL :: gridded, grid file, land mask, time grid
CHARACTER (LEN=1) :: status
CHARACTER (LEN=lentime) :: enddate, refdate, startdate
INTEGER :: ncout, nodim, nostats, nowetout, nrout, nstepout, nzout, &
& time format
INTEGER, DIMENSION(3) :: tlims, xlims, ylims, zlims
REAL :: deltout
END TYPE OutGridParams
File
datatypes.f90
Type
Purpose
Parameters for user-defined output and attributes of output data grids
Description
deltout Output time step. Unit is seconds in case of an absolute
time. Otherwise, the unit is determined by the value of
time format.
enddate Date and time of the last output
gridded .TRUE. (.FALSE.) for gridded (non-gridded) output
grid file The coordinates of the output grid are written to a sepa-
rate external file if .TRUE.
land mask The data are written with a land mask (i.e. without land
points) if .TRUE.
ncout X-dimension of the output grid in case of gridded data
nodim Spatial dimension of the output grid (0,2,3)
nostats Number of output stations in case of non-gridded data
nowetout Number of wet output data in case a land mask is applied
nrout Y-dimension of the output grid in case of gridded data
nstepout Number of output time steps
nzout Vertical dimension of the output grid
refdate Reference date/time used when the time coordinate is writ-
ten in a numerical format in which case it is defined as the
time elapsed since this reference date.
startdate Date and time of the first output
status Status of the corresponding output files
‘W’ data are written to a newly created file
‘P’ data are appended to an existing file. This option is
currently not yet available.
time format Format of the time coordinate. The first and last case are
absolute times, the other ones relative times with respect
to the refdate
0: date/time in string format
1: seconds
2: minutes
3: hours
4: days
5: months (one month is taken as 30.4375 days)
6: years (one year is taken as 365.25 days)
7: date in years
time grid Create a time-dependent grid if .TRUE. and nodim = 3.
tlims Start/end/step output time index. The step value deter-
mines the period in case of time-averaged or harmonic out-
put.
xlims Start/end/step output space index in the X-direction in
case of gridded data
ylims Start/end/step output space index in the Y-direction in
case of gridded data
zlims Start/end/step output space index in the vertical direction
StationLocs
(MODULE datatypes)
TYPE :: StationLocs
INTEGER :: ipos, jpos
CHARACTER (LEN=lenname) :: name
END TYPE StationLocs
File
datatypes.f90
Type
Purpose
Attributes of the output station locations in case of non-gridded output.
The stations are assumed to be located at C-nodes.
Description
ipos C-node X-index of the stations
jpos C-node Y-index of the stations
name Name of the station
VariableAtts
(MODULE datatypes)
INTEGER :: data type, ivarid, klev, nrank, oopt
INTEGER, DIMENSION(4) :: shape
File
datatypes.f90
Type
Purpose
Variable attributes
Description
f90 name FORTRAN 90 name
long name Long descriptive name
vector name Associated vector name in case the variable denotes a vec-
tor component
units Variable unit
node Nodal location of the variable on the model grid. In case
of user output, the nodal location on the output grid (‘C’
or ‘W’)
data type Data type of the variable (see Table 6.1)
ivarid Variable key id (a zero means undefined)
klev Vertical level used when oopt equals oopt klev
nrank Variable rank (0 for a scalar)
oopt Selects the operator to be applied in case the variable is
selected for user output
oopt null No operator applied
oopt min Minimum value
oopt max Maximum value
oopt mean Spatially averaged value

oopt klev Value at a specified vertical level
oopt max Value at a specified depth below the surface
shape Array shape (not defined in case of a scalar)
dep Depth value used when oopt equals oopt dep
VRelativeCoords
(MODULE datatypes)
TYPE :: VRelativeCoords
INTEGER :: kcoord
REAL :: zcoord
END TYPE VRelativeCoords
File
datatypes.f90
Type
Purpose
Vertical relative coordinates
Description
kcoord Vertical level of the grid point along the reference grid just
below the data point
zcoord Normalised vertical distance from the vertical level kcoord to
the location of the data point (between 0 and 1)
25.3 Density
MODULE density
REAL, DIMENSION(0:ncloc+1,0:nrloc+1,nz) :: beta sal, beta temp, dens
REAL, DIMENSION(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz) :: sal, temp
File
density.f90
Type
Module
25.4. WATER DEPTHS 1123
Purpose
Density arrays
Description
beta sal Salinity expansion coefficient βS [PSU−1 ]
beta temp Temperature expansion coefficient βT [0 C−1 ]
dens Mass density ρ [kg/m3 ]
sal Salinity S [PSU]
temp Temperature T [0 C]
25.4 Water depths

MODULE depths
REAL, DIMENSION(0:ncloc+1,0:nrloc+1) :: depmeanatc, deptotatc
REAL, DIMENSION(ncloc,nrloc) :: deptotatc old, deptotatc err
REAL, DIMENSION(0:ncloc+1,nrloc) :: depmeanatu, deptotatu old
REAL, DIMENSION(1-nhalo:ncloc+nhalo,0:nrloc+1) :: deptotatu
REAL, DIMENSION(ncloc,0:nrloc+1) :: depmeanatv, deptotatv old
REAL, DIMENSION(0:ncloc+1,1-nhalo:nrloc+nhalo) :: deptotatv
REAL, DIMENSION(ncloc+1,nrloc+1) :: depmeanatuv, deptotatuv
REAL, DIMENSION(0:nc+1,0:nr+1) :: depmeanglb
REAL, DIMENSION(0:ncloc+1,0:nrloc+1) :: zeta
File
depths.f90
Type
Module
Purpose
Water depths and sea surface elevations
Description
depmeanatc Mean water depth at the C-nodes [m]
depmeanatu Mean water depths at the U-nodes [m]
depmeanatuv Mean water depth at the UV-nodes [m]
depmeanatv Mean water depth at the V-nodes [m]
depmeanglb Mean water depth (global) at C- (or -UV-nodes) [m]
deptotatc Total water depth at the C-nodes [m]
deptotatc err Total water depth error δe H at the C-nodes [m]

deptotatc old Total water depth at the C-nodes and old baroclinic time
step [m]
deptotatu Total water depth at the U-nodes [m]
deptotatuv Total water depth at the UV-nodes [m]
deptotatu old Total water depth at the U-nodes and old baroclinic time
step [m]
deptotatv Total water depth at the V-nodes [m]
deptotatv old Total water depth at the V-nodes and old baroclinic time
step [m]
zeta Surface elevation [m]
25.5 Diffusion
MODULE diffusion
REAL, DIMENSION(0:ncloc,0:nrloc) :: hdifcoef2datc
REAL, DIMENSION(ncloc+1,nrloc+1) :: hdifcoef2datuv
REAL, DIMENSION(0:ncloc,0:nrloc,nz) :: hdifcoef3datc
REAL, DIMENSION(ncloc+1,nrloc,nz) :: hdifcoef3datu
REAL, DIMENSION(ncloc,nrloc+1,nz) :: hdifcoef3datv
REAL, DIMENSION(ncloc+1,nrloc+1,nz) :: hdifcoef3datuv
REAL, DIMENSION(0:ncloc,0:nrloc,nz+1) :: vdifcoefmom
REAL, DIMENSION(ncloc,nrloc,nz+1) :: vdifcoefscal, vdifcoeftke
File
diffusion.f90
Type
Module
Purpose
Horizontal and vertical diffusion coefficients
Description
hdifcoef2datc Vertically integrated horizontal diffusion coefficient νH
at the C-nodes [m3 /s]
hdifcoef2datuv Vertically integrated horizontal diffusion coefficient νH
at the UV-nodes [m3 /s]
25.6. FLUXES 1125
hdifcoef3datc Horizontal 3-D diffusion coefficient νH at the C-nodes

[m2 /s]
hdifcoef3datu Horizontal 3-D diffusion coefficient λH at the U-nodes
[m2 /s]
hdifcoef3datuv Horizontal 3-D diffusion coefficient νH at the UV-nodes
[m2 /s]
hdifcoef3datv Horizontal 3-D diffusion coefficient λH at the V-nodes
[m2 /s]
vdifcoefmom Vertical diffusion coefficient νT for momentum at the
W-nodes [m2 /s]
vdifcoefscal Vertical diffusion coefficient λT for scalars at the W-
nodes [m2 /s]
vdifcoeftke Vertical diffusion coefficient νk for turbulent kinetic en-
ergy at the W-nodes [m2 /s]
25.6 Fluxes
MODULE fluxes
REAL, DIMENSION(ncloc,nrloc) :: bfricatu, bfricatv, bstresatc, ces, &
& chs, qlatent, qlwave, qnonsol, qsensible, &
& ssalflux, sstresatc, ubstresatu, &
& usstresatu, vbstresatv, vsstresatv, zeros2d
REAL, DIMENSION(0:ncloc,0:nrloc) :: bdragcoefatc, cds, zroughatc
REAL, DIMENSION(0:ncloc,nrloc) :: usstresatc
REAL, DIMENSION(ncloc,0:nrloc) :: vsstresatc
REAL, DIMENSION(0:nwind,-ntemp:ntemp,nrelhum) :: cdstab, cestab, chstab
File
fluxes.f90
Type
Module
Purpose
Bottom and surface flux arrays
Description
bdragcoefatc Bottom drag coefficient Cdb at the C-nodes
bfricatu Bottom friction velocity u⋆b at the U-nodes [m/s]
bfricatv Bottom friction velocity u⋆b at the V-nodes [m/s]

bstresatc Magnitude of the bottom stress τb at the C-nodes [m2 /s2 ]
cds Surface drag coefficient Cds
cdstab Surface drag coefficient given in tabular form as function
of wind speed, air minus sea temperature difference and
relative humidity. The table is used for interpolation in
case a Monin-Obokhov formulation is selected.
ces Exchange coefficient for the latent heat flux Ce (Dalton
number)
cestab Dalton number given in tabular as function of wind speed,
air minus sea temperature difference and relative humid-
ity. The table is used for interpolation in case a Monin-
Obokhov formulation is selected.
chs Exchange coefficient for the sensible heat flux Ch (Stanton
number)
chstab Stanton number given in tabular form as function of wind
speed, air minus sea temperature difference and relative
humidity. The table is used for interpolation in case a
Monin-Obokhov formulation is selected.
qlatent Latent surface heat flux [W/m2 ]
qlwave Long-wave surface heat flux [W/m2 ]
qnonsol Non-solar surface heat flux [W/m2 ]
qsensible Sensible surface heat flux [W/m2 ]
ssalflux Surface salinity flux [PSU m/s]
sstresatc Magnitude of the surface stress τs at the C-nodes [m2 /s2 ]
ubstresatu X-component of the bottom stress τb1 at the U-nodes
[m2 /s2 ]
usstresatc X-component of the surface stress τs1 at the C-nodes
[m2 /s2 ]
usstresatu X-component of the surface stress τs1 at the U-nodes
[m2 /s2 ]
vbstresatv Y-component of the bottom stress τb2 at the V-nodes
[m2 /s2 ]
vsstresatc Y-component of the surface stress τs2 at the C-nodes
[m2 /s2 ]
vsstresatv Y-component of the surface stress τs2 at the V-nodes

[m2 /s2 ]
zeros2d Work space array with zero values
zroughatc Bottom roughness length z0 at the C-nodes [m]
25.7 Model grid arrays

MODULE grid
LOGICAL, DIMENSION(nobu) :: westobu
LOGICAL, DIMENSION(nobv) :: soutobv
LOGICAL, DIMENSION(nobx) :: westobx
LOGICAL, DIMENSION(noby) :: soutoby
LOGICAL, DIMENSION(ncloc,nrloc) :: maskatc int
INTEGER, DIMENSION(nobu) :: indexobu, iobu, jobu

INTEGER, DIMENSION(nobv) :: indexobv, iobv, jobv
INTEGER, DIMENSION(nobx) :: indexobx, iobx, jobx
INTEGER, DIMENSION(noby) :: indexoby, ioby, joby
INTEGER, DIMENSION(nobuloc2) :: iobuloc, jobuloc
INTEGER, DIMENSION(nobvloc2) :: iobvloc, jobvloc
INTEGER, DIMENSION(nobxloc1) :: iobxloc, jobxloc
INTEGER, DIMENSION(nobyloc1) :: iobyloc, jobyloc
INTEGER, DIMENSION(ncloc,nrloc) :: klevbotatu, klevbotatv, &
& klevsuratu, klevsuratv
INTEGER, DIMENSION(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo) :: &
& nodeatc, node2du, node2duv, node2dv
INTEGER, DIMENSION(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz) :: &
& nodeatu, nodeatuv, nodeatv
INTEGER, DIMENSION(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz+1) :: &
& nodeatuw, nodeatvw
REAL, DIMENSION(ncloc,nrloc) :: alphatc fld, alphatu fld, alphatv fld, &
& gaccatu, gaccatv, grcos, grsin, &
& rlxobcatu, rlxobcatv
REAL, DIMENSION(ncloc+1,0:nrloc) :: coriolatu
REAL, DIMENSION(0:ncloc,nrloc+1) :: coriolatv
REAL, DIMENSION(0:ncloc+1,0:nrloc+1) :: gaccatc, gxcoord, gycoord
REAL, DIMENSION(0:ncloc,0:nrloc) :: gxlon, gylat
REAL, DIMENSION(0:nc+1,0:nr+1) :: gxcoordglb, gycoordglb
REAL, DIMENSION(0:nc+1,0:nr+1,nz+1) :: gscoordglb
REAL, DIMENSION(0:ncloc+1,0:nrloc+1,nz+1) :: gscoord, gscoordatuw, &
& gscoordatvw, gscoordatw

REAL, DIMENSION(0:ncloc+1,0:nrloc+1,2:nz) :: delzatw
REAL, DIMENSION(0:ncloc+1,0:nrloc+1,nz) :: delzatc, gscoordatc, gscoordatu, &
& gscoordatv
REAL, DIMENSION(nz+1) :: gsigcoord
REAL, DIMENSION(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo) :: &
& delxatc, delxatu, delxatuv, delxatv, &
& delyatc, delyatu, delyatuv, delyatv
REAL, DIMENSION(0:ncloc+1,nrloc,nz) :: delzatu
REAL, DIMENSION(ncloc,0:nrloc+1,nz) :: delzatv
REAL, DIMENSION(ncloc+1,nrloc+1,nz) :: delzatuv
REAL, DIMENSION(ncloc+1,nrloc,2:nz) :: delzatuw
REAL, DIMENSION(ncloc,nrloc+1,2:nz) :: delzatvw
File
grid.f90
Type
Module
Purpose
Arrays for the model grid
Description
alphatc fld α-factor used in the drying/wetting algorithm at the C-
nodes
alphatu fld α-factor used in the drying/wetting algorithm at the U-
nodes
alphatv fld α-factor used in the drying/wetting algorithm at the V-
nodes
coriolatu Coriolis frequency at the U-nodes [rad/s]
coriolatv Coriolis frequency at the V-nodes [rad/s]
delxatc Grid spacing in the X-direction at the C-nodes [m]
delxatu Grid spacing in the X-direction at the U-nodes [m]
delxatuv Grid spacing in the X-direction at the UV-nodes [m]
delxatv Grid spacing in the X-direction at the V-nodes [m]
delyatc Grid spacing in the Y-direction at the C-nodes [m]
delyatu Grid spacing in the Y-direction at the U-nodes [m]
delyatuv Grid spacing in the Y-direction at the UV-nodes [m]
delzatc Vertical grid spacing at the C-nodes [m]

delzatu Vertical grid spacing at the U-nodes [m]
delzatuv Vertical grid spacing at the UV-nodes [m]
delzatuw Vertical grid spacing at the UW-nodes [m]
delzatv Vertical grid spacing at the V-nodes [m]
delzatvw Vertical grid spacing at the VW-nodes [m]
delzatw Vertical grid spacing at the W-nodes [m]
delyatv Grid spacing in the Y-direction at the V-nodes [m]
2
gaccatc Acceleration of gravity at the C-nodes [m /s]
gaccatu Acceleration of gravity at the U-nodes [m2 /s]
gaccatv Acceleration of gravity at the V-nodes [m2 /s]
grcos Cosine of the angle between the coordinate line in the ξ1 -
direction at the C-nodes and the X-axis in the reference
coordinate system (West-East latitude circle in the sphe-
rical case)
grsin Sine of the angle between the coordinate line in the ξ1 -
direction at the C-nodes and the X-axis in the reference
coordinate system (West-East latitude circle in the sphe-
rical case)
gscoord Sigma coordinates of the UVW-nodes
gscoordatc Sigma coordinates of the C-nodes
gscoordatu Sigma coordinates of the U-nodes
gscoordatuw Sigma coordinates of the UW-nodes
gscoordatv Sigma coordinates of the V-nodes
gscoordatvw Sigma coordinates of the VW-nodes
gscoordatw Sigma coordinates of the W-nodes
gscoordglb Sigma coordinates of the W- or UVW-nodes (global array)
gsigcoord Sigma coordinates in case the vertical grid is horizontally
uniform (iopt grid vtype=1)
gxcoord X-coordinates of the UV-nodes (local array)
gxcoordglb X-coordinates of the UV-nodes (global array)
gxlon Longitude coordinate at the C-nodes [rad]
gycoord Y-coordinates of the UV-nodes (local array)

gycoordglb Y-coordinates of the UV-nodes (global array)
gylat Latitude coordinate at the C-nodes [rad]
indexobu Maps the local open boundary indices at the U-nodes to
their corresponding global ones.
indexobv Maps the local open boundary indices at the V-nodes to
indexobx Maps the local open boundary indices at the X-nodes to
indexoby Maps the local open boundary indices at the Y-nodes to
iobu Global X-index of the West/East U-node open boundaries
iobuloc Local X-index of the West/East U-node open boundaries
iobv Global X-index of the South/North V-node open bounda-
ries
iobvloc Local X-index of the South/North V-node open bounda-
ries
iobx Global X-index of the West/East X-node open boundaries
iobxloc Local X-index of the West/East X-node open boundaries
ioby Global X-index of the South/North Y-node open bounda-
ries
iobyloc Local X-index of the South/north Y-node open bounda-
ries
jobu Global Y-index of the West/East U-node open boundaries
jobuloc Local Y-index of the West/East U-node open boundaries
jobv Global Y-index of the South/North V-node open bounda-
ries
jobvloc Local Y-index of the South/North V-node open bounda-
ries
jobx Global Y-index of the West/East X-node open boundaries
jobxloc Local Y-index of the West/East X-node open boundaries
joby Global Y-index of the South/north Y-node open bounda-
ries
jobyloc Local Y-index of the South/north Y-node open bounda-

ries
klevbotatu Vertical level of the lowest wet vertical level at the U-nodes
where the bottom boundary condition is applied
klevbotatv Vertical level of the lowest wet vertical level at the V-nodes
where the bottom boundary condition is applied
klevsuratu Vertical level of the highest wet vertical level at the U-
nodes where the surface boundary condition is applied
klevsuratv Vertical level of the highest wet vertical level at the V-
nodes where the surface boundary condition is applied
maskatc int .TRUE./.FALSE. at wet/dry C-node grid points
nodeatc Pointers at C-nodes
0: dry cell
1: wet cell
nodeatu Pointers at U-node cell faces
1: coastal or solid structure boundary
2: interior wet U-node
nodeatuv Pointer at corner (UV) nodes
0: at least two surrrounding U-nodes or at least two sur-
rrounding V-nodes are dry
1: interior wet node, i.e. at most one surrounding U-node
and at most one surrounding V-node is dry and none
of the four surrounding velocity nodes are open boun-
daries
2: X-node open boundary, in which case at least one of
the surrounding U-nodes is an open boundary while
the other one is either a closed node or open boundary,
but the node is not a Y-node open boundary
3: Y-node open boundary, in which case at least one of
the surrounding V-nodes is an open boundary while
but the node is not an X-node open boundary

nodeatuw Pointer at UW-node cell faces
0: dry (land) cell face or bottom cell (1) or surface cell
(nz+1)
2: interior wet UW-node
nodeatv Pointers at V-node cell faces
2: interior wet V-node
nodeatvw Pointer at VW-node cell faces
0: dry (land) cell face or bottom cell (1) or surface cell
(nz+1)
2: interior wet VW-node
node2du Pointers at U-nodes for 2-D calculations
1: coastal boundary
2: at least one U-node interface in the vertical is wet
node2dv Pointers at V-nodes for 2-D calculations
1: coastal boundary
2: at least one V-node interface in the vertical is wet
25.8. MODEL GRID PARAMETERS 1133

node2duv Pointer at corner (UV) nodes for 2-D calculations
0: at least two surrrounding U-nodes or at least two sur-
rrounding V-nodes are dry
1: at least one corner node in the vertical is an interior wet
node, i.e. at most one surrounding U-node and at most
one surrounding V-node (at the same vertical position)
is dry and none of the four surrounding velocity nodes
are open boundaries
2: X-node open boundary, in which case at least one of
the surrounding U-nodes is an open boundary while
but the node is not a Y-node open boundary
3: Y-node open boundary, in which case at least one of
the surrounding V-nodes is an open boundary while
but the node is not an X-node open boundary
rlxobcatu Relaxation factor for horizontal momentum advection at
U-nodes
rlxobcatv Relaxation factor for horizontal momentum advection at
V-nodes
soutobv .TRUE./.FALSE. at South/North V-open boundaries (global
array)
soutoby .TRUE./.FALSE. at South/North Y-open boundaries (global
array)
westobu .TRUE./.FALSE. at West/East V-open boundaries (global
array)
westobx .TRUE./.FALSE. at West/East X-open boundaries (global
array)
25.8 Model grid parameters

MODULE gridpars
!---grid dimensions
INTEGER :: nc = 0, nr = 0, nz = 0
INTEGER :: ncloc, nc1loc, nc2loc, nrloc, nr1loc, nr2loc
!---number of open boundary points

INTEGER :: nobu, nobv, nobx, noby
INTEGER :: nosbu = 0, nosbv = 0, nrvbu = 0, nrvbv = 0
INTEGER :: nobuloc, nobuloc1, nobuloc2
INTEGER :: nobvloc, nobvloc1, nobvloc2
INTEGER :: nobxloc, nobxloc1, nobyloc, nobyloc1
INTEGER :: nosbuloc, nosbvloc, nrvbuloc, nrvbvloc
!---shortcuts for regular grid spacings
LOGICAL :: dXregX, dXregY, dYregX, dYregY, dXYreg, dZregZ
!---halo dimensions
INTEGER, PARAMETER :: nhalo = 2
INTEGER :: nhdens, nhfvel, nhscal, nhturb, nh2vel, nh3vel
!---number of open boundary points
INTEGER :: noseaatc, noseaatcloc, nowetatc, nowetatcloc
!---mean grid spacing
REAL :: delgrid, distrlx obc
File
gridpars.f90
Type
Module
Purpose
Model grid parameters
Description
delgrid Domain-averaged grid spacing for both X- and Y-direction
[m]
distrlx obc Maximum distance dmax (from the open boundaries) used
in the relaxation factor (5.279) for momentum advection
dXregX .TRUE. if the grid spacing in the X-direction is uniform
in the X-direction
dXregY .TRUE. if the grid spacing in the X-direction is uniform
in the Y-direction
dXYreg .TRUE. if all grid spacings are uniform in both X- and
Y-directions
dYregX .TRUE. if the grid spacing in the Y-direction is uniform
in the X-direction
25.8. MODEL GRID PARAMETERS 1135
dYregY .TRUE. if the grid spacing in the Y-direction is uniform

in the Y-direction
dZregZ .TRUE. for a uniform vertical vertical grid (iopt grid vtype=1)
nc Number of grid cells in the X-direction on the global grid
ncloc Number of grid cells in the X-direction on the local grid
nc1loc Global X-index of cell (1,1) on the local grid
nc2loc Global X-index of cell (ncloc,1) on the local grid
nhalo Maximum size of a halo in all directions. The current
value of 2 cannot be changed.
nhdens Minimum required size of the halo needed for density ar-
rays (1/2)
nhfvel Minimum required size of the halo for horizontal advective
currents (1/2)
nhscal Minimum required size of the halo for scalar (non-density)
arrays (1/2)
nhturb Minimum required size of the halo for the turbulence
transport arrays (0/1/2)
nh2vel Minimum required size of the halo for the 2-D depth-
integrated currents (1/2)
nh3vel Minimum required size of the halo for the 3-D currents
(1/2)
nobu Global number of open boundary points at the U-nodes
nobuloc Local number of open boundary points at the U-nodes
nobuloc1 Local number number of open boundary points at the U-
nodes including those in the eastern halo
nobuloc2 Local number of open boundary points at the U-nodes
including those in all halos
nobv Global number of open boundary points at the V-nodes
nobvloc Local number of open boundary points at the V-nodes
nobvloc1 Local number of open boundary points at the V-nodes
including those in the northern halo
nobvloc2 Local number of open boundary points at the V-nodes
including those in all halos
nobx Global number of open boundary points at the X-nodes
nobxloc Local number of open boundary points at the X-nodes
nobxloc1 Local number of open boundary points at the X-nodes

including those in the eastern halo
noby Global number of open boundary points at the Y-nodes
nobyloc Local number of open boundary points at the Y-nodes
nobyloc1 Local number of open boundary points at the Y-nodes
including those in the northern halo
nosbu Global number of open sea open boundary points at the
U-nodes
nosbuloc Local number of open sea open boundary points at the
U-nodes
nosbv Global number of open sea open boundary points at the
V-nodes
nosbvloc Local number of open sea open boundary points at the
V-nodes
noseaatc Number of sea (wet or dry) C-nodes on the global domain
noseaatcloc Number of sea (wet or dry) C-nodes on the local domain
nowetatc Number of active wet C-nodes on the global domain
nowetatcloc Number of active wet C-nodes on the local domain
nr Number of grid cells in the Y-direction on the global grid
nrloc Number of grid cells in the Y-direction on the local grid
nrvbu Global number of river open boundary points at the U-
nodes
nrvbuloc Local number of river open boundary points at the U-
nodes
nrvbv Global number of river open boundary points at the V-
nodes
nrvbvloc Local number of river open boundary points at the V-
nodes
nr1loc Global Y-index of cell (1,1) on the local grid
nr2loc Global Y-index of cell (1,nrloc) on the local grid
nz Number of grid cells in the vertical direction
25.9 General and I/O parameters

MODULE iopars
25.9. GENERAL AND I/O PARAMETERS 1137
General parameters
LOGICAL :: cold start = .FALSE., next simul = .FALSE.
INTEGER :: isimul = 0, nopenf = 0, nrecunit = 4
CHARACTER (LEN=lentitle) :: intitle, outtitle, runtitle
CHARACTER (LEN=lenname), DIMENSION(MaxProgLevels) :: procname
LOGICAL :: log fill = log undef
INTEGER :: int fill = int undef
REAL :: real fill = real undef, real min = real flag
File
iopars.f90
Type
Module
Purpose
General parameters mainly related to all kinds of input and output
Description
cold start If .TRUE., the program only executes the initialisation and
finalisation phases, but does not enter the time loop.
intitle Title for model forcing files
int fill Data flag for invalid integer data
isimul Number of the simulation (as given by the corresponding
line number in the defruns excluding comment lines)
log fill Data flag for invalid logical data
next simul When a new data line is read from the defruns file, its value
is set to .TRUE. to start a new simulation or to .FALSE. to
exit the program.
nopenf Number of current connected files
nrecunit Unit record size in bytes for direct access I/O (not used in
the present implementation)
outtitle Title for user output files
procname Name of the subprogram at the current program level
runtitle Simulation title
real fill Data flag for invalid real data
real min Real data are considered as valid or invalid if they are greater
than or lower than (or equal to) this critical threshold
Parameters for model forcing

(MODULE iopars)
INTEGER, DIMENSION(MaxIOTypes,2) :: maxdatafiles
INTEGER, DIMENSION(MaxCIFTypes) :: ciflinenum
TYPE (FileParams), DIMENSION(MaxCIFTypes) :: ciffiles
TYPE (GridParams), DIMENSION(MaxGridTypes,MaxGridFiles) :: surfacegrids
INTEGER, PARAMETER :: io mppmod = 1, io inicon = 2, io modgrd = 3, &
& io metgrd = 4, io sstgrd = 5, io biogrd = 6, &
& io nstgrd = 7, io biospc = 8, io 1uvsur = 9, &
& io 2uvobc = 10, io 3uvobc = 11, io salobc = 12, &
& io tmpobc = 13, io bioobc = 14, io rlxobc = 15, &
& io nstspc = 16, io 2uvnst = 17, io 3uvnst = 18, &
& io salnst = 19, io tmpnst = 20, io bionst = 21, &
& io metsur = 22, io sstsur = 23, io biosur = 24, &
INTEGER, PARAMETER :: icif defruns= 1, icif model = 2, icif bio = 3
INTEGER, PARAMETER :: ics phys = 1, ics bio = 2
INTEGER, PARAMETER :: igrd model = 1, igrd meteo = 2, igrd sst = 3, &
& igrd bio = 4
CHARACTER (LEN=6), DIMENSION(MaxIOTypes) :: modfiles desc = &
& (/’mppmod’,’inicon’,’modgrd’,’metgrd’,’sstgrd’,’biogrd’,’nstgrd’,’biospc’,
& ’1uvsur’,’2uvobc’,’3uvobc’,’salobc’,’tmpobc’,’bioobc’,’rlxobc’,’nstspc’,
& ’2uvnst’,’3uvnst’,’salnst’,’tmpnst’,’bionst’,’metsur’,’sstsur’,’biosur’/
File
iopars.f90
Type
Module
Purpose
Parameters for model forcing
Description
ciflinenum Number of the last input line read from a CIF
ciffiles Attributes of CIFs
icif * Key ids of CIFs
icif defruns defruns file
icif model CIF with model setup parameters
icif bio CIF with setup parameters for the biological

model (currently not implemented)
ics * Key ids for the file index in case the first index of modfiles
equals io inicon
ics bio initial conditions for biological arrays (currently
not implemented)
ics phys initial conditions for physical arrays
igrd * Key ids used for defining surface data grids
igrd bio surface grid for biological data (currently not
implemented)
igrd meteo meteorological grid
igrd model (horizontal) model grid
igrd sst SST grid
io * File descriptor key ids
io biogrd surface grid for biological data (currently not
implemented)
io bionst biological output for nesting (currently not
implemented)
io bioobc definitions of open boundary conditions for
biological variables (file number equals 1) or
input of open boundary data (file number
larger than 1). Currently not implemented.
io biospc (time-independent) arrays used for the setup
of a biological model (currently not imple-
mented)
io biosur biological surface data (currently not imple-
mented)
io inicon initial conditions
io metgrd surface meteo grid
io metsur meteorological forcing data
io modgrd model grid, bathymetry and open boundary
locations
io mppmod domain decomopistion
io nstgrd locations of nested sub-grid open boundaries
io nstspc number of open boundary locations at sub-

grid nested grids
io rlxobc definitions of areas for the application of the
relaxation open boundary scheme
io salnst salinity output for nesting
io salobc definitions of open boundary conditions for
salinity (file number equals 1) or input of
open boundary data (file number larger than
1)
io sstgrd surface SST grid
io sstsur SST data
io tmpnst temperature output for nesting
io tmpobc definitions of open boundary conditions for
temperature (file number equals 1) or input
of open boundary data (file number larger
than 1)
io 1uvsur definitions of surface boundary conditions (file
number equals 1) or input of surface data (file
number greater than 1) in case the model is
applied in water column (1-D) mode
io 2uvnst 2-D mode output for nesting
io 2uvobc definitions of 2-D open boundary conditions
(file number equals 1) or input of open boun-
dary data (file number larger than 1)
io 3uvnst 3-D mode output for nesting
io 3uvobc definitions of open boundary conditions for
the baroclinic currents (file number equals 1)
or input of open boundary data (file number
larger than 1)
maxdatafiles Largest file index (second dimension of modfiles) for a
given file descriptor (first index of modfiles)
modfiles Attributes of model forcing files. The first index is given
by a file descriptor key id of the form io * (see below),
the second is the file index, the third equals 1 for input
or 2 for output.
modfiles desc Descriptors of forcing files
surfacegrids Attributes of surface data grids. The first index is given

by a grid descriptor key id of the form igrd * (see above),
the second is the file index (currently equal to 1)
Parameters for user-defined output

(MODULE iopars)
!---time series
INTEGER :: nosetstsr = 0, nostatstsr = 0, novarstsr = 0
TYPE (FileParams), DIMENSION(nosetstsr) :: tsrgrd, tsr0d, tsr2d, tsr3d
!---time averages
INTEGER :: nosetsavr = 0, nostatsavr = 0, novarsavr = 0
TYPE (FileParams), DIMENSION(nosetsavr) :: avrgrd, avr0d, avr2d, avr3d
!---harmonic analysis
INTEGER :: nofreqsanal = 0, nosetsanal = 0, nostatsanal = 0, novarsanal = 0
CHARACTER (LEN=lentime), DIMENSION(nosetsanal) :: cdate time ref
CHARACTER (LEN=lenfreq), DIMENSION(nofreqsanal) :: harm freq names
INTEGER, DIMENSION(nofreqsanal) :: index anal
INTEGER, DIMENSION(nosetsanal) :: nofreqsharm
INTEGER, DIMENSION(nosetsanal,nofreqsanal) :: ifreqsharm
REAL, DIMENSION(nofreqsanal) :: harm freq
TYPE (FileParams), DIMENSION(nosetsanal) :: analgrd, res0d, res2d, res3d
& amp0d, amp2d, amp3d, &
& pha0d, pha2d, pha3d, &
& ell2d, ell3d
!---elliptic parameters
TYPE (VariableAtts), DIMENSION(14) :: ellvars
!---output operators
INTEGER, PARAMETER :: oopt null = 0, oopt dep = 1, oopt klev = 2, &
& oopt min = 3, oopt max = 4, oopt mean = 5
File
iopars.f90
Type
Module
Purpose
Parameters for user-defined output
Description
analgpars Attributes of the output grids for harmonic output
analgrd Attributes of the grid file for harmonic output con-
taining coordinate data only
analstatlocs Attributes of all output stations for harmonic output
(locations, names)
analvars Attributes of all variables for harmonic output
amp0d Attributes of the 0-D files for the harmonic output of
amplitudes
amplitudes
amplitudes
avrgpars Attributes of the output grids for time averaged out-
put
avrgrd Attributes of the grid file for time averaged output
containing coordinate data only
avrstatlocs Attributes of all output stations for time averaged
output (locations, names)
avrvars Attributes of all variables for time averaged output
avr0d Attributes of the 0-D files for time averaged output

cdate time ref Reference date with respect to which the analysed
phases are given. If not defined, the phases are given
with respect to the central analysis time or the Green-
wich astronomical phase.
ellvars Attributes of all possible elliptic variables (set by the
program)
ell2d Attributes of the 2-D files for harmonic output of el-
liptic parameters
ell3d Attributes of the 3-D files for harmonic output of el-
liptic parameters
harm freq Frequencies used for analysis [radian/s]
harm freq names Names of the frequencies used for harmonic analysis
ifreqsharm Index mapping array for harmonic frequencies. The
element ifreqsharm(iset,ifreq) maps, for set iset, the lo-
cal frequency ifreq into the corresponding “global” ar-
ray index as defined in the array index anal.
index anal Key ids of the harmonic constituents. If zero, the
corresponding frequencies need to be defined by the
user as well.
ivarsanal Index mapping array for harmonic output. The el-
ement ivarsanal(iset,ivar) maps, for set iset, the local
variable index ivar into the corresponding array index
in analvars.
ivarsavr Index mapping array for time averaged output. The
element ivarsavr(iset,ivar) maps, for set iset, the local
in avrvars.
ivarsell Index mapping array selecting the elliptic parameters
for output. The element ivarsell(iset,ivar) maps, for set
iset, the local variable index ivar into the correspon-
ding array index in ellvars.
ivarstsr Index mapping array for time series output. The el-
ement ivarstsr(iset,ivar) maps, for set iset, the local
in tsrvars (see below).
ivecell2d Indices of the elements in analvars representing the X-

and Y-component of the 2-D elliptic vectors
ivecell3d Indices of the elements in analvars representing the X-
and Y-component of the 3-D elliptic vectors
lstatsanal Station label for harmonic output. The element lstat-
sanal(iset,istat) maps, for set iset, the local index istat
into the corresponding global array index in analstat-
locs.
lstatsavr Station label for time averaged output. The element
lstatsavr(iset,istat) maps, for set iset, the local index is-
tat into the corresponding global array index in avrstat-
locs.
lstatstsr Station label for time series output. The element lstat-
stsr(iset,istat) maps, for set iset, the local index istat
into the corresponding global array index in tsrstat-
locs.
nofreqsanal Total number of frequencies for harmonic analysis
nofreqsharm Number of frequencies used for each output set
nosetsanal Number of output sets for harmonic output
nosetsavr Number of output sets for time averaged output
nosetstsr Number of time series output sets
nostatsanal Total number of stations for harmonic output
nostatsavr Total number of stations for time averaged output
nostatstsr Total number of stations for time series output
novarsanal Total number of variables for harmonic output
novarsavr Total number of variables for time averaged output
novarstsr Total number of variables for time series output
oopt * User output operators
oopt dep At a specified depth from the surface
oopt klev At a specified vertical level
oopt max Maximum value
oopt mean Spatially averaged value
oopt min Minimum value
oopt null No operator
pha0d Attributes of the 0-D files for the harmonic output of

phases
phases
phases
res0d Attributes of the 0-D files for the residual harmonic
output
output
output
tsrgpars Attributes of the output grids for time series output
tsrgrd Attributes of the grid file for time series output con-
taining coordinate data only
tsrstatlocs Attributes of all output stations for time series output
(locations, names)
tsrvars Attributes of all variables for time series output
tsr0d Attributes of the 0-D files for time series output
Parameters for monitoring

(MODULE iopars)
!---log files
LOGICAL :: exitlog
CHARACTER (LEN=*), PARAMETER :: logfmt1 = ’(I1,’’:’’,A)’, &
& logfmt2 = ’(I2,’’:’’,A)’
CHARACTER (LEN=1), PARAMETER :: logexit = ’R’
CHARACTER (len=leniofile) :: inilog file, runlog file
INTEGER :: iolog = 0, loglev1, loglev2, pglev, runlog count
INTEGER, DIMENSION(levprocs) :: levprocs ini, levprocs run
!---error files
LOGICAL :: errchk
CHARACTER (len=leniofile) :: errlog file
INTEGER :: errstat, ioerr = 0, maxerrors, nerrs = 0
INTEGER, DIMENSION(npworld) :: levprocs err
INTEGER, PARAMETER :: &

& ierrno fopen = 1, ierrno fclose = 2, ierrno read = 3, ierrno write = 4,&
& ierrno fend = 5, ierrno input = 6, ierrno inival = 7,ierrno runval = 8,&
& ierrno alloc = 9, ierrno arg = 10, ierrno comms = 11, ierrno MPI = 12, &
& ierrno CDF = 13
CHARACTER (LEN=lenerrcode), PARAMETER, DIMENSION(MaxErrCodes) :: error code
!---warning file
LOGICAL :: warnflag, warning
CHARACTER (len=leniofile) :: warlog file
INTEGER :: iowarn = 0
!---timer
LOGICAL :: timer = .FALSE.
CHARACTER (len=leniofile) :: timing file
INTEGER :: levtimer = 0, maxwaitsecs = 3600, nowaitsecs = 0, npcc max, &
& npcc rate, timer format = 1
INTEGER (KIND=kndilong), DIMENSION(MaxTimers) :: nopcc
& itm hydro = 1, itm 1dmode = 2, itm 2dmode = 3, itm 3dmode = 4, &
& itm dens = 5, itm temp = 6, itm sal = 7, itm init = 8, &
& itm trans = 9, itm adv = 10, itm hdif = 11, itm vdif = 12, &
& itm phgrad = 13, itm input = 14, itm output = 15, itm inout = 16, &
& itm com coll = 17, itm com comb = 18, itm com copy = 19, &
& itm com dist = 20, itm com exch = 21, itm com util = 22, itm coms = 23, &
& itm MPI = 24, itm CDF = 25, itm arrint = 26, itm user = 27, &
& itm nest = 28, itm libs = 29, itm astro = 30, itm bconds = 31, &
& itm meteo = 32, itm wait = 33, itm biolgy = 34
!---timer descriptions
CHARACTER (LEN=20), DIMENSION(MaxTimers) :: desctimer
File
iopars.f90
Type
Module
Purpose
Parameters for monitoring
Description
desctimer Strings written to the timer report for each (active)
timer
errchk Enables/disables error checking

errlog file Default name of the “errlog” file (appended by the
process id in the parallel case)
error code Error message string corresponding to an error code
number
errstat Error status number as returned by MPI, netCDF and
FORTRAN calls (e.g. ALLOCATE statement)
exitlog Enables/disables the writing of the “exit” message to
the “log” file when the program exits a routine
ierrno ⋆ Key ids for error messages
ierrno alloc allocation error
ierrno arg missing or invalid routine argument
ierrno CDF netCDF error
ierrno comms parallel communication error
ierrno fclose an error occurred when a file is closed
ierrno fend end of file condition
ierrno fopen an error occurred when a file is opened
ierrno inival invalid value for a setup or initial scalar
or array parameter
ierrno input an error occurred when reading an in-
valid value for a parameter or array from
a data file
ierrno MPI MPI error
ierrno read read error
ierrno runval invalid value for a scalar or array para-
meter during the time loop
ierrno write write error
inilog file Default name of the “inilog” file (appended by the
ioerr File unit of the “errlog” file
iolog File unit of the “inilog” and “runlog” files
iowarn File unit of the warning file
itm ⋆ Timer key ids
itm adv advection routines
itm arrint interpolation of model grid arrays

itm astro astronomical tide
itm bconds boundary conditions
itm biolgy biology (currently not activated)
itm CDF total of all netCDF calls
itm coms total of all communication calls
itm com coll collect communication calls
itm com comb combine communications calls
itm com copy copy communication calls
itm com dist distribute communication calls
itm com exch exchange communication calls
itm com util (parallel) utility communication calls
itm dens total of density (including temperature
and salinity) calculations
itm hdif horizontal diffusion
itm hydro hydrodynamics
itm init initialisation procedures
itm inout total of input and output operations
itm input input operations
itm libs calls to library routines
itm meteo meteorological routines
itm MPI total of all MPI calls
itm nest nesting procedures
itm output output operations
itm phgrad baroclinic pressure gradient
itm sal salinity
itm temp temperature
itm trans transport routines
itm user calls to usrdef routines
itm vdif vertical diffusion (including turbulence
modules)
itm wait wait calls
itm 1dmode water column mode (1-D) calculations

levprocs err Level of error checking
0: error checking disabled
1: error checking enabled during the initialisation phase
only
2: error checking enabled during the whole simulation
levprocs ini Maximum program level for writing a tracer informa-
tion message to the “inilog” file when a routine is en-
tered. Its value is determined for each process sepa-
rately.
levprocs run Maximum program level for writing a tracer informa-
tion message to the “runlog” file when a routine is
entered. Its value is determined for each process sep-
arately.
levtimer Defines the information in the timer report
0: no timer report is written
1: only the execution time is written
2: Execution time and time information (in percent-
age of total time) is written for all “timers”. In
case of a parallel simulation, the percentages are
given for the process with the largest amount of
time, the lowest amount of time, an average value
over all processes and for the master process.
3: As the previous case, but the time percentages are
now given for each individual process in addition.
In the serial case, behaviour is as for case 2.
logexit Exit message string written to the “log” file on exiting
of a routine
logfmt1 Format specification for writing the tracer information
to the “log” file
logfmt2 As logfmt1 now for program levels higher than 9
loglev1 Maximum program level for writing a tracer informa-
tion message when a routine is entered
loglev2 Maximum program level for writing a tracer informa-
tion message when a routine is exited
maxerrors Maximum number of messages written to the “errlog”

file
maxwaitsecs Maximum allowed time (in seconds) for suspension of
the program
nerrs Number of detected errors
nopcc Current number of process clock counts stored for each
timer
nowaitsecs Number of seconds to suspend the execution of the
program during a wait call
npcc max Maximum number of clock counts which can be re-
turned by the process clock
npcc rate Number of process clock counts per second
pglev Current program level
runlog count Determines the number of (2-D) time steps after which
the log-file will be re-written
runlog file Default name of the “runlog” file (appended by the
timer .TRUE. if levtimer>0 (see above)
timer format Unit of the execution time in the timer report
1: seconds
2: minutes
3: hours
4: days
timing file Default name of the time report file
warlog file Default name of the “warning” file
warnflag Enables/disables the writing of a warning (“warlog”)
file by the master process (.TRUE. on the master only
if warning is .TRUE.)
warning Enables/disables the writing of warning messages
netCDF parameters
(MODULE iopars)
INTEGER :: char NF90 = 0, clobber NF90 = 0, fill NF90 = 0, global NF90 = 0,&
& int NF90 = 0, noerr NF90 = 0, nofill NF90 = 0, nowrite NF90 = 0,&
25.10. METEOROLOGICAL ARRAYS 1151
& offset 64bit NF90 = 0, real NF90 = 0, share NF90 = 0,&

& sizehint default NF90 = 0, unlimited NF90 = 0, write NF90 = 0
File
iopars.f90
Type
Module
Purpose
Aliases for parameters of the netCDF library
Description
char NF90 Alias for NF90 char
clobber NF90 Alias for NF90 clobber
fill NF90 Alias for NF90 fill
global NF90 Alias for NF90 global
int NF90 Alias for NF90 int
noerr NF90 Alias for NF90 noerr
nofill NF90 Alias for NF90 nofill
nowrite NF90 Alias for NF90 nowrite
offset 64bit NF90 Alias for NF90 offset 64bit
real NF90 Alias for NF90 real
share NF90 Alias for NF90 share
sizehint default NF90 Alias for NF90 sizehint default
unlimited NF90 Alias for NF90 unlimited
write NF90 Alias for NF90 write
25.10 Meteorological arrays

MODULE meteo
REAL, DIMENSION(0:ncloc,0:nrloc) :: atmpres, uwindatc, vwindatc, &
& airtemp, sst
REAL, DIMENSION(ncloc,nrloc) :: cloud cover, evapminprec, &
& evaporation, precipitation, relhum
File
meteo.f90
Type
Module
Purpose
Meteorological data variables
Description
airtemp Air temperature interpolated in time and in space at
the C-nodes [0 C]
atmpres Atmospheric pressure interpolated in time and in space
at the C-nodes [Pa]
cloud cover Cloud cover interpolated in time and in space at the
C-nodes (between 0 and 1)
evapminprec Evaporation minus precipitation rate interpolated in
time and in space at the C-nodes [kg/m2 /s]
evaporation Evaporation rate interpolated in time and in space at
the C-nodes [kg/m2 /s]
precipitation Precipitation rate interpolated in time and in space at
the C-nodes [kg/m2 /s]
relhum Relative humidity interpolated in time and in space at
the C-nodes (between 0 and 1)
sst Sea surface temperature [0 C]
uwindatc X-component of the wind at 10m height interpolated
in time and in space at C-nodes [m/s]
vwindatc Y-component of the wind at 10m height interpolated
in time and in space at C-nodes [m/s]
25.11 Key ids of model variables

MODULE modids
!---model grid
& iarr alphatc fld = 1, iarr alphatu fld = 2, iarr_alphatv fld = 3,&
....
File
modids.f90
25.12. NESTED SUB-GRIDS 1153
Type
Module
Purpose
Definitions of key ids for model variables. The key id name has the
form iarr ⋆ where ⋆ is the FORTRAN name of the variable.
25.12 Nested sub-grids

MODULE nestgrids
INTEGER :: nonestsets = 0
INTEGER, DIMENSION(nonestsets) :: nestcoords, nohnstglbc, &
& nohnstglbu, nohnstglbv
INTEGER, DIMENSION(nonestsets) :: nohnstatc, nohnstatu, nohnstatv, novnst
INTEGER, DIMENSION(nonestsets) :: inst2dtype, lbhnstatc, lbhnstatu, lbhnstatv
INTEGER, DIMENSION(nprocs,nonestsets) :: nohnstcprocs, nohnstuvprocs
INTEGER, DIMENSION(nprocs,MAXVAL(nohnstcprocs),nonestsets) :: indexnstc
INTEGER, DIMENSION(nprocs,MAXVAL(nohnstuvprocs),nonestsets) :: indexnstuv
TYPE (HRelativeCoords), DIMENSION(SUM(nohnstatc)) :: hnstctoc
TYPE (HRelativeCoords), DIMENSION(SUM(nohnstatu)) :: hnstctou, hnstutou
TYPE (HRelativeCoords), DIMENSION(SUM(nohnstatv)) :: hnstctov, hnstvtov
TYPE (VRelativeCoords), DIMENSION(2,2,SUM(nohnstatc),&
& MAXVAL(novnst)) :: vnstctoc
TYPE (VRelativeCoords), DIMENSION(2,2,SUM(nohnstatu),&
& MAXVAL(novnst)) :: vnstutou
TYPE (VRelativeCoords), DIMENSION(2,2,SUM(nohnstatv),&
& MAXVAL(novnst)) :: vnstvtov
File
nestgrids.f90
Type
Module
Purpose
Arrays for the setup of sub-grid nesting
Description
hnstctoc Relative horizontal coordinates of the C-node sub-grid
points with respect to the local C-node main grid
hnstctou Relative horizontal coordinates of the U-node sub-grid

hnstctov Relative horizontal coordinates of the V-node sub-grid
hnstutou Relative horizontal coordinates of the U-node sub-grid
points with respect to the local U-node main grid
hnstvtov Relative horizontal coordinates of the V-node sub-grid
points with respect to the local V-node main grid
indexnstc Index mapping array for C-node points. Element indexn-
stc(iproc,lsub,iset) equals lglb-l1+1 where iproc is the pro-
cess number, lglb the corresponding index in the global
indexing system and l1 the index in the global indexing
system of the first global point in set iset
indexnstuv Index mapping array for U- and V-points. Element in-
dexnstuv(iproc,lsub,iset) equals lglb-l1+1 where iproc is
the process number, lglb the index in the global index-
ing system and l1 the index in the global indexing system
of the first global point in set iset. Note that U-points
are counted before V-node points.
inst2dtype Type of data used for 2-D nesting
1: transports and elevations
2: elevations
3: transports
lbhnstatc The C-node sub-grid points are indexed globally over
all sub-grids. The element lbhnstatc(iset) represents the
global index of the first point in the global indexing sys-
tem which is located on the local sub-domain.
lbhnstatu The U-node sub-grid points are indexed globally over
all sub-grids. The element lbhnstatu(iset) represents the
lbhnstatv The V-node sub-grid points are indexed globally over
all sub-grids. The element lbhnstatv(iset) represents the
nestcoords Type of coordinates used in the setup
1: absolute coordinates
25.13. OPEN BOUNDARY CONDITIONS 1155
2: relative coordinates
nohnstatc Local number of C-node (horizontal) sub-grid open boun-
dary points
nohnstatu Local number of U-node (horizontal) sub-grid open boun-
dary points
nohnstatv Local number of V-node (horizontal) sub-grid open boun-
dary points
nohnstcprocs Number of C-node sub-grid points for each sub-domain
and each sub-grid
nohnstglbc Global number of C-node (horizontal) sub-grid open boun-
dary points
nohnstglbu Global number of U-node (horizontal) sub-grid open boun-
dary points
nohnstglbv Global number of V-node (horizontal) sub-grid open boun-
dary points
nohnstuvprocs Number of U- and V-node sub-grid points for each sub-
domain and each sub-grid
nonestsets Number of sub-grid nests
novnst Number of vertical levels on the sub-grid
vnstctoc Relative vertical coordinates of the C-node sub-grid points
with respect to the local main C-node grid taken at the
four points surrounding each sub-grid point.
vnstctou Relative vertical coordinates of the C-node sub-grid points
with respect to the local main U-node grid taken at the
vnstctov Relative vertical coordinates of the C-node sub-grid points
with respect to the local main V-node grid taken at the
25.13 Open boundary conditions

MODULE obconds
!---2-D open boundary conditions
INTEGER, DIMENSION(nobu) :: iloczobu, ityp2dobu
INTEGER, DIMENSION(nobv) :: iloczobv, ityp2dobv
!nofiles = maxdatafiles(io_2uvobc,1)
INTEGER, DIMENSION(2:nofiles) :: iobc2dtype, no2dobc
INTEGER, DIMENSION(nobu+nobv,2:nofiles) :: index2dobc

REAL, DIMENSION(nobu,2) :: ud2obu, zetobu
REAL, DIMENSION(nobv,2) :: vd2obv, zetobv
REAL, DIMENSION(nobu,nconobc) :: ud2obu amp, ud2obu pha, &
& zetobu amp, zetobu pha
REAL, DIMENSION(nobv,nconobc) :: vd2obv amp, vd2obv pha, &
& zetobv amp, zetobv pha
REAL, DIMENSION(nobu,2) :: obc2uvatu
REAL, DIMENSION(nobv,2) :: obc2uvatv
!---3-D open boundary forcing
REAL, DIMENSION(nobu,nz,2) :: obc3uvatu
REAL, DIMENSION(nobv,nz,2) :: obc3uvatv
REAL, DIMENSION(nobu,nz,0:2) :: obcsalatu, obctmpatu
REAL, DIMENSION(nobv,nz,0:2) :: obcsalatv, obctmpatv
!---surface forcing (1-D application)
INTEGER :: isur1dtype
REAL :: gxslope = 0.0, gyslope = 0.0
REAL, DIMENSION(nconobc) :: gxslope amp, gxslope pha, gyslope amp, &
& gyslope pha, zeta amp, zeta pha
File
obconds.f90
Type
Module
Purpose
Parameters and arrays used to define open boundary conditions for the
2-D and 3-D mode or surface boundary conditions (surface slope and
elevations) for 1-D applications
Description
gxslope X-component of the (barotropic) pressure gradient in case
of a 1-D application [m/s2 ]
gxslope amp Amplitudes of the X-component of the (barotropic) pres-
sure gradient in case of a 1-D application [m/s2 ]
gxslope pha Phases of the X-component of the (barotropic) pressure
gradient in case of a 1-D application [rad]
gyslope Y-component of the (barotropic) pressure gradient in case
of a 1-D application [m/s2 ]
gyslope amp Amplitudes of the Y-component of the (barotropic) pres-

sure gradient in case of a 1-D application [m/s2 ]
gyslope pha Phases of the Y-component of the (barotropic) pressure
gradient in case of a 1-D application [rad]
iloczobu If the elevation has to be specified at a U-open boundary,
the array selects the position of the specified elevation
with respect to the open boundary.
0: not required
1: at the open boundary U-node
2: at the “nearest” C-node outside the domain
iloczobv The same as iloczobu now at V-open boundaries
index2dobc Each 2-D open boundary data file contains a sub-set of
open boundary data points. The element index2dobc(idat,ifil)
maps, for file ifil, the local data point idat into a cor-
responding global open boundary index (between 1:nobu
for U- and nobu+1:nobu+nobv for V-open boundaries).
The physical size of the first dimension for file ifil equals
no2dobc(ifil).
iobc2dtype Identifies the type of variables within each 2-D open boun-
dary data file
1: depth-integrated currents and elevations
2: elevations only
3: depth-integrated currents only
isur1dtype Identifies the variables within a 1-D surface forcing data
file.
1: components of the pressure gradient and elevation
2: surface elevation
3: components of the pressure gradient
ityp2dobu Type of open boundary conditions at the U-nodes (0/13)
0 : clamped
1 : zero slope
2 : zero volume flux
3 : specified elevation
4 : specified transport
5 : radiation condition using shallow water speed
6 : Orlanski (1976) condition

7 : Camerlengo & O’Brien (1980)
8 : Flather (1976) with specified elevation and transport
10: Røed & Smedstad (1984)
11: characteristic method with specified elevation and trans-
port
13: characteristic method using a zero normal gradient
condition
ityp2dobv Type of open boundary condition at the V-nodes. Mean-
ing is the same as for ityp2dobu with U replaced by V and
West/East by South/North.
no2dobc Number of input open boundary locations for each 2-D
open boundary data file
obcsalatu Storage array for salinity S in case the open boundary
conditions at the U-nodes require the solution of a differ-
ential equation in time
obcsalatv Storage array for salinity S in case the open boundary
conditions at the V-nodes require the solution of a differ-
ential equation in time
obctmpatu Storage array for temperature T in case the open boun-
dary conditions at the U-nodes require the solution of a
differential equation in time
obctmpatv Storage array for temperature T in case the open boun-
dary conditions at the V-nodes require the solution of a
differential equation in time
obc2uvatu Storage array for the X-component of the transport U in
case the open boundary conditions at the U-nodes require
the solution of a differential equation in time
obc2uvatv Storage array for the Y-component of the transport V in
case the open boundary conditions at the V-nodes require
the solution of a differential equation in time
obc3uvatu Storage array for the X-component of the baroclinic cur-
rent δu in case the open boundary conditions at the U-
nodes require the solution of a differential equation in time
obc3uvatv Storage array for the Y-component of the baroclinic cur-

rent δv in case the open boundary conditions at the V-
nodes require the solution of a differential equation intime
ud2obu X-component of the transport U at U-open boundaries
as given by (4.340). The external term term is stored in
elements (*,1), the full expression (including the harmonic
expansion) in elements (*,2) [m2 /s]
ud2obu amp Amplitudes An in the harmonic expansion of the X-com-
ponent of the transport U at U-open boundaries [m2 /s]
ud2obu pha Phases ϕ in the harmonic expansion of the X-component
of the transport U at U-open boundaries [rad]
vd2obv Y-component of the transport V at V-open boundaries
as given by (4.340). The external term term is stored in
elements (*,1), the full expression (including the harmonic
expansion) in elements (*,2) [m2 /s]
vd2obv amp Amplitudes An in the harmonic expansion of the Y-com-
ponent of the transport V at V-open boundaries [m2 /s]
vd2obv pha Phases ϕ in the harmonic expansion of the Y-component
of the transport V at V-open boundaries [rad]
zeta amp Amplitudes of the surface elevation ζ in case of a 1-D
application [m]
zeta pha Phases of the surface elevation ζ in case of a 1-D applica-
tion [rad]
zetobu Surface elevation at U-open boundaries as given by (4.340).
The external term term is stored in elements (*,1), the full
expression (including the harmonic expansion) in elements
(*,2) [m]
zetobu amp Amplitudes An in the harmonic expansion of the surface
elevation ζ at U-open boundaries [m]
zetobu pha Phases ϕ in the harmonic expansion of the surface eleva-
tion ζ at U-open boundaries [rad]
zetobv Surface elevation at V-open boundaries as given by (4.340).
The external term term is stored in elements (*,1), the full
expression (including the harmonic expansion) in elements
(*,2) [m]
zetobv amp Amplitudes An in the harmonic expansion of the surface
elevation ζ at V-open boundaries [m]
zetobv pha Phases ϕ in the harmonic expansion of the surface eleva-

tion ζ at V-open boundaries [rad]
25.14 Optical arrays

MODULE optics
REAL, DIMENSION(ncloc,nrloc) :: optattcoef2, qrad
REAL, DIMENSION(ncloc,nrloc,nz+1) :: radiance
File
optics.f90
Type
Module
Purpose
Optical arrays
Description
optattcoef2 Inverse optical attenuation depth for the short-wave spec-
trum [m−1 ]
qrad Solar downard irradiance within the water column [W/m2 ]
radiance Solar irradiance incident on the surface [W/m2 ]
25.15 Parameters for parallel processing

MODULE paralpars
LOGICAL :: parallel set = .FALSE.
LOGICAL :: master, spare, worker
INTEGER :: idmaster = 0, nprocs = 1, nprocsx = 0, nprocsy = 0
INTEGER :: comm work, icoordloc, idloc, iprocloc, jcoordloc, npworld
INTEGER, DIMENSION(2*nprocs) :: comprocs
INTEGER, DIMENSION(npworld) :: idprocs
INTEGER, DIMENSION(nprocs) :: icoordprocs, jcoordprocs, ncprocs, nc1procs, &
& nc2procs, nobuprocs, nobvprocs, nobxprocs, &
& nobyprocs, nosbuprocs, nosbvprocs, nrprocs, &
& nrvbuprocs, nrvbvprocs, nr1procs, nr2procs
INTEGER, DIMENSION(0:nprocsx+1,0:nprocsy+1) :: iddomain
INTEGER, DIMENSION(nobu,nprocs) :: indexobuprocs
INTEGER, DIMENSION(nobv,nprocs) :: indexobvprocs
25.15. PARAMETERS FOR PARALLEL PROCESSING 1161
INTEGER, DIMENSION(nobx,nprocs) :: indexobxprocs

INTEGER, DIMENSION(noby,nprocs) :: indexobyprocs
TYPE(ExchComms), DIMENSION(MaxHaloComms) :: halocomms
!---MPI definitions
INTEGER :: bsend overhead MPI = 0, comm null MPI = 0, comm world MPI = 0, &
& proc null MPI = 0, undefined MPI = 0
File
paralpars.f90
Type
Module
Purpose
Parameters for parallel applications
Description
bsend overhead MPI Alias for MPI bsend overhead
comm null MPI Alias for MPI comm null
comm work MPI communicator containing all worker (non-idle)
processes
comm world MPI Alias for MPI comm world
comprocs Array defining the rank order for all-to-all com-
munications (see Section 9.4.3.1)
halocomms Parameters for exchange (send/receive) communi-
cations
icoordloc Domain index in the X-direction of the local pro-
cess on the parallel grid
icoordprocs Array with the values of icoordloc for each process
iddomain Process ranks as defined on the parallel domain
grid
idloc Rank of the local process
idmaster Rank of the master process
idprocs Array of process ranks (global)
indexobuprocs Index mapping array at the U-open boundaries.
The element indexobuprocs(llloc,iproc) maps the lo-
cal open boundary index lloc on the local process
iproc to the corresponding global open boundary
index.
indexobvprocs Index mapping array at the V-open boundaries.

The element indexobvprocs(llloc,iproc) maps the lo-
index.
indexobxprocs Index mapping array at the X-open boundaries.
The element indexobxprocs(llloc,iproc) maps the lo-
index.
indexobyprocs Index mapping array the Y-open boundaries. The
element indexobyprocs(llloc,iproc) maps the local
open boundary index lloc on the local process iproc
to the corresponding global open boundary index.
iprocloc Local process number (=idloc+1)
jcoordloc Domain index in the Y-direction of the local pro-
cess on the parallel grid
jcoordprocs Array with the values of jcoordloc for each process
master .TRUE. on the master process, .FALSE. otherwise
ncprocs Array with the X-dimension ncloc of each sub-
domain (global)
nc1procs Array with the values of nc1loc for each sub-domain
(global)
nc2procs Array with the values of nc2loc for each sub-domain
(global)
nobuprocs Array with the values of nobuloc for each process
nobvprocs Array with the values of nobvloc for each process
nobxprocs Array with the values of nobxloc for each process
nobyprocs Array with the values of nobyloc for each process
nosbuprocs Array with the values of nosbuloc for each process
nosbvprocs Array with the values of nosbvloc for each process
nprocs Total number of active (“worker”) processes used
in the simulation
nprocsx X-dimension of the parallel grid
nprocsy Y-dimension of the parallel grid
25.16. PHYSICAL AND NUMERICAL MODEL PARAMETERS 1163
npworld Total number of processes in MPI comm world. This

equals the number given in the script used to launch
the program
nrprocs Array with the Y-dimension nrloc of each sub-
domain (global)
nr1procs Array with the values of nr1loc for each sub-domain
(global)
nr2procs Array with the values of nr2loc for each sub-domain
(global)
nrvbuprocs Array with the values of nrvbuloc for each process
nrvbvprocs Array with the values of nrvbvloc for each process
parallel set Enables/disables the parallel mode. The switch is
automatically set by the program if the compiler
option -DMPI is defined in options.cpp.
proc null MPI Alias for MPI proc null
spare .TRUE. if the local process is an idle (spare) pro-
cess which is currently inactive
undefined MPI Alias for MPI undefined
worker .TRUE. for an active on (worker) process. Is the
same as .NOT.spare.
25.16 Physical and numerical model parame-

ters
MODULE physpars
!---general
REAL :: Rearth = 6371000.0, rho air = 1.2, specheat = 3987.5
!---reference and minimum values
REAL :: atmpres ref = 101325.0, beta sal_ref, beta temp_ref, density ref, &
& dlat ref = 0.0, dlon ref = 0.0, dlon ref anal = 0.0, &
& dlon ref obc = 0.0, gacc mean, gacc ref = real undef, &
& sal ref = 33.0, sst ref = 12.0, temp min = 0.0, temp ref = 12.0
!---diffusion coefficients
REAL :: hdifmom cst = 0.0, hdifscal cst = 0.0, smag coef mom = 0.1, &
& smag coef scal = 0.1, vdifmom cst = 1.0E-06, vdifscal cst = 1.0E-06
!---water depths
REAL :: depmean cst = 0.0
!---inundation schemes
INTEGER, PARAMETER :: nofldmasks = 11
REAL :: dcrit fld = 0.1, dmin fld = 0.02, dthd fld = 0.1
INTEGER, DIMENSION(nofldmasks) :: fld mask
!---bottom/surface fluxes
REAL :: bdragcoef cst = 0.0, bdraglin = 0.0, ccharno = 0.014, &
& cds cst = 0.0013, ces cst = 0.00113, chs cst = 0.00113, ckar = 0.4, &
& zref atm = 10.0, zrough cst = 0.0
!---open boundary conditions
REAL :: cgravratio = 0.03
!---optical parameters
REAL :: optattcoef1 cst = 10.0, optattcoef2 cst = 0.067, opt frac = 0.54
!---parameters for exchange coefficients in tabular form
INTEGER :: nrelhum, ntemp, nwind
REAL :: drelhum = 0.05, dtempdif = 1.0, dtempmax = 5.0, dtempmin = -5.0, &
& dwind = 0.25, relhummax = 1.0, relhummin = 0.5, uwindmax = 50.0, &
& uwindmin = 3.0
!---numerical
REAL :: theta cor = 0.5, theta vadv = 0.501, theta vdif = 1.0
REAL, PARAMETER :: eps adv = 1.0E-12
File
physpars.f90
Type
Module
Purpose
Physical and numerical model parameters
Description
atmpres ref Reference atmospheric pressure Pref [Pa]
bdragcoef cst Constant bottom drag coefficient Cdb when
iopt bstres drag=1
bdraglin Bottom friction velocity klin used in the linear bottom
friction law if iopt bstres form=1 [m/s]
beta sal ref Reference value for the salinity contraction coefficient
βS [PSU−1 ]
beta temp ref Reference value for the temperature expansion coeffi-
cient βT [0 C−1 ]
ccharno Charnock’s constant a used in Charnock’s relation (4.279)

cds cst Constant surface drag coefficient Cds when
iopt sflux cds=0
ces cst Constant surface exchange coefficient Ce when
iopt sflux cehs=0
cgravratio Ratio of the internal to the external wave speed (used
in the open boundary condition (4.368)
chs cst Constant surface exchange coefficient Ch when
iopt sflux cehs=0
ckar von Karman’s constant κ
dcrit fld Critical water depth dcrit used in the drying/wetting
algorithm [m]
density ref Reference density ρ0 [kg/m3 ]
depmean cst Constant water depth used to set up a default bathy-
metry [m]
dlat ref Reference latitude to be used for the Coriolis frequency
in case of a Cartesian grid [degrees]
dlon ref Reference longitude to be used in case of a Cartesian
grid [degrees, positive East]
dlon ref anal If iopt astro anal=1, the harmonically analysed phases
are taken with respect to the astronomical argument
for this reference longitude.
[degrees, positive East]
dlon ref obc If iopt astro pars>0, the phases at open boundaries are
assumed to be taken with respect to the astronomical
argument at this reference value. If zero, the reference
longitude is taken at Greenwich.
[degrees, positive East]
dmin fld Minimum water depth dmin used in the drying/wetting
algorithm [m]
drelhum Interval of relative humidities taken to calculate the
surface exchange coefficients using the Monin-Obukhov
theory in tabular form
dtempdif Interval of air minus sea temperature differences taken
to calculate the surface exchange coefficients using the
Monin-Obukhov theory in tabular form [0 C]
dtempmax Maximum air minus sea surface temperature differ-

ence taken to calculate the surface exchange coeffi-
cients using the Monin-Obukhov theory in tabular form
[0 C]
dtempmin Minimum air minus sea surface temperature differ-
ence taken to calculate the surface exchange coeffi-
cients using the Monin-Obukhov theory in tabular form
[0 C]
dthd fld Threshold water depth dth used in mask criteria for
the inundation scheme [m]
dwind Interval of wind speeds taken to calculate the surface
exchange coefficients using the Monin-Obukhov theory
in tabular form [m/s]
eps adv Tolerance factor for the calculation of the flux ratios
with the TVD advection scheme
fld mask Enables (0) or disables (1) a specific mask criterium
gacc mean Mean acceleration of gravity
• If gacc ref is defined, gacc mean=gacc ref.
• If gacc ref is undefined and the grid is Cartesian,
gacc mean is defined by the geodetic formula (4.47)
at the latitude given by dlat ref.
• If gacc ref is undefined and the grid is spherical,
gacc mean is defined by the geodetic formula (4.47)
applied at each C-node point and averaged over
the physical domain.
gacc ref If different from real fill, the acceleration of gravity is
taken as horizontally uniform. Otherwise, g is evalu-
ated as function of latitude using (4.47) [m/s2 ].
hdifmom cst Constant coefficient for horizontal momentum diffu-
sion νH when iopt hdif coef=1 [m2 /s]
hdifscal cst Constant coefficient for horizontal scalar diffusion λH
when iopt hdif coef=1 [m2 /s]
nofldmasks Number of available mask criteria
nrelhum Number of relative humidities taken to calculate the
surface exchange coefficients using the Monin-Obukhov
ntemp Number of air minus sea temperature differences taken

to calculate the surface exchange coefficients using the
Monin-Obukhov theory in tabular form
nwind Number of wind speeds taken to calculate the surface
in tabular form
1 ) for the absorp-
tion of long-wave solar radiation as used in (4.48)[m−1 ]
2 ) for the absorp-
tion of short-wave solar radiation as used in (4.48)
[m−1 ]
opt frac Long-wave fraction R of the surface solar radiance as
used in (4.48)
Rearth Mean radius of the Earth [m]
relhummax Maximum relative humidity taken to calculate the sur-
face exchange coefficients using the Monin-Obukhov
relhummin Minimum relative humidity taken to calculate the sur-
face exchange coefficients using the Monin-Obukhov
rho air Air mass density ρa [kg/m3 ]
sal ref Reference salinity Sref used if iopt sal=0 or in the lin-
ear equation of state (4.97) or as default initial condi-
tion [PSU]
smag coef mom Smagorinsky coefficient Cm for horizontal diffusion of
momentum
smag coef scal Smagorinsky coefficient Cs for horizontal diffusion of
scalars
specheat Specific heat of seawater cp at constant pressure
[J/kg/0 C]
sst ref Reference sea surface temperature [0 C]
temp min Minimum temperature. If set to real fill, the minimum
is taken as the freezing point of sea water which is a
function of salinity. [0 C]
temp ref Reference temperature Tref used if iopt temp=0 or in
the linear equation of state (4.97) or as default initial
condition [0 C]
theta cor Implicity factor θc for the Coriolis term (between 0.0
and 1.0)
theta vadv Implicity factor θa for vertical advection (between 0.0
and 1.0)
theta vdif Implicity factor θd for vertical diffusion (between 0.0
and 1.0)
uwindmax Maximum wind speed taken to calculate the surface
uwindmin Minimum wind speed taken to calculate the surface
vdifmom cst Constant coefficient for vertical diffusion of momen-
tum used if iopt vdif coef=1 or as background value if
iopt turb iwlim=0 [m2 /s]
vdifscal cst Constant coefficient for vertical diffusion of scalars used
if iopt vdif coef=1 or as background value if
iopt turb iwlim=0 [m2 /s]
zref atm Reference height za for meteorological variables (taken
by default at 10 m height) [m]
zrough cst Constant bottom roughness length z0 taken when
iopt bstres drag=3 [m]
25.17 Relaxation zones

MODULE relaxation
INTEGER :: norlxzones = 0
INTEGER, DIMENSION(2) :: inodesrlx = 0
INTEGER, DIMENSION(norlxzones) :: idirrlx, iposrlx, ityprlx, &
& jposrlx, ncrlx, nrrlx
INTEGER, DIMENSION(ncloc,nrloc,2) :: indexrlxatc, indexrlxatuv
REAL, DIMENSION(ncloc,nrloc,2) :: rlxwghtatc, rlxwghtatuv
File
relaxation.f90
Type
Module
25.17. RELAXATION ZONES 1169
Purpose
Definitions for application of relaxation conditions near open bounda-
ries
Description
idirrlx Defines the orientation of each zone
1: western boundary
2: eastern boundary
3: southern boundary
4: northern boundary
indexrlxatc Each C-node grid point within a zone must have an as-
sociated boundary location. The array stores both the
corresponding zonal index and the (global) index of the
corresponding open boundary index. If the grid point is
outside all zones, its value is 0. The last array index refers
to either U-node (1) or V-node (2) boundaries.
indexrlxatuv Each velocity node grid point within a zone must have an
associated boundary location. The array stores both the
corresponding zonal index and the (global) index of the
corresponding open boundary index. If the grid point is
outside all zones, its value is 0. The last array index refers
to either U-node (1) or V-node (2) boundaries.
inodesrlx The first element disables (0) or enables (1) the application
of relaxation condition for C-node (scalar quantities), the
second element for quantities at velocity (U- or V-) nodes.
iposrlx (Global) X-index of the southwest corner of each relaxation
zone
ityprlx Type of interpolation (weighting) scheme within the relax-
ation zones
1: linear
2: quadratic
3: hyperbolic
jposrlx (Global) Y-index of the southwest corner of each relaxation
zone
ncrlx Sizes of the zones (number of C- or velocity-node grid
points) in the X-direction
norlxzones Number of relaxation zones
nrrlx Sizes of the zones (number of C- or velocity-node grid

points) in the Y-direction
rlxwghtatc Weight factors used in the interpolation for C-node quan-
tities. If the last index is 1(2), weighting is performed with
respect to U-node (V-node) boundaries.
rlxwghtatuv Weight factors used in the interpolation for U-node or V-
node quantities. If the last index is 1(2), weighting is per-
formed with respect to U-node (V-node) boundaries.
25.18 Model switches

MODULE switches
!---grid
INTEGER :: iopt grid htype = 1, iopt grid node = 1, iopt grid nodim = 3, &
& iopt grid sph = 0, iopt grid vtype = 1
!---interpolation
INTEGER :: iopt arrint hreg = 0, iopt arrint vreg = 0
!---currents
INTEGER :: iopt mode 2D = 1, iopt mode 3D = 1
!---density
INTEGER :: iopt dens = 0, iopt dens grad = 1, iopt sal = 0, iopt sal sbc = 0, &
& iopt temp = 0, iopt temp optic = 1, iopt temp sbc = 1
!---biology
INTEGER :: iopt biolgy = 0
!---bottom stress
INTEGER :: iopt bstres drag = 3, iopt bstres form = 2, iopt bstres nodim = 3
!---transport
INTEGER :: iopt transp full = 0
!---advection
INTEGER :: iopt adv scal = 3, iopt adv turb = 0, iopt adv tvd = 1, &
& iopt adv 2D = 1, iopt adv 3D = 1
!---diffusion
INTEGER :: iopt hdif coef = 0, iopt hdif scal = 0, iopt hdif turb = 0, &
& iopt hdif 2D = 0, iopt hdif 3D = 0, iopt vdif coef = 3
!---turbulence
INTEGER :: iopt turb alg = 1, iopt turb dis bbc = 2, iopt turb dis sbc = 2, &
& iopt turb iwlim = 0, iopt turb lmix = 4, iopt turb ntrans = 1, &
& iopt turb param = 2, iopt turb stab form = 3, &
& iopt turb stab lev = 1, iopt turb stab mod = 4, &
& iopt turb stab tke = 2, iopt turb tke bbc = 2, &
& iopt turb tke sbc = 2

!---drying/wetting
INTEGER :: iopt fld = 0
!---structures
INTEGER :: iopt structs = 0
!---explicit/implicit integration
INTEGER :: iopt cor impl = 1, iopt vadv impl = 1, iopt vdif impl = 2
!---open boundary conditions
INTEGER :: iopt obc advflux = 1, iopt obc advrlx = 0, iopt obc bio = 0, &
& iopt obc invbar = 0, iopt obc relax = 0, iopt obc sal = 0, &
& iopt obc temp = 0, iopt obc 2D = 0, iopt_obc 3D = 0
!---astronomical tide
INTEGER :: iopt astro anal = 0, iopt astro pars = 0, iopt astro tide = 0
!---1-D applications
INTEGER:: iopt sur 1D = 0
!---meteo surface forcing
INTEGER :: iopt meteo = 0, iopt meteo heat = 0, iopt meteo salflx = 0, &
& iopt meteo stres = 0
!---surface fluxes
INTEGER :: iopt sflux cds = 0, iopt sflux cehs = 0, iopt sflux strat = 0
!---nesting
INTEGER :: iopt nests = 0
!---parallel processing (MPI)
INTEGER :: iopt MPI, iopt MPI abort = 0, iopt MPI comm all = 2, &
& iopt MPI comm coll = 0, iopt MPI comm exch = 2, &
& iopt MPI comm full = 0, iopt MPI comm gath = 2, &
& iopt MPI comm scat = 2, iopt MPI partit = 1, iopt MPI sync = 0
!---output
INTEGER :: iopt out anal = 0, iopt out avrgd = 0, iopt out tsers = 1
!---netCDF
INTEGER :: iopt CDF, iopt CDF abort = 0, iopt CDF fill = 0, &
& iopt CDF format = 1
!---verification procedure
INTEGER :: iopt verif
File
switches.f90
Type
Module
Purpose
Model switches
Reference
Section 12.4
Description
iopt adv scal Type of scheme for the advection of scalar quan-
tities
0: advection disabled
1: upwind scheme
2: Lax-Wendroff (explicit) in the horizontal, cen-
tral (semi-implicit) in the vertical
3: TVD scheme
iopt adv turb Type of scheme for the advection of turbulence
quantities.
1: upwind scheme
3: TVD scheme
iopt adv tvd Type of limiting function for the TVD scheme.
1: superbee limiter
2: monotone limiter
iopt adv 2D Type of scheme for the advection of 2-D trans-
ports.
1: upwind scheme
3: TVD scheme
iopt adv 3D Type of scheme for the advection of 3-D cur-
rents.
1: upwind scheme

3: TVD scheme
iopt arrint hreg Disables/enables (0/1) the use of non-uniform weighted
averages for interpolation in the horizontal of ar-
rays on the model grid.
iopt arrint vreg Disables/enables (0/1) the use of non-uniform weighted
averages for interpolation in the vertical of arrays
on the model grid.
iopt astro anal Disables/enables (0/1) the use of astronomical ar-
guments for harmonic analysis if iopt astro pars >
0 and iopt out anal = 1.
iopt astro pars Enables or disables the inclusion of astronomical
arguments and nodal corrections in the harmonic
expansions (4.218) and (4.340).
0: astronomical argument set to zero, nodal fac-
tors set to 1, nodal phases set to zero
1: evaluate astronomical phases at a given time
and reference longitude, nodal factors are set
to 1, nodal phases set to zero
2: evaluate astronomical phases and nodal cor-
rections at a given time and reference longi-
tude
iopt astro tide Disables/enables (0/1) the inclusion of the astro-
nomical tidal force in the momentum equations.
This requires that the model uses a spherical grid
(iopt grid sph=1).
iopt biolgy Disables/enables (0/1) the biological module. Cur-
rently not implemented.
iopt bstres drag Formulation for the bottom drag coefficient Cdb .
0: not used
1: spatially uniform value
2: spatially non-uniform
3: using a spatially uniform roughness length
4: using a specified, spatially non-uniform rough-
ness length
iopt bstres form Type of formulation for the bottom stress.

0: bottom stress set to zero
1: linear bottom stress law (4.326) or (4.327)
2: quadratic bottom stress (4.328) or (4.327)
iopt bstres nodim Type of currents in the (linear or quadratic) bot-
tom stress formulation.
2: depth-mean currents
3: 3-D current taken at the bottom grid cell
iopt CDF Disables/enables (0/1) the use of netCDF format.
The format of all user output is set by default to
netCDF (‘N’) if switched on. This switch cannot
be defined by the user, but is set automatically
when -DCDF is defined as CPP compiler option
in options.cpp.
iopt CDF abort Disables/enables (0/1) automatic abortion of the
program when an error is detected whithin a netCDF
call.
iopt CDF fill Disables/enables (0/1) the use of fill values in
netCDF files.
iopt CDF format Selects the type netCDF file format.
1: classic format
2: 64-bit offset format
iopt cor impl Time-integration of the Coriolis term.
0: explicit
1: semi-implicit
2: implicit
iopt dens Evaluation of the density and expansion coeffi-
cients.
0: uniform density, zero expansion coefficients
1: density from the linear equation of state (4.97),
expansion coefficients are uniform
2: from the McDougall et al. (2003) general equa-
tion of state (4.92)–(4.96) without pressure ef-
fects
3: from the McDougall et al. (2003) general equa-

tion of state (4.92)–(4.96) with pressure effects
included
iopt dens grad Selects the numerical algorithm for the discreti-
sation of the baroclinic pressure gradient.
0: gradient set to zero
1: traditional σ-coordinate (second order) method
2: z-level method
3: method of Shchepetkin & McWilliams (2003)
iopt fld Selects the type of drying/wetting scheme.
0: Drying/wetting disabled
1: Drying/wetting algorithm without dynamic masks
2: Drying/wetting algorithm using dynamic masks
iopt grid htype Type of horizontal grid.
3: curvilinear grid
iopt grid node Grid location of the input bathymetry and the
σ-coordinate grid.
1: at grid centers (‘C’-nodes)
2: at cell corners (‘UV’-nodes and ‘UVW’-nodes)
iopt grid nodim Grid dimension.
1: 1-dimensional grid (water column model)
2: 2-dimensional grid (depth-averaged model with-
out vertical structure)
3: 3-dimensional grid
iopt grid sph Type of coordinates.
0: Cartesian coordinates
1: spherical coordinates
iopt grid vtype Type of vertical grid.
1: uniform σ-grid
2: non-uniform σ-grid in the vertical, uniform in
the horizontal
3: non-uniform σ-coordinate grid in the horizon-

tal and the vertical
iopt hdif coef Type of scheme for horizontal diffusion coefficients.
0: not used
1: spatially uniform
2: Smagorinsky formulation (4.69) for momentum
and (4.70) for scalars
iopt hdif scal Disables/enables (0/1) horizontal diffusion in the
scalar transport equations.
iopt hdif turb Disables/enables (0/1) horizontal diffusion in the
turbulence transport equations.
iopt hdif 2D Disables/enables (0/1) horizontal diffusion in the
2-D transport equations.
iopt hdif 3D Disables/enables (0/1) horizontal diffusion in the
3-D current transport equations.
iopt meteo Disables/enables (0/1) meteorological input and
evaluation of all surface fluxes.
iopt meteo heat Selects type of input data for the heat fluxes.
0: no input
1: air temperature Ta , relative humidity RH, cloud
cover fc
2: total (downward) non-solar surface heat flux,
cloud cover fc
3: total (downward) non-solar surface heat flux,
surface solar radiance Qrad
4: cloud cover fc
5: surface solar radiance Qrad
iopt meteo salflx Selects type of input data for the salinity flux.
0: no input
1: evaporation minus precipitation rate Evap −Prc
2: precipitation rate Prc
iopt meteo stres Selects type of input data for the barotropic mode,
i.e. surface stress and pressure.
0: no input
1: components of the wind speed (U10 ,V10 ) and

(unless iopt grid nodim=1) the atmospheric pres-
sure Pa
2: components of the surface stress (τsu ,τsv ) and
(unless iopt grid nodim=1) the atmospheric pres-
sure Pa
iopt mode 2D Disables/enables (0/1) the 2-D hydrodynamical
mode.
iopt mode 3D Disables/enables (0/1) the 3-D hydrodynamical
mode.
iopt MPI Disables/enables (0/1) the use of parallel com-
munications. This switch cannot be defined by
the user, but is set automatically when -DMPI is
defined as CPP compiler option in options.cpp.
iopt MPI abort Disables/enables (0/1) automatic abortion of the
program when an error is detected whithin a MPI
call.
iopt MPI comm all Communication type for “all to all” operations.
iopt MPI comm coll Disables/enables (0/1) the use of MPI collective
calls.
iopt MPI comm exch Communication type for “exchange” operations.
5: send-receive blocking calls
iopt MPI comm full Disables/enables (0/1) the exchange of 4-D ar-
rays. Currently not implemented.
iopt MPI comm gath Communication type for “all to one” gather (com-
bine) operations.

iopt MPI comm scat Communication type for “one to all” scatter (dis-
tribute and copy) operations.
iopt MPI partit Selects the method for domain decomposition.
1: “simple” partition based on the values of nprocsx
and nprocsy
2: decomposition obtained from an external data
file or defined in usrdef partition
iopt MPI sync Disables/enables (0/1) synchronisation calls at the
end of a series of blocking or non-blocking opera-
tions.
iopt nests Disables/enables (0/1) the writing of open boun-
dary data for nested sub-grids.
iopt obc advflux Type of open boundary condition for the cross-
stream (2-D and 3-D) advective fluxes (see Sec-
tion 5.3.15.2)
1: zero gradient condition
2: quasi-upwind scheme
iopt obc advrlx Disables/enables (0/1) the relaxation scheme for
horizontal momentum advection (see Section 5.3.15.2)
0 relaxation scheme disabled (default)
1 relaxation scheme enabled. In that case the pa-
rameter distrlx obc (representing the parameter
dmax ) must be defined by the user in usrdef mod params
or in the CIF.
iopt obc bio (General) type of open boundary conditions for
biological variables. Currently not implemented.
1: non-default conditions for at least one open

boundary point
iopt obc invbar Disables/enables (0/1) the inverse barometric ef-
fect at open boundaries.
iopt obc relax Disables/enables (0/1) the open boundary relax-
ation as discussed in Section 4.10.3.
iopt obc sal (General) type of open boundary conditions for
salinity.
boundary point
iopt obc temp (General) type of open boundary conditions for
temperature.
boundary point
iopt obc 2D (General) type of open boundary conditions for
the 2-D mode.
boundary point
iopt obc 3D (General) type of open boundary conditions for
the 3-D baroclinic currents.
boundary point
iopt out anal Disables/enables (0/1) harmonic output.
iopt out avrgd Disables/enables (0/1) time averaged output.
iopt out tsers Disables/enables (0/1) time series output.
iopt sal Salinity update.
0: uniform (space and time) salinity field
1: salinity field initialised but not updated in time
2: salinity field initialised and updated in time
iopt sal sbc Type of surface boundary condition for salinity.
0: zero surface flux

1: surface flux given by (4.264)
iopt sflux cds Formulation for the neutral surface drag coeffi-
cient Cds .
0: constant value as given by the parameter cds cst
1: equation (4.274) from Large & Pond (1981)
2: equation (4.275) from Smith & Banke (1975)
3: equation (4.276) from Geernaert et al. (1986)
4: equation (4.277) from Kondo (1975)
5: equation (4.278) from Wu (1980)
6: equation (4.279) from Charnock (1955)
iopt sflux cehs Formulation for the neutral surface (heat) exchange
coefficients Ce , Ch .
0: constant value as given by the parameter ces cst
or chs cst
1: equation (4.280) from Large & Pond (1982)
2: equation (4.281) from Anderson & Smith (1981)
3: equation (4.282 from Kondo (1975)
4: equation (4.283) from Wu (1980)
iopt sflux strat Selects dependence of the surface drag and ex-
change coefficients on atmospheric stratification
effects.
0: no dependence
1: using the Kondo (1975) parameterisation (Sec-
tion 4.8.2)
2: using the Monin-Obukhov similarity theory (Sec-
tion 4.8.3)
iopt structs Disables/enables (0/1) the definition of structures
inside the computational domain. Current value
must be 0.
iopt sur 1D Disables/enables surface forcing (surface slopes
and elevations) in case of a 1-D (iopt grid nodim=1)
water column application.
iopt temp Temperature update.
0: uniform (space and time) temperature field

1: temperature field initialised but not updated
in time
2: temperature field initialised and updated in
time
iopt temp optic Disables/enables (0/1) the optical module.
0: all solar radiation is assumed to be absorbed at
the surface, i.e. the water column is considered
as opaque
1: solar radiation is absorbed within the water
column using specified values for the attenua-
tion depths
iopt temp sbc Type of surface boundary condition for tempera-
ture.
1: Neumann using the model’s surface heat flux
formulations
2: Dirichlet using prescribed surface temperatures
taken at the first grid point below the surface
3: Dirichlet using prescribed surface temperature
taken at the surface itself
iopt transp full Selects how a series of tranport variables are up-
dated in the transport routine. Currently not im-
plemented.
0: Each equation is updated separately.
1: The equations are simultaneously updated.
iopt turb alg Type of algebraic scheme if iopt vdif coef=2.
1: Pacanowski-Philander formulation (4.121)–(4.124)
2: Munk-Anderson formulation (4.125)–(4.129)
3: flow dependent formulation as described in Sec-
tion 4.4.2.2 with α given by (4.137)
iopt turb dis bbc Type of the bottom boundary condition for the
dissipation rate ε.

iopt turb dis sbc Type of the surface boundary condition for the
dissipation rate ε.
iopt turb iwlim Type of the background mixing scheme as descri-
bed in Section 4.4.3.6.
0: using uniform background coefficients
1: using limiting conditions for turbulence para-
meters giving the background limits (4.213)–
(4.214)
2: the Large et al. (1994) scheme given by (4.215)
iopt turb lmix Mixing length formulation as described in Sec-
tion 4.4.3.5.
1: parabolic law (4.201)
2: “modified” parabolic law (4.202)
3: “Xing” formulation (4.203)
4: “Blackadar” asymptotic formulation (4.204)
iopt turb ntrans Number of transport equations as described in
Section 4.4.3.4.
0: zero-equation model (equilibrium or Mellor-Yamada
level 2 method)
1: turbulence energy equation with a mixing length
selected by iopt turb lmix
2: k-ε of k-kl equation depending on the value of
iopt turb param
iopt turb param Selects the type of second turbulent variable.
1: mixing length l (k-l scheme)
2: dissipation rate ε (k-ε scheme)
iopt turb stab form Selects the type of stability function.
1: constant value (4.186)
2: Munk-Anderson form (4.187)
3: from a RANS model as explained in Section 4.4.3.3
iopt turb stab lev Selects the level for stability functions if iopt turb stab form=
3.
1: quasi-equilibrium method (Section 4.4.3.3)
2: non-equilibrium method (Section 4.4.3.3)
iopt turb stab mod Selects the type of closure (RANS) model.
1: MY82-model (Mellor & Yamada, 1982)
2: KC94-model (Kantha & Clayson, 1994)
3: BB95-model (Burchard & Baumert, 1995)
4: HR82-model (Hossain & Rodi, 1982)
5: CA01-model (Canuto et al., 2001)
6: CA02-model (Canuto et al., 2001)
iopt turb stab tke Formulation for the turbulent diffusion coefficient
νk (or stability coefficient Sk ) of turbulent en-
ergy.
1: constant value for Sk as given by equation (4.188)
2: Sk is taken as proportional to the momentum
stability function Su as given by (4.189)
3: using the formulation of Daly & Harlow (1970)
as given by (4.173) or (4.179)
iopt turb tke bcc Type of the bottom boundary condition for tur-
bulence energy.
iopt turb tke sbc Type of the surface boundary condition for tur-
bulence energy.
iopt vadv impl Time-integration for vertical advection
0: explicit
1: semi-implicit
2: implicit
iopt vdif coef Selects the (general) type of the vertical diffusion
scheme.
0: vertical diffusion disabled

1: uniform diffusion coefficient
2: algebraic formulation as described in Section 4.4.2.2
3: second order turbulence closure as described
in Section 4.4.3
iopt vdif impl Time-integration for vertical diffusion.
0: explicit
1: semi-implicit
2: implicit
iopt verif Disables/enables (0/1) the use of the verification
procedure (not documented). This switch cannot
be defined by the user, but is set automatically
when -DVERIF is added as CPP compiler option
in options.cpp. The only effect of the switch is
that a different output is produced when running
a pre-defined test case.
25.19 Constants and system parameters

MODULE syspars
!--kind parameters
INTEGER, PARAMETER :: kndchar = KIND(’A’), kndlog = KIND(.TRUE.), &
& kndint = KIND(1), &
& kndilong = MAX(4,SELECTED INT KIND(10)), &
& kndreal = KIND(1.0), kndlong = 8, kndcmplx = 8
!---data types
INTEGER, PARAMETER :: char type = 1, log type = 2, int type = 3, &
& longint type = 4, real type = 5, long type = 6, &
& cmplx type = 7
!---universal parameters
REAL, PARAMETER :: pi = 3.14159265, halfpi = 1.57079633, twopi = 6.28318531
REAL (KIND=kndlong), PARAMETER :: pi d = 3.1415926535897932 kndlong
REAL (KIND=kndlong), PARAMETER :: halfpi d = 1.5707963267948966 kndlong
REAL (KIND=kndlong), PARAMETER :: twopi d = 6.2831853071795865 kndlong
REAL, PARAMETER :: degtorad = pi/180.0, radtodeg = 180.0/pi
REAL, PARAMETER :: degtorad d = pi d/180.0 kndlong, &
& radtodeg d = 180.0 kndlong/pi d
!---tidal parameters
25.19. CONSTANTS AND SYSTEM PARAMETERS 1185
INTEGER, PARAMETER :: MaxAstroTides = 56, MaxConstituents = 77

!---random generators
INTEGER, PARAMETER :: MaxGenerators = 32
!---MPI communications
INTEGER, PARAMETER :: MaxHaloComms = 8
!---model variables
INTEGER, PARAMETER :: MaxBioArids = 500, MaxModArids = 1000, &
& MaxTotArids = MaxModArids + MaxBioArids
!---model I/O
INTEGER, PARAMETER :: MaxCIFTypes = 3, MaxCIFVars = 50, MaxGridTypes = 4, &
& MaxGridFiles = 2, MaxIOFiles = 30, MaxIOTypes = 24, &
& MaxProgLevels = 20, MaxRestarts = 10
!---monitoring files and error coding
INTEGER, PARAMETER :: MaxErrCodes = 13, MaxErrMesgs = 50, MaxTimers = 34
!---character string lengths
INTEGER, PARAMETER :: lencifline = 300, lencifvar = 120, lendesc = 120, &
& lenerrcode = 120, lenformat = 120, lenfreq = 7, &
& leniofile = 120, lenname = 31, lennode = 3, &
& lentime = 23, lentitle = 20, lenunit = 60, &
& lenversion = 10
!---cif file
CHARACTER (LEN=1), PARAMETER :: cifcom = ’!’, cifend =’#’, cifsep =’,’
!---user output
LOGICAL, PARAMETER :: DegreesOut = .TRUE.
CHARACTER (LEN=lenversion), PARAMETER :: model version = ’V2.1.2’
!---output formats
CHARACTER (LEN=lenformat), PARAMETER :: IntegerFormat=’(50I11)’,&
& RealFormat=’(50G16.7)’
!---undefined and zero values
LOGICAL, PARAMETER :: log undef = .FALSE.
INTEGER, PARAMETER :: int undef = -2147483647, izero = 0
INTEGER (KIND=kndilong), PARAMETER :: izero d = 0 kndilong, &
& longint undef = -2147483647 kndilong
REAL, PARAMETER :: real undef = -9.9692099683868690E+36, &
& real flag = -9.9692099683868690E+35, rzero = 0.0
REAL (KIND=kndlong), PARAMETER :: rzero d = 0.0 kndlong
CHARACTER (LEN=lentime), PARAMETER :: cdatetime undef = &
& ’xxxx/xx/xx;00:00:00,000’
File
syspars.f90
Type
Module
Purpose
Constants and other system parameters. The Max* parameters are
mostly intended for the dimensioning of arrays which cannot be de-
clared as allocatable.
Description
DegreesOut Determines the unit of phases and angles in user-
defined output files
.TRUE. degrees
.FALSE. radians
IntegerFormat Format string used for reading/writing integer data
from/to a ASCII (‘A’) file in standard COHERENS
format
MaxAstroTides Maximum allowed number of constituents for the as-
tronomical forcing
MaxBioArids Maximum available number of key ids for biological
array variables. Currently not implemented.
MaxCIFTypes Maximum number of CIF files
MaxCIFVars Maximum number of data variables on a CIF line
MaxConstituents Maximum allowed number of tidal constituents at open
boundaries
MaxErrCodes Maximum number of key ids for error messages
MaxErrMesgs Default maximum number of error messages
MaxGenerators Maximum available number of random generators which
can be simultaneously used in the program
MaxGridFiles Maximum number of surface grid files for each grid
type. Current value is 1.
MaxGridTypes Maximum number of surface grid types
MaxHaloComms Maximum available number of exchange communica-
tions (send or receive)
MaxIOFiles Maximum number of forcing files for a given file de-
scriptor key id.
25.19. CONSTANTS AND SYSTEM PARAMETERS 1187
MaxIOTypes Maximum number of file descriptor key ids.

MaxModArids Maximum available number of key ids for physical
model array variables
MaxProgLevels Maximum number of subprogram levels
MaxRestarts Maximum number of output times for the writing of
restart conditions
MaxTimers Maximum available number of timers
MaxTotArids Maximum available number of key ids for all model
arrays
RealFormat Format string used for reading/writing real data from/to
a ASCII (‘A’) file in standard COHERENS format
cdatetime undef Flag for an undefined date/time string
char type Type parameter for character variables
cifcom Comment character on a CIF line
cifend Character marking the end of a data block in a CIF
cifsep Data separator character within a CIF line
cmplx type Type parameter for complex variables
degtorad Factor to convert degrees to radians
degtorad d Factor to convert degrees to radians in double preci-
sion
halfpi The number π/2
halfpi d The number π/2 in double precision
int type Type parameter for integer variables
int undef Flag for undefined or invalid integer values
izero The number zero in single precision
izero d The number zero in long integer format
kndchar Kind parameter for character variables
kndcmplx Kind parameter for complex variables
kndilong Kind parameter for long integer variables
kndint Kind parameter for integer variables
kndlog Kind parameter for logical variables
kndlong Kind parameter for double precision real variables
kndreal Kind parameter for real variables
lencifline Maximum length of a data line in a CIF

lencifvar Maximum length of a CIF data value in string format
lendesc Maximum length of a long name attribute
lenerrcode Maximum length of an error code message
lenformat Maximum length of a string format specification
lenfreq Maximim length of a frequency name
leniofile Maximum length for the name of a file in standard
COHERENS format
lenname Maximum length of a f90 name attribute
lennode Maximum length of a node attribute
lentime Length of a date/time string
lentitle Maximum length of a simulation title
lenunit Maximum length of the units attribute
lenversion Maximum length of the model version string
log type Type parameter for logical variables
log undef Flag for undefined or invalid logical data
longint type Type parameter for a long integer variable
longint undef Flag for undefined or invalid long integer values
long type Type parameter for double precision real variables
model version Current COHERENS version number in string format
pi The number π
pi d The number π in double precision
radtodeg Factor to convert radians to degrees
radtodeg d Factor to convert radians to degrees in double preci-
sion
real flag Flag below which input data are considered as invalid
(default value). Actual parameter used in the pro-
gram is real min.
real type Type parameter for real variables
real undef Default flag for undefined or invalid real values. Ac-
tual parameter used in the program is real fill.
rzero The number zero in single precision real format
rzero d The number zero in double precision real format
25.20. TIDAL FORCING 1189
twopi The number 2π

twopi d The number 2π in double precision
25.20 Tidal forcing

MODULE tide
!---number of tidal constituents
INTEGER :: nconastro = 0, nconobc = 0
!---tidal indices
INTEGER, DIMENSION(MaxAstroTides) :: index astro = 0
INTEGER, DIMENSION(MaxConstituents) :: index obc = 0
!---nodal factors
REAL, DIMENSION(nconastro) :: fnode astro
REAL, DIMENSION(nconobc) :: fnode obc
!---tidal phases
REAL, DIMENSION(nconastro) :: phase astro
REAL, DIMENSION(nconobc) :: phase obc
!---tidal force
REAL, DIMENSION(ncloc,nrloc) :: fxastro, fyastro
!---key ids for tidal constituents
INTEGER, PARAMETER ::&
& icon MS0 = 1, icon Sa = 2, icon Ssa = 3, icon 058 = 4,&
...
!---tidal species index
INTEGER, DIMENSION(MaxConstituents) :: ispec tides
DATA ispec tides /12*0, 21*1, 22*2, 1*3, 1*2, 4*3, 5*4, 6*6, 5*8/
!---amplitudes of the equilibrium tide
REAL, DIMENSION(MaxAstroTides) :: astro_ampl = &
& (/0.198419, 0.003103, 0.019542, 0.001142, 0.004239, 0.022191, 0.003677, &
..., 0.003455/)
!---amplitude corrections for the earth tide
REAL, DIMENSION(MaxAstroTides) :: astro earth
DATA astro earth /15*0.693, 0.6946, 0.6948, 0.6950, 0.6956, 0.693, 0.6962, &
..., 24*0.693/
!---tidal frequencies
REAL, DIMENSION(MaxConstituents) :: tidal spectrum = &
&(/0.0000000E+00, 1.9909688E-07, 3.9821277E-07, 5.9730965E-07, &
& ..., 5.8177642E-04/)
!---names of tidal frequencies
CHARACTER (LEN=lenfreq), DIMENSION(MaxConstituents) :: tidal freq names = &
& (/’MS0 ’ ,’Sa ’ ,’Ssa ’, ’058 ’, ’Msm ’, ’Mm ’,&

& ..., ’S8 ’/)
File
tide.f90
Type
Module
Purpose
Parameters and arrays for tidal forcing
Description
astro ampl Amplitudes of the astronomical equilibrium tide [m]
astro earth Elasticity factor αqn representing the effect of the Earth
tides on the tidal force
fnode astro Nodal factors of the constituents used for the astro-
nomical tidal force
fnode obc Nodal factors of the tidal constituents used at open
boundaries
fxastro X-component of the astronomical tidal force [m2 /s]
fyastro Y-component of the astronomical tidal force [m2 /s]
icon ⋆ Key ids of all tidal constituents
index astro Key ids of the constituents used in the calulcation of
the astronomical force
index obc Key ids of the constituents used at the open bounda-
ries
ispec tides Tidal species indices q for each frequency
nconastro Number of tidal constituents used in the calculation
of the astronomical force
nconobc Number of tidal constituents used at open boundaries
phase astro Astronomical phases of the constituents used for the
astronomical tidal force, at Greenwhich. Nodal cor-
rections are included if iopt astro pars=2. [rad]
phase obc Astronomical phases of the constituents used at open
boundaries with respect to the reference longitude
dlon ref obc. Nodal corrections are included if iopt -
astro pars=2. [rad]
25.21. TIME PARAMETERS 1191
tidal freq names Names of all pre-defined tidal frequencies

tidal spectrum Frequencies of all pre-defined tidal constituents [rad/s]
25.21 Time parameters

MODULE timepars
LOGICAL :: corrstep, metstepin, predstep
CHARACTER (LEN=lentime) :: CDateTime, CEndDateTime = cdatetime undef,&
& CStartDateTime = cdatetime undef, ClockTime
INTEGER :: julianday, norestarts = 0, nstep = 0, nt = 0, ntobcrlx = 0
INTEGER :: ic3d = 1, icnodal = 0
INTEGER (KIND=kndilong) :: nosecsrun = 0
REAL :: delt2d, delt3d, time zone = 0.0
INTEGER, DIMENSION(6) :: time convert = (/1,60,3600,86400,2629800,31557600/)
INTEGER, DIMENSION(7) :: IDateTime, IEndDateTime, IStartDateTime
INTEGER, DIMENSION(12) :: days in month = &
& (/31,28,31,30,31,30,31,31,30,31,30,31/)
INTEGER, DIMENSION(13) :: monthdays = &
& (/0,31,59,90,120,151,181,212,243,273,304,334,365/)
INTEGER, DIMENSION(MaxRestarts) :: ntrestart = 0
File
timepars.f90
Type
Module
Purpose
Time parameters
Description
CDateTime Current date and time in string format
CEndDateTime End date and time in string format
CStartDateTime Start date and time in string format
ClockTime Date and time from the machine’s internal real-time
clock at the start of the simulation
IDateTime Current date and time in integer vector format
IEndDateTime End date and time in integer vector format
IStartDateTime Start date and time in integer vector format
corrstep Set to .TRUE. at the corrector time steps

days in month Number of days in each month (without correction for
leap years)
delt2d Barotropic (2-D) time step [s]
delt3d Baroclinic (3-D) time step [s]
icnodal Time step (measured in units of delt2d) for an update
of the nodal tidal factors and astronomical arguments
if iopt astro pars >0. If zero, nodal corrections (am-
plitudes and phases) are evaluated at the initial time
only.
ic3d Ratio of the 3-D (baroclinic) and 2-D time steps
julianday Julian day (year day between 1 and 365 or 366)
metstepin Set to .TRUE. at time steps when an update of surface
fluxes is required.
monthdays Day number of the first day in each month (without
correction for leap years)
norestarts Number of times for the writing of re-start initial con-
ditions
nosecsrun Number of seconds since the start of the simulation
nstep Number of 2-D time steps
nt Time index (time since the start of the simulation di-
vided by delt2d)
ntobcrlx The relaxation period Tr , divided by the 2-D time step
delt2d, (optionally) used to define the relaxation factor
αr (t) (see equation (4.342)) for the 2-D mode at open
boundaries.
ntrestart The times during a simulation, measured in time in-
dices, when re-start conditions have to be written
predstep Set to .TRUE. at the predictor time steps
time convert Factors for converting the time in seconds to another
unit
time zone Time zone, i.e. the difference of the local time with
respect to GMT. Difference is positive (negative) east-
wards (westwards) from Greenwich. [hours]
25.22. TURBULENCE MODEL PARAMETERS 1193
25.22 Turbulence model parameters

MODULE turbpars
!---stability functions
INTEGER :: ib22
REAL :: cfequil(5), cfstabtke(3), cfstab1(8), cfstab2(11)
REAL :: c sk = 0.15, keps0, f0stabmom, f0stabscal, f0stabtke, &
& skeps = 0.09, sq my = 0.2
!---limiting conditions
REAL :: alphaM max, alphaN max, alphaN min, alphaN sl, &
& dissipmin = 1.0E-012, tkelim = 1.0E-06, tkemin = 1.0E-014, &
& zlmixmin = 1.7E-010
!---t.k.e.-equation
REAL :: sigma k = 1.0, wfltke = 0.0
!---kl-equation
REAL :: e1 my = 1.8, e2 my = 1.33, e3 my = 1.0, sigma kl
!---eps-equation
REAL :: c1 eps = 1.44, c2 eps = 1.92, c31 eps = 0.2, c32 eps = 1.0, sigma eps
!---roughness lengths
REAL :: zrough bot = 0.0, zrough sur = 0.0
!---KPP scheme for internal waves
REAL :: riccrit iw = 0.7, vdifmom iw = 1.0E-04, vdifscal iw = 5.0E-05, &
& vdifshear iw = 0.005
!---Pacanowski-Philander relations
REAL :: alpha pp = 5.0, expmom pp = 2.0, vbmom pp = 1.0E-04, &
& vbscal pp = 1.0E-05, vmax pp = 3.0, v0dif pp = 0.01
!---Munk-Anderson relations
REAL :: alpha ma = 10.0, beta ma = 3.33, expmom ma = 0.5, &
& expscal ma = 1.5, & vmaxmom ma = 3.0, vmaxscal ma = 4.0, v0dif ma = 0.06
!---algebraic flow-dependent relations
REAL :: cnu ad = 2.0, delta1 ad = 0.0, delta2 ad = 0.0, k1 ad =0.0025, &
& k2 ad = 2.0E-05, lambda ad = 0.0, omega1 ad = 1.0E-04, &
& r1 ad = 1.0, r2 ad = 1.0
!---algebraic mixing length formulations
REAL :: alpha Black = 0.2, beta Xing = 2.0
File
turbpars.f90
Type
Module
Purpose
Parameters for turbulence schemes
Description
alpha Black constant α1 in the Blackadar (1962) mixing length for-
mulation (4.205)
alphaM max maximum value for the stability parameter αM in case
of stable stratification when the the non-equilibrium
method is applied
alphaN max maximum value for the stability parameter αN in case
of stable stratification
alphaN min minimum value for the stability parameter αN in case
of unstable stratification
alphaN sl slope of the limiting curve for αN in the case of a stable
stratification
alpha ma parameter αm in the Munk & Anderson (1948) scheme
(4.125)–(4.128)
alpha pp parameter αp in the Pacanowski & Philander (1981)
scheme (4.121)–(4.123)
beta ma parameter βm in the Munk & Anderson (1948) scheme
(4.125)–(4.128)
beta Xing attenuation factor β1 in the Xing & Davies (1996) mix-
ing length formulation (4.203)
cfequil coefficients Cd used in the equilibrium formulation (4.182–
4.183) for the stability functions
cfstabtke coefficients used in the non-equilibrium (4.173) or the
quasi-equilibrium (4.179) method for the stability func-
tion Sk
cfstab1 coefficients Cb or Cc used in the quasi-equilibrium for-
mulation (4.175) or (4.178) for the stability functions
cfstab2 coefficients Ca used in the non-equilibrium formulation
(4.170) for the stability functions
cnu ad parameter Cν in equation (4.140)
c1 eps constant c1ε in the shear production term of the ε-
equation (4.193)
c2 eps constant c2ε in the dissipation term of the ε-equation
(4.193)
25.22. TURBULENCE MODEL PARAMETERS 1195
c31 eps constant c3ε in the buoyance sink term of the ε-equation
(4.193) in case of stable stratification (N 2 > 0)
c32 eps constant c3ε in the buoyancy source term of the ε-
equation (4.193) in case of unstable stratification (N 2 <
0)
c sk Daly-Harlow parameter csk in (4.165)
delta1 ad parameter δ1 in equation (4.132)
delta2 ad parameter δ2 in equation (4.132)
dissipmin numerical lower limit εmin for ε [W/kg]
eps0 parameter ǫ0 as defined by (4.270)
expmom ma parameter n1 in the Munk & Anderson (1948) scheme
(4.125)–(4.128)
expmom pp parameter np in the Pacanowski & Philander (1981)
scheme (4.121)–(4.123)
expscal ma parameter n2 in the Munk & Anderson (1948) scheme
(4.125)–(4.128)
e1 my constant E1 in the shear production term of the kl-
equation (4.197)
e2 my constant E2 in the wall proximity term (4.198) of the
kl-equation (4.197)
e3 my constant E3 in the buocancy source/sink term of the
kl-equation (4.197)
f0stabmom neutral stability coefficient Su0 for momentum (quasi-
equilibrium or equilibrium method)
f0stabscal neutral stability coefficient Sb0 for scalars (quasi-equilibrium
or equilibrium method)
f0stabtke constant stability coefficient Sk0 for turbulent kinetic
energy
ib22 Equals 1 when the parameter c22β 6= 0, 0 otherwise
k1 ad parameter K1 in equations (4.137) and (4.139)
k2 ad parameter K2 in equation (4.138)
lambda ad parameter λ⋆ in equation (4.135) [m]
omega1 ad parameter ω1 in equation (4.140) [s−1 ]
riccrit iw critical Richardson number Ri0 in the Large et al.
(1994) background mixing scheme (4.215)
r1 ad parameter r1 in equation (4.132)

r2 ad parameter r2 in equation (4.132)
sigma eps the parameter σε as obtained from (4.194)
sigma k parameter σk used to define Sk in (4.189)
sigma kl the parameter σkl obtained from (4.199)
skeps neutral value Sk0 of the stability coefficient Sk in the
k-ε model (see equation (4.188))
sq my parameter Sq used to determine Sk0 in the Mellor-
Yamada model (see equation (4.190))
tkelim background limit klim for k (see equation (4.214)) [J/kg]
tkemin numerical lower limit kmin for k [J/kg]
vbmom pp parameter νbp in the Pacanowski & Philander (1981)
scheme (4.121)–(4.123) [m2 /s]
vbscal pp parameter λbp in the Pacanowski & Philander (1981)
scheme (4.121)–(4.123) [m2 /s]
vdifmom iw internal wave breaking diffusion coefficient νT 0 for mo-
mentum in the Large et al. (1994) background mixing
scheme (4.215) [m2 /s]
vdifscal iw internal wave breaking diffusion coefficient λT 0 for scalars
in the Large et al. (1994) background mixing scheme
(4.215) [m2 /s]
vdifshear iw maximum mixing due to resolved vertical shear ν0s in
[m2 /s]
vmaxmom ma parameter νmax in the Munk & Anderson (1948) scheme
(4.125)–(4.128)
vmaxscal ma parameter λmax in the Munk & Anderson (1948) scheme
(4.125)–(4.128)
vmax pp parameter νmax in the Pacanowski & Philander (1981)
scheme (4.121)–(4.123)
v0dif ma parameter ν0m in the Munk & Anderson (1948) scheme
(4.125)–(4.128) [m2 /s]
v0dif pp parameter ν0p in the Pacanowski & Philander (1981)
scheme (4.121)–(4.123) [m2 /s]
wfltke surface wave factor cw used in the surface flux condi-
tion (4.271) for turbulent energy
25.23. TURBULENCE ARRAYS 1197
zlmixmin numerical lower limit lmin for l [m]

zrough bot bottom roughness length z0b in the mixing length for-
mulation (4.200) [m]
zrough sur surface roughness length z0s in the mixing length for-
mulation (4.200) [m]
25.23 Turbulence arrays

MODULE turbulence
REAL, DIMENSION(1-nhalo:ncloc+nhalo,1-nhalo:nrloc+nhalo,nz+1) :: &
& dissip, tke, tke old, zlmix
REAL, DIMENSION(ncloc,nrloc,nz+1) :: buofreq2, shearfreq2
File
turbulence.f90
Type
Module
Purpose
Turbulence arrays
Description
buofreq2 Squared buoyancy frequency N 2 [1/s2 ]
dissip Dissipation of turbulent kinetic energy [W/kg]
tke Turbulent kinetic energy [J/kg]
tke old Turbulent kinetic energy at the old 3-D time step [J/kg]
2
shearfreq2 Squared shear frequency M [1/s2 ]
zlmix Turbulent mixing length [m]

CoherensBook PDF

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

CoherensBook PDF

Caricato da

Copyright:

Formati disponibili

COHERENS

A Coupled Hydrodynamical-Ecological Model

Version 2.3, April 2012

Royal Belgian Institute of Natural Sciences (RBINS-MUMM)

Marcelo Heredia Gomez and Ivan Rocabado

Everyone is permitted to copy and distribute verbatim copies of this license

COHERENS is a open-source multi-purpose hydrodynamical model, orig-

2. Including COHERENS in other programs or packages for which fees are

However, COHERENS commercial exploitation remains possible in the frame-

Luyten, P. 2011. COHERENS — A Coupled Hydrodynamical-

4.8.1 Neutral formulations . . . . . . . . . . . . . . . . . . . 101

5 Numerical methods 129

5.3.3 Discretisation of 3-D horizontal advection . . . . . . . 162

5.3.16.3 boundary conditions for the 3-D mode at closed

5.6.2.2 advection in the Y-direction . . . . . . . . . . 223

III Description of the model code 239

7 Model input and output 273

8 Model grid and spatial interpolation 337

8.1.2.4 pointer arrays . . . . . . . . . . . . . . . . . . 343

9 Aspects of parallellisation 361

10 Structure of the model code 379

IV User manual 401

12 Control parameters 409

12.6.1 Grid descriptors . . . . . . . . . . . . . . . . . . . . . . 436

13 Model grid and initial conditions 443

14 Open boundary conditions 451

15 Surface forcing and nesting 465

16 User output 477

V Test cases 511

18 Advection schemes 519

19 Turbulence and heat flux formulations 545

20 Density fronts and river plumes 565

20.3.2 Experiments and output parameters . . . . . . . . . . 586

21 Inundation schemes 597

22 Shelf sea modelling 619

A Transformed model equations 627

B Solutions of the RANS equations 633

C Discretisation of the Coriolis force 637

D Energy balance equation 639

E List of standard output variables 641

VI Reference manual 659

22.4 Coherens Program.f90 . . . . . . . . . . . . . . . . . . . . . . 678

23 Description of modules routines 803

23.13Library of mathematical routines . . . . . . . . . . . . . . . . 1009

24 Description of user defined routines 1091

25 Description of program variables 1111

25.20Tidal forcing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1189

4.1 Examples of horizontal grids. . . . . . . . . . . . . . . . . . . 39

5.1 Layout of the (global) computational grid in the horizontal. . . 131

8.1 Interpolation of model grid arrays at a different node. . . . . . 346

9.4 Horizontal layout of the computational grid on a local sub-

10.1 General structure of COHERENS. . . . . . . . . . . . . . . . . 384

18.1 The initial configuration of the cones test case. . . . . . . . 520

18.7 The initial configuration of the seich test case. . . . . . . . . 532

22.1 Bathymetry of the Bohai Sea. The diamond symbols locate

2.1 Test case descriptions . . . . . . . . . . . . . . . . . . . . . . . 21

4.1 Values of the empirical parameters in the McDougall et al.

6.1 Model data types. . . . . . . . . . . . . . . . . . . . . . . . . . 247

8.1 Model grid parameters and arrays. . . . . . . . . . . . . . . . 339

10.1 List of declaration module files. . . . . . . . . . . . . . . . . . 380

16.1 List of available elliptic parameters (corresponding variable

17.1 Calculation times (in seconds) for test case experiments on a

This report is the User Documentation of COHERENS version V2.3. Changes